Bug 917988 - Sphinx managed build system documentation; add mach build-docs; r=bsmedberg
authorGregory Szorc <gps@mozilla.com>
Fri, 20 Sep 2013 15:46:43 -0700
changeset 148201 85811665eed7647ab247e1abab263e670c19b02c
parent 148200 392068d519fbd2d1a4aec7c31027d9712b5c1d8e
child 148202 265b3d9cf20191fd47484ad6c998687d0f2405bf
push id25330
push userphilringnalda@gmail.com
push dateSun, 22 Sep 2013 16:14:09 +0000
treeherdermozilla-central@f97307cb4c95 [default view] [failures only]
perfherder[talos] [build metrics] [platform microbench] (compared to previous push)
reviewersbsmedberg
bugs917988
milestone27.0a1
first release with
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
last release without
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
Bug 917988 - Sphinx managed build system documentation; add mach build-docs; r=bsmedberg
build/docs/conf.py
build/docs/glossary.rst
build/docs/index.rst
build/docs/mozbuild/dumbmake.rst
build/docs/mozbuild/frontend.rst
build/docs/mozbuild/index.rst
build/docs/mozconfigs.rst
build/docs/pgo.rst
python/mozbuild/README.rst
python/mozbuild/dumbmake/README.rst
python/mozbuild/mozbuild/frontend/README.rst
python/mozbuild/mozbuild/mach_commands.py
new file mode 100644
--- /dev/null
+++ b/build/docs/conf.py
@@ -0,0 +1,49 @@
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at http://mozilla.org/MPL/2.0/.
+
+from __future__ import unicode_literals
+
+import os
+import re
+
+from datetime import datetime
+
+
+here = os.path.abspath(os.path.dirname(__file__))
+mozilla_dir = os.path.normpath(os.path.join(here, '..', '..'))
+
+import mdn_theme
+
+extensions = [
+    'sphinx.ext.autodoc',
+]
+
+templates_path = ['_templates']
+source_suffix = '.rst'
+master_doc = 'index'
+project = u'Mozilla Build System'
+year = datetime.now().year
+copyright = u'%s, Mozilla Foundation, CC BY-SA 3.0' % year
+
+# Grab the version from the source tree's milestone.
+with open(os.path.join(mozilla_dir, 'config', 'milestone.txt'), 'rt') as fh:
+    for line in fh:
+        line = line.strip()
+
+        if not line or line.startswith('#'):
+            continue
+
+        release = line
+        break
+
+version = re.sub(r'[ab]\d+$', '', release)
+
+exclude_patterns = ['_build']
+pygments_style = 'sphinx'
+
+html_theme_path = [mdn_theme.get_theme_dir()]
+html_theme = 'mdn'
+
+html_static_path = ['_static']
+htmlhelp_basename = 'MozillaBuildSystemdoc'
new file mode 100644
--- /dev/null
+++ b/build/docs/glossary.rst
@@ -0,0 +1,28 @@
+========
+Glossary
+========
+
+.. glossary::
+   :sorted:
+
+   object directory
+       A directory holding the output of the build system. The build
+       system attempts to isolate all file modifications to this
+       directory. By convention, object directories are commonly
+       directories under the source directory prefixed with **obj-**.
+       e.g. **obj-firefox**.
+
+   mozconfig
+       A shell script used to configure the build system.
+
+   configure
+       A generated shell script which detects the current system
+       environment, applies a requested set of build configuration
+       options, and writes out metadata to be consumed by the build
+       system.
+
+   config.status
+       An executable file produced by **configure** that takes the
+       generated build config and writes out files used to build the
+       tree. Traditionally, config.status writes out a bunch of
+       Makefiles.
new file mode 100644
--- /dev/null
+++ b/build/docs/index.rst
@@ -0,0 +1,41 @@
+==================================
+Mozilla Build System Documentation
+==================================
+
+Overview
+========
+
+.. toctree::
+   :maxdepth: 1
+
+   glossary
+
+Important Concepts
+==================
+.. toctree::
+   :maxdepth: 1
+
+   Mozconfig Files <mozconfigs>
+   Profile Guided Optimization <pgo>
+
+mozbuild
+========
+
+mozbuild is a Python package containing a lot of the code for the
+Mozilla build system.
+
+.. toctree::
+   :maxdepth: 1
+
+   mozbuild/index
+   mozbuild/frontend
+   mozbuild/dumbmake
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
+
rename from python/mozbuild/dumbmake/README.rst
rename to build/docs/mozbuild/dumbmake.rst
rename from python/mozbuild/mozbuild/frontend/README.rst
rename to build/docs/mozbuild/frontend.rst
rename from python/mozbuild/README.rst
rename to build/docs/mozbuild/index.rst
new file mode 100644
--- /dev/null
+++ b/build/docs/mozconfigs.rst
@@ -0,0 +1,68 @@
+===============
+mozconfig Files
+===============
+
+mozconfig files are used to configure how a build works.
+
+mozconfig files are actually shell scripts. They are executed in a
+special context with specific variables and functions exposed to them.
+
+API
+===
+
+Functions
+---------
+
+The following special functions are available to a mozconfig script.
+
+ac_add_options
+^^^^^^^^^^^^^^
+
+This function is used to declare extra options/arguments to pass into
+configure.
+
+e.g.::
+
+    ac_add_options --disable-tests
+    ac_add_options --enable-optimize
+
+mk_add_options
+^^^^^^^^^^^^^^
+
+This function is used to inject statements into client.mk for execution.
+It is typically used to define variables, notably the object directory.
+
+e.g.::
+
+    mk_add_options AUTOCLOBBER=1
+
+ac_add_options
+^^^^^^^^^^^^^^
+
+This is a variant of ac_add_options() which only adds configure options
+for a specified application. This is only used when building multiple
+applications through client.mk. This function is typically not needed.
+
+Special mk_add_options Variables
+--------------------------------
+
+For historical reasons, the method for communicating certain
+well-defined variables is via mk_add_options(). In this section, we
+document what those special variables are.
+
+MOZ_OBJDIR
+^^^^^^^^^^
+
+This variable is used to define the :term:`object directory` for the current
+build.
+
+Finding the active mozconfig
+============================
+
+Multiple mozconfig files can exist to provide different configuration
+options for different tasks. The rules for finding the active mozconfig
+are defined in the
+:py:func:`mozbuild.mozconfig.MozconfigLoader.find_mozconfig` method:
+
+.. autoclass:: mozbuild.mozconfig.MozconfigLoader
+   :members: find_mozconfig
new file mode 100644
--- /dev/null
+++ b/build/docs/pgo.rst
@@ -0,0 +1,40 @@
+.. _pgo:
+
+===========================
+Profile Guided Optimization
+===========================
+
+:abbr:`PGO (Profile Guided Optimization)` is the process of adding
+probes to a compiled binary, running said binary, then using the
+run-time information to *recompile* the binary to (hopefully) make it
+faster.
+
+How PGO Builds Work
+===================
+
+The supported interface for invoking a PGO build is to evaluate the
+*build* target of client.mk with *MOZ_PGO* defined. e.g.::
+
+    $ make -f client.mk MOZ_PGO=1
+
+This is equivalent to::
+
+    $ make -f client.mk profiledbuild
+
+Which is roughly equivalent to:
+
+#. Perform a build with *MOZ_PROFILE_GENERATE=1* and *MOZ_PGO_INSTRUMENTED=1*
+#. Package with *MOZ_PGO_INSTRUMENTED=1*
+#. Performing a run of the instrumented binaries
+#. $ make maybe_clobber_profiledbuild
+#. Perform a build with *MOZ_PROFILE_USE=1*
+
+Differences between toolchains
+==============================
+
+There are some implementation differences depending on the compiler
+toolchain being used.
+
+The *maybe_clobber_profiledbuild* step gets its name because of a
+difference. On Windows, this step merely moves some *.pgc* files around.
+Using GCC or Clang, it is equivalent to a *make clean*.
--- a/python/mozbuild/mozbuild/mach_commands.py
+++ b/python/mozbuild/mozbuild/mach_commands.py
@@ -908,8 +908,42 @@ class MachDebug(object):
             if verbose:
                 print('config substitutions:')
                 for k in sorted(config.substs):
                     print('\t%s: %s' % (k, config.substs[k]))
 
                 print('config defines:')
                 for k in sorted(config.defines):
                     print('\t%s' % k)
+
+
+@CommandProvider
+class Documentation(MachCommandBase):
+    """Helps manage in-tree documentation."""
+
+    @Command('build-docs', category='build-dev',
+        description='Generate documentation for the tree.')
+    @CommandArgument('--format', default='html',
+        help='Documentation format to write.')
+    @CommandArgument('outdir', default='<DEFAULT>', nargs='?',
+        help='Where to write output.')
+    def build_docs(self, format=None, outdir=None):
+        self._activate_virtualenv()
+
+        self.virtualenv_manager.install_pip_package('mdn-sphinx-theme==0.3')
+
+        import sphinx
+
+        if outdir == '<DEFAULT>':
+            outdir = os.path.join(self.topobjdir, 'docs', format)
+
+        args = [
+            sys.argv[0],
+            '-b', format,
+            os.path.join(self.topsrcdir, 'build', 'docs'),
+            outdir,
+        ]
+
+        result = sphinx.main(args)
+
+        print('Docs written to %s.' % outdir)
+
+        return result