+.TP
+.B DYLD_PRINT_RPATHS
+Cause dyld to print a line each time it expands an @rpath variable and whether
+that expansion was successful or not.
+.TP
+.B DYLD_SHARED_CACHE_DIR
+This is a directory containing dyld shared cache files. This variable can be used in
+conjunction with DYLD_SHARED_REGION=private to run a process with an alternate shared cache.
+.TP
+.SH 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/libSystem.B.dylib).
+But there are times when a full path is not appropriate; for instance, may want your
+binaries to be installable 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/ prefix.
+.TP
+.B @executable_path/
+This variable is replaced with the path to the directory containing 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/Contents/Frameworks/Foo.framework/Versions/A/Foo, then
+the framework load path could be encoded as
+@executable_path/../Frameworks/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.
+.TP
+.B @loader_path/
+This variable is replaced with the path to the directory containing 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 framework/dylib embedded in a plug-in, if the final file
+system location of the plugin-in unknown (so absolute paths cannot be used) or if the plug-in
+is used by multiple applications (so @executable_path cannot be used). If the plug-in mach-o
+file is at /some/path/Myfilter.plugin/Contents/MacOS/Myfilter and a framework dylib
+file is at /some/path/Myfilter.plugin/Contents/Frameworks/Foo.framework/Versions/A/Foo, then
+the framework load path could be encoded as
+@loader_path/../Frameworks/Foo.framework/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.
+.TP
+.B @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 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 directory 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 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.
projects / apple / dyld.git / blobdiff