MacOS: dll-path & hardcode-dll-paths

[JBouwer]

Thanks to Nikita Kniazev's work on marrying clang-darwin into gcc (#281), clang on Darwin now also enjoys the delights of -rpath linking.

Below:

• Overview - B2 functionality
• Overview - MacOS linking
• Observations & Deductions

Overview - B2 functionality

Refer to B2 documentation for: dll-path & hardcode-dll-paths, and also to FAQ 9.9. Why are the dll-path and hardcode-dll-paths properties useful?

The hardcode-dll-paths documentation states:

Note that on Mac OSX, the paths are unconditionally hardcoded by the linker, and it is not possible to disable that behaviour

Overview - MacOS linking

Note the Apple term dylib, meaning shared library, or dll.

• From man ld (On a macOS 10.13.6);

  Options when creating a dynamic library (dylib)
  -install_name name

  Sets an internal "install path" (LC_ID_DYLIB) in a dynamic
  library. Any clients linked against the library will record
  that path as the way dyld should locate this library.  If
  this option is not specified, then the -o path will be used.
  This option is also called -dylib_install_name for compati-
  bility.
  

  Options that control symbol resolution
  -rpath path

  Add path to the runpath search path list for image being cre-
  ated.  At runtime, dyld uses the runpath when searching for
  dylibs whose load path begins with @rpath/.
  

• From man dyld;

  DYNAMIC LIBRARY LOADING

    Unlike many other operating  systems,  Darwin  does  not  locate
    dependent  dynamic  libraries via their leaf file name.  Instead
    the full path to  each  dylib  is  used  (e.g.  /usr/lib/libSys-
    tem.B.dylib).   But  there  are  times  when  a full path is not
    appropriate; for instance, may want your binaries to be  instal-
    lable in anywhere on the disk.  To support that, there are three
    @xxx/ variables that can be used as a path prefix.   At  runtime
    dyld substitutes a dynamically generated path for the @xxx/ pre-
    fix.
  

  • @executable_path/

    This variable is replaced with the path to  the  directory  con-
    taining the main executable for the process.  This is useful for
    loading dylibs/frameworks embedded in a .app directory.  If  the
    main  executable  file is at /some/path/My.app/Contents/MacOS/My
    and  a  framework  dylib  file  is   at   /some/path/My.app/Con-
    tents/Frameworks/Foo.framework/Versions/A/Foo,  then  the frame-
    work load path could be  encoded  as  @executable_path/../Frame-
    works/Foo.framework/Versions/A/Foo  and the .app directory could
    be moved around in the file system and dyld will still  be  able
    to load the embedded framework.
    

  • @loader_path/

    This  variable  is  replaced with the path to the directory con-
    taining the mach-o binary which contains the load command  using
    @loader_path.  Thus, in every binary, @loader_path resolves to a
    different path, whereas @executable_path always resolves to  the
    same  path. @loader_path is useful as the load path for a frame-
    work/dylib embedded in a plug-in, if the final file system loca-
    tion of the plugin-in unknown (so absolute paths cannot be used)
    or if the plug-in is used by  multiple  applications  (so  @exe-
    cutable_path  cannot  be used). If the plug-in mach-o file is at
    /some/path/Myfilter.plugin/Contents/MacOS/Myfilter and a  frame-
    work dylib file is at /some/path/Myfilter.plugin/Contents/Frame-
    works/Foo.framework/Versions/A/Foo, then the framework load path
    could   be   encoded   as  @loader_path/../Frameworks/Foo.frame-
    work/Versions/A/Foo and the Myfilter.plugin directory  could  be
    moved  around  in the file system and dyld will still be able to
    load the embedded framework.
    

  • @rpath/

    Dyld maintains a current stack of  paths  called  the  run  path
    list.   When  @rpath  is encountered it is substituted with each
    path in the run path list until a loadable dylib if found.   The
    run  path  stack is built from the LC_RPATH load commands in the
    depencency[sic] chain that lead to the current dylib load. You can
    add  an LC_RPATH load command to an image with the -rpath option
    to ld(1).  You can even add a LC_RPATH load  command  path  that
    starts  with  @loader_path/,  and it will push a path on the run
    path stack that relative to the image containing  the  LC_RPATH.
    The  use of @rpath is most useful when you have a complex direc-
    tory structure of programs and dylibs  which  can  be  installed
    anywhere,  but  keep  their  relative  positions.  This scenario
    could be implemented using @loader_path, but every client  of  a
    dylib  could  need  a  different  load path because its relative
    position in the file system is  different.  The  use  of  @rpath
    introduces a level of indirection that simplies[sic] things. You
    pick a location in your directory structure as an anchor  point.
    Each dylib then gets an install path that starts with @rpath and
    is the path to the dylib relative to the anchor point. Each main
    executable  is linked with -rpath @loader_path/zzz, where zzz is
    the path from the executable to the anchor  point.   At  runtime
    dyld sets it run path to be the anchor point, then each dylib is
    found relative to the anchor point.
    

Observations & Deductions

• At least since (unify clang-darwin linking with gcc #281) - and perhaps earlier for gcc - B2 do support the <dll-path> & <hardcode-dll-paths> features for macOS (or OSX, before rebranding). The mechanism works as follows:

  • The host shared library is linked with an -install_name "@rpath/library_name".
    This results in any other binary linked with it, to be predestined to use it's "run path list" to find it.
    (Apparently consistent with other "Unix-type" platforms.)

  • The client binary (executable or other library) is linked with optional -rpath options.
    These options are determined by (in order):

    • Automatic (development) paths of linked shared libraries -
      only for exe targets, and only for <hardcode-dll-paths>true properties (default for exe).

    • Any <dll-path> properties set (explicitly) for the target.

• MacOS also supports dylib @xxx/ placeholders for the -rpath option - these provide additional flexibility for shared library locations.

- but-

• In its current incarnation, B2 will "bind" any @xxx/ placeholders passed via <dll-path>, to the resulting directory in the filesystem - just like a regular path.

[JBouwer]

Preventing @xxx placeholder translation

As a feature with the path attribute, B2 is "kind" enough to bind¹ the value of <dll-path> to the filesystem before the generators are invoked (i.e. the link & link.dll rules/actions).
This is undesirable for any of the dyld @xxx/ placeholders - and should be prevented or undone.

We are left with the following options.

Bypass the translation.

The options are:

• Specifying a

  <target-os>darwin:<linkflags>"-install_name @xxx/libLibraryName.dylib"
  

  for the lib target in the jam file;

  ❌ This does not work, as the flag is overridden in the toolset actions.

• Specifying a:

  <target-os>darwin:<linkflags>"-rpath @xxx/"
  

  for the exe target in the jam file;

  ✅ This does work, as another -rpath argument can be added to the linker command line.

Prevent the translation.

• An ideal solution seemingly presents itself with the
  translate-path feature.
  I did not manage to get it working straight out of the box though. (See Using translate-path below.)
• Alternatively, hardcoding some very platform-specific exceptions to the translation functionality, were even more messier than it sounds - and best avoided, I think.

Undo the translation.

• Apart from the obvious undesirability of this approach, it also needs to be repeated for each toolset - so best not to go there.

Using translate-path

I considered the following:

• Any custom <translate-path> property ideally needs to be qualified as Darwin-only.
  Apart from the processing overhead, we don't want to burden paths on all platforms with magic values that clearly only pertain to a platform minority.

• Adding an explicit

  <target-os>darwin:<translate-path>@special-rule
  

  ❌ did not work - see below;

  It does not fit cleanly into the B2 ethos of "specify the build result - not the method" either.

• The <translate-path> functionality is actioned relatively high up in the call stack;

  • I don't believe that meta-targets have been resolved into concrete targets (& hence platform) at the time when it executes¹.
  • This leave just a few sites to inject a suitable <translate-path> property for Darwin - and none seemed suitable to me.

• Only 1 <translate-path> property is currently supported by B2¹.
  This is already used with the install rule².

Footnotes

1. See rule translate in property.jam. ↩ ↩² ↩³

2. See stage.jam. ↩

[JBouwer]

Pull request #335 submitted as possible resolution.

[grafikrobot]

Decided to go a much simpler way to resolve this. See d1c2312

[JBouwer]

Excellent! 👌
Thanks for your consideration!