1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/build/docs/mozconfigs.rst Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,70 @@
1.4 +.. _mozconfig:
1.5 +
1.6 +===============
1.7 +mozconfig Files
1.8 +===============
1.9 +
1.10 +mozconfig files are used to configure how a build works.
1.11 +
1.12 +mozconfig files are actually shell scripts. They are executed in a
1.13 +special context with specific variables and functions exposed to them.
1.14 +
1.15 +API
1.16 +===
1.17 +
1.18 +Functions
1.19 +---------
1.20 +
1.21 +The following special functions are available to a mozconfig script.
1.22 +
1.23 +ac_add_options
1.24 +^^^^^^^^^^^^^^
1.25 +
1.26 +This function is used to declare extra options/arguments to pass into
1.27 +configure.
1.28 +
1.29 +e.g.::
1.30 +
1.31 + ac_add_options --disable-tests
1.32 + ac_add_options --enable-optimize
1.33 +
1.34 +mk_add_options
1.35 +^^^^^^^^^^^^^^
1.36 +
1.37 +This function is used to inject statements into client.mk for execution.
1.38 +It is typically used to define variables, notably the object directory.
1.39 +
1.40 +e.g.::
1.41 +
1.42 + mk_add_options AUTOCLOBBER=1
1.43 +
1.44 +ac_add_options
1.45 +^^^^^^^^^^^^^^
1.46 +
1.47 +This is a variant of ac_add_options() which only adds configure options
1.48 +for a specified application. This is only used when building multiple
1.49 +applications through client.mk. This function is typically not needed.
1.50 +
1.51 +Special mk_add_options Variables
1.52 +--------------------------------
1.53 +
1.54 +For historical reasons, the method for communicating certain
1.55 +well-defined variables is via mk_add_options(). In this section, we
1.56 +document what those special variables are.
1.57 +
1.58 +MOZ_OBJDIR
1.59 +^^^^^^^^^^
1.60 +
1.61 +This variable is used to define the :term:`object directory` for the current
1.62 +build.
1.63 +
1.64 +Finding the active mozconfig
1.65 +============================
1.66 +
1.67 +Multiple mozconfig files can exist to provide different configuration
1.68 +options for different tasks. The rules for finding the active mozconfig
1.69 +are defined in the
1.70 +:py:func:`mozbuild.mozconfig.MozconfigLoader.find_mozconfig` method:
1.71 +
1.72 +.. autoclass:: mozbuild.mozconfig.MozconfigLoader
1.73 + :members: find_mozconfig
