NO BUG - Document mozinfo attributes, test manifest naming convention
authorGregory Szorc <gps@mozilla.com>
Tue, 01 Oct 2013 09:28:39 +0200
changeset 163157 0d9f5e4bd5b8789fe2f516972844d76c520c8077
parent 163156 d71579c316c17b0ca7aa1130075dc9d70d3ff5b3
child 163169 a55240c523be90da13c0ec2134a5731f05afdbd4
push id3066
push userakeybl@mozilla.com
push dateMon, 09 Dec 2013 19:58:46 +0000
treeherdermozilla-beta@a31a0dce83aa [default view] [failures only]
perfherder[talos] [build metrics] [platform microbench] (compared to previous push)
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
NO BUG - Document mozinfo attributes, test manifest naming convention DONTBUILD (NPOTB)
build/docs/glossary.rst
build/docs/index.rst
build/docs/mozinfo.rst
build/docs/test_manifests.rst
--- a/build/docs/glossary.rst
+++ b/build/docs/glossary.rst
@@ -37,8 +37,12 @@ Glossary
    clobber build
       A build performed with an initially empty object directory. All
       build actions must be performed.
 
    incremental build
       A build performed with the result of a previous build in an
       object directory. The build should not have to work as hard because
       it will be able to reuse the work from previous builds.
+
+   mozinfo
+      An API for accessing a common and limited subset of the build and
+      run-time configuration. See :ref:`mozinfo`.
--- a/build/docs/index.rst
+++ b/build/docs/index.rst
@@ -19,16 +19,17 @@ Important Concepts
    Mozconfig Files <mozconfigs>
    mozbuild-files
    Profile Guided Optimization <pgo>
    slow
    environment-variables
    build-targets
    python
    test_manifests
+   mozinfo
 
 mozbuild
 ========
 
 mozbuild is a Python package containing a lot of the code for the
 Mozilla build system.
 
 .. toctree::
new file mode 100644
--- /dev/null
+++ b/build/docs/mozinfo.rst
@@ -0,0 +1,122 @@
+.. _mozinfo:
+
+=======
+mozinfo
+=======
+
+``mozinfo`` is a solution for representing a subset of build
+configuration and run-time data.
+
+``mozinfo`` data is typically accessed through a ``mozinfo.json`` file
+which is written to the :term:`object directory` during build
+configuration. The code for writing this file lives in
+:py:mod:`mozbuild.mozinfo`.
+
+``mozinfo.json`` is an object/dictionary of simple string values.
+
+The attributes in ``mozinfo.json`` are used for many purposes. One use
+is to filter tests for applicability to the current build. For more on
+this, see :ref:`test_manifests`.
+
+.. _mozinfo_attributes:
+
+mozinfo.json Attributes
+=================================
+
+``mozinfo`` currently records the following attributes.
+
+appname
+   The application being built.
+
+   Value comes from ``MOZ_APP_NAME`` from ``config.status``.
+
+   Optional.
+
+asan
+   Whether address sanitization is enabled.
+
+   Values are ``true`` and ``false``.
+
+   Always defined.
+
+bin_suffix
+   The file suffix for binaries produced with this build.
+
+   Values may be an empty string, as not all platforms have a binary
+   suffix.
+
+   Always defined.
+
+bits
+   The number of bits in the CPU this build targets.
+
+   Values are typically ``32`` or ``64``.
+
+   Universal Mac builds do not have this key defined.
+
+   Unkown processor architectures (see ``processor`` below) may not have
+   this key defined.
+
+   Optional.
+
+crashreporter
+   Whether the crash reporter is enabled for this build.
+
+   Values are ``true`` and ``false``.
+
+   Always defined.
+
+debug
+   Whether this is a debug build.
+
+   Values are ``true`` and ``false``.
+
+   Always defined.
+
+mozconfig
+   The path of the :ref:`mozconfig file <mozconfig>` used to produce this build.
+
+   Optional.
+
+os
+   The operating system the build is produced for. Values for tier-1
+   supported platforms are ``linux``, ``win``, ``mac``, ``b2g``, and
+   ``android``. For other platforms, the value is the lowercase version
+   of the ``OS_TARGET`` variable from ``config.status``.
+
+   Always defined.
+
+processor
+   Information about the processor architecture this build targets.
+
+   Values come from ``TARGET_CPU``, however some massaging may be
+   performed.
+
+   If the build is a universal build on Mac (it targets both 32-bit and
+   64-bit), the value is ``universal-x86-x86_64``.
+
+   If the value starts with ``arm``, the value is ``arm``.
+
+   If the value starts with a string of the form ``i[3-9]86]``, the
+   value is ``x86``.
+
+   Always defined.
+
+tests_enabled
+   Whether tests are enabled for this build.
+
+   Values are ``true`` and ``false``.
+
+   Always defined.
+
+toolkit
+   The widget toolkit in case. The value comes from the
+   ``MOZ_WIDGET_TOOLKIT`` ``config.status`` variable.
+
+   Always defined.
+
+topsrcdir
+   The path to the source directory the build came from.
+
+   Always defined.
+
--- a/build/docs/test_manifests.rst
+++ b/build/docs/test_manifests.rst
@@ -5,16 +5,37 @@ Test Manifests
 ==============
 
 Many test suites have their test metadata defined in files called
 **test manifests**.
 
 Test manifests are divided into two flavors: :ref:`manifest_destiny_manifests`
 and :ref:`reftest_manifests`.
 
+Naming Convention
+=================
+
+The build system does not enforce file naming for test manifest files.
+However, the following convention is used.
+
+mochitest.ini
+   For the *plain* flavor of mochitests.
+
+chrome.ini
+   For the *chrome* flavor of mochitests.
+
+browser.ini
+   For the *browser chrome* flavor of mochitests.
+
+a11y.ini
+   For the *a11y* flavor of mochitests.
+
+xpcshell.ini
+   For *xpcshell* tests.
+
 .. _manifest_destiny_manifests:
 
 Manifest Destiny Manifests
 ==========================
 
 Manifest destiny manifests are essentially ini files that conform to a basic
 set of assumptions.
 
@@ -121,18 +142,24 @@ run-sequentially
 
 Manifest Filter Language
 ------------------------
 
 Some manifest keys accept a special filter syntax as their values. These
 values are essentially boolean expressions that are evaluated at test
 execution time.
 
+The expressions can reference a well-defined set of variables, such as
+``os`` and ``debug``. These variables are populated from the
+``mozinfo.json`` file. For the full list of available variables, see
+the :ref:`mozinfo documentation <mozinfo_attributes>`.
+
 See
-`the source <https://hg.mozilla.org/mozilla-central/file/default/testing/mozbase/manifestdestiny/manifestparser/manifestparser.py>`_.
+`the source <https://hg.mozilla.org/mozilla-central/file/default/testing/mozbase/manifestdestiny/manifestparser/manifestparser.py>`_ for the full documentation of the
+expression syntax until it is documented here.
 
 .. todo::
 
    Document manifest filter language.
 
 .. _manifest_file_installation:
 
 File Installation