1.Dd Oct 10, 2008
2.Dt update_dyld_shared_cache 1
3.Os Darwin
4.Sh NAME
5.Nm update_dyld_shared_cache
6.Nd "Updates dyld's shared cache"
7.Sh SYNOPSIS
8.Nm
9.Op Fl root Ar directory 
10.Op Fl overlay Ar directory 
11.Op Fl arch Ar arch 
12.Op Fl force 
13.Op Fl debug
14.Op Fl sort_by_name 
15.Op Fl universal_boot 
16.Op Fl verify
17.Op Fl dylib_list Ar file
18.Op Fl iPhone
19.Op Fl cache_dir Ar dir
20.Sh DESCRIPTION
21.Nm update_dyld_shared_cache
22ensures that dyld's shared cache is up-to-date.  This tool is normally
23only run by Apple's Installer and Software Update, as they are the only
24official ways for OS dylibs to be updated.  But if for some reason you
25used another mechanism to alter an OS dylib, you should manually run
26.Nm update_dyld_shared_cache . 
27.Pp
28Note that the new cache does not take effect until the OS is rebooted.  
29.Pp
30If a safe-boot is
31done (booting with shift key held down) the cache is deleted.  
32.Pp
33The dyld shared cache
34is mapped by dyld into a process at launch time. Later, when loading
35any mach-o image, dyld will first check if is in the share cache, and if
36it is will use that pre-bound version instead of opening, mapping, and binding
37the original file.  This results in significant performance improvements to
38launch time.
39.Pp
40.Nm update_dyld_shared_cache
41scans the directory /var/db/dyld/shared_region_roots for text files containing paths to
42mach-o executables.  The full dependencies of all dylibs required by those executables is
43used to determine which libraries are commonly used and should be placed in the
44shared cache. If one of the text files contains a path to a dylib, that dylib and its
45dependents will be forced into the cache.
46.Pp
47.Nm update_dyld_shared_cache
48builds a separate cache file for each architecture.  The cache files and a readable text
49map of the cached are generated to /var/db/dyld.
50.Pp
51You must be root to run this tool.
52.Pp
53The options are as follows:
54.Bl -tag
55.It Fl root Ar directory
56This option specifies the root of an OS installation for which dyld's
57shared cache should be updated.  This is used by the Installer to update the
58dyld shared cache in a partition other than the one you into which you are currently 
59booted.  The cache files are created in the var/db/dyld directory of the specified directory.
60Note: if you are manually doing this, be sure to run the update_dyld_shared_cache tool
61that is in the partition being updated.  This assures the cache format created will
62match that expected when booting off that partition. 
63.It Fl overlay Ar directory
64This option specifies the root of a sparse directory tree.  When building
65the dyld shared cache, any corresponding mach-o files in the sparse directory 
66will override those in the boot partition.  This is used by Software
67Update to build a dyld shared cache for the update that is about to be
68installed.  The cache files
69are created in the var/db/dyld directory of the specified directory.
70.It Fl arch Ar arch
71By default 
72.Nm update_dyld_shared_cache 
73generates cache files for all architecture that the current machine
74can execute.  You can override this behavior by specifying one or more -arch options and list
75exactly which architectures should have their shared caches updated.
76.It Fl force
77This option will cause 
78.Nm update_dyld_shared_cache
79to regenerated the shared cache files even if they appear to be already up-to-date. 
80.It Fl debug
81This option prints out additional information about the work being done.
82.It Fl sort_by_name
83By default
84.Nm update_dyld_shared_cache
85assigns a random start address to each mach-o image in the cache.
86This option causes the start addresses to be chosen in path order, thus subsequent runs will
87produce the same address layout which can help reproduce some bugs.
88.It Fl universal_boot
89This option can only be used running on an machine with an Intel processor.  It builds caches
90that can be used when booting on both 32-bit and 64-bit machines.
91.It Fl dylib_list Ar file
92Instead of scanning /var/db/dyld/shared_region_roots/, this option provides a file that contains
93a list of the dylibs to use when building the shared cache file.
94.It Fl verify
95Will regenerate a shared cache in-memory that matches the randomization of the existing shared 
96cache file.  Then instead of writing the cache file, it compares the in-memory cache file to
97the on disk version and reports any differences.  
98.It Fl iPhone
99indicates that cache is not for the current Mac OS X, but for rather for an iPhone
100.It Fl cache_dir Ar directory
101This option specifies the directory in which to create the cache file(s).  If not specified,
102the cache file(s) are created in the standard location (e.g. var/db/dyld/) of the root partition.
103.El
104.Sh FILES
105.Tp
106/var/db/dyld/shared_region_roots
107directory of text files with paths to mach-o images used to determine what should be in shared cache.
108.Sh SEE ALSO
109.Xr dyld 1
110