1:mod:`macholib.dyld` --- Dyld emulation
2=======================================
3
4.. module:: macholib.dyld
5   :synopsis: Emulation of functonality of the dynamic linker
6
7This module defines a number of functions that can be used
8to emulate the functionality of the dynamic linker (``dyld``)
9w.r.t. looking for library files and framworks.
10
11.. function:: dyld_image_suffix([env])
12
13   Looks up the suffix to append to shared library and
14   framework names and returns this value when found.
15   Returns ``None`` when no suffix should be appended.
16
17   The *env* argument is a dictionary, which defaults
18   to :data:`os.environ`.
19
20   See the description of ``DYLD_IMAGE_SUFFIX`` in the
21   manual page for dyld(1) for more information.
22
23.. function:: dydl_framework_path([env])
24
25   Returns a user-specified framework search path,
26   or an empty list when only the default search path
27   should be used.
28
29   The *env* argument is a dictionary, which defaults
30   to :data:`os.environ`.
31
32   See the description of ``DYLD_FRAMEWORK_PATH`` in the
33   manual page for dyld(1) for more information.
34
35.. function:: dyld_library_path([env])
36
37   Returns a user-specified library search path,
38   or an empty list when only the default search path
39   should be used.
40
41   The *env* argument is a dictionary, which defaults
42   to :data:`os.environ`.
43
44   See the description of ``DYLD_LIBRARY_PATH`` in the
45   manual page for dyld(1) for more information.
46
47.. function:: dyld_fallback_framework_path([env])
48
49   Return a user specified list of of directories where
50   to look for frameworks that aren't in their install path,
51   or an empty list when the default fallback path should
52   be  used.
53
54   The *env* argument is a dictionary, which defaults
55   to :data:`os.environ`.
56
57   See the description of ``DYLD_FALLBACK_FRAMEWORK_PATH`` in the
58   manual page for dyld(1) for more information.
59
60.. function:: dyld_fallback_library_path([env])
61
62   Return a user specified list of of directories where
63   to look for libraries that aren't in their install path,
64   or an empty list when the default fallback path should
65   be  used.
66
67   The *env* argument is a dictionary, which defaults
68   to :data:`os.environ`.
69
70   See the description of ``DYLD_FALLBACK_LIBRARY_PATH`` in the
71   manual page for dyld(1) for more information.
72
73.. function:: dyld_image_suffix_search(iterator[, env])
74
75   Yields all items in *iterator*, and prepents names
76   with the image suffix to those items when the suffix
77   is specified.
78
79   The *env* argument is a dictionary, which defaults
80   to :data:`os.environ`.
81
82.. function:: dyld_override_search(name[, env])
83
84   If *name* is a framework name yield filesystem
85   paths relative to the entries in the framework
86   search path.
87
88   Always yield the filesystem paths relative to the
89   entries in the library search path.
90
91   The *env* argument is a dictionary, which defaults
92   to :data:`os.environ`.
93
94.. function:: dyld_executable_path_search(name, executable_path)
95
96   If *name* is a path starting with ``@executable_path/`` yield
97   the path relative to the specified *executable_path*.
98
99   If *executable_path* is None nothing is yielded.
100
101.. function:: dyld_loader_search(name, loader_path)
102
103   If *name* is a path starting with ``@loader_path/`` yield
104   the path relative to the specified *loader_path*.
105
106   If *loader_path* is None nothing is yielded.
107
108   .. versionadded: 1.6
109
110.. function:: dyld_default_search(name[, env])
111
112   Yield the filesystem locations to look for a dynamic
113   library or framework using the default locations
114   used by the system dynamic linker.
115
116   This function will look in ``~/Library/Frameworks``
117   for frameworks, even though the system dynamic linker
118   doesn't.
119
120   The *env* argument is a dictionary, which defaults
121   to :data:`os.environ`.
122
123.. function:: dyld_find(name[, executable_path[, env [, loader_path]]])
124
125   Returns the path of the requested dynamic library,
126   raises :exc:`ValueError` when the library cannot be found.
127
128   This function searches for the library in the same
129   locations and de system dynamic linker.
130
131   The *executable_path* should be the filesystem path
132   of the executable to which the library is linked (either
133   directly or indirectly).
134
135   The *env* argument is a dictionary, which defaults
136   to :data:`os.environ`.
137
138   The *loader_path* argument is an optional filesystem path for
139   the object file (binary of shared library) that references
140   *name*.
141
142   .. versionchanged:: 1.6
143
144      Added the *loader_path* argument.
145
146.. function:: framework_find(fn[, executable_path[, env]])
147
148   Find a framework using the same semantics as the
149   system dynamic linker, but will accept looser names
150   than the system linker.
151
152   This function will return a correct result for input
153   values like:
154
155   * Python
156
157   * Python.framework
158
159   * Python.framework/Versions/Current
160