test-manifest-toml.rst

Test Manifest TOML

==================

This linter verifies syntax for ManifestParser TOML files.

Run Locally

-----------

This Test Manifest linter can be run using mach:

.. parsed-literal::

    $ ./mach lint --linter test-manifest-toml <file paths>

Configuration

-------------

The configuration excludes all non-ManifestParser TOML files (as well as

generated TOML manifests).

Conditional Expressions

-----------------------

In order to make conditional expressions (e.g. **skip-if**, **run-if**)

consistent and machine readable it is important that the

variable comparisons come before flags and are in a specific

order (ranking). Not all comparisons are required, but when

they appear they should be in ranked order.

What to put in **run-if**: should specify platform(s) where this test *should* run. This can be very general, e.g. ``os == 'linux'``.

What to put in **skip-if**: platforms where the test currently does not run and has a bug to resolve the issue (with as much detail on the buggy conditions as possible).

Expression ranks:

1. **os** == 'android' (or 'linux', 'mac', 'win')

2. **os_version** == '14' (see below: Platforms that are currently supported in CI)

3. **arch** == 'aarch64' (or 'x86', 'x86_64', deprecated 'armeabi-v7a')

4. **display** == 'wayland' (or 'x11' -- on linux only)

5. **buildapp** == 'browser'

6. **appname** == 'firefox' (or 'seamonkey', 'thunderbird')

7. **build_type** FLAG, one of: asan, ccov, debug, tsan, opt

8. **variant** FLAG

   * a11y_checks

   * condprof

   * e10s

   * emewmf

   * fission

   * headless

   * http2

   * http3

   * inc_origin_init

   * mda_gpu

   * msix

   * nogpu

   * remote_async

   * snapshot

   * socketprocess_e10s

   * socketprocess_networking

   * swgl

   * trainhop

   * vertical_tab

   * wmfme

   * xorigin

9. **other** FLAG

   * artifact

   * crashreporter

   * datareporting

   * devedition

   * early_beta_or_earlier

   * false (*deprecated*)

   * gecko_profiler

   * isolated_process

   * is_emulator

   * is_ubuntu (*deprecated*)

   * msix

   * nightly_build

   * release_or_beta

   * require_signing

   * sessionHistoryInParent

   * sync

   * true

   * updater

   * verify

   * verify_standalone

Notes

-----

Certain build types have special significance:

* ``opt`` implies => ``!asan && !ccov && !debug && !tsan``

* Instead of ``!debug`` use separate conditions for ``asan``, ``ccov`` (rarely used), ``opt``, and ``tsan``

Errors Detected

---------------

* Invalid TOML

* Disabling a path by commenting out the section

* Conditional contains explicit ||

* Conditional is NOT an array

* Missing include file

* Invalid combinations of platform and build-types (not present in CI)

   * ``"os == 'linux' && os_version == '22.04' && asan"``

   * ``"os == 'linux' && os_version == '22.04' && tsan"``

   * ``"os == 'win' && tsan``

* Non canonically formed conditions

   * superfluous expression parenthesis

   * unknown variables, flags or values

   * variables and flags out of canonical order

Warnings Detected (fixable)

---------------------------

* Missing DEFAULT section

* Sections not in alphabetical order

* Section name not double quoted

Non idiomatic manifest warnings (fixable)

-----------------------------------------

* Using ``processor`` instead of ``arch``

* Using ``bits`` instead of ``arch``

* Using ``android_version`` instead of ``os_version``

* Using platform combination variables: ``apple_catalina``, ``apple_silicon``, ``win10_2009``, ``win11_2009`` (unused)

* Platforms no longer used by CI: ``Linux 18.04`` (not enforced -- will be deprecated soon), ``MacOS 11.20``, ``Windows 11.2009``

* Not specifying display on Linux

* Specifying display ``x11`` on Linux 22.04 where only ``wayland`` is supported

* Specifying display ``wayland`` on Linux 24.04 where only ``x11`` is supported

* Using ``!debug`` instead of ``asan``, ``opt``, or ``tsan``

* Using literal boolean values for single variables like ``debug == false``

Platforms that are currently supported in CI

--------------------------------------------

* ``os`` one of ``android``, ``linux``, ``mac``, ``win``

* ``os_version`` depends on os

   * ``os == 'android'``

      * ``os_version == '14'`` arch: aarch64, x86_64

   * ``os == 'linux'``

      * ``os_version == '22.04'`` arch: aarch64, x86_64

      * ``os_version == '24.04'`` arch: aarch64, x86_64

   * ``os == 'mac'``

      * ``os_version == '10.15'`` arch: x86_64

      * ``os_version == '14.70'`` arch: x86_64

      * ``os_version == '15.30'`` arch: aarch64

   * ``os == 'win'``

      * ``os_version == '10.2009'`` arch: x86_64

      * ``os_version == '10.26100'`` arch: aarch64, x86, x86_64

* ``display`` required for linux

   * ``os == 'linux'``

      * ``os_version == '22.04'`` display: wayland

      * ``os_version == '24.04'`` display: x11

Sources

-------

* `Configuration (YAML) <https://searchfox.org/mozilla-central/source/tools/lint/test-manifest-toml.yml>`_

* `Source <https://searchfox.org/mozilla-central/source/tools/lint/test-manifest-toml/__init__.py>`_

Developer Information

---------------------

* The linter relies on code in: ``testing/mozbase/manifestparser/manifestparser/``

   * In particular the "legal" values for variables are defined in: ``token.py``

* The linter self-test can be run with: ``./mach python-test --subsuite mozlint tools/lint/test/test_manifest_toml.py``

Source code

Revision control

Copy as Markdown

Other Tools