diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/markdown/Build-options.md | 21 | ||||
| -rw-r--r-- | docs/markdown/CMake-module.md | 2 | ||||
| -rw-r--r-- | docs/markdown/Contributing.md | 37 | ||||
| -rw-r--r-- | docs/markdown/Custom-build-targets.md | 4 | ||||
| -rw-r--r-- | docs/markdown/Dependencies.md | 2 | ||||
| -rw-r--r-- | docs/markdown/Pkgconfig-module.md | 2 | ||||
| -rw-r--r-- | docs/markdown/Python-module.md | 5 | ||||
| -rw-r--r-- | docs/markdown/Reference-manual.md | 27 | ||||
| -rw-r--r-- | docs/markdown/Reference-tables.md | 31 | ||||
| -rw-r--r-- | docs/markdown/snippets/minstall_quiet.md | 11 | ||||
| -rw-r--r-- | docs/markdown/snippets/pkgconfig_dataonly.md | 15 |
11 files changed, 125 insertions, 32 deletions
diff --git a/docs/markdown/Build-options.md b/docs/markdown/Build-options.md index 8b29afd..2d53e28 100644 --- a/docs/markdown/Build-options.md +++ b/docs/markdown/Build-options.md @@ -83,9 +83,9 @@ Currently supported in - `disabled` do not look for the dependency and always return 'not-found'. When getting the value of this type of option using `get_option()`, a special -object is returned instead of the string representation of the option's value. -That object has three methods returning boolean and taking no argument: -`enabled()`, `disabled()`, and `auto()`. +[feature option object](Reference-manual.md#feature-option-object) +is returned instead of the string representation of the option's value. +This object can be passed to `required`: ```meson d = dependency('foo', required : get_option('myfeature')) @@ -94,6 +94,21 @@ if d.found() endif ``` +To check the value of the feature, the object has three methods +returning a boolean and taking no argument: + +- `.enabled()` +- `.disabled()` +- `.auto()` + +This is useful for custom code depending on the feature: + +```meson +if get_option('myfeature').enabled() + # ... +endif +``` + If the value of a `feature` option is set to `auto`, that value is overridden by the global `auto_features` option (which defaults to `auto`). This is intended to be used by packagers who want to have full control on which dependencies are diff --git a/docs/markdown/CMake-module.md b/docs/markdown/CMake-module.md index a021396..a15e3c2 100644 --- a/docs/markdown/CMake-module.md +++ b/docs/markdown/CMake-module.md @@ -99,6 +99,8 @@ and supports the following methods: - `get_variable(name)` fetches the specified variable from inside the subproject. Usually `dependency()` or `target()` should be preferred to extract build targets. + - `found` returns true if the subproject is available, otherwise false + *new in in 0.53.2* ## CMake configuration files diff --git a/docs/markdown/Contributing.md b/docs/markdown/Contributing.md index f545b77..c5b8608 100644 --- a/docs/markdown/Contributing.md +++ b/docs/markdown/Contributing.md @@ -127,6 +127,8 @@ 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`. +### Project tests + 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. @@ -139,7 +141,7 @@ 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 +own. They are all in the `test cases` subdirectory. The simplest way to run a single project test is to do something like `./meson.py test\ cases/common/1\ trivial builddir`. The one exception to this is `test cases/unit` directory discussed below. @@ -153,13 +155,32 @@ should be implemented as a Python script. The goal of test projects is also to provide sample projects that end users can use as a base for their own projects. -All project tests follow the same pattern: they are compiled, tests -are run and finally install is run. Passing means that building and -tests succeed and installed files match the `installed_files.txt` file -in the test's source root. Any tests that require more thorough -analysis, such as checking that certain compiler arguments can be -found in the command line or that the generated pkg-config files -actually work should be done with a unit test. +All project tests follow the same pattern: they are configured, compiled, tests +are run and finally install is run. Passing means that configuring, building and +tests succeed and that installed files match those expected. + +Any tests that require more thorough analysis, such as checking that certain +compiler arguments can be found in the command line or that the generated +pkg-config files actually work should be done with a unit test. + +The following files in the test's source root are consulted, if they exist: + +* `installed_files.txt` lists the files which are expected to be installed. +Various constructs containing `?` are used to indicate platform specific +filename variations (e.g. `?so` represents the platform appropriate suffix for a +shared library) + +* `setup_env.json` contains a dictionary which specifies additional +environment variables to be set during the configure step of the test. `@ROOT@` +is replaced with the absolute path of the source directory. + +* `crossfile.ini` and `nativefile.ini` are passed to the configure step with +`--cross-file` and `--native-file` options, respectively. + +Additionally: + +* `mlog.cmd_ci_include()` can be called from anywhere inside meson to capture the +contents of an additional file into the CI log on failure. Projects needed by unit tests are in the `test cases/unit` subdirectory. They are not run as part of `./run_project_tests.py`. diff --git a/docs/markdown/Custom-build-targets.md b/docs/markdown/Custom-build-targets.md index 9a0f2a1..f0b50d8 100644 --- a/docs/markdown/Custom-build-targets.md +++ b/docs/markdown/Custom-build-targets.md @@ -16,8 +16,8 @@ infile = 'source_code.txt' outfile = 'output.bin' mytarget = custom_target('targetname', - output : 'output.bin', - input : 'source_code.txt', + output : outfile, + input : infile, command : [comp, '@INPUT@', '@OUTPUT@'], install : true, install_dir : 'subdir') diff --git a/docs/markdown/Dependencies.md b/docs/markdown/Dependencies.md index 50ea92f..8cffba4 100644 --- a/docs/markdown/Dependencies.md +++ b/docs/markdown/Dependencies.md @@ -181,7 +181,7 @@ should only be used if the CMake files are not stored in the project itself. Additional CMake parameters can be specified with the `cmake_args` property. -### Some notes on Dub +## Dub Please understand that meson is only able to find dependencies that exist in the local Dub repository. You need to manually fetch and diff --git a/docs/markdown/Pkgconfig-module.md b/docs/markdown/Pkgconfig-module.md index 678090b..13fc4e6 100644 --- a/docs/markdown/Pkgconfig-module.md +++ b/docs/markdown/Pkgconfig-module.md @@ -56,6 +56,8 @@ keyword arguments. D sources referred to by this pkg-config file - `uninstalled_variables` used instead of the `variables` keyword argument, when generating the uninstalled pkg-config file. Since *0.54.0* +- `dataonly` field. (*since 0.54.0*) this is used for architecture-independent + pkg-config files in projects which also have architecture-dependent outputs. Since 0.46 a `StaticLibrary` or `SharedLibrary` object can optionally be passed as first positional argument. If one is provided a default value will be diff --git a/docs/markdown/Python-module.md b/docs/markdown/Python-module.md index 152aa5c..d99b36a 100644 --- a/docs/markdown/Python-module.md +++ b/docs/markdown/Python-module.md @@ -103,8 +103,9 @@ need to add `dependencies : py_installation.dependency()`, see [][`dependency()` python_dependency py_installation.dependency(...) ``` -This method accepts the same arguments as the standard [dependency] function and -the following additional keyword arguments: +This method accepts no positional arguments, and the same keyword arguments as +the standard [dependency] function. It also supports the following keyword +argument: - `embed`: *(since 0.53.0)* If true, meson will try to find a python dependency that can be used for embedding python into an application. diff --git a/docs/markdown/Reference-manual.md b/docs/markdown/Reference-manual.md index 510d443..475b711 100644 --- a/docs/markdown/Reference-manual.md +++ b/docs/markdown/Reference-manual.md @@ -846,8 +846,10 @@ configuration as-is, which may be absolute, or relative to `prefix`. if you need the absolute path to one of these e.g. to use in a define etc., you should use `get_option('prefix') / get_option('localstatedir')` -For options of type `feature` a special object is returned instead of -a string. See [`feature` options](Build-options.md#features) +For options of type `feature` a +[feature option object](#feature-option-object) +is returned instead of a string. +See [`feature` options](Build-options.md#features) documentation for more details. ### get_variable() @@ -1226,7 +1228,7 @@ This function is used to summarize build configuration at the end of the build process. This function provides a way for projects (and subprojects) to report this information in a clear way. -The content is a serie of key/value pairs grouped into sections. If the section +The content is a series of key/value pairs grouped into sections. If the section keyword argument is omitted, those key/value pairs are implicitly grouped into a section with no title. key/value pairs can optionally be grouped into a dictionary, but keep in mind that dictionaries does not guarantee ordering. `key` must be string, @@ -1285,7 +1287,7 @@ My Project 1.0 The first argument to this function must be a string defining the name of this project. It is followed by programming languages that the project uses. Supported values for languages are `c`, `cpp` (for -`C++`), `d`, `objc`, `objcpp`, `fortran`, `java`, `cs` (for `C#`), +`C++`), `cuda`, `d`, `objc`, `objcpp`, `fortran`, `java`, `cs` (for `C#`), `vala` and `rust`. Since version `0.40.0` the list of languages is optional. @@ -1718,8 +1720,11 @@ the following methods. given as an argument to be run during the install step, this script will have the environment variables `MESON_SOURCE_ROOT`, `MESON_BUILD_ROOT`, `MESON_INSTALL_PREFIX`, - `MESON_INSTALL_DESTDIR_PREFIX`, and `MESONINTROSPECT` set. All - additional arguments are passed as parameters. + `MESON_INSTALL_DESTDIR_PREFIX`, and `MESONINTROSPECT` set. + All positional arguments are passed as parameters. + + *(added 0.54)* If `meson install` is called with the `--quiet` option, the + environment variable `MESON_INSTALL_QUIET` will be set. Meson uses the `DESTDIR` environment variable as set by the inherited environment to determine the (temporary) installation @@ -2469,6 +2474,16 @@ library. This object has the following methods: object will only inherit other attributes from its parent as controlled by keyword arguments. +### Feature option object + +The following methods are defined for all [`feature` options](Build-options.md#features): + +- `enabled()` returns whether the feature was set to `'enabled'` +- `disabled()` returns whether the feature was set to `'disabled'` +- `auto()` returns whether the feature was set to `'auto'` + +Feature options are available since 0.47.0. + ### `generator` object This object is returned by [`generator()`](#generator) and contains a diff --git a/docs/markdown/Reference-tables.md b/docs/markdown/Reference-tables.md index 86524b7..9f432f0 100644 --- a/docs/markdown/Reference-tables.md +++ b/docs/markdown/Reference-tables.md @@ -33,16 +33,27 @@ These are return values of the `get_id` (Compiler family) and ## Linker ids -These are return values of the `get_linker_id` (Linker family) method in a compiler object. - -| Value | Linker family | -| ----- | --------------- | -| ld.bfd | GNU Compiler Collection | -| {ld.bfd,lld} | Clang non-Windows | -| link | MSVC, Clang-cl, clang Windows | -| pgi | Portland/Nvidia PGI | -| {ld.bfd,gold,xild} | Intel compiler non-Windows | -| xilink | Intel-cl Windows | +These are return values of the `get_linker_id` method in a compiler object. + +| Value | Linker family | +| ----- | --------------- | +| ld.bfd | The GNU linker | +| ld.gold | The GNU gold linker | +| ld.lld | The LLVM linker, with the GNU interface | +| ld.solaris | Solaris and illumos | +| ld64 | Apple ld64 | +| link | MSVC linker | +| lld-link | The LLVM linker, with the MSVC interface | +| xilink | Used with Intel-cl only, MSVC like | +| optlink | optlink (used with DMD) | +| rlink | The Renesas linker, used with CCrx only | +| armlink | The ARM linker (arm and armclang compilers) | +| pgi | Portland/Nvidia PGI | +| nvlink | Nvidia Linker used with cuda | + +For languages that don't have separate dynamic linkers such as C# and Java, the +`get_linker_id` will return the compiler name. + ## Script environment variables diff --git a/docs/markdown/snippets/minstall_quiet.md b/docs/markdown/snippets/minstall_quiet.md new file mode 100644 index 0000000..3a7ff31 --- /dev/null +++ b/docs/markdown/snippets/minstall_quiet.md @@ -0,0 +1,11 @@ +## New option `--quiet` to `meson install` + +Now you can run `meson install --quiet` and meson will not verbosely print +every file as it is being installed. As before, the full log is always +available inside the builddir in `meson-logs/install-log.txt`. + +When this option is passed, install scripts will have the environment variable +`MESON_INSTALL_QUIET` set. + +Numerous speed-ups were also made for the install step, especially on Windows +where it is now 300% to 1200% faster than before depending on your workload. diff --git a/docs/markdown/snippets/pkgconfig_dataonly.md b/docs/markdown/snippets/pkgconfig_dataonly.md new file mode 100644 index 0000000..8a2564c --- /dev/null +++ b/docs/markdown/snippets/pkgconfig_dataonly.md @@ -0,0 +1,15 @@ +## Introduce dataonly for the pkgconfig module +This allows users to disable writing out the inbuilt variables to +the pkg-config file as they might actualy not be required. + +One reason to have this is for architecture-independent pkg-config +files in projects which also have architecture-dependent outputs. + +``` +pkgg.generate( + name : 'libhello_nolib', + description : 'A minimalistic pkgconfig file.', + version : libver, + dataonly: true +) +``` |