doc/man/man1/update_dyld_shared_cache.1

   1 .Dd June 23, 2016
   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 universal_boot
  15 .Op Fl verify
  16 .Sh DESCRIPTION
  17 .Nm update_dyld_shared_cache
  18 ensures that dyld's shared cache is up-to-date.  This tool is normally
  19 only run by Apple's Installer and Software Update, as they are the only
  20 official ways for OS dylibs to be updated.  But if for some reason you
  21 used another mechanism to alter an OS dylib, you should manually run
  22 .Nm update_dyld_shared_cache .
  23 .Pp
  24 Note that the new cache does not take effect until the OS is rebooted.
  25 .Pp
  26 If a safe-boot is
  27 done (booting with shift key held down) the cache is deleted.
  28 .Pp
  29 The dyld shared cache
  30 is mapped by dyld into a process at launch time. Later, when loading
  31 any mach-o image, dyld will first check if is in the share cache, and if
  32 it is will use that pre-bound version instead of opening, mapping, and binding
  33 the original file.  This results in significant performance improvements to
  34 launch time.
  35 .Pp
  36 .Nm update_dyld_shared_cache
  37 scans the directory /var/db/dyld/shared_region_roots for text files containing paths to
  38 mach-o executables.  The full dependencies of all dylibs required by those executables is
  39 used to determine which libraries are commonly used and should be placed in the
  40 shared cache. If one of the text files contains a path to a dylib, that dylib and its
  41 dependents will be forced into the cache.
  42 .Pp
  43 .Nm update_dyld_shared_cache
  44 builds a separate cache file for each architecture.  The cache files and a readable text
  45 map of the cached are generated to /var/db/dyld.
  46 .Pp
  47 You must be root to run this tool.
  48 .Pp
  49 The options are as follows:
  50 .Bl -tag
  51 .It Fl root Ar directory
  52 This option specifies the root of an OS installation for which dyld's
  53 shared cache should be updated.  This is used by the Installer to update the
  54 dyld shared cache in a partition other than the one you into which you are currently
  55 booted.  The cache files are created in the var/db/dyld directory of the specified directory.
  56 Note: if you are manually doing this, be sure to run the update_dyld_shared_cache tool
  57 that is in the partition being updated.  This assures the cache format created will
  58 match that expected when booting off that partition.
  59 .It Fl overlay Ar directory
  60 This option specifies the root of a sparse directory tree.  When building
  61 the dyld shared cache, any corresponding mach-o files in the sparse directory
  62 will override those in the boot partition.  This is used by Software
  63 Update to build a dyld shared cache for the update that is about to be
  64 installed.  The cache files
  65 are created in the var/db/dyld directory of the specified directory.
  66 .It Fl arch Ar arch
  67 By default
  68 .Nm update_dyld_shared_cache
  69 generates cache files for all architecture that the current machine
  70 can execute.  You can override this behavior by specifying one or more -arch options and list
  71 exactly which architectures should have their shared caches updated.
  72 .It Fl force
  73 This option will cause
  74 .Nm update_dyld_shared_cache
  75 to regenerated the shared cache files even if they appear to be already up-to-date.
  76 .It Fl debug
  77 This option prints out additional information about the work being done.
  78 .It Fl universal_boot
  79 This option builds caches for all machines.
  80 .It Fl verify
  81 Will regenerate a shared cache in-memory that matches the randomization of the existing shared
  82 cache file.  Then instead of writing the cache file, it compares the in-memory cache file to
  83 the on disk version and reports any differences.
  84 .El
  85 .Sh FILES
  86 .Tp
  87 /var/db/dyld/shared_region_roots
  88 directory of text files with paths to mach-o images used to determine what should be in shared cache.
  89 .Sh SEE ALSO
  90 .Xr dyld 1