docs/windows_precompiled_headers.md

   1 # Windows precompiled headers
   2
   3 Using precompiled headers on Windows can speed builds up by around 25%.
   4
   5 Precompiled headers are used by default when GYP generates project files for
   6 Visual Studio 2010.
   7
   8 When using Visual Studio 2008, use of precompiled headers is off by default (see
   9 discussion below). To turn on precompiled headers in your client when using
  10 MSVS 2008, make sure your `~\.gyp\include.gypi` file looks something like this,
  11 then run `gclient runhooks` to update the solution files generated by GYP:
  12
  13     {
  14       'variables': {
  15         'chromium_win_pch': 1,
  16       }
  17     }
  18
  19 Since [r174228](http://src.chromium.org/viewvc/chrome?view=rev&revision=174228),
  20 default is using precompiled header for non `Official` build.
  21
  22 ## Discussion
  23
  24 MSVS 2008 has some limitations in how well it handles precompiled headers.
  25 We've run into two issues:
  26
  27 1.  Using precompiled headers can push our official builders over the edge of
  28     the world, into the dangerous Kingdom of Oom (out of memory).
  29 1.  When compilation flags are changed, instead of doing the right thing and
  30     rebuilding the precompiled headers and their dependents, MSVS prints a
  31     warning instead, saying the precompiled header file was built with
  32     different flags than the current file.
  33
  34 Because of the above, we disabled use of precompiled headers by default, and
  35 required the `chromium_win_pch` flag discussed above to be set.
  36
  37 We may be able to turn use of precompiled headers back on for Debug builds by
  38 default, by adding a workaround to MSVS's limitations to GYP, i.e. if it detects
  39 a change in compile flags it could blow away MSVS's output directory.
  40
  41 ## Troubleshooting
  42
  43 Both of these apply to Visual Studio 2008 only.
  44
  45 ### Precompiled header is missing
  46
  47 **Problem**: You didn't rebuild recently, and you want to build an individual
  48 source file (Ctrl+F7). MSVS complains that the precompiled header is missing.
  49
  50 **Solution**: You could do a full build of the target your source file is in. If
  51 you'd like to avoid that, find the precompiled header generator file, located
  52 within a filter somewhere like `../../build/precompile.cc` in your project,
  53 individually build that file, then individually build the source file you
  54 intended to build. The `precompile.cc` file is the generator for the precompiled
  55 header file.
  56
  57 ### specified for precompiled header but not for current compile
  58
  59 **Problem**: MSVS prints out a warning like this (that we treat as an error):
  60 `warning C4651: '/D_FOOBAR' specified for precompiled header but not for current
  61 compile`
  62
  63 **Solution**: This means compilation flags have changed from when the
  64 precompiled header file was generated. The issue is that MSVS does not handle
  65 this correctly. As compilation flags may affect the precompiled header file, it
  66 should be rebuilt along with its dependents. The workaround for now is to do a
  67 full rebuild, or (if you want to try to be minimal) a rebuild of all projects
  68 previously built that use precompiled headers.