1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/build/docs/pgo.rst Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,40 @@
1.4 +.. _pgo:
1.5 +
1.6 +===========================
1.7 +Profile Guided Optimization
1.8 +===========================
1.9 +
1.10 +:abbr:`PGO (Profile Guided Optimization)` is the process of adding
1.11 +probes to a compiled binary, running said binary, then using the
1.12 +run-time information to *recompile* the binary to (hopefully) make it
1.13 +faster.
1.14 +
1.15 +How PGO Builds Work
1.16 +===================
1.17 +
1.18 +The supported interface for invoking a PGO build is to evaluate the
1.19 +*build* target of client.mk with *MOZ_PGO* defined. e.g.::
1.20 +
1.21 + $ make -f client.mk MOZ_PGO=1
1.22 +
1.23 +This is equivalent to::
1.24 +
1.25 + $ make -f client.mk profiledbuild
1.26 +
1.27 +Which is roughly equivalent to:
1.28 +
1.29 +#. Perform a build with *MOZ_PROFILE_GENERATE=1* and *MOZ_PGO_INSTRUMENTED=1*
1.30 +#. Package with *MOZ_PGO_INSTRUMENTED=1*
1.31 +#. Performing a run of the instrumented binaries
1.32 +#. $ make maybe_clobber_profiledbuild
1.33 +#. Perform a build with *MOZ_PROFILE_USE=1*
1.34 +
1.35 +Differences between toolchains
1.36 +==============================
1.37 +
1.38 +There are some implementation differences depending on the compiler
1.39 +toolchain being used.
1.40 +
1.41 +The *maybe_clobber_profiledbuild* step gets its name because of a
1.42 +difference. On Windows, this step merely moves some *.pgc* files around.
1.43 +Using GCC or Clang, it is equivalent to a *make clean*.
