doc: examples of run_project_tests.py options

1 files changed, 42 insertions, 33 deletions

diff --git a/docs/markdown/Contributing.md b/docs/markdown/Contributing.md
index 95324d6..f545b77 100644
--- a/docs/markdown/Contributing.md
+++ b/docs/markdown/Contributing.md
@@ -33,15 +33,15 @@ remove them.
 
 Every new feature requires some extra steps, namely:
 
- - Must include a project test under `test cases/`, or if that's not
-   possible or if the test requires a special environment, it must go
-   into `run_unittests.py`.
- - Must be registered with the [FeatureChecks framework](Release-notes-for-0.47.0.md#feature-detection-based-on-meson_version-in-project)
-   that will warn the user if they try to use a new feature while
-   targeting an older meson version.
- - Needs a release note snippet inside `docs/markdown/snippets/` with
-   a heading and a brief paragraph explaining what the feature does
-   with an example.
+- Must include a project test under `test cases/`, or if that's not
+  possible or if the test requires a special environment, it must go
+  into `run_unittests.py`.
+- Must be registered with the [FeatureChecks framework](Release-notes-for-0.47.0.md#feature-detection-based-on-meson_version-in-project)
+  that will warn the user if they try to use a new feature while
+  targeting an older meson version.
+- Needs a release note snippet inside `docs/markdown/snippets/` with
+  a heading and a brief paragraph explaining what the feature does
+  with an example.
 
 ## Acceptance and merging
 
@@ -68,19 +68,19 @@ require the approval of the project lead.
 
 In a simplified list form the split would look like the following:
 
- - members with commit access can do:
-   - documentation changes (directly to master if warranted)
-   - bug fixes that don't change functionality
-   - refactorings
-   - new dependency types
-   - new tool support (e.g. a new Doxygen-kind of tool)
-   - support for new compilers to existing languages
- - project leader decision is needed for:
-   - new modules
-   - new functions in the Meson language
-   - syntax changes for Meson files
-   - changes breaking backwards compatibility
-   - support for new languages
+- members with commit access can do:
+  - documentation changes (directly to master if warranted)
+  - bug fixes that don't change functionality
+  - refactorings
+  - new dependency types
+  - new tool support (e.g. a new Doxygen-kind of tool)
+  - support for new compilers to existing languages
+- project leader decision is needed for:
+  - new modules
+  - new functions in the Meson language
+  - syntax changes for Meson files
+  - changes breaking backwards compatibility
+  - support for new languages
 
 ## Strategy for merging pull requests to trunk
 
@@ -97,14 +97,14 @@ often requires some judgement on part of the person doing the
 merge. Github provides three different merge options, The rules of
 thumb for choosing between them goes like this:
 
- - single commit pull requests should always be rebased
+- single commit pull requests should always be rebased
 
- - a pull request with one commit and one "fixup" commit (such as
-   testing something to see if it passes CI) should be squashed
+- a pull request with one commit and one "fixup" commit (such as
+  testing something to see if it passes CI) should be squashed
 
- - large branches with many commits should be merged with a merge
-   commit, especially if one of the commits does not pass all tests
-   (which happens in e.g. large and difficult refactorings)
+- large branches with many commits should be merged with a merge
+  commit, especially if one of the commits does not pass all tests
+  (which happens in e.g. large and difficult refactorings)
 
 If in doubt, ask for guidance on IRC.
 
@@ -127,6 +127,17 @@ project tests. To run all tests, execute `./run_tests.py`. Unit tests
 can be run with `./run_unittests.py` and project tests with
 `./run_project_tests.py`.
 
+Subsets of project tests can be selected with
+`./run_project_tests.py --only` option. This can save a great deal of
+time when only a certain part of Meson is being tested.
+For example, a useful and easy contribution to Meson is making
+sure the full set of compilers is supported. One could for example test
+various Fortran compilers by setting `FC=ifort` or `FC=flang` or similar
+with `./run_project_test.py --only fortran`.
+Some families of tests require a particular backend to run.
+For example, all the CUDA project tests run and pass on Windows via
+`./run_project_tests.py --only cuda --backend ninja`
+
 Each project test is a standalone project that can be compiled on its
 own. They are all in `test cases` subdirectory. The simplest way to
 run a single project test is to do something like `./meson.py test\
@@ -168,7 +179,7 @@ Continuous integration systems currently used:
 
 To promote consistent naming policy, use:
 
-   - `[skip ci]` in the commit title if you want to disable all integration tests
+- `[skip ci]` in the commit title if you want to disable all integration tests
 
 ## Documentation
 
@@ -225,8 +236,6 @@ those are simple.
 - indent 4 spaces, no tabs ever
 - brace always on the same line as if/for/else/function definition
 
-
-
 ## External dependencies
 
 The goal of Meson is to be as easily usable as possible. The user
@@ -257,8 +266,8 @@ languages. It has inputs, which include `meson.build` files, values of
 options, compilers and so on. These are passed to a function, which
 generates output build definition. This function is pure, which means that:
 
- - for any given input the output is always the same
- - running Meson twice in a row _always_ produce the same output in both runs
+- for any given input the output is always the same
+- running Meson twice in a row _always_ produce the same output in both runs
 
 The latter one is important, because it enforces that there is no way
 for "secret state" to pass between consecutive invocations of