docs/windows_split_dll.md

   1 # Windows Split DLLs
   2
   3 A build mode where chrome.dll is split into two separate DLLs. This was
   4 undertaken as one possible workaround for toolchain limitations on Windows.
   5
   6 ## How
   7
   8 Normally, you probably don't need to worry about doing this build. If for some
   9 reason you need to build it locally:
  10
  11 1.  From a _Visual Studio Command Prompt_ running as **Administrator** run
  12     `python tools\win\split_link\install_split_link.py`.
  13 1.  Set `GYP_DEFINES=chrome_split_dll=1`. In particular, don't have
  14     `component=shared_library`. Other things, like `buildtype` or `fastbuild`
  15     are fine.
  16 1.  `gclient runhooks`
  17 1.  `ninja -C out\Release chrome`
  18
  19 `chrome_split_dll` currently applies only to chrome.dll (and not test binaries).
  20
  21 ## What
  22
  23 This is intended to be a temporary measure until either the toolchain is
  24 improved or the code can be physically separated into two DLLs (based on a
  25 browser/child split).
  26
  27 The link replacement forcibly splits chrome.dll into two halves based on a
  28 description in `build\split_link_partition.py`. Code is primarily split along
  29 browser/renderer lines. Roughly, Blink and its direct dependencies are in the
  30 "chrome1.dll", and the rest of the browser code remains in "chrome.dll".
  31
  32 TODO: build\split_link_partition.py doesn't exist.
  33
  34 Splitting the code this way allows keeping maximum optimization on the Blink
  35 portion of the code, which is important for performance.
  36
  37 There is a compile time define set when building in this mode
  38 `CHROME_SPLIT_DLL`, however it should be used very sparingly-to-not-at-all.
  39
  40 ## Details
  41
  42 This forcible split is implemented by putting .lib files in either one DLL or
  43 the other, and causing unresolved externals that result during linking to be
  44 forcibly exported from the other DLL. This works relatively cleanly for function
  45 import/export, however it cannot work for data export.
  46
  47 There are relatively few instances where data exports are required across the
  48 DLL boundary. The waterfall builder
  49 http://build.chromium.org/p/chromium/waterfall?show=Win%20Split will detect when
  50 new data exports are added, and these will need to be repaired. For constants,
  51 the data can be duplicated to both DLLs, but for writeable data, a wrapping
  52 set/get function will need to be added.
  53
  54 http://build.chromium.org/p/chromium/waterfall?show=Win%20Split does not exist.
  55
  56 Some more details can be found on the initial commit of the split_link script
  57 http://src.chromium.org/viewvc/chrome?revision=200049&view=revision and the
  58 associated bugs: http://crbug.com/237249 http://crbug.com/237267.