Chiebot-Mirror
/
meson
mirror of https://github.com/mesonbuild/meson.git
8
0
Fork 0
Code Issues Projects Releases Wiki Activity

Made Commands.md dynamically generated (#7346)

Browse Source
pull/7405/head
TheQwertiest 5 years ago committed by GitHub
parent 83a973ca04
commit b6981bd16e
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
6 changed files with 548 additions and 748 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Split View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 658
      docs/markdown/Commands.md
  2. 296
      docs/markdown_dynamic/Commands.md
  3. 32
      docs/meson.build
  4. 105
      run_unittests.py
  5. 55
      tools/copy_files.py
  6. 150
      tools/regenerate_docs.py

658
docs/markdown/Commands.md
Unescape View File

@ -1,658 +0,0 @@
# Command-line commands
There are two different ways of invoking Meson. First, you can run it directly
from the source tree with the command `/path/to/source/meson.py`. Meson may
also be installed in which case the command is simply `meson`. In this manual
we only use the latter format for simplicity.
Meson is invoked using the following syntax:
`meson [COMMAND] [COMMAND_OPTIONS]`
This section describes all available commands and some of their Optional arguments.
The most common workflow is to run [`setup`](#setup), followed by [`compile`](#compile), and then [`install`](#install).
For the full list of all available options for a specific command use the following syntax:
`meson COMMAND --help`
### configure
```
$ meson configure [-h] [--prefix PREFIX] [--bindir BINDIR]
[--datadir DATADIR] [--includedir INCLUDEDIR]
[--infodir INFODIR] [--libdir LIBDIR]
[--libexecdir LIBEXECDIR] [--localedir LOCALEDIR]
[--localstatedir LOCALSTATEDIR] [--mandir MANDIR]
[--sbindir SBINDIR] [--sharedstatedir SHAREDSTATEDIR]
[--sysconfdir SYSCONFDIR]
[--auto-features {enabled,disabled,auto}]
[--backend {ninja,vs,vs2010,vs2015,vs2017,vs2019,xcode}]
[--buildtype {plain,debug,debugoptimized,release,minsize,custom}]
[--debug] [--default-library {shared,static,both}]
[--errorlogs] [--install-umask INSTALL_UMASK]
[--layout {mirror,flat}] [--optimization {0,g,1,2,3,s}]
[--stdsplit] [--strip] [--unity {on,off,subprojects}]
[--unity-size UNITY_SIZE] [--warnlevel {0,1,2,3}]
[--werror]
[--wrap-mode {default,nofallback,nodownload,forcefallback}]
[--force-fallback-for FORCE_FALLBACK_FOR]
[--pkg-config-path PKG_CONFIG_PATH]
[--build.pkg-config-path BUILD.PKG_CONFIG_PATH]
[--cmake-prefix-path CMAKE_PREFIX_PATH]
[--build.cmake-prefix-path BUILD.CMAKE_PREFIX_PATH]
[-D option] [--clearcache]
[builddir]
```
Changes options of a configured meson project.
```
positional arguments:
builddir
optional arguments:
-h, --help show this help message and exit
--prefix PREFIX Installation prefix.
--bindir BINDIR Executable directory.
--datadir DATADIR Data file directory.
--includedir INCLUDEDIR Header file directory.
--infodir INFODIR Info page directory.
--libdir LIBDIR Library directory.
--libexecdir LIBEXECDIR Library executable directory.
--localedir LOCALEDIR Locale data directory.
--localstatedir LOCALSTATEDIR Localstate data directory.
--mandir MANDIR Manual page directory.
--sbindir SBINDIR System executable directory.
--sharedstatedir SHAREDSTATEDIR Architecture-independent data directory.
--sysconfdir SYSCONFDIR Sysconf data directory.
--auto-features {enabled,disabled,auto}
Override value of all 'auto' features
(default: auto).
--backend {ninja,vs,vs2010,vs2015,vs2017,vs2019,xcode}
Backend to use (default: ninja).
--buildtype {plain,debug,debugoptimized,release,minsize,custom}
Build type to use (default: debug).
--debug Debug
--default-library {shared,static,both}
Default library type (default: shared).
--errorlogs Whether to print the logs from failing
tests
--install-umask INSTALL_UMASK Default umask to apply on permissions of
installed files (default: 022).
--layout {mirror,flat} Build directory layout (default:
mirror).
--optimization {0,g,1,2,3,s} Optimization level (default: 0).
--stdsplit Split stdout and stderr in test logs
--strip Strip targets on install
--unity {on,off,subprojects} Unity build (default: off).
--unity-size UNITY_SIZE Unity block size (default: (2, None,
4)).
--warnlevel {0,1,2,3} Compiler warning level to use (default:
1).
--werror Treat warnings as errors
--wrap-mode {default,nofallback,nodownload,forcefallback}
Wrap mode (default: default).
--force-fallback-for FORCE_FALLBACK_FOR
Force fallback for those subprojects
(default: []).
--pkg-config-path PKG_CONFIG_PATH List of additional paths for pkg-config
to search (default: []). (just for host
machine)
--build.pkg-config-path BUILD.PKG_CONFIG_PATH
List of additional paths for pkg-config
to search (default: []). (just for build
machine)
--cmake-prefix-path CMAKE_PREFIX_PATH
List of additional prefixes for cmake to
search (default: []). (just for host
machine)
--build.cmake-prefix-path BUILD.CMAKE_PREFIX_PATH
List of additional prefixes for cmake to
search (default: []). (just for build
machine)
-D option Set the value of an option, can be used
several times to set multiple options.
--clearcache Clear cached state (e.g. found
dependencies)
```
Most arguments are the same as in [`setup`](#setup).
Note: reconfiguring project will not reset options to their default values (even if they were changed in `meson.build`).
#### Examples:
List all available options:
```
meson configure builddir
```
Change value of a single option:
```
meson configure builddir -Doption=new_value
```
### compile
*(since 0.54.0)*
```
$ meson compile [-h] [--clean] [-C BUILDDIR] [-j JOBS] [-l LOAD_AVERAGE]
[--verbose] [--ninja-args NINJA_ARGS] [--vs-args VS_ARGS]
[TARGET [TARGET ...]]
```
Builds a default or a specified target of a configured meson project.
```
positional arguments:
TARGET Targets to build. Target has the
following format: [PATH_TO_TARGET/]TARGE
T_NAME[:TARGET_TYPE].
optional arguments:
-h, --help show this help message and exit
--clean Clean the build directory.
-C BUILDDIR The directory containing build files to
be built.
-j JOBS, --jobs JOBS The number of worker jobs to run (if
supported). If the value is less than 1
the build program will guess.
-l LOAD_AVERAGE, --load-average LOAD_AVERAGE
The system load average to try to
maintain (if supported).
--verbose Show more verbose output.
--ninja-args NINJA_ARGS Arguments to pass to `ninja` (applied
only on `ninja` backend).
--vs-args VS_ARGS Arguments to pass to `msbuild` (applied
only on `vs` backend).
```
`--verbose` argument is available since 0.55.0.
#### Targets
*(since 0.55.0)*
`TARGET` has the following syntax `[PATH/]NAME[:TYPE]`, where:
- `NAME`: name of the target from `meson.build` (e.g. `foo` from `executable('foo', ...)`).
- `PATH`: path to the target relative to the root `meson.build` file. Note: relative path for a target specified in the root `meson.build` is `./`.
- `TYPE`: type of the target. Can be one of the following: 'executable', 'static_library', 'shared_library', 'shared_module', 'custom', 'run', 'jar'.
`PATH` and/or `TYPE` can be ommited if the resulting `TARGET` can be used to uniquely identify the target in `meson.build`.
#### Backend specific arguments
*(since 0.55.0)*
`BACKEND-args` use the following syntax:
If you only pass a single string, then it is considered to have all values separated by commas. Thus invoking the following command:
```
$ meson compile --ninja-args=-n,-d,explain
```
would add `-n`, `-d` and `explain` arguments to ninja invocation.
If you need to have commas or spaces in your string values, then you need to pass the value with proper shell quoting like this:
```
$ meson compile "--ninja-args=['a,b', 'c d']"
```
#### Examples:
Build the project:
```
meson compile -C builddir
```
Execute a dry run on ninja backend with additional debug info:
```
meson compile --ninja-args=-n,-d,explain
```
Build three targets: two targets that have the same `foo` name, but different type, and a `bar` target:
```
meson compile foo:shared_library foo:static_library bar
```
Produce a coverage html report (if available):
```
meson compile coverage-html
```
### dist
*(since 0.52.0)*
```
$ meson dist [-h] [-C WD] [--formats FORMATS] [--include-subprojects]
[--no-tests]
```
Generates a release archive from the current source tree.
```
optional arguments:
-h, --help show this help message and exit
-C WD directory to cd into before running
--formats FORMATS Comma separated list of archive types to create.
--include-subprojects Include source code of subprojects that have been used
for the build.
--no-tests Do not build and test generated packages.
```
See [notes about creating releases](Creating-releases.md) for more info.
#### Examples:
Create a release archive:
```
meson dist -C builddir
```
### init
*(since 0.45.0)*
```
$ meson init [-h] [-C WD] [-n NAME] [-e EXECUTABLE] [-d DEPS]
[-l {c,cpp,cs,cuda,d,fortran,java,objc,objcpp,rust}] [-b]
[--builddir BUILDDIR] [-f] [--type {executable,library}]
[--version VERSION]
[sourcefile [sourcefile ...]]
```
Creates a basic set of build files based on a template.
```
positional arguments:
sourcefile source files. default: all recognized
files in current directory
optional arguments:
-h, --help show this help message and exit
-C WD directory to cd into before running
-n NAME, --name NAME project name. default: name of current
directory
-e EXECUTABLE, --executable EXECUTABLE
executable name. default: project name
-d DEPS, --deps DEPS dependencies, comma-separated
-l {c,cpp,cs,cuda,d,fortran,java,objc,objcpp,rust}, --language {c,cpp,cs,cuda,d,fortran,java,objc,objcpp,rust}
project language. default: autodetected
based on source files
-b, --build build after generation
--builddir BUILDDIR directory for build
-f, --force force overwrite of existing files and
directories.
--type {executable,library} project type. default: executable based
project
--version VERSION project version. default: 0.1
```
#### Examples:
Create a project in `sourcedir`:
```
meson init -C sourcedir
```
### introspect
```
$ meson introspect [-h] [--ast] [--benchmarks] [--buildoptions]
[--buildsystem-files] [--dependencies]
[--scan-dependencies] [--installed] [--projectinfo]
[--targets] [--tests]
[--backend {ninja,vs,vs2010,vs2015,vs2017,vs2019,xcode}]
[-a] [-i] [-f]
[builddir]
```
Displays information about a configured meson project.
```
positional arguments:
builddir The build directory
optional arguments:
-h, --help show this help message and exit
--ast Dump the AST of the meson file.
--benchmarks List all benchmarks.
--buildoptions List all build options.
--buildsystem-files List files that make up the build
system.
--dependencies List external dependencies.
--scan-dependencies Scan for dependencies used in the
meson.build file.
--installed List all installed files and
directories.
--projectinfo Information about projects.
--targets List top level targets.
--tests List all unit tests.
--backend {ninja,vs,vs2010,vs2015,vs2017,vs2019,xcode}
The backend to use for the
--buildoptions introspection.
-a, --all Print all available information.
-i, --indent Enable pretty printed JSON.
-f, --force-object-output Always use the new JSON format for
multiple entries (even for 0 and 1
introspection commands)
```
#### Examples:
Display basic information about a configured project in `builddir`:
```
meson introspect builddir
```
### install
*(since 0.47.0)*
```
$ meson install [-h] [-C WD] [--no-rebuild] [--only-changed] [--quiet]
```
Installs the project to the prefix specified in [`setup`](#setup).
```
optional arguments:
-h, --help show this help message and exit
-C WD directory to cd into before running
--no-rebuild Do not rebuild before installing.
--only-changed Only overwrite files that are older than the copied file.
--quiet Do not print every file that was installed.
```
See [the installation documentation](Installing.md) for more info.
#### Examples:
Install project to `prefix`:
```
meson install -C builddir
```
Install project to `$DESTDIR/prefix`:
```
DESTDIR=/path/to/staging/area meson install -C builddir
```
### rewrite
*(since 0.50.0)*
```
$ meson rewrite [-h] [-s SRCDIR] [-V] [-S]
{target,kwargs,default-options,command} ...
```
Modifies the meson project.
```
optional arguments:
-h, --help show this help message and exit
-s SRCDIR, --sourcedir SRCDIR Path to source directory.
-V, --verbose Enable verbose output
-S, --skip-errors Skip errors instead of aborting
Rewriter commands:
Rewrite command to execute
{target,kwargs,default-options,command}
target Modify a target
kwargs Modify keyword arguments
default-options Modify the project default options
command Execute a JSON array of commands
```
See [the meson file rewriter documentation](Rewriter.md) for more info.
### setup
```
$ meson setup [-h] [--prefix PREFIX] [--bindir BINDIR] [--datadir DATADIR]
[--includedir INCLUDEDIR] [--infodir INFODIR]
[--libdir LIBDIR] [--libexecdir LIBEXECDIR]
[--localedir LOCALEDIR] [--localstatedir LOCALSTATEDIR]
[--mandir MANDIR] [--sbindir SBINDIR]
[--sharedstatedir SHAREDSTATEDIR] [--sysconfdir SYSCONFDIR]
[--auto-features {enabled,disabled,auto}]
[--backend {ninja,vs,vs2010,vs2015,vs2017,vs2019,xcode}]
[--buildtype {plain,debug,debugoptimized,release,minsize,custom}]
[--debug] [--default-library {shared,static,both}]
[--errorlogs] [--install-umask INSTALL_UMASK]
[--layout {mirror,flat}] [--optimization {0,g,1,2,3,s}]
[--stdsplit] [--strip] [--unity {on,off,subprojects}]
[--unity-size UNITY_SIZE] [--warnlevel {0,1,2,3}] [--werror]
[--wrap-mode {default,nofallback,nodownload,forcefallback}]
[--force-fallback-for FORCE_FALLBACK_FOR]
[--pkg-config-path PKG_CONFIG_PATH]
[--build.pkg-config-path BUILD.PKG_CONFIG_PATH]
[--cmake-prefix-path CMAKE_PREFIX_PATH]
[--build.cmake-prefix-path BUILD.CMAKE_PREFIX_PATH]
[-D option] [--native-file NATIVE_FILE]
[--cross-file CROSS_FILE] [-v] [--fatal-meson-warnings]
[--reconfigure] [--wipe]
[builddir] [sourcedir]
```
Configures a build directory for the meson project.
This is the default meson command (invoked if there was no COMMAND supplied).
```
positional arguments:
builddir
sourcedir
optional arguments:
-h, --help show this help message and exit
--prefix PREFIX Installation prefix.
--bindir BINDIR Executable directory.
--datadir DATADIR Data file directory.
--includedir INCLUDEDIR Header file directory.
--infodir INFODIR Info page directory.
--libdir LIBDIR Library directory.
--libexecdir LIBEXECDIR Library executable directory.
--localedir LOCALEDIR Locale data directory.
--localstatedir LOCALSTATEDIR Localstate data directory.
--mandir MANDIR Manual page directory.
--sbindir SBINDIR System executable directory.
--sharedstatedir SHAREDSTATEDIR Architecture-independent data directory.
--sysconfdir SYSCONFDIR Sysconf data directory.
--auto-features {enabled,disabled,auto}
Override value of all 'auto' features
(default: auto).
--backend {ninja,vs,vs2010,vs2015,vs2017,vs2019,xcode}
Backend to use (default: ninja).
--buildtype {plain,debug,debugoptimized,release,minsize,custom}
Build type to use (default: debug).
--debug Debug
--default-library {shared,static,both}
Default library type (default: shared).
--errorlogs Whether to print the logs from failing
tests
--install-umask INSTALL_UMASK Default umask to apply on permissions of
installed files (default: 022).
--layout {mirror,flat} Build directory layout (default:
mirror).
--optimization {0,g,1,2,3,s} Optimization level (default: 0).
--stdsplit Split stdout and stderr in test logs
--strip Strip targets on install
--unity {on,off,subprojects} Unity build (default: off).
--unity-size UNITY_SIZE Unity block size (default: (2, None,
4)).
--warnlevel {0,1,2,3} Compiler warning level to use (default:
1).
--werror Treat warnings as errors
--wrap-mode {default,nofallback,nodownload,forcefallback}
Wrap mode (default: default).
--force-fallback-for FORCE_FALLBACK_FOR
Force fallback for those subprojects
(default: []).
--pkg-config-path PKG_CONFIG_PATH List of additional paths for pkg-config
to search (default: []). (just for host
machine)
--build.pkg-config-path BUILD.PKG_CONFIG_PATH
List of additional paths for pkg-config
to search (default: []). (just for build
machine)
--cmake-prefix-path CMAKE_PREFIX_PATH
List of additional prefixes for cmake to
search (default: []). (just for host
machine)
--build.cmake-prefix-path BUILD.CMAKE_PREFIX_PATH
List of additional prefixes for cmake to
search (default: []). (just for build
machine)
-D option Set the value of an option, can be used
several times to set multiple options.
--native-file NATIVE_FILE File containing overrides for native
compilation environment.
--cross-file CROSS_FILE File describing cross compilation
environment.
-v, --version show program's version number and exit
--fatal-meson-warnings Make all Meson warnings fatal
--reconfigure Set options and reconfigure the project.
Useful when new options have been added
to the project and the default value is
not working.
--wipe Wipe build directory and reconfigure
using previous command line options.
Useful when build directory got
corrupted, or when rebuilding with a
newer version of meson.
```
See [meson introduction page](Running-Meson.md#configuring-the-build-directory) for more info.
#### Examples:
Configures `builddir` with default values:
```
meson setup builddir
```
### subprojects
*(since 0.49.0)*
```
$ meson subprojects [-h] {update,checkout,download,foreach} ...
```
Manages subprojects of the meson project.
```
optional arguments:
-h, --help show this help message and exit
Commands:
{update,checkout,download,foreach}
update Update all subprojects from wrap files
checkout Checkout a branch (git only)
download Ensure subprojects are fetched, even if
not in use. Already downloaded subprojects
are not modified. This can be used to pre-
fetch all subprojects and avoid downloads
during configure.
foreach Execute a command in each subproject
directory.
```
### test
```
$ meson test [-h] [--repeat REPEAT] [--no-rebuild] [--gdb]
[--gdb-path GDB_PATH] [--list] [--wrapper WRAPPER] [-C WD]
[--suite SUITE] [--no-suite SUITE] [--no-stdsplit]
[--print-errorlogs] [--benchmark] [--logbase LOGBASE]
[--num-processes NUM_PROCESSES] [-v] [-q]
[-t TIMEOUT_MULTIPLIER] [--setup SETUP]
[--test-args TEST_ARGS]
[args [args ...]]
```
Run tests for the configure meson project.
```
positional arguments:
args Optional list of tests to run
optional arguments:
-h, --help show this help message and exit
--repeat REPEAT Number of times to run the tests.
--no-rebuild Do not rebuild before running tests.
--gdb Run test under gdb.
--gdb-path GDB_PATH Path to the gdb binary (default: gdb).
--list List available tests.
--wrapper WRAPPER wrapper to run tests with (e.g.
Valgrind)
-C WD directory to cd into before running
--suite SUITE Only run tests belonging to the given
suite.
--no-suite SUITE Do not run tests belonging to the given
suite.
--no-stdsplit Do not split stderr and stdout in test
logs.
--print-errorlogs Whether to print failing tests' logs.
--benchmark Run benchmarks instead of tests.
--logbase LOGBASE Base name for log file.
--num-processes NUM_PROCESSES How many parallel processes to use.
-v, --verbose Do not redirect stdout and stderr
-q, --quiet Produce less output to the terminal.
-t TIMEOUT_MULTIPLIER, --timeout-multiplier TIMEOUT_MULTIPLIER
Define a multiplier for test timeout,
for example when running tests in
particular conditions they might take
more time to execute.
--setup SETUP Which test setup to use.
--test-args TEST_ARGS Arguments to pass to the specified
test(s) or all tests
```
See [the unit test documentation](Unit-tests.md) for more info.
#### Examples:
Run tests for the project:
```
meson test -C builddir
```
Run only `specific_test_1` and `specific_test_2`:
```
meson test -C builddir specific_test_1 specific_test_2
```
### wrap
```
$ meson wrap [-h] {list,search,install,update,info,status,promote} ...
```
An utility to manage WrapDB dependencies.
```
optional arguments:
-h, --help show this help message and exit
Commands:
{list,search,install,update,info,status,promote}
list show all available projects
search search the db by name
install install the specified project
update update the project to its newest
available release
info show available versions of a project
status show installed and available versions of
your projects
promote bring a subsubproject up to the master
project
```
See [the WrapDB tool documentation](Using-wraptool.md) for more info.

296
docs/markdown_dynamic/Commands.md
Unescape View File

@ -0,0 +1,296 @@
# Command-line commands
There are two different ways of invoking Meson. First, you can run it directly
from the source tree with the command `/path/to/source/meson.py`. Meson may
also be installed in which case the command is simply `meson`. In this manual
we only use the latter format for simplicity.
Meson is invoked using the following syntax:
`meson [COMMAND] [COMMAND_OPTIONS]`
This section describes all available commands and some of their Optional arguments.
The most common workflow is to run [`setup`](#setup), followed by [`compile`](#compile), and then [`install`](#install).
For the full list of all available options for a specific command use the following syntax:
`meson COMMAND --help`
### configure
```
{{ cmd_help['configure']['usage'] }}
```
Changes options of a configured meson project.
```
{{ cmd_help['configure']['arguments'] }}
```
Most arguments are the same as in [`setup`](#setup).
Note: reconfiguring project will not reset options to their default values (even if they were changed in `meson.build`).
#### Examples:
List all available options:
```
meson configure builddir
```
Change value of a single option:
```
meson configure builddir -Doption=new_value
```
### compile
*(since 0.54.0)*
```
{{ cmd_help['compile']['usage'] }}
```
Builds a default or a specified target of a configured meson project.
```
{{ cmd_help['compile']['arguments'] }}
```
`--verbose` argument is available since 0.55.0.
#### Targets
*(since 0.55.0)*
`TARGET` has the following syntax `[PATH/]NAME[:TYPE]`, where:
- `NAME`: name of the target from `meson.build` (e.g. `foo` from `executable('foo', ...)`).
- `PATH`: path to the target relative to the root `meson.build` file. Note: relative path for a target specified in the root `meson.build` is `./`.
- `TYPE`: type of the target. Can be one of the following: 'executable', 'static_library', 'shared_library', 'shared_module', 'custom', 'run', 'jar'.
`PATH` and/or `TYPE` can be ommited if the resulting `TARGET` can be used to uniquely identify the target in `meson.build`.
#### Backend specific arguments
*(since 0.55.0)*
`BACKEND-args` use the following syntax:
If you only pass a single string, then it is considered to have all values separated by commas. Thus invoking the following command:
```
$ meson compile --ninja-args=-n,-d,explain
```
would add `-n`, `-d` and `explain` arguments to ninja invocation.
If you need to have commas or spaces in your string values, then you need to pass the value with proper shell quoting like this:
```
$ meson compile "--ninja-args=['a,b', 'c d']"
```
#### Examples:
Build the project:
```
meson compile -C builddir
```
Execute a dry run on ninja backend with additional debug info:
```
meson compile --ninja-args=-n,-d,explain
```
Build three targets: two targets that have the same `foo` name, but different type, and a `bar` target:
```
meson compile foo:shared_library foo:static_library bar
```
Produce a coverage html report (if available):
```
meson compile coverage-html
```
### dist
*(since 0.52.0)*
```
{{ cmd_help['dist']['usage'] }}
```
Generates a release archive from the current source tree.
```
{{ cmd_help['dist']['arguments'] }}
```
See [notes about creating releases](Creating-releases.md) for more info.
#### Examples:
Create a release archive:
```
meson dist -C builddir
```
### init
*(since 0.45.0)*
```
{{ cmd_help['init']['usage'] }}
```
Creates a basic set of build files based on a template.
```
{{ cmd_help['init']['arguments'] }}
```
#### Examples:
Create a project in `sourcedir`:
```
meson init -C sourcedir
```
### introspect
```
{{ cmd_help['introspect']['usage'] }}
```
Displays information about a configured meson project.
```
{{ cmd_help['introspect']['arguments'] }}
```
#### Examples:
Display basic information about a configured project in `builddir`:
```
meson introspect builddir
```
### install
*(since 0.47.0)*
```
{{ cmd_help['install']['usage'] }}
```
Installs the project to the prefix specified in [`setup`](#setup).
```
{{ cmd_help['install']['arguments'] }}
```
See [the installation documentation](Installing.md) for more info.
#### Examples:
Install project to `prefix`:
```
meson install -C builddir
```
Install project to `$DESTDIR/prefix`:
```
DESTDIR=/path/to/staging/area meson install -C builddir
```
### rewrite
*(since 0.50.0)*
```
{{ cmd_help['rewrite']['usage'] }}
```
Modifies the meson project.
```
{{ cmd_help['rewrite']['arguments'] }}
```
See [the meson file rewriter documentation](Rewriter.md) for more info.
### setup
```
{{ cmd_help['setup']['usage'] }}
```
Configures a build directory for the meson project.
This is the default meson command (invoked if there was no COMMAND supplied).
```
{{ cmd_help['setup']['arguments'] }}
```
See [meson introduction page](Running-Meson.md#configuring-the-build-directory) for more info.
#### Examples:
Configures `builddir` with default values:
```
meson setup builddir
```
### subprojects
*(since 0.49.0)*
```
{{ cmd_help['subprojects']['usage'] }}
```
Manages subprojects of the meson project.
```
{{ cmd_help['subprojects']['arguments'] }}
```
### test
```
{{ cmd_help['test']['usage'] }}
```
Run tests for the configure meson project.
```
{{ cmd_help['test']['arguments'] }}
```
See [the unit test documentation](Unit-tests.md) for more info.
#### Examples:
Run tests for the project:
```
meson test -C builddir
```
Run only `specific_test_1` and `specific_test_2`:
```
meson test -C builddir specific_test_1 specific_test_2
```
### wrap
```
{{ cmd_help['wrap']['usage'] }}
```
An utility to manage WrapDB dependencies.
```
{{ cmd_help['wrap']['arguments'] }}
```
See [the WrapDB tool documentation](Using-wraptool.md) for more info.

32
docs/meson.build
Unescape View File

@ -1,16 +1,40 @@
project('Meson documentation', version: '1.0')
cur_bdir = meson.current_build_dir()
# Copy all files to build dir, since HotDoc uses relative paths
run_command(
files('../tools/copy_files.py'),
'-C', meson.current_source_dir(),
'--output-dir', cur_bdir,
'markdown', 'theme', 'sitemap.txt',
check: true)
# Only the script knows which files are being generated
docs_gen = custom_target(
'gen_docs',
input: files('markdown/index.md'),
output: 'gen_docs.dummy',
command: [
files('../tools/regenerate_docs.py'),
'--output-dir', join_paths(cur_bdir, 'markdown'),
'--dummy-output-file', '@OUTPUT@',
],
build_by_default: true,
install: false)
hotdoc = import('hotdoc')
documentation = hotdoc.generate_doc(meson.project_name(),
project_version: meson.project_version(),
sitemap: 'sitemap.txt',
sitemap: join_paths(cur_bdir, 'sitemap.txt'),
build_by_default: true,
index: 'markdown/index.md',
depends: docs_gen,
index: join_paths(cur_bdir, 'markdown/index.md'),
install: false,
extra_assets: ['images/'],
include_paths: ['markdown'],
include_paths: [join_paths(cur_bdir, 'markdown')],
default_license: 'CC-BY-SAv4.0',
html_extra_theme: join_paths('theme', 'extra'),
html_extra_theme: join_paths(cur_bdir, 'theme', 'extra'),
git_upload_repository: 'git@github.com:jpakkane/jpakkane.github.io.git',
edit_on_github_repository: 'https://github.com/mesonbuild/meson/',
syntax_highlighting_activate: true,

105
run_unittests.py
Unescape View File

@ -4783,81 +4783,16 @@ recommended as it is not supported on some platforms''')
'''
Test that all listed meson commands are documented in Commands.md.
'''
help_usage_start_pattern = re.compile(r'^usage:[\t ]*[\r\n]*', re.MULTILINE)
help_positional_start_pattern = re.compile(r'^positional arguments:[\t ]*[\r\n]+', re.MULTILINE)
help_options_start_pattern = re.compile(r'^optional arguments:[\t ]*[\r\n]+', re.MULTILINE)
help_commands_start_pattern = re.compile(r'^[A-Za-z ]*[Cc]ommands:[\t ]*[\r\n]+', re.MULTILINE)
def get_next_start(iterators, end):
return next((i.start() for i in iterators if i), end)
def parse_help(help):
help_len = len(help)
usage = help_usage_start_pattern.search(help)
positionals = help_positional_start_pattern.search(help)
options = help_options_start_pattern.search(help)
commands = help_commands_start_pattern.search(help)
arguments_start = get_next_start([positionals, options, commands], None)
self.assertIsNotNone(arguments_start, 'Cmd command is missing argument list')
return {
'usage': help[usage.end():arguments_start],
'arguments': help[arguments_start:help_len],
}
md_code_pattern = re.compile(r'^```[\r\n]*', re.MULTILINE)
md_usage_pattern = re.compile(r'^\$ ', re.MULTILINE)
def parse_section(text, section_start, section_end):
matches = [i
for i in md_code_pattern.finditer(text, pos=section_start, endpos=section_end)]
self.assertGreaterEqual(len(matches), 4, '.md command is missing usage description and/or argument list')
usage = md_usage_pattern.search(text, pos=matches[0].end(), endpos=matches[1].start())
return {
'usage': text[usage.end():matches[1].start()],
'arguments': text[matches[2].end():matches[3].start()],
}
def normalize_text(text):
# clean up formatting
out = re.sub(r'( {2,}|\t+)', r' ', text, flags=re.MULTILINE) # replace whitespace chars with a single space
out = re.sub(r'\r\n+', r'\r', out, flags=re.MULTILINE) # replace newlines with a single linux EOL
out = re.sub(r'(^ +| +$)', '', out, flags=re.MULTILINE) # strip lines
out = re.sub(r'(^\n)', '', out, flags=re.MULTILINE) # remove empty lines
return out
def clean_dir_arguments(text):
# Remove platform specific defaults
args = [
'prefix',
'bindir',
'datadir',
'includedir',
'infodir',
'libdir',
'libexecdir',
'localedir',
'localstatedir',
'mandir',
'sbindir',
'sharedstatedir',
'sysconfdir'
]
out = text
for a in args:
out = re.sub(r'(--' + a + r' .+?)[ |\n]\(default:.+?\)(\.)?', r'\1\2', out, flags=re.MULTILINE|re.DOTALL)
return out
## Get command sections
doc_path = 'docs/markdown_dynamic/Commands.md'
md = None
with open('docs/markdown/Commands.md', encoding='utf-8') as f:
with open(doc_path, encoding='utf-8') as f:
md = f.read()
self.assertIsNotNone(md)
## Get command sections
section_pattern = re.compile(r'^### (.+)$', re.MULTILINE)
md_command_section_matches = [i for i in section_pattern.finditer(md)]
md_command_sections = dict()
@ -4872,26 +4807,24 @@ recommended as it is not supported on some platforms''')
help_output = self._run(self.meson_command + ['--help'])
help_commands = set(c.strip() for c in re.findall(r'usage:(?:.+)?{((?:[a-z]+,*)+?)}', help_output, re.MULTILINE|re.DOTALL)[0].split(','))
self.assertEqual(md_commands | {'help'}, help_commands)
self.assertEqual(md_commands | {'help'}, help_commands, 'Doc file: `{}`'.format(doc_path))
## Validate command options
## Validate that each section has proper placeholders
for command in md_commands:
print('Current command: {}'.format(command))
def get_data_pattern(command):
return re.compile(
r'^```[\r\n]'
r'{{ cmd_help\[\'' + command + r'\'\]\[\'usage\'\] }}[\r\n]'
r'^```[\r\n]'
r'.*?'
r'^```[\r\n]'
r'{{ cmd_help\[\'' + command + r'\'\]\[\'arguments\'\] }}[\r\n]'
r'^```',
flags = re.MULTILINE|re.DOTALL)
help_cmd_output = self._run(self.meson_command + [command, '--help'], override_envvars={'COLUMNS': '80'})
parsed_help = parse_help(help_cmd_output)
parsed_section = parse_section(md, *md_command_sections[command])
for p in [parsed_help, parsed_section]:
p['usage'] = normalize_text(p['usage'])
p['arguments'] = normalize_text(p['arguments'])
if command in ['setup', 'configure']:
parsed_help['arguments'] = clean_dir_arguments(parsed_help['arguments'])
self.assertEqual(parsed_help['usage'], parsed_section['usage'])
self.assertEqual(parsed_help['arguments'], parsed_section['arguments'])
for command in md_commands:
m = get_data_pattern(command).search(md, pos=md_command_sections[command][0], endpos=md_command_sections[command][1])
self.assertIsNotNone(m, 'Command `{}` is missing placeholders for dynamic data. Doc file: `{}`'.format(command, doc_path))
def test_coverage(self):
if mesonbuild.environment.detect_msys2_arch():

55
tools/copy_files.py
Unescape View File

@ -0,0 +1,55 @@
#!/usr/bin/env python3
# Copyright 2018 The Meson development team
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
# http://www.apache.org/licenses/LICENSE-2.0
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
'''
Copy files
'''
import argparse
import shutil
import typing as T
from pathlib import Path
PathLike = T.Union[Path,str]
def copy_files(files: T.List[str], input_dir: PathLike, output_dir: PathLike) -> None:
if not input_dir:
raise ValueError(f'Input directory value is not set')
if not output_dir:
raise ValueError(f'Output directory value is not set')
input_dir = Path(input_dir).resolve()
output_dir = Path(output_dir).resolve()
output_dir.mkdir(parents=True, exist_ok=True)
for f in files:
if (input_dir/f).is_dir():
shutil.copytree(input_dir/f, output_dir/f)
else:
shutil.copy2(input_dir/f, output_dir/f)
if __name__ == '__main__':
parser = argparse.ArgumentParser(description='Copy files')
parser.add_argument('files', metavar='FILE', nargs='*')
parser.add_argument('-C', dest='input_dir', required=True)
parser.add_argument('--output-dir', required=True)
args = parser.parse_args()
copy_files(files=args.files,
input_dir=args.input_dir,
output_dir=args.output_dir)

150
tools/regenerate_docs.py
Unescape View File

@ -0,0 +1,150 @@
#!/usr/bin/env python3
# Copyright 2018 The Meson development team
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
# http://www.apache.org/licenses/LICENSE-2.0
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
'''
Regenerate markdown docs by using `meson.py` from the root dir
'''
import argparse
import jinja2
import os
import re
import subprocess
import sys
import textwrap
import typing as T
from pathlib import Path
PathLike = T.Union[Path,str]
def _get_meson_output(root_dir: Path, args: T.List):
env = os.environ.copy()
env['COLUMNS'] = '80'
return subprocess.run([str(sys.executable), str(root_dir/'meson.py')] + args, check=True, capture_output=True, text=True, env=env).stdout.strip()
def get_commands_data(root_dir: Path):
usage_start_pattern = re.compile(r'^usage: ', re.MULTILINE)
positional_start_pattern = re.compile(r'^positional arguments:[\t ]*[\r\n]+', re.MULTILINE)
options_start_pattern = re.compile(r'^optional arguments:[\t ]*[\r\n]+', re.MULTILINE)
commands_start_pattern = re.compile(r'^[A-Za-z ]*[Cc]ommands:[\t ]*[\r\n]+', re.MULTILINE)
def get_next_start(iterators, end):
return next((i.start() for i in iterators if i), end)
def normalize_text(text):
# clean up formatting
out = text
out = re.sub(r'\r\n', r'\r', out, flags=re.MULTILINE) # replace newlines with a linux EOL
out = re.sub(r'^ +$', '', out, flags=re.MULTILINE) # remove trailing whitespace
out = re.sub(r'(?:^\n+|\n+$)', '', out) # remove trailing empty lines
return out
def parse_cmd(cmd):
cmd_len = len(cmd)
usage = usage_start_pattern.search(cmd)
positionals = positional_start_pattern.search(cmd)
options = options_start_pattern.search(cmd)
commands = commands_start_pattern.search(cmd)
arguments_start = get_next_start([positionals, options, commands], None)
assert arguments_start
# replace `usage:` with `$` and dedent
dedent_size = (usage.end() - usage.start()) - len('$ ')
usage_text = textwrap.dedent(f'{dedent_size * " "}$ {normalize_text(cmd[usage.end():arguments_start])}')
return {
'usage': usage_text,
'arguments': normalize_text(cmd[arguments_start:cmd_len]),
}
def clean_dir_arguments(text):
# Remove platform specific defaults
args = [
'prefix',
'bindir',
'datadir',
'includedir',
'infodir',
'libdir',
'libexecdir',
'localedir',
'localstatedir',
'mandir',
'sbindir',
'sharedstatedir',
'sysconfdir'
]
out = text
for a in args:
out = re.sub(r'(--' + a + r' .+?)\s+\(default:.+?\)(\.)?', r'\1\2', out, flags=re.MULTILINE|re.DOTALL)
return out
output = _get_meson_output(root_dir, ['--help'])
commands = set(c.strip() for c in re.findall(r'usage:(?:.+)?{((?:[a-z]+,*)+?)}', output, re.MULTILINE|re.DOTALL)[0].split(','))
commands.remove('help')
cmd_data = dict()
for cmd in commands:
cmd_output = _get_meson_output(root_dir, [cmd, '--help'])
cmd_data[cmd] = parse_cmd(cmd_output)
if cmd in ['setup', 'configure']:
cmd_data[cmd]['arguments'] = clean_dir_arguments(cmd_data[cmd]['arguments'])
return cmd_data
def regenerate_commands(root_dir: Path, output_dir: Path) -> None:
with open(root_dir/'docs'/'markdown_dynamic'/'Commands.md') as f:
template = f.read()
cmd_data = get_commands_data(root_dir)
t = jinja2.Template(template, undefined=jinja2.StrictUndefined, keep_trailing_newline=True)
content = t.render(cmd_help=cmd_data)
output_file = output_dir/'Commands.md'
with open(output_file, 'w') as f:
f.write(content)
print(f'`{output_file}` was regenerated')
def regenerate_docs(output_dir: PathLike,
dummy_output_file: T.Optional[PathLike]) -> None:
if not output_dir:
raise ValueError(f'Output directory value is not set')
output_dir = Path(output_dir).resolve()
output_dir.mkdir(parents=True, exist_ok=True)
root_dir = Path(__file__).resolve().parent.parent
regenerate_commands(root_dir, output_dir)
if dummy_output_file:
with open(output_dir/dummy_output_file, 'w') as f:
f.write('dummy file for custom_target output')
if __name__ == '__main__':
parser = argparse.ArgumentParser(description='Generate meson docs')
parser.add_argument('--output-dir', required=True)
parser.add_argument('--dummy-output-file', type=str)
args = parser.parse_args()
regenerate_docs(output_dir=args.output_dir,
dummy_output_file=args.dummy_output_file)
Write Preview
Loading…
Cancel
Save