[PATCH] lib: make notmuch shared library install_name be full path on Mac OS X

[PATCH] lib: make notmuch shared library install_name be full path on Mac OS X

[J. Lewis Muir]

The install_name of libnotmuch.dylib on Mac OS X is what is written
into a program that links against it.  If it is just the name of the
shared library file, as opposed to the full path, the program won't be
able to find it when it runs and will abort.  Instead, the install_name
should be the full path to the shared library (in its final installed
location).

An example on Mac OS X Mavericks (10.9.4) follows.

We configure, build, and install notmuch, assuming the user has write
access to /opt:

===
$ CFLAGS='-I/pkg/include' LDFLAGS='-L/pkg/lib' ./configure \
      --prefix=/opt/notmuch-current --without-emacs
$ make
$ make install
===

We inspect the installed notmuch library using the otool system program:

===
$ otool -L /opt/notmuch-current/lib/libnotmuch.dylib
/opt/notmuch-current/lib/libnotmuch.dylib:
  libnotmuch.3.dylib \
(compatibility version 3.1.0, current version 3.1.0)
  /pkg/lib/libgmime-2.4.2.dylib \
(compatibility version 7.0.0, current version 7.33.0)
  /pkg/lib/libgobject-2.0.0.dylib \
(compatibility version 3801.0.0, current version 3801.2.0)
  /pkg/lib/libglib-2.0.0.dylib \
(compatibility version 3801.0.0, current version 3801.2.0)
  /pkg/lib/libintl.8.dylib \
(compatibility version 10.0.0, current version 10.2.0)
  /pkg/lib/libtalloc.2.1.1.dylib \
(compatibility version 0.0.0, current version 0.0.0)
  /pkg/lib/libz.1.dylib \
(compatibility version 2.0.0, current version 2.2.0)
  /pkg/lib/libxapian.22.dylib \
(compatibility version 29.0.0, current version 29.4.0)
  /usr/lib/libc++.1.dylib \
(compatibility version 1.0.0, current version 120.0.0)
  /usr/lib/libSystem.B.dylib \
(compatibility version 1.0.0, current version 1197.1.1)
===

That's not good.  The second line shows the install_name, and it's not a
full path, so any program that links against it as a dependent library
will not be able to find it.

We try running the notmuch program (which is linked against the notmuch
library), and, sure enough, it aborts:

===
$ /opt/notmuch-current/bin/notmuch --version
dyld: Library not loaded: libnotmuch.3.dylib
  Referenced from: /opt/notmuch-current/bin/notmuch
  Reason: image not found
Trace/BPT trap: 5
===

After applying this commit to fix the problem and configuring, building,
and installing again as above, the notmuch library's install_name is now
the correct full path:

===
$ otool -L /opt/notmuch-current/lib/libnotmuch.dylib
/opt/notmuch-current/lib/libnotmuch.dylib:
  /opt/notmuch-current/lib/libnotmuch.3.dylib \
(compatibility version 3.1.0, current version 3.1.0)
  /pkg/lib/libgmime-2.4.2.dylib \
(compatibility version 7.0.0, current version 7.33.0)
  /pkg/lib/libgobject-2.0.0.dylib \
(compatibility version 3801.0.0, current version 3801.2.0)
  /pkg/lib/libglib-2.0.0.dylib \
(compatibility version 3801.0.0, current version 3801.2.0)
  /pkg/lib/libintl.8.dylib \
(compatibility version 10.0.0, current version 10.2.0)
  /pkg/lib/libtalloc.2.1.1.dylib \
(compatibility version 0.0.0, current version 0.0.0)
  /pkg/lib/libz.1.dylib \
(compatibility version 2.0.0, current version 2.2.0)
  /pkg/lib/libxapian.22.dylib \
(compatibility version 29.0.0, current version 29.4.0)
  /usr/lib/libc++.1.dylib \
(compatibility version 1.0.0, current version 120.0.0)
  /usr/lib/libSystem.B.dylib \
(compatibility version 1.0.0, current version 1197.1.1)
===

And the notmuch program is able to find the notmuch library when run:

===
$ /opt/notmuch-current/bin/notmuch --version
notmuch 0.18.1+84~g658a00e
===

References:

* http://www.finkproject.org/doc/porting/porting.en.html#\
shared.build-lib

* https://developer.apple.com/library/mac/documentation/DeveloperTools/\
Conceptual/DynamicLibraries/100-Articles/OverviewOfDynamicLibraries.html
---
 lib/Makefile.local | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/lib/Makefile.local b/lib/Makefile.local
index c56cba9..c83f387 100644
--- a/lib/Makefile.local
+++ b/lib/Makefile.local
@@ -27,7 +27,7 @@ LIBRARY_SUFFIX = dylib
 LINKER_NAME = libnotmuch.$(LIBRARY_SUFFIX)
 SONAME = libnotmuch.$(LIBNOTMUCH_VERSION_MAJOR).$(LIBRARY_SUFFIX)
 LIBNAME = libnotmuch.$(LIBNOTMUCH_VERSION_MAJOR).$(LIBNOTMUCH_VERSION_MINOR).$(LIBNOTMUCH_VERSION_RELEASE).$(LIBRARY_SUFFIX)
-LIBRARY_LINK_FLAG = -dynamiclib -install_name $(SONAME) -compatibility_version $(LIBNOTMUCH_VERSION_MAJOR).$(LIBNOTMUCH_VERSION_MINOR) -current_version $(LIBNOTMUCH_VERSION_MAJOR).$(LIBNOTMUCH_VERSION_MINOR).$(LIBNOTMUCH_VERSION_RELEASE)
+LIBRARY_LINK_FLAG = -dynamiclib -install_name $(libdir)/$(SONAME) -compatibility_version $(LIBNOTMUCH_VERSION_MAJOR).$(LIBNOTMUCH_VERSION_MINOR) -current_version $(LIBNOTMUCH_VERSION_MAJOR).$(LIBNOTMUCH_VERSION_MINOR).$(LIBNOTMUCH_VERSION_RELEASE)
 else
 LIBRARY_SUFFIX = so
 LINKER_NAME = libnotmuch.$(LIBRARY_SUFFIX)
-- 
1.8.5.2 (Apple Git-48)

Re: [PATCH] lib: make notmuch shared library install_name be full path on Mac OS X

[David Bremner]

"J. Lewis Muir" <jlmuir@imca-cat.org> writes:

> The install_name of libnotmuch.dylib on Mac OS X is what is written
> into a program that links against it.  If it is just the name of the
> shared library file, as opposed to the full path, the program won't be
> able to find it when it runs and will abort.  Instead, the install_name
> should be the full path to the shared library (in its final installed
> location).

Hi Lewis;

Unfortunately we did not receive any feedback from Mac users in the
meantime. It would be nice to know that your patch won't break the
existing macports and brew packages.  I suppose that those work because
they install the libraries into a well known location.

d

Re: [PATCH] lib: make notmuch shared library install_name be full path on Mac OS X

[J. Lewis Muir]

On 2/25/15 1:34 AM, David Bremner wrote:
> Unfortunately we did not receive any feedback from Mac users in the
> meantime. It would be nice to know that your patch won't break the
> existing macports and brew packages.  I suppose that those work
> because they install the libraries into a well known location.

Hi, David.

I just tried installing to /usr/local (now on OS X Yosemite 10.10.2),
and you're right about that; it appears that because it's a standard
location, it works without my patch.  Looking at the dyld(1) man page,
it says the following for the DYLD_FALLBACK_LIBRARY_PATH environment
variable (and I think the fact that /usr/local/lib is in the default
list is the reason why it works without the patch):

  This is a colon separated list of directories that contain
  libraries.  It is used as the default location for libraries
  not found in their install path.  By default, it is set to
  $(HOME)/lib:/usr/local/lib:/lib:/usr/lib.

However, if I install to /opt, it does *not* work without my patch.  So,
I'm still confident that the patch is correct and needed.

The reason it works in Homebrew is twofold.  One, assuming Homebrew
installs packages to /usr/local, the dynamic linker finds the notmuch
library in /usr/local/lib because it's in the default list of locations
that the dynamic linker looks for libraries.  Two, Homebrew globally
corrects all install names in dynamically shared libraries and binaries
for all packages.  So, even if the package is broken, Homebrew corrects
it automatically, and no one ever knows.

The reason it works in MacPorts is because they apply a patch that's the
same as what I submitted!  See:

  https://trac.macports.org/browser/trunk/dports/mail/notmuch/files/patch-lib-Makefile.local.diff

For any OS X notmuch developer willing to test this, here are
the five commands to run to reproduce the problem (note: another
libnotmuch*.dylib must *not* be in /usr/local/lib where it would
be found automatically by the dynamic linker; similarly, no DYLD_*
environment variables should be set for this test; obviously, change the
CFLAGS and LDFLAGS environment variables in the ./configure command to
point to where the libraries are that notmuch needs):

===
$ git clone git://notmuchmail.org/git/notmuch
$ CFLAGS='-I/pkg/include' LDFLAGS='-L/pkg/lib' ./configure --prefix=/opt --without-emacs
$ make
$ make install
$ /opt/bin/notmuch --version
===

When I run the just-installed notmuch in that last command, it produces
the following output:

===
dyld: Library not loaded: libnotmuch.4.dylib
  Referenced from: /opt/bin/notmuch
  Reason: image not found
Trace/BPT trap: 5 (core dumped)
===

Regards,

Lewis

Re: [PATCH] lib: make notmuch shared library install_name be full path on Mac OS X

[Tomi Ollila]

On Thu, Feb 26 2015, "J. Lewis Muir" <jlmuir@imca-cat.org> wrote:

> On 2/25/15 1:34 AM, David Bremner wrote:
>> Unfortunately we did not receive any feedback from Mac users in the
>> meantime. It would be nice to know that your patch won't break the
>> existing macports and brew packages.  I suppose that those work
>> because they install the libraries into a well known location.
>
> Hi, David.
>
> I just tried installing to /usr/local (now on OS X Yosemite 10.10.2),
> and you're right about that; it appears that because it's a standard
> location, it works without my patch.  Looking at the dyld(1) man page,
> it says the following for the DYLD_FALLBACK_LIBRARY_PATH environment
> variable (and I think the fact that /usr/local/lib is in the default
> list is the reason why it works without the patch):
>
>   This is a colon separated list of directories that contain
>   libraries.  It is used as the default location for libraries
>   not found in their install path.  By default, it is set to
>   $(HOME)/lib:/usr/local/lib:/lib:/usr/lib.
>
> However, if I install to /opt, it does *not* work without my patch.  So,
> I'm still confident that the patch is correct and needed.

It definitely make sense that when loading "dynamically linked" binary,
and the names of the libraries it tries to open do not contain '/':s (or
perhaps is not absolute), the system attempts to find it from pre-defined
location -- and (possibly) otherwise uses the path coded in the name

The commit message is just (IMO) somewhat confusing; what is this

  $ otool -L /opt/notmuch-current/lib/libnotmuch.dylib

is there files /opt/notmuch-current/lib/libnotmuch.dylib and
/opt/notmuch-current/lib/libnotmuch.3.dylib in the fs -- and
what does otool -L opt/notmuch-current/bin/notmuch output

As a non-mac user it is hard to review this when full visibility
to the file system is not available...

>
> Regards,
>
> Lewis


Tomi

Re: [PATCH] lib: make notmuch shared library install_name be full path on Mac OS X

[J. Lewis Muir]

On 2/26/15 1:04 PM, Tomi Ollila wrote:
> The commit message is just (IMO) somewhat confusing; what is this
>
>   $ otool -L /opt/notmuch-current/lib/libnotmuch.dylib
>
> is there files /opt/notmuch-current/lib/libnotmuch.dylib and
> /opt/notmuch-current/lib/libnotmuch.3.dylib in the fs

Hi, Tomi.

Those files are actually known to you because they are what "make
install" installed.  The "./configure" script was invoked with the
option "--prefix=/opt/notmuch-current".

> and what does otool -L opt/notmuch-current/bin/notmuch output

The otool program is kind of like the ldd program on Unix-like OSes.
When invoked with the -L option, otool prints the shared libraries that
the object file uses.  When invoked on a shared library, it also shows
the install name of the shared library.  This is what I was trying to
show was not an absolute path.

In hindsight, maybe it would have been more clear if I had shown the
output of "otool -L" on the notmuch binary itself.  It would have shown
all the shared library dependencies with absolute paths except for
libnotmuch.dylib which was just the file name which is why the dynamic
linker couldn't find it when running the notmuch binary.  But I was
showing the "otool -L" output on libnotmuch.dylib because that was the
source of the problem (i.e. the install name was not set to an absolute
path).

I'm sorry for the confusing commit message.  As per David's subsequent
email on this thread, I'll try submitting again with a better one.

Regards,

Lewis

Re: [PATCH] lib: make notmuch shared library install_name be full path on Mac OS X

[David Bremner]

"J. Lewis Muir" <jlmuir@imca-cat.org> writes:


>
> I'm sorry for the confusing commit message.  As per David's subsequent
> email on this thread, I'll try submitting again with a better one.
>

Just for the record, I appreciate the effort to explain the problem. One
convention that might be useful is that additional commentary not
suitable for the commit message can be added below the -- line in a
patch/message.


David

Re: [PATCH] lib: make notmuch shared library install_name be full path on Mac OS X

[David Bremner]

"J. Lewis Muir" <jlmuir@imca-cat.org> writes:

I think Tomi and I agree the content of the patch is OK, or at least as
far as we can verify. If you don't mind, could you rework the commit
message a bit?

this part is fine:

> The install_name of libnotmuch.dylib on Mac OS X is what is written
> into a program that links against it.  If it is just the name of the
> shared library file, as opposed to the full path, the program won't be
> able to find it when it runs and will abort.  Instead, the install_name
> should be the full path to the shared library (in its final installed
> location).


Drop this part; it makes the commit message overwhelming, especially
since most of us don't have (easy) access to a Mac.

>
> An example on Mac OS X Mavericks (10.9.4) follows.
>
> We configure, build, and install notmuch, assuming the user has write
> access to /opt:
>
> ===
> $ CFLAGS='-I/pkg/include' LDFLAGS='-L/pkg/lib' ./configure \
>       --prefix=/opt/notmuch-current --without-emacs
> $ make
> $ make install
> ===
>
> We inspect the installed notmuch library using the otool system program:
>
> ===
> $ otool -L /opt/notmuch-current/lib/libnotmuch.dylib
> /opt/notmuch-current/lib/libnotmuch.dylib:
>   libnotmuch.3.dylib \
> (compatibility version 3.1.0, current version 3.1.0)
>   /pkg/lib/libgmime-2.4.2.dylib \
> (compatibility version 7.0.0, current version 7.33.0)
>   /pkg/lib/libgobject-2.0.0.dylib \
> (compatibility version 3801.0.0, current version 3801.2.0)
>   /pkg/lib/libglib-2.0.0.dylib \
> (compatibility version 3801.0.0, current version 3801.2.0)
>   /pkg/lib/libintl.8.dylib \
> (compatibility version 10.0.0, current version 10.2.0)
>   /pkg/lib/libtalloc.2.1.1.dylib \
> (compatibility version 0.0.0, current version 0.0.0)
>   /pkg/lib/libz.1.dylib \
> (compatibility version 2.0.0, current version 2.2.0)
>   /pkg/lib/libxapian.22.dylib \
> (compatibility version 29.0.0, current version 29.4.0)
>   /usr/lib/libc++.1.dylib \
> (compatibility version 1.0.0, current version 120.0.0)
>   /usr/lib/libSystem.B.dylib \
> (compatibility version 1.0.0, current version 1197.1.1)
> ===
>
> That's not good.  The second line shows the install_name, and it's not a
> full path, so any program that links against it as a dependent library
> will not be able to find it.
>
> We try running the notmuch program (which is linked against the notmuch
> library), and, sure enough, it aborts:
>
> ===
> $ /opt/notmuch-current/bin/notmuch --version
> dyld: Library not loaded: libnotmuch.3.dylib
>   Referenced from: /opt/notmuch-current/bin/notmuch
>   Reason: image not found
> Trace/BPT trap: 5
> ===
>
> After applying this commit to fix the problem and configuring, building,
> and installing again as above, the notmuch library's install_name is now
> the correct full path:
>
> ===
> $ otool -L /opt/notmuch-current/lib/libnotmuch.dylib
> /opt/notmuch-current/lib/libnotmuch.dylib:
>   /opt/notmuch-current/lib/libnotmuch.3.dylib \
> (compatibility version 3.1.0, current version 3.1.0)
>   /pkg/lib/libgmime-2.4.2.dylib \
> (compatibility version 7.0.0, current version 7.33.0)
>   /pkg/lib/libgobject-2.0.0.dylib \
> (compatibility version 3801.0.0, current version 3801.2.0)
>   /pkg/lib/libglib-2.0.0.dylib \
> (compatibility version 3801.0.0, current version 3801.2.0)
>   /pkg/lib/libintl.8.dylib \
> (compatibility version 10.0.0, current version 10.2.0)
>   /pkg/lib/libtalloc.2.1.1.dylib \
> (compatibility version 0.0.0, current version 0.0.0)
>   /pkg/lib/libz.1.dylib \
> (compatibility version 2.0.0, current version 2.2.0)
>   /pkg/lib/libxapian.22.dylib \
> (compatibility version 29.0.0, current version 29.4.0)
>   /usr/lib/libc++.1.dylib \
> (compatibility version 1.0.0, current version 120.0.0)
>   /usr/lib/libSystem.B.dylib \
> (compatibility version 1.0.0, current version 1197.1.1)
> ===
>
> And the notmuch program is able to find the notmuch library when run:
>
> ===
> $ /opt/notmuch-current/bin/notmuch --version
> notmuch 0.18.1+84~g658a00e
> ===
>

Add a brief explanation of why Homebrew and Macports already work
(a few lines summarizing the info from your followup message).

Thanks!


> References:
>
> * http://www.finkproject.org/doc/porting/porting.en.html#\
> shared.build-lib
>
> * https://developer.apple.com/library/mac/documentation/DeveloperTools/\
> Conceptual/DynamicLibraries/100-Articles/OverviewOfDynamicLibraries.html
> ---
>  lib/Makefile.local | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
>
> diff --git a/lib/Makefile.local b/lib/Makefile.local
> index c56cba9..c83f387 100644
> --- a/lib/Makefile.local
> +++ b/lib/Makefile.local
> @@ -27,7 +27,7 @@ LIBRARY_SUFFIX = dylib
>  LINKER_NAME = libnotmuch.$(LIBRARY_SUFFIX)
>  SONAME = libnotmuch.$(LIBNOTMUCH_VERSION_MAJOR).$(LIBRARY_SUFFIX)
>  LIBNAME = libnotmuch.$(LIBNOTMUCH_VERSION_MAJOR).$(LIBNOTMUCH_VERSION_MINOR).$(LIBNOTMUCH_VERSION_RELEASE).$(LIBRARY_SUFFIX)
> -LIBRARY_LINK_FLAG = -dynamiclib -install_name $(SONAME) -compatibility_version $(LIBNOTMUCH_VERSION_MAJOR).$(LIBNOTMUCH_VERSION_MINOR) -current_version $(LIBNOTMUCH_VERSION_MAJOR).$(LIBNOTMUCH_VERSION_MINOR).$(LIBNOTMUCH_VERSION_RELEASE)
> +LIBRARY_LINK_FLAG = -dynamiclib -install_name $(libdir)/$(SONAME) -compatibility_version $(LIBNOTMUCH_VERSION_MAJOR).$(LIBNOTMUCH_VERSION_MINOR) -current_version $(LIBNOTMUCH_VERSION_MAJOR).$(LIBNOTMUCH_VERSION_MINOR).$(LIBNOTMUCH_VERSION_RELEASE)
>  else
>  LIBRARY_SUFFIX = so
>  LINKER_NAME = libnotmuch.$(LIBRARY_SUFFIX)
> -- 
> 1.8.5.2 (Apple Git-48)
>
> _______________________________________________
> notmuch mailing list
> notmuch@notmuchmail.org
> http://notmuchmail.org/mailman/listinfo/notmuch