NO BUG - Document mozinfo attributes, test manifest naming convention

DONTBUILD (NPOTB)

build/docs/glossary.rst

@@ -42,3 +42,7 @@ Glossary
       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`.

build/docs/index.rst

@@ -24,6 +24,7 @@ Important Concepts
    build-targets
    python
    test_manifests
+   mozinfo
 
 mozbuild
 ========

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.
+

build/docs/test_manifests.rst

@@ -10,6 +10,27 @@ Many test suites have their test metadata defined in files called
 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
@@ -126,8 +147,14 @@ 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::