diff options
Diffstat (limited to 'docs')
64 files changed, 1424 insertions, 560 deletions
diff --git a/docs/.editorconfig b/docs/.editorconfig new file mode 100644 index 0000000..b5276f1 --- /dev/null +++ b/docs/.editorconfig @@ -0,0 +1,2 @@ +[sitemap.txt] +indent_style = tab diff --git a/docs/README.md b/docs/README.md index 18509c7..55fc3ec 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,15 +1,40 @@ -# Building the documentation +# Meson Documentation -1. Get [hotdoc](https://hotdoc.github.io/installing.html) (0.8.9 required) -1. Run hotdoc in the docs/ directory: +## Build dependencies - ../meson/meson.py build/ +Meson uses itself and [hotdoc](https://github.com/hotdoc/hotdoc) for generating documentation. + +Minimum required version of hotdoc is *0.8.9*. + +Instructions on how to install hotdoc are [here](https://hotdoc.github.io/installing.html). + +## Building the documentation + +From the Meson repository root dir: +``` +$ cd docs/ +$ meson built_docs +$ ninja -C built_docs/ upload +``` +Now you should be able to open the documentation locally +``` +built_docs/Meson documentation-doc/html/index.html +``` ## Upload -We are using the git-upload hotdoc plugin which basically +Meson uses the git-upload hotdoc plugin which basically removes the html pages and replaces with the new content. You can simply run: +``` +$ ninja -C built_docs/ upload +``` + +## Contributing to the documentation - ninja -C build/ upload +Commits that only change documentation should have `[skip ci]` in their commit message, so CI is not run (it is quite slow). +For example: +``` +A commit message [skip ci] +``` diff --git a/docs/markdown/Adding-arguments.md b/docs/markdown/Adding-arguments.md index 117622b..8dd8488 100644 --- a/docs/markdown/Adding-arguments.md +++ b/docs/markdown/Adding-arguments.md @@ -37,6 +37,19 @@ You should set only the most essential flags with this setting, you should *not* set debug or optimization flags. Instead they should be specified by selecting an appropriate build type. +Project arguments +-- + +Project arguments work similar to global arguments except that they +are valid only within the current subproject. The usage is simple: + +```meson +add_project_arguments('-DMYPROJ=projname', language : 'c') +``` + +This would add the compiler flags to all C sources in the current +project. + Per target arguments -- diff --git a/docs/markdown/Adding-new-projects-to-wrapdb.md b/docs/markdown/Adding-new-projects-to-wrapdb.md index 00fd0d7..c79cfd3 100644 --- a/docs/markdown/Adding-new-projects-to-wrapdb.md +++ b/docs/markdown/Adding-new-projects-to-wrapdb.md @@ -1,84 +1,120 @@ -# Adding new projects to wrap +# Adding new projects to WrapDB -**If you don't have permissions to do something on this page, please - open issue against https://github.com/mesonbuild/wrapweb/issues to - let us know that you want to start new project.** -## Overview +## How it works -The wrap provider service is a simple web service that makes it easy -to download build definitions for projects. It works in much the same -way as Debian: we take the unaltered upstream source package and add a -new build system to it as a patch. These build systems are stored as -Git repositories on GitHub. They only contain build definition -files. You may also think of them as an overlay to upstream source. +Each wrap repository has a master branch with only one initial commit and *no* wrap files. +And that is the only commit ever made on that branch. -## Creator script +For every release of a project a new branch is created. The new branch is named after the +the upstream release number (e.g. `1.0.0`). This branch holds a wrap file for +this particular release. + +There are two types of wraps on WrapDB - regular wraps and wraps with Meson build +definition patches. A wrap file in a repository on WrapDB must have a name `upstream.wrap`. + +Wraps with Meson build definition patches work in much the same way as Debian: we take the unaltered upstream source package and add a new build system to it as a patch. These build systems are stored as Git repositories on GitHub. They only contain build definition files. You may also think of them as an overlay to upstream source. + +Whenever a new commit is pushed into GitHub's project branch, a new wrap is generated +with an incremented version number. All the old releases remain unaltered. +New commits are always done via GitHub merge requests and must be reviewed by +someone other than the submitter. -The WrapDB repository has a [helper -script](https://github.com/mesonbuild/wrapweb/blob/master/mesonwrap.py) -to generate new repositories, verify them and update them. The documentation below roughly explains -what it does to create a new wrap repository using plain shell commands. +Note that your Git repo with wrap must not contain the subdirectory of the source +release. That gets added automatically by the service. You also must not commit +any source code from the original tarball into the wrap repository. ## Choosing the repository name Wrapped subprojects are used much like external dependencies. Thus -they should have the same name as the upstream projects. If the -project provides a pkg-config file, then the repository name should be +they should have the same name as the upstream projects. + +If the project provides a pkg-config file, then the repository name should be the same as the pkg-config name. Usually this is the name of the project, such as `libpng`. Sometimes it is slightly different, however. As an example the libogg project's chosen pkg-config name is `ogg` instead of `libogg`, which is the reason why the repository is named plain `ogg`. -## Adding new project to the Wrap provider service +If there is no a pkg-config file, the name the project uses/promotes should be used, +lowercase only (Catch2 -> catch2). -Each project gets its own repo. It is initialized like this: +## How to contribute a new wrap - git init - git add readme.txt - git add LICENSE.build - git commit -a -m 'Create project foobar' - git remote add origin <repo url> - git push -u origin master +If the project already uses Meson build system, then only a wrap file - `upstream.wrap` +should be provided. In other case a Meson build definition patch - a set of `meson.build` +files - should be also provided. -Note that this is the *only* commit that will ever be made to master branch. All other commits are done to branches. +### Request a new repository or branch -Repo names must fully match this regexp: `[a-z0-9._]+`. +Create an issue on the [wrapweb bug tracker](https://github.com/mesonbuild/wrapweb/issues) +using *Title* and *Description* below as a template. -## Adding a new branch to an existing project +*Title:* `new wrap: <project_name>` -Create a new branch whose name matches the upstream release number. +*Description:* +``` +upstream url: <link_to_updastream> +version: <version_you_have_a_wrap_for> +``` - git checkout master - git checkout -b 1.0.0 - git push origin 1.0.0 - (or from GitHub web page, remember to branch from master) +Wait until the new repository or branch is created. A link to the new repository or branch +will be posted in a comment to this issue. -Branch names must fully match this regexp: `[a-z0-9._]+`. +### Add a new wrap -## Adding a new release to an existing branch +First you need to fork the repository to your own page. +Then you can create the first Wrap commit that usually looks something like this. -Here is where the magic happens. Whenever a new commit is pushed into GitHub's project branch, a new wrap is generated with an incremented version number. All the old releases remain unaltered. New commits are always done via GitHub merge requests and must be reviewed by someone other than the submitter. +``` +tar xzf libfoo-1.0.0.tar.gz +git clone -b 1.0.0 git@github.com:yourusername/libfoo.git tmpdir +mv tmpdir/.git libfoo-1.0.0 +rm -rf tmpdir +cd libfoo-1.0.0 +git reset --hard +emacs upstream.wrap meson.build +<verify that your project builds and runs> +git add upstream.wrap meson.build +git commit -a -m 'Add wrap files for libfoo-1.0.0' +git push origin 1.0.0 +``` -Note that your Git repo must *not* contain the subdirectory of the source release. That gets added automatically by the service. You also must *not* commit any source code from the original tarball into the wrap repository. +Now you should create a pull request on GitHub. Remember to create it against the +correct branch rather than master (`1.0.0` branch in this example). GitHub should do +this automatically. -First you need to fork the repository to your own page. Then you can create the first Wrap commit that usually looks something like this. +## What is done by WrapDB maintainers - tar xzf libfoo_1.0.0.tar.gz - git clone -b 1.0.0 git@github.com:yourusername/libfoo.git tmpdir - mv tmpdir/.git libfoo-1.0.0 - rm -rf tmpdir - cd libfoo-1.0.0 - git reset --hard - emacs upstream.wrap meson.build - <verify that your project builds and runs> - git add upstream.wrap meson.build - git commit -a -m 'Created wrap files for libfoo-1.0.0.' - git push origin 1.0.0 +### Adding new project to the Wrap provider service -Now you can file a merge request. Remember to file it against branch -1.0.0 rather than master. GitHub should do this automatically. +Each project gets its own repo. It is initialized like this: + +``` +git init +git add readme.txt +git add LICENSE.build +git commit -a -m 'Create project foobar' +git remote add origin <repo url> +git push -u origin master +``` + +Note that this is the *only* commit that will ever be made to master branch. All other commits are done to branches. + +Repo names must fully match this regexp: `[a-z0-9._]+`. + +### Adding a new branch to an existing project + +Create a new branch whose name matches the upstream release number. + +``` +git checkout master +git checkout -b 1.0.0 +git push origin 1.0.0 +(or from GitHub web page, remember to branch from master) +``` + +Branch names must fully match this regexp: `[a-z0-9._]+`. ## Changes to original source @@ -93,6 +129,12 @@ to functionality. All such changes must be submitted to upstream. You may also host your own Git repo with the changes if you wish. The Wrap system has native support for Git subprojects. +## Creator script + +The WrapDB repository has a +[helper script](https://github.com/mesonbuild/wrapweb/blob/master/mesonwrap.py) +to generate new repositories, verify them and update them. + ## Reviewing wraps See [Wrap review guidelines](Wrap-review-guidelines.md). diff --git a/docs/markdown/Builtin-options.md b/docs/markdown/Builtin-options.md index 55352aa..ce14304 100644 --- a/docs/markdown/Builtin-options.md +++ b/docs/markdown/Builtin-options.md @@ -82,6 +82,7 @@ platforms or with all compilers: | b_pgo | off | off, generate, use | Use profile guided optimization | | b_sanitize | none | see below | Code sanitizer to use | | b_staticpic | true | true, false | Build static libraries as position independent | +| b_pie | false | true, false | Build position-independent executables (since 0.49.0)| The value of `b_sanitize` can be one of: `none`, `address`, `thread`, `undefined`, `memory`, `address,undefined`. @@ -119,4 +120,8 @@ compiler being used: The default values of `c_winlibs` and `cpp_winlibs` are in compiler-specific argument forms, but the libraries are: kernel32, user32, gdi32, winspool, -shell32, ole32, oleaut32, uuid, comdlg32, advapi32 +shell32, ole32, oleaut32, uuid, comdlg32, advapi32. + +c_args, cpp_args, c_link_args, and cpp_link_args only affect native builds, +when cross compiling they will not be applied to binaries or libraries +targeting the host system, only those being run on the build system. diff --git a/docs/markdown/Compiler-properties.md b/docs/markdown/Compiler-properties.md index 1228f42..4f5ebdb 100644 --- a/docs/markdown/Compiler-properties.md +++ b/docs/markdown/Compiler-properties.md @@ -29,9 +29,17 @@ Compiler id == The compiler object has a method called `get_id`, which returns a -lower case string describing the "family" of the compiler. See -[reference tables](Reference-tables.md) for a list of supported -compiler ids. +lower case string describing the "family" of the compiler. + +The compiler object also has a method `get_argument_syntax` which +returns a lower case string of `gcc`, `msvc`, or another undefined string +value; identifying whether the compiler arguments use the same syntax as +either `gcc` or `msvc`, or that its arguments are not like either. This should +only be used to select the syntax of the arguments, such as those to test +with `has_argument`. + +See [reference tables](Reference-tables.md#compiler-ids) for a list of supported compiler +ids and their argument type. Does code compile? == diff --git a/docs/markdown/Configuration.md b/docs/markdown/Configuration.md index 8b79bc6..cd1af14 100644 --- a/docs/markdown/Configuration.md +++ b/docs/markdown/Configuration.md @@ -121,6 +121,38 @@ you to specify which file encoding to use. It is however strongly advised to convert your non utf-8 file to utf-8 whenever possible. Supported file encodings are those of python3, see [standard-encodings](https://docs.python.org/3/library/codecs.html#standard-encodings). +## Using dictionaries + +Since *0.49.0* `configuration_data()` takes an optional dictionary as first +argument. If provided, each key/value pair is added into the +`configuration_data` as if `set()` method was called for each of them. +`configure_file()`'s `configuration` kwarg also accepts a dictionary instead of +a configuration_data object. + +Example: +```meson +cdata = configuration_data({ + 'STRING' : '"foo"', + 'INT' : 42, + 'DEFINED' : true, + 'UNDEFINED' : false, +}) + +configure_file(output : 'config1.h', + configuration : cdata, +) + +configure_file(output : 'config2.h', + configuration : { + 'STRING' : '"foo"', + 'INT' : 42, + 'DEFINED' : true, + 'UNDEFINED' : false, + } +) + +``` + # A full example Generating and using a configuration file requires the following steps: diff --git a/docs/markdown/Contributing.md b/docs/markdown/Contributing.md index c0eea29..2881837 100644 --- a/docs/markdown/Contributing.md +++ b/docs/markdown/Contributing.md @@ -156,19 +156,19 @@ subdirectory. They are not run as part of `./run_project_tests.py`. ### Skipping integration tests Meson uses several continuous integration testing systems that have slightly -different interface. To promote consistent naming policy, use: - -- `[skip ci]` in the commit title if you want to disable all integration tests -- `[skip appveyor]` in the commit title if you want to disable Windows-only tests +different interfaces for indicating a commit should be skipped. Continuous integration systems currently used: - -- [Travis-CI](https://docs.travis-ci.com/user/customizing-the-build/#Skipping-a-build) +- [Travis-CI](https://docs.travis-ci.com/user/customizing-the-build#skipping-a-build) allows `[skip ci]` anywhere in the commit messages. -- [AppVeyor](https://www.appveyor.com/docs/how-to/filtering-commits/#skip-directive-in-commit-message) - requires `[skip ci]` or `[skip appveyor]` in the commit title. +- [Azure Pipelines](https://docs.microsoft.com/en-us/azure/devops/pipelines/scripts/git-commands?view=vsts&tabs=yaml#how-do-i-avoid-triggering-a-ci-build-when-the-script-pushes) + allows `***NO_CI***` in the commit message. - [Sider](https://sider.review) - runs Flake8 (see below) + runs Flake8 ([see below](#python-coding-style)) + +To promote consistent naming policy, use: + + - `[skip ci]` in the commit title if you want to disable all integration tests ## Documentation @@ -291,4 +291,3 @@ Environment variables are like global variables, except that they are also hidden by default. Envvars should be avoided whenever possible, all functionality should be exposed in better ways such as command line switches. - diff --git a/docs/markdown/Custom-build-targets.md b/docs/markdown/Custom-build-targets.md index 30a16e3..9a0f2a1 100644 --- a/docs/markdown/Custom-build-targets.md +++ b/docs/markdown/Custom-build-targets.md @@ -27,6 +27,8 @@ This would generate the binary `output.bin` and install it to `${prefix}/subdir/output.bin`. Variable substitution works just like it does for source generation. +See [Generating Sources](Generating-sources.md) for more information on this topic. + ## Details on compiler invocations Meson only permits you to specify one command to run. This is by diff --git a/docs/markdown/D.md b/docs/markdown/D.md index 15de2f7..2b0eaac 100644 --- a/docs/markdown/D.md +++ b/docs/markdown/D.md @@ -14,15 +14,21 @@ project('myapp', 'd') executable('myapp', 'app.d') ``` -## Compiling different versions +## [Conditional compilation](https://dlang.org/spec/version.html) -If you are using the [version()](https://dlang.org/spec/version.html) feature for conditional compilation, +If you are using the [version()](https://dlang.org/spec/version.html#version-specification) feature for conditional compilation, you can use it using the `d_module_versions` target property: ```meson project('myapp', 'd') executable('myapp', 'app.d', d_module_versions: ['Demo', 'FeatureA']) ``` +For debugging, [debug()](https://dlang.org/spec/version.html#debug) conditions are compiled automatically in debug builds, and extra identifiers can be added with the `d_debug` argument: +```meson +project('myapp', 'd') +executable('myapp', 'app.d', d_debug: [3, 'DebugFeatureA']) +``` + ## Using embedded unittests If you are using embedded [unittest functions](https://dlang.org/spec/unittest.html), your source code needs diff --git a/docs/markdown/Dependencies.md b/docs/markdown/Dependencies.md index 08ff1e2..e3fedc4 100644 --- a/docs/markdown/Dependencies.md +++ b/docs/markdown/Dependencies.md @@ -114,13 +114,40 @@ of all the work behind the scenes to make this work. You can use the keyword `method` to let meson know what method to use when searching for the dependency. The default value is `auto`. -Aditional dependencies methods are `pkg-config`, `config-tool`, +Aditional dependencies methods are `pkg-config`, `config-tool`, `cmake`, `system`, `sysconfig`, `qmake`, `extraframework` and `dub`. ```meson cups_dep = dependency('cups', method : 'pkg-config') ``` +The dependency method order for `auto` is: + + 1. `pkg-config` + 2. `cmake` + 3. `extraframework` (OSX only) + +## CMake + +Meson can use the CMake `find_package()` function to detect +dependencies with the builtin `Find<NAME>.cmake` modules and exported +project configurations (usually in `/usr/lib/cmake`). Meson is able +to use both the old-style `<NAME>_LIBRARIES` variables as well as +imported targets. + +It is possible to manually specify a list of CMake targets that should +be used with the `modules` property. Howerver, this step is optional +since meson tries to automatically guess the correct target based on the +name of the dependency. + +Depending on the dependency it may be neccessary to explicitly specify +a CMake target with the `modules` property if meson is unable to guess +it automatically. + +```meson + cmake_dep = dependency('ZLIB', method : 'cmake', modules : ['ZLIB::ZLIB']) +``` + ### Some notes on Dub Please understand that meson is only able to find dependencies that @@ -165,15 +192,16 @@ wmf_dep = dependency('libwmf', method : 'config-tool') ## Dependencies using config tools [CUPS](#cups), [LLVM](#llvm), [pcap](#pcap), [WxWidgets](#wxwidgets), -[libwmf](#libwmf), and GnuStep either do not provide pkg-config +[libwmf](#libwmf), [GCrypt](#libgcrypt), and GnuStep either do not provide pkg-config modules or additionally can be detected via a config tool -(cups-config, llvm-config, etc). Meson has native support for these +(cups-config, llvm-config, libgcrypt-config, etc). Meson has native support for these tools, and they can be found like other dependencies: ```meson pcap_dep = dependency('pcap', version : '>=1.0') cups_dep = dependency('cups', version : '>=1.4') llvm_dep = dependency('llvm', version : '>=4.0') +libgcrypt_dep = dependency('libgcrypt', version: '>= 1.8') ``` ## AppleFrameworks @@ -217,7 +245,7 @@ libraries that have been compiled for single-threaded use instead. ## CUPS -`method` may be `auto`, `config-tool`, `pkg-config` or `extraframework`. +`method` may be `auto`, `config-tool`, `pkg-config`, `cmake` or `extraframework`. ## GL @@ -309,6 +337,12 @@ The `language` keyword may used. `method` may be `auto`, `config-tool` or `pkg-config`. +## libgcrypt + +*(added 0.49.0)* + +`method` may be `auto`, `config-tool` or `pkg-config`. + ## Python3 Python3 is handled specially by meson: diff --git a/docs/markdown/Generating-sources.md b/docs/markdown/Generating-sources.md index cbe6c0d..306bee3 100644 --- a/docs/markdown/Generating-sources.md +++ b/docs/markdown/Generating-sources.md @@ -46,10 +46,79 @@ file individually by index. Then you just put that in your program and you're done. +### Generating headers + +Adding a generated header to a source list will ensure that the header is +generated and that the proper include paths are created for the target: + ```meson -executable('program', 'main.c', gen_src) +prog_python = import('python').find_installation('python3') + +foo_c = custom_target( + 'foo.c', + output : 'foo.c', + input : 'my_gen.py', + command : [prog_python, '@INPUT@', '--code', '@OUTPUT@'], +] + +foo_h = custom_target( + 'foo.h', + output : 'foo.h', + input : 'my_gen.py', + command : [prog_python, '@INPUT@', '--header', '@OUTPUT@'], +] + +libfoo = static_library('foo', [foo_c, foo_h]) + +executable('myexe', ['main.c', foo_h], link_with : libfoo) ``` +Each target that depends on a generated header should add that header to it's sources, +as seen above with `libfoo` and `myexe`. This is because there is no way for +meson or the backend to know that `myexe` depends on `foo.h` just because +`libfoo` does, it could be a private header. + +### Generating multiple files at a time + +Sometimes it makes sense for a single generator to create two or more files at +a time, (perhaps a header and source file), meson has this case covered as +well. `custom_target`s can be indexed like a list to get each output file +separately. The order is the same as the order of the output argument to +`custom_target` + +```meson +prog_python = import('python').find_installation('python3') + +foo_ch = custom_target( + 'foo.[ch]', + output : ['foo.c', 'foo.h'], + input : 'my_gen.py', + command : [prog_python, '@INPUT@', '@OUTPUT@'], +] + +libfoo = static_library('foo', [foo_ch]) + +executable('myexe', ['main.c', foo_ch[1]], link_with : libfoo) +``` + +In this case `libfoo` depends on both `foo.c` and `foo.h` but `myexe` only +depends on `foo.h`, the second output. + +### Using dependencies to manage generated resources + +In some cases it might be easier to use `declare_dependency` to "bundle" the header +and library dependency, especially if there are many generated headers: + +```meson +idep_foo = declare_dependency( + sources : [foo_h, bar_h], + link_with : [libfoo], +) +``` + +See [dependencies](Dependencies.md#declaring-your-own), and +[reference](Reference-manual.md#decalre_dependency) for more information. + ## Using generator() Generators are similar to custom targets, except that we define a diff --git a/docs/markdown/Gnome-module.md b/docs/markdown/Gnome-module.md index cc85d87..dcd843f 100644 --- a/docs/markdown/Gnome-module.md +++ b/docs/markdown/Gnome-module.md @@ -323,6 +323,7 @@ of the module. * `dependencies`: a list of dependencies * `fixxref_args`: a list of arguments to pass to `gtkdoc-fixxref` * `gobject_typesfile`: a list of type files +* `include_directories`: extra include paths to pass to `gtkdoc-scangobj` * `ignore_headers`: a list of header files to ignore * `html_assets`: a list of assets for the HTML pages * `html_args` a list of arguments to pass to `gtkdoc-mkhtml` @@ -332,8 +333,11 @@ of the module. * `main_xml`: specifies the main XML file * `main_sgml`: equal to `main_xml` * `mkdb_args`: a list of arguments to pass to `gtkdoc-mkdb` +* `namespace`: specifies the name space to pass to `gtkdoc-mkdb` +* `module_version`: the version of the module, affects the installed location and the devhelp2 file location * `scan_args`: a list of arguments to pass to `gtkdoc-scan` * `scanobjs_args`: a list of arguments to pass to `gtkdoc-scangobj` +* `c_args`: (*Added 0.48.0*) additional compile arguments to pass * `src_dir`: include_directories to include This creates a `$module-doc` target that can be ran to build docs and diff --git a/docs/markdown/IDE-integration.md b/docs/markdown/IDE-integration.md index 2ce4b78..5f0c0a6 100644 --- a/docs/markdown/IDE-integration.md +++ b/docs/markdown/IDE-integration.md @@ -30,12 +30,48 @@ In order to make code completion work, you need the compiler flags for each comp Note that if the target has dependencies (such as generated sources), then the commands for those show up in this list as well, so you need to do some filtering. Alternatively you can grab every command invocation in the [Clang tools db](https://clang.llvm.org/docs/JSONCompilationDatabase.html) format that is written to a file called `compile_commands.json` in the build directory. +## Build Options + The next thing to display is the list of options that can be set. These include build type and so on. Here's how to extract them. meson introspect --buildoptions +This command returns a list of all supported buildoptions with the format: + +```json +{ + "name": "name of the option", + "description": "the description", + "type": "type ID", + "value": "value depends on type", + "section": "section ID" +} +``` + +The supported types are: + + - string + - boolean + - combo + - integer + - array + +For the type `combo` the key `choices` is also present. Here all valid values for the option are stored. + +The possible values for `section` are: + + - core + - backend + - base + - compiler + - directory + - user + - test + To set the options, use the `meson configure` command. +## Tests + Compilation and unit tests are done as usual by running the `ninja` and `ninja test` commands. A JSON formatted result log can be found in `workspace/project/builddir/meson-logs/testlog.json`. When these tests fail, the user probably wants to run the failing test in a debugger. To make this as integrated as possible, extract the test test setups with this command. diff --git a/docs/markdown/Installing.md b/docs/markdown/Installing.md index 8348d4a..1aa444a 100644 --- a/docs/markdown/Installing.md +++ b/docs/markdown/Installing.md @@ -26,7 +26,7 @@ Other install commands are the following. ```meson install_headers('header.h', subdir : 'projname') # -> include/projname/header.h -install_man('foo.1') # -> share/man/man1/foo.1.gz +install_man('foo.1') # -> share/man/man1/foo.1 install_data('datafile.dat', install_dir : join_paths(get_option('datadir'), 'progname')) # -> share/progname/datafile.dat ``` diff --git a/docs/markdown/Native-environments.md b/docs/markdown/Native-environments.md new file mode 100644 index 0000000..af7edd2 --- /dev/null +++ b/docs/markdown/Native-environments.md @@ -0,0 +1,76 @@ +--- +short-description: Setting up native compilation +... + +# Persistent native environments + +New in 0.49.0 + +Meson has [cross files for describing cross compilation environments](Cross-compilation.md), +for describing native environments it has equivalent "native files". + +Natives describe the *build machine*, and can be used to override properties of +non-cross builds, as well as properties that are marked as "native" in a cross +build. + +There are a couple of reasons you might want to use a native file to keep a +persistent environment: + +* To build with a non-default native tool chain (such as clang instead of gcc) +* To use a non-default version of another binary, such as yacc, or llvm-config + + +## Changing native file settings + +All of the rules about cross files and changed settings apply to native files +as well, see [here](Cross-compilation.md#Changing-cross-file-settings) + + +## Defining the environment + +### Binaries + +Currently the only use of native files is to override native binaries. This +includes the compilers and binaries collected with `find_program`, and those +used by dependencies that use a config-tool instead of pkgconfig for detection, +like `llvm-config` + +```ini +[binaries] +c = '/usr/local/bin/clang' +cpp = '/usr/local/bin/clang++' +rust = '/usr/local/bin/rust' +llvm-conifg = '/usr/local/llvm-svn/bin/llvm-config' +``` + +## Loading multiple native files + +Unlike cross file, native files allow layering. More than one native file can be +loaded, with values from a previous file being overridden by the next. The +intention of this is not overriding, but to allow composing native files. + +For example, if there is a project using C and C++, python 3.4-3.7, and LLVM +5-7, and it needs to build with clang 5, 6, and 7, and gcc 5.x, 6.x, and 7.x; +expressing all of these configurations in monolithic configurations would +result in 81 different native files. By layering them, it can be expressed by +just 12 native files. + + +## Native file locations + +Like cross files, native files may be installed to user or system wide +locations, defined as: + - $XDG_DATA_DIRS/meson/native + (/usr/local/share/meson/native:/usr/share/meson/native if $XDG_DATA_DIRS is + undefined) + - $XDG_DATA_HOME/meson/native ($HOME/.local/share/meson/native if + $XDG_DATA_HOME is undefined) + +The order of locations tried is as follows: + - A file relative to the local dir + - The user local location + - The system wide locations in order + +These files are not intended to be shipped by distributions, unless they are +specifically for distribution packaging, they are mainly intended for +developers. diff --git a/docs/markdown/Pkg-config-files.md b/docs/markdown/Pkg-config-files.md index 0427b0e..305a6d8 100644 --- a/docs/markdown/Pkg-config-files.md +++ b/docs/markdown/Pkg-config-files.md @@ -18,4 +18,4 @@ pkg.generate(libraries : libs, This causes a file called `simple.pc` to be created and placed into the install directory during the install phase. -More infromation on the pkg-config module and the parameters can be found on the [pkgconfig-module](http://mesonbuild.com/Pkgconfig-module.html) page. +More infromation on the pkg-config module and the parameters can be found on the [pkgconfig-module](Pkgconfig-module.md) page. diff --git a/docs/markdown/Pkgconfig-module.md b/docs/markdown/Pkgconfig-module.md index 77db809..9a34e14 100644 --- a/docs/markdown/Pkgconfig-module.md +++ b/docs/markdown/Pkgconfig-module.md @@ -14,16 +14,16 @@ can, of course, replace the name `pkg` with anything else. The generated file's properties are specified with the following keyword arguments. -- `description` a string describing the library +- `description` a string describing the library, used to set the `Description:` field - `extra_cflags` a list of extra compiler flags to be added to the `Cflags` field after the header search path -- `filebase`, the base name to use for the pkg-config file, as an - example the value of `libfoo` would produce a pkg-config file called +- `filebase` the base name to use for the pkg-config file; as an + example, the value of `libfoo` would produce a pkg-config file called `libfoo.pc` - `install_dir` the directory to install to, defaults to the value of option `libdir` followed by `/pkgconfig` - `libraries` a list of built libraries (usually results of - shared_library) that the user needs to link against. Arbitraty strings can + shared_library) that the user needs to link against. Arbitrary strings can also be provided and they will be added into the `Libs` field. Since 0.45.0 dependencies of built libraries will be automatically added to `Libs.private` field. If a dependency is provided by pkg-config then it will be added in @@ -33,7 +33,7 @@ keyword arguments. - `libraries_private` list of built libraries or strings to put in the `Libs.private` field. Since 0.45.0 it can also contain dependency objects, their `link_args` will be added to `Libs.private`. -- `name` the name of this library +- `name` the name of this library, used to set the `Name:` field - `subdirs` which subdirs of `include` should be added to the header search path, for example if you install headers into `${PREFIX}/include/foobar-1`, the correct value for this argument @@ -48,7 +48,8 @@ keyword arguments. reference other pkgconfig variables, e.g. `datadir=${prefix}/share`. The names `prefix`, `libdir` and `installdir` are reserved and may not be used. -- `version` a string describing the version of this library +- `version` a string describing the version of this library, used to set the + `Version:` field. Defaults to the project version if unspecified. - `d_module_versions` a list of module version flags used when compiling D sources referred to by this pkg-config file diff --git a/docs/markdown/Python-3-module.md b/docs/markdown/Python-3-module.md index 7dda672..50ec4e4 100644 --- a/docs/markdown/Python-3-module.md +++ b/docs/markdown/Python-3-module.md @@ -3,14 +3,19 @@ This module provides support for dealing with Python 3. It has the following methods. +This module is deprecated and replaced by the [python](Python-module.md) module. + ## find_python This is a cross platform way of finding the Python 3 executable, which may have a different name on different operating systems. Returns an -[external program](Reference-manual.html#external-program-object) object. +[external program](Reference-manual.md#external-program-object) object. *Added 0.38.0* +Deprecated, replaced by [`find_installation`](Python-module.md#find_installation) +function from `python` module. + ## extension_module Creates a `shared_module` target that is named according to the naming @@ -24,15 +29,24 @@ need to add `dependencies : dependency('python3')`, see *Added 0.38.0* +Deprecated, replaced by [`extension_module`](Python-module.md#extension_module) +method from `python` module. + ## language_version Returns a string with the Python language version such as `3.5`. *Added 0.40.0* +Deprecated, replaced by [`language_version`](Python-module.md#language_version) +method from `python` module. + ## sysconfig_path Returns the Python sysconfig path without prefix, such as `lib/python3.6/site-packages`. *Added 0.40.0* + +Deprecated, replaced by [`get_path`](Python-module.md#get_path) +method from `python` module. diff --git a/docs/markdown/Python-module.md b/docs/markdown/Python-module.md index 51721f0..a50a33d 100644 --- a/docs/markdown/Python-module.md +++ b/docs/markdown/Python-module.md @@ -45,7 +45,12 @@ Keyword arguments are the following: abort if no python installation can be found. If `required` is set to `false`, Meson will continue even if no python installation was found. You can then use the `.found()` method on the returned object to check - whether it was found or not. + whether it was found or not. Since *0.48.0* the value of a + [`feature`](Build-options.md#features) option can also be passed to the + `required` keyword argument. +- `disabler`: if `true` and no python installation can be found, return a + [disabler object](Reference-manual.md#disabler-object) instead of a not-found object. + *Since 0.49.0* **Returns**: a [python installation][`python_installation` object] diff --git a/docs/markdown/Qt5-module.md b/docs/markdown/Qt5-module.md index 46fbd84..3a51954 100644 --- a/docs/markdown/Qt5-module.md +++ b/docs/markdown/Qt5-module.md @@ -9,6 +9,9 @@ This method takes the following keyword arguments: - `moc_headers`, `moc_sources`, `ui_files`, `qresources`, which define the files that require preprocessing with `moc`, `uic` and `rcc` - `include_directories`, the directories to add to header search path for `moc` (optional) - `moc_extra_arguments`, any additional arguments to `moc` (optional). Available since v0.44.0. + - `uic_extra_arguments`, any additional arguments to `uic` (optional). Available since v0.49.0. + - `rcc_extra_arguments`, any additional arguments to `rcc` (optional). Available since v0.49.0. + - `dependencies`, dependency objects needed by moc. Available since v0.48.0. It returns an opaque object that should be passed to a main build target. @@ -39,7 +42,8 @@ qt5_dep = dependency('qt5', modules: ['Core', 'Gui']) inc = include_directories('includes') moc_files = qt5.preprocess(moc_headers : 'myclass.h', moc_extra_arguments: ['-DMAKES_MY_MOC_HEADER_COMPILE'], - include_directories: inc) + include_directories: inc, + dependencies: qt5_dep) translations = qt5.compile_translations(ts_files : 'myTranslation_fr.ts', build_by_default : true) executable('myprog', 'main.cpp', 'myclass.cpp', moc_files, include_directories: inc, diff --git a/docs/markdown/Reference-manual.md b/docs/markdown/Reference-manual.md index b616d3e..a723b03 100644 --- a/docs/markdown/Reference-manual.md +++ b/docs/markdown/Reference-manual.md @@ -105,6 +105,9 @@ the following: - `exe_wrapper` a list containing the wrapper command or script followed by the arguments to it - `gdb` if `true`, the tests are also run under `gdb` - `timeout_multiplier` a number to multiply the test timeout with +- `is_default` a bool to set whether this is the default test setup. + If `true`, the setup will be used whenever `meson test` is run + without the `--setup` option. Since 0.49.0 To use the test setup, run `meson test --setup=*name*` inside the build dir. @@ -112,6 +115,14 @@ Note that all these options are also available while running the `meson test` script for running tests instead of `ninja test` or `msbuild RUN_TESTS.vcxproj`, etc depending on the backend. +### assert() + +``` meson + void assert(*condition*, *message*) +``` + +Abort with an error message if `condition` evaluates to `false`. + ### benchmark() ``` meson @@ -167,13 +178,17 @@ methods section](#build-target-object) below. ### configuration_data() ``` meson - configuration_data_object = configuration_data() + configuration_data_object = configuration_data(...) ``` Creates an empty configuration object. You should add your configuration with [its method calls](#configuration-data-object) and finally use it in a call to `configure_file`. +Since *0.49.0* takes an optional dictionary as first argument. If provided, each +key/value pair is added into the `configuration_data` as if `set()` method was +called for each of them. + ### configure_file() ``` meson @@ -187,7 +202,8 @@ When a [`configuration_data()`](#configuration_data) object is passed to the `configuration:` keyword argument, it takes a template file as the `input:` (optional) and produces the `output:` (required) by substituting values from the configuration data as detailed in [the -configuration file documentation](Configuration.md). +configuration file documentation](Configuration.md). Since *0.49.0* a dictionary +can be passed instead of a [`configuration_data()`](#configuration_data) object. When a list of strings is passed to the `command:` keyword argument, it takes any source or configured file as the `input:` and assumes @@ -242,7 +258,7 @@ Create a custom top level build target. The only positional argument is the name of this target and the keyword arguments are the following. -- `build_by_default` *(added 0.38.0)* causes, when set to true, to +- `build_by_default` *(added 0.38)* causes, when set to true, to have this target be built by default, that is, when invoking plain `ninja`; the default value is false - `build_always` (deprecated) if `true` this target is always considered out of @@ -256,7 +272,7 @@ following. this argument is set to true, Meson captures `stdout` and writes it to the target file. Note that your command argument list may not contain `@OUTPUT@` when capture mode is active. -- `console` keyword argument conflicts with `capture`, and is meant +- `console` *(added 0.48)* keyword argument conflicts with `capture`, and is meant for commands that are resource-intensive and take a long time to finish. With the Ninja backend, setting this will add this target to [Ninja's `console` pool](https://ninja-build.org/manual.html#_the_literal_console_literal_pool), @@ -349,10 +365,10 @@ keyword arguments. ``` Finds an external dependency (usually a library installed on your -system) with the given name with `pkg-config` if possible, as a -framework (OSX only), and with +system) with the given name with `pkg-config` and [with CMake](Dependencies.md#CMake) +if `pkg-config` fails. Additionally, frameworks (OSX only) and [library-specific fallback detection logic](Dependencies.md#dependencies-with-custom-lookup-functionality) -otherwise. This function supports the following keyword arguments: +are also supported. This function supports the following keyword arguments: - `default_options` *(added 0.37.0)* an array of default option values that override those set in the subproject's `meson_options.txt` @@ -395,6 +411,9 @@ otherwise. This function supports the following keyword arguments: [library-specific](Dependencies.md#dependencies-with-custom-lookup-functionality) keywords may also be accepted (e.g. `modules` specifies submodules to use for dependencies such as Qt5 or Boost. ) +- `disabler` if `true` and the dependency couldn't be found, return a + [disabler object](#disabler-object) instead of a not-found dependency. + *Since 0.49.0* If dependency_name is `''`, the dependency is always not found. So with `required: false`, this always returns a dependency object for which the @@ -537,7 +556,9 @@ be passed to [shared and static libraries](#library). - `d_import_dirs` list of directories to look in for string imports used in the D programming language - `d_unittest`, when set to true, the D modules are compiled in debug mode -- `d_module_versions` list of module versions set when compiling D sources +- `d_module_versions` list of module version identifiers set when compiling D sources +- `d_debug` list of module debug identifiers set when compiling D sources +- `pie` *(added 0.49.0)* build a position-independent executable The list of `sources`, `objects`, and `dependencies` is always flattened, which means you can freely nest and add lists while @@ -585,6 +606,10 @@ Keyword arguments are the following: defined there, then from the system. If set to `true`, the cross file is ignored and the program is only searched from the system. +- `disabler` if `true` and the program couldn't be found, return a + [disabler object](#disabler-object) instead of a not-found object. + *Since 0.49.0* + Meson will also autodetect scripts with a shebang line and run them with the executable/interpreter specified in it both on Windows (because the command invocator will reject the command otherwise) and @@ -679,6 +704,7 @@ argument also accepts the following: - `@OUTPUT@`: the full path to the output file - `@INPUT@`: the full path to the input file +- `@DEPFILE@`: the full path to the depfile - `@SOURCE_DIR@`: the full path to the root of the source tree - `@CURRENT_SOURCE_DIR@`: this is the directory where the currently processed meson.build is located in - `@BUILD_DIR@`: the full path to the root of the build dir where the output will be placed @@ -893,8 +919,7 @@ An example value could be `['rwxr-sr-x', 'root', 'root']`. Installs the specified man files from the source tree into system's man directory during the install step. This directory can be overridden by specifying it with the `install_dir` keyword -argument. All man pages are compressed during installation and -installed with a `.gz` suffix. +argument. The `install_mode` argument can be used to specify the file mode in symbolic format and optionally the owner/uid and group/gid for the installed files. @@ -983,7 +1008,7 @@ the jar with `java -jar file.jar`. ### join_paths() ``` meson - string join_paths(string1, string2, ...) +string join_paths(string1, string2, ...) ``` Joins the given strings into a file system path segment. For example @@ -993,6 +1018,15 @@ dropped. That means that `join_paths('foo', '/bar')` returns `/bar`. *Added 0.36.0* +Since 0.49.0 using the`/` operator on strings is equivalent to calling +`join_paths`. + +```meson +# res1 and res2 will have identical values +res1 = join_paths(foo, bar) +res2 = foo / bar +``` + ### library() ``` meson @@ -1172,6 +1206,9 @@ and subdirectory the target was defined in, respectively. Assigns a value to the given variable name. Calling `set_variable('foo', bar)` is equivalent to `foo = bar`. +**Note:** Prior to v0.46.1, the `value` parameter could not be an +array type, due to flattening of the function parameters. + ### shared_library() ``` meson @@ -1405,7 +1442,7 @@ be up to date on every build. Keywords are similar to `custom_target`. Meson will read the contents of `input`, substitute the `replace_string` with the detected revision number, and write the -result to `output`. This method returns a +result to `output`. This method returns a [`custom_target`](#custom_target) object that (as usual) should be used to signal dependencies if other targets use the file outputted by this. @@ -1428,14 +1465,14 @@ The `meson` object allows you to introspect various properties of the system. This object is always mapped in the `meson` variable. It has the following methods. -- `add_dist_script` causes the script given as argument to run during +- `add_dist_script(script_name, arg1, arg, ...)` causes the script given as argument to run during `dist` operation after the distribution source has been generated but before it is archived. Note that this runs the script file that is in the _staging_ directory, not the one in the source directory. If the script file can not be found in the staging directory, it is a hard error. This command can only invoked from the main project, calling it from a subproject is a hard - error. Available since 0.48.0. + error. Available since 0.48.0. Before 0.49.0, the function only accepted a single argument. - `add_install_script(script_name, arg1, arg2, ...)` causes the script given as an argument to be run during the install step, this script @@ -1530,7 +1567,7 @@ the following methods. compilation to reduce build time) and `false` otherwise. - `override_find_program(progname, program)` [*(Added - 0.46.0)*](Release-notes-for-0-46-0.html#can-override-find_program) + 0.46.0)*](Release-notes-for-0.46.0.md#can-override-find_program) specifies that whenever `find_program` is used to find a program named `progname`, Meson should not not look it up on the system but instead return `program`, which may either be the result of @@ -1564,7 +1601,7 @@ methods: etc. - `system()` returns the operating system name. [This - table](Reference-tables.html#operating-system-names) Lists all of + table](Reference-tables.md#operating-system-names) Lists all of the currently known Operating System names, these are guaranteed to continue working. @@ -1622,6 +1659,9 @@ the following methods: the positional argument, you can specify external dependencies to use with `dependencies` keyword argument. +- `cmd_array()` returns an array containing the command arguments for + the current compiler. + - `compiles(code)` returns true if the code fragment given in the positional argument compiles, you can specify external dependencies to use with `dependencies` keyword argument, `code` can be either a @@ -1645,6 +1685,9 @@ the following methods: argument, which can be either a string or a list of strings. Since *0.47.0* the value of a [`feature`](Build-options.md#features) option can also be passed to the `required` keyword argument. + *Since 0.49.0* if the keyword argument `disabler` is `true` and the + dependency couldn't be found, return a [disabler object](#disabler-object) + instead of a not-found dependency. - `first_supported_argument(list_of_strings)`, given a list of strings, returns the first argument that passes the `has_argument` @@ -1660,7 +1703,14 @@ the following methods: the compiler would. E.g. `"a" "b"` will become `"ab"`. - `get_id()` returns a string identifying the compiler. For example, - `gcc`, `msvc`, [and more](Reference-tables.html#compiler-ids). + `gcc`, `msvc`, [and more](Reference-tables.md#compiler-ids). + +- `get_argument_syntax()` *(new in 0.49.0)* returns a string identifying the type + of arguments the compiler takes. Can be one of `gcc`, `msvc`, or an undefined + string value. This method is useful for identifying compilers that are not + gcc or msvc, but use the same argument syntax as one of those two compilers + such as clang or icc, especially when they use different syntax on different + operating systems. - `get_supported_arguments(list_of_string)` *(added 0.43.0)* returns an array containing only the arguments supported by the compiler, @@ -1759,7 +1809,7 @@ the following methods: compiler supports the GNU style (`__attribute__(...)`) `name`. This is preferable to manual compile checks as it may be optimized for compilers that do not support such attributes. - [This table](Reference-tables.html#gcc-attribute-support) Lists all of the + [This table](Reference-tables.md#gcc-__attribute__) lists all of the supported attributes. - `get_supported_function_attributes(list_of_names)` *(added in 0.48.0) @@ -1773,7 +1823,7 @@ The following keyword arguments can be used: required to find the header or symbol. For example, you might need to pass the include path `-Isome/path/to/header` if a header is not in the default include path. In versions newer than 0.38.0 you - should use the `include_directories` keyword described above. You + should use the `include_directories` keyword described below. You may also want to pass a library name `-lfoo` for `has_function` to check for a function. Supported by all methods except `get_id`, `version`, and `find_library`. @@ -1786,6 +1836,9 @@ The following keyword arguments can be used: `run()`. If this keyword argument is not passed to those methods, no message will be printed about the check. +- `no_builtin_args` when set to true, the compiler arguments controlled + by built-in configuration options are not added. + - `prefix` can be used to add #includes and other things that are required for the symbol to be declared. System definitions should be passed via compiler args (eg: `_GNU_SOURCE` is often required for @@ -1794,7 +1847,7 @@ The following keyword arguments can be used: `sizeof`, `has_type`, `has_function`, `has_member`, `has_members`, `check_header`, `has_header`, `has_header_symbol`. -**Note:** These compiler checks do not use compiler arguments added with +**Note:** These compiler checks do not use compiler arguments added with `add_*_arguments()`, via `-Dlang_args` on the command-line, or through `CFLAGS`/`LDFLAGS`, etc in the environment. Hence, you can trust that the tests will be fully self-contained, and won't fail because of custom diff --git a/docs/markdown/Reference-tables.md b/docs/markdown/Reference-tables.md index ab79abd..b561e86 100644 --- a/docs/markdown/Reference-tables.md +++ b/docs/markdown/Reference-tables.md @@ -2,38 +2,41 @@ ## Compiler ids -These are return values of the `get_id` method in a compiler object. - -| Value | Compiler family | -| ----- | ---------------- | -| gcc | The GNU Compiler Collection | -| clang | The Clang compiler | -| msvc | Microsoft Visual Studio | -| intel | Intel compiler | -| llvm | LLVM-based compiler (Swift, D) | -| mono | Xamarin C# compiler | -| dmd | D lang reference compiler | -| rustc | Rust compiler | -| valac | Vala compiler | -| pathscale | The Pathscale Fortran compiler | -| pgi | The Portland Fortran compiler | -| sun | Sun Fortran compiler | -| g95 | The G95 Fortran compiler | -| open64 | The Open64 Fortran Compiler | -| nagfor | The NAG Fortran compiler | -| lcc | Elbrus C/C++/Fortran Compiler | -| arm | ARM compiler | -| armclang | ARMCLANG compiler | +These are return values of the `get_id` (Compiler family) and +`get_argument_syntax` (Argument syntax) method in a compiler object. + +| Value | Compiler family | Argument syntax | +| ----- | --------------- | --------------- | +| arm | ARM compiler | | +| armclang | ARMCLANG compiler | | +| ccrx | Renesas RX Family C/C++ compiler | | +| clang | The Clang compiler | gcc | +| clang-cl | The Clang compiler (MSVC compatible driver) | msvc | +| dmd | D lang reference compiler | | +| g95 | The G95 Fortran compiler | | +| gcc | The GNU Compiler Collection | gcc | +| intel | Intel compiler | msvc on windows, otherwise gcc | +| lcc | Elbrus C/C++/Fortran Compiler | | +| llvm | LLVM-based compiler (Swift, D) | | +| mono | Xamarin C# compiler | | +| msvc | Microsoft Visual Studio | msvc | +| nagfor | The NAG Fortran compiler | | +| open64 | The Open64 Fortran Compiler | | +| pathscale | The Pathscale Fortran compiler | | +| pgi | The Portland Fortran compiler | | +| rustc | Rust compiler | | +| sun | Sun Fortran compiler | | +| valac | Vala compiler | | ## Script environment variables | Value | Comment | | ----- | ------- | -| MESON_SOURCE_ROOT | Absolute path to the source dir | -| MESON_BUILD_ROOT | Absolute path to the build dir | | MESONINTROSPECT | Command to run to run the introspection command, may be of the form `python /path/to/meson introspect`, user is responsible for splitting the path if necessary. | -| MESON_SUBDIR | Current subdirectory, only set for `run_command` | +| MESON_BUILD_ROOT | Absolute path to the build dir | | MESON_DIST_ROOT | Points to the root of the staging directory, only set when running `dist` scripts | +| MESON_SOURCE_ROOT | Absolute path to the source dir | +| MESON_SUBDIR | Current subdirectory, only set for `run_command` | ## CPU families @@ -44,40 +47,48 @@ set in the cross file. | Value | Comment | | ----- | ------- | -| x86 | 32 bit x86 processor | -| x86_64 | 64 bit x86 processor | -| ia64 | Itanium processor | -| arm | 32 bit ARM processor | | aarch64 | 64 bit ARM processor | +| arc | 32 bit ARC processor | +| arm | 32 bit ARM processor | +| e2k | MCST Elbrus processor | +| ia64 | Itanium processor | | mips | 32 bit MIPS processor | | mips64 | 64 bit MIPS processor | +| parisc | HP PA-RISC processor | | ppc | 32 bit PPC processors | | ppc64 | 64 bit PPC processors | -| e2k | MCST Elbrus processor | -| parisc | HP PA-RISC processor | | riscv32 | 32 bit RISC-V Open ISA| | riscv64 | 64 bit RISC-V Open ISA| +| rx | Renesas RX 32 bit MCU | +| s390x | IBM zSystem s390x | | sparc | 32 bit SPARC | | sparc64 | SPARC v9 processor | -| s390x | IBM zSystem s390x | +| x86 | 32 bit x86 processor | +| x86_64 | 64 bit x86 processor | Any cpu family not listed in the above list is not guaranteed to remain stable in future releases. +Those porting from autotools should note that meson does not add +endianness to the name of the cpu_family. For example, autotools +will call little endian PPC64 "ppc64le", meson will not, you must +also check the `.endian()` value of the machine for this information. + ## Operating system names These are provided by the `.system()` method call. | Value | Comment | | ----- | ------- | -| linux | | -| darwin | Either OSX or iOS | -| windows | Any version of Windows | | cygwin | The Cygwin environment for Windows | -| haiku | | -| freebsd | FreeBSD and its derivatives | +| darwin | Either OSX or iOS | | dragonfly | DragonFly BSD | +| freebsd | FreeBSD and its derivatives | +| gnu | GNU Hurd | +| haiku | | +| linux | | | netbsd | | +| windows | Any version of Windows | Any string not listed above is not guaranteed to remain stable in future releases. @@ -100,6 +111,19 @@ These are the parameter names for passing language specific arguments to your bu | Rust | rust_args | | Vala | vala_args | +## Compiler and linker flag environment variables + +These environment variables will be used to modify the compiler and +linker flags. + +| CFLAGS | Flags for the C compiler | +| CXXFLAGS | Flags for the C++ compiler | +| OBJCFLAGS | Flags for the Objective C compiler | +| FFLAGS | Flags for the Fortran compiler | +| DFLAGS | Flags for the D compiler | +| VALAFLAGS | Flags for the Vala compiler | +| RUSTFLAGS | Flags for the Rust compiler | +| LDFLAGS | The linker flags, used for all languages | ## Function Attributes @@ -107,7 +131,7 @@ These are the parameters names that are supported using `compiler.has_function_attribute()` or `compiler.get_supported_function_attributes()` -### GCC __attribute__ +### GCC `__attribute__` These values are supported using the GCC style `__attribute__` annotations, which are supported by GCC, Clang, and other compilers. diff --git a/docs/markdown/Release-notes-for-0.47.0.md b/docs/markdown/Release-notes-for-0.47.0.md index 9736256..a427a72 100644 --- a/docs/markdown/Release-notes-for-0.47.0.md +++ b/docs/markdown/Release-notes-for-0.47.0.md @@ -34,11 +34,10 @@ The environment path should be set properly for the ARM compiler executables. The `--target`, `-mcpu` options with the appropriate values should be mentioned in the cross file as shown in the snippet below. -``` +```ini [properties] c_args = ['--target=arm-arm-none-eabi', '-mcpu=cortex-m0plus'] cpp_args = ['--target=arm-arm-none-eabi', '-mcpu=cortex-m0plus'] - ``` Note: @@ -106,7 +105,7 @@ When called without an input file, `configure_file` generates a C header file by default. A keyword argument was added to allow specifying the output format, for example for use with nasm or yasm: -``` +```meson conf = configuration_data() conf.set('FOO', 1) diff --git a/docs/markdown/Release-notes-for-0.48.0.md b/docs/markdown/Release-notes-for-0.48.0.md index cf3db4c..99673a4 100644 --- a/docs/markdown/Release-notes-for-0.48.0.md +++ b/docs/markdown/Release-notes-for-0.48.0.md @@ -1,17 +1,307 @@ --- title: Release 0.48 -short-description: Release notes for 0.48 (preliminary) +short-description: Release notes for 0.48 ... # New features -This page is a placeholder for the eventual release notes. +## Toggles for build type, optimization and vcrt type -Notable new features should come with release note updates. This is -done by creating a file snippet called `snippets/featurename.md` and -whose contents should look like this: +Since the very beginning Meson has provided different project types to +use, such as *debug* and *minsize*. There is also a *plain* type that +adds nothing by default but instead makes it the user's responsibility +to add everything by hand. This works but is a bit tedious. - ## Feature name +In this release we have added new new options to manually toggle +e.g. optimization levels and debug info so those can be changed +independently of other options. For example by default the debug +buildtype has no optmization enabled at all. If you wish to use GCC's +`-Og` instead, you could set it with the following command: - A short description explaining the new feature and how it should be used. +``` +meson configure -Doptimization=g +``` +Similarly we have added a toggle option to select the version of +Visual Studio C runtime to use. By default it uses the debug runtime +DLL debug builds and release DLL for release builds but this can be +manually changed with the new base option `b_vscrt`. + +## Meson warns if two calls to `configure_file()` write to the same file + +If two calls to [`configure_file()`](#Reference-manual.md#configure_file) +write to the same file Meson will print a `WARNING:` message during +configuration. For example: +```meson +project('configure_file', 'cpp') + +configure_file( + input: 'a.in', + output: 'out', + command: ['./foo.sh'] +) +configure_file( + input: 'a.in', + output: 'out', + command: ['./foo.sh'] +) +``` + +This will output: + +``` +The Meson build system +Version: 0.47.0.dev1 +Source dir: /path/to/srctree +Build dir: /path/to/buildtree +Build type: native build +Project name: configure_file +Project version: undefined +Build machine cpu family: x86_64 +Build machine cpu: x86_64 +Configuring out with command +WARNING: Output file out for configure_file overwritten. First time written in line 3 now in line 8 +Configuring out with command +Build targets in project: 0 +Found ninja-1.8.2 at /usr/bin/ninja +``` + +## New kwarg `console` for `custom_target()` + +This keyword argument conflicts with `capture`, and is meant for +commands that are resource-intensive and take a long time to +finish. With the Ninja backend, setting this will add this target to +[Ninja's `console` +pool](https://ninja-build.org/manual.html#_the_literal_console_literal_pool), +which has special properties such as not buffering stdout and +serializing all targets in this pool. + +The primary use-case for this is to be able to run external commands +that take a long time to exeute. Without setting this, the user does +not receive any feedback about what the program is doing. + +## `dependency(version:)` now applies to all dependency types + +Previously, version constraints were only enforced for dependencies found using +the pkg-config dependency provider. These constraints now apply to dependencies +found using any dependency provider. + +Some combinations of dependency, host and method do not currently support +discovery of the version. In these cases, the dependency will not be found if a +version constraint is applied, otherwise the `version()` method for the +dependency object will return `'unknown'`. + +(If discovering the version in one of these combinations is important to you, +and a method exists to determine the version in that case, please file an issue +with as much information as possible.) + +## python3 module is deprecated + +A generic module `python` has been added in Meson `0.46.0` and has a superset of +the features implemented by the previous `python3` module. + +In most cases, it is a simple matter of renaming: +```meson +py3mod = import('python3') +python = py3mod.find_python() +``` + +becomes + +```meson +pymod = import('python') +python = pymod.find_installation() +``` + +## Dictionary addition + +Dictionaries can now be added, values from the second dictionary overrides values +from the first + +```meson +d1 = {'a' : 'b'} +d3 = d1 + {'a' : 'c'} +d3 += {'d' : 'e'} +``` + +## Dist scripts + +You can now specify scripts that are run as part of the `dist` +target. An example usage would go like this: + +```meson +project('foo', 'c') + +# other stuff here + +meson.add_dist_script('dist_cleanup.py') +``` + +## Fatal warnings + +A new command line option has been added: `--fatal-meson-warnings`. When enabled, any +warning message printed by Meson will be fatal and raise an exception. It is +intended to be used by developers and CIs to easily catch deprecation warnings, +or any other potential issues. + +## Helper methods added for checking GNU style attributes: `__attribute__(...)` + +A set of new helpers have been added to the C and C++ compiler objects for +checking GNU style function attributes. These are not just simpler to use, they +may be optimized to return fast on compilers that don't support these +attributes. Currently this is true for MSVC. + +```meson +cc = meson.get_compiler('c') +if cc.has_function_attribute('aligned') + add_project_arguments('-DHAVE_ALIGNED', language : 'c') +endif +``` + +Would replace code like: + +```meson +if cc.compiles('''into foo(void) __attribute__((aligned(32)))''') + add_project_arguments('-DHAVE_ALIGNED', language : 'c') +endif +``` + +Additionally, a multi argument version has been added: + +```meson +foreach s : cc.get_supported_function_attributes(['hidden', 'alias']) + add_project_arguments('-DHAVE_@0@'.format(s.to_upper()), language : 'c') +endforeach +``` + +## `gnome.generate_gir()` now optionally accepts multiple libraries + +The GNOME module can now generate a single gir for multiple libraries, which +is something `g-ir-scanner` supported, but had not been exposed yet. + +gnome.generate_gir() will now accept multiple positional arguments, if none +of these arguments are an `Executable` instance. + +## Hotdoc module + +A new module has been written to ease generation of +[hotdoc](https://hotdoc.github.io/) based documentation. It supports +complex use cases such as hotdoc subprojects (to create documentation +portals) and makes it straight forward to leverage full capabilities +of hotdoc. + +Simple usage: + +``` meson +hotdoc = import('hotdoc') + +hotdoc.generate_doc( + 'foobar', + c_smart_index: true, + project_version: '0.1', + sitemap: 'sitemap.txt', + index: 'index.md', + c_sources: ['path/to/file.c'], + languages: ['c'], + install: true, +) +``` + +## `i18n.merge_file()` now fully supports variable substitutions defined in `custom_target()` + +Filename substitutions like @BASENAME@ and @PLAINNAME@ were previously +accepted but the name of the build target wasn't altered leading to +colliding target names when using the substitution twice. +i18n.merge_file() now behaves as custom_target() in this regard. + +## Projects args can be set separately for cross and native builds (potentially breaking change) + +It has been a longstanding bug (or let's call it a "delayed bug fix") +that if yo do this: + +```meson +add_project_arguments('-DFOO', language : 'c') +``` + +Then the flag is used both in native and cross compilations. This is +very confusing and almost never what you want. To fix this a new +keyword `native` has been added to all functions that add arguments, +namely `add_global_arguments`, `add_global_link_arguments`, +`add_project_arguments` and `add_project_link_arguments` that behaves +like the following: + +```meson +# Added to native builds when compiling natively and to cross +# compilations when doing cross compiles. +add_project_arguments(...) + +# Added only to native compilations, not used in cross compilations. +add_project_arguments(..., native : true) + +# Added only to cross compilations, not used in native compilations. +add_project_arguments(..., native : false) +``` + +Also remember that cross compilation is a property of each +target. There can be target that are compiled with the native compiler +and some which are compiled with the cross compiler. + +Unfortunately this change is backwards incompatible and may cause some +projects to fail building. However this should be very rare in practice. + +## More flexible `override_find_program()`. + +It is now possible to pass an `executable` to +`override_find_program()` if the overridden program is not used during +configure. + +This is particularly useful for fallback dependencies like Protobuf +that also provide a tool like protoc. + +## `shared_library()` now supports setting dylib compatibility and current version + +Now, by default `shared_library()` sets `-compatibility_version` and +`-current_version` of a macOS dylib using the `soversion`. + +This can be overriden by using the `darwin_versions:` kwarg to +[`shared_library()`](Reference-manual.md#shared_library). As usual, you can +also pass this kwarg to `library()` or `build_target()` and it will be used in +the appropriate circumstances. + +## Version comparison + +`dependency(version:)` and other version constraints now handle versions +containing non-numeric characters better, comparing versions using the rpmvercmp +algorithm (as using the `pkg-config` autoconf macro `PKG_CHECK_MODULES` does). + +This is a breaking change for exact comparison constraints which rely on the +previous comparison behaviour of extending the compared versions with `'0'` +elements, up to the same length of `'.'`-separated elements. + +For example, a version of `'0.11.0'` would previously match a version constraint +of `'==0.11'`, but no longer does, being instead considered strictly greater. + +Instead, use a version constraint which exactly compares with the precise +version required, e.g. `'==0.11.0'`. + +## Keyword argument for GNU symbol visibility + +Build targets got a new keyword, `gnu_symbol_visibility` that controls +how symbols are exported from shared libraries. This is most commonly +used to hide implementation symbols like this: + +```meson +shared_library('mylib', ... + gnu_symbol_visibility: 'hidden') +``` + +In this case only symbols explicitly marked as visible in the source +files get exported. + +## Git wraps can now clone submodules automatically + +To enable this, the following needs to be added to the `.wrap` file: + +```ini +clone-recursive=true +``` diff --git a/docs/markdown/Release-notes-for-0.49.0.md b/docs/markdown/Release-notes-for-0.49.0.md new file mode 100644 index 0000000..bdf5769 --- /dev/null +++ b/docs/markdown/Release-notes-for-0.49.0.md @@ -0,0 +1,22 @@ +--- +title: Release 0.49 +short-description: Release notes for 0.49 (preliminary) +... + +# New features + +This page is a placeholder for the eventual release notes. + +Notable new features should come with release note updates. This is +done by creating a file snippet called `snippets/featurename.md` and +whose contents should look like this: + + ## Feature name + + A short description explaining the new feature and how it should be used. + +## Libgcrypt dependency now supports libgcrypt-config + +Earlier, `dependency('libgcrypt')` could only detect the library with pkg-config +files. Now, if pkg-config files are not found, Meson will look for +`libgcrypt-config` and if it's found, will use that to find the library. diff --git a/docs/markdown/Running-Meson.md b/docs/markdown/Running-Meson.md index 00b70ed..426e87d 100644 --- a/docs/markdown/Running-Meson.md +++ b/docs/markdown/Running-Meson.md @@ -92,6 +92,22 @@ You can then open the generated solution with Visual Studio and compile it in the usual way. A list of backends can be obtained with `meson --help`. +Environment Variables +-- + +Sometimes you want to add extra compiler flags, this can be done by +passing them in environment variables when calling meson. See [the +reference +tables](Reference-tables.md#compiler-and-linker-flag-envrionment-variables) +for a list of all the environment variables. Be aware however these +environment variables are only used for the native compiler and will +not affect the compiler used for cross-compiling, where the flags +specified in the cross file will be used. + +Furthermore it is possible to stop meson from adding flags itself by +using the `--buildtype=plain` option, in this case you must provide +the full compiler and linker arguments needed. + Building the source == diff --git a/docs/markdown/Subprojects.md b/docs/markdown/Subprojects.md index 80ed3e7..2e3e2ea 100644 --- a/docs/markdown/Subprojects.md +++ b/docs/markdown/Subprojects.md @@ -14,45 +14,46 @@ Meson tries to solve this problem by making it extremely easy to provide both at the same time. The way this is done is that Meson allows you to take any other Meson project and make it a part of your build without (in the best case) any changes to its Meson setup. It -becomes a transparent part of the project. The basic idiom goes -something like this. +becomes a transparent part of the project. -```meson -dep = dependency('foo', fallback : [subproject_name, variable_name]) -``` +It should be noted that this only works for subprojects that are built +with Meson. It can not be used with any other build system. The reason +is the simple fact that there is no possible way to do this reliably +with mixed build systems. + +## A subproject example + +Usually dependencies consist of some header files plus a library to link against. +To declare this internal dependency use `declare_dependency` function. As an example, suppose we have a simple project that provides a shared -library. It would be set up like this. +library. It's `meson.build` would look like this. ```meson -project('simple', 'c') -i = include_directories('include') -l = shared_library('simple', 'simple.c', include_directories : i, install : true) -simple_dep = declare_dependency(include_directories : i, - link_with : l) -``` +project('libsimple', 'c') -Then we could use that from a master project. First we generate a -subdirectory called `subprojects` in the root of the master -directory. Then we create a subdirectory called `simple` and put the -subproject in that directory. Now the subproject can be used like -this. +inc = include_directories('include') +libsimple = shared_library('simple', + 'simple.c', + include_directories : inc, + install : true) -```meson -project('master', 'c') -dep = dependency('simple', fallback : ['simple', 'simple_dep']) -exe = executable('prog', 'prog.c', - dependencies : dep, install : true) +libsimple_dep = declare_dependency(include_directories : inc, + link_with : libsimple) ``` -With this setup the system dependency is used when it is available, -otherwise we fall back on the bundled version. If you wish to always -use the embedded version, then you would declare it like this: +### Naming convention for dependency variables -```meson -simple_sp = subproject('simple') -dep = simple_sp.get_variable('simple_dep') -``` +Ideally the dependency variable name should be of `<project_name>_dep` form. +This way one can just use it without even looking inside build definitions of that subproject. + +In cases where there are multiple dependencies need to be declared, the default one +should be named as `<project_name>_dep` (e.g. `gtest_dep`), and others can have +`<project_name>_<other>_<name>_dep` form (e.g. `gtest_main_dep` - gtest with main function). + +There may be exceptions to these rules where common sense should be applied. + +### Build options in subproject All Meson features of the subproject, such as project options keep working and can be set in the master project. There are a few @@ -62,17 +63,111 @@ must not set global arguments because there is no way to do that reliably over multiple subprojects. To check whether you are running as a subproject, use the `is_subproject` function. -It should be noted that this only works for subprojects that are built -with Meson. It can not be used with any other build system. The reason -is the simple fact that there is no possible way to do this reliably -with mixed build systems. +## Using a subproject + +All subprojects must be inside `subprojects` directory. +The `subprojects` directory must be at the top level of your project. +Subproject declaration must be in your top level `meson.build`. + +### A simple example + +Let's use `libsimple` as a subproject. + +At the top level of your project create `subprojects` directory. +Then copy `libsimple` into `subprojects` directory. + +Your project's `meson.build` should look like this. + +```meson +project('my_project', 'cpp') + +libsimple_proj = subproject('libsimple') +libsimple_dep = libsimple_proj.get_variable('libsimple_dep') + +executable('my_project', + 'my_project.cpp', + dependencies : libsimple_dep, + install : true) +``` + +Note that the subproject object is *not* used as the dependency, but +rather you need to get the declared dependency from it with +`get_variable` because a subproject may have multiple declared +dependencies. + +### Toggling between system libraries and embedded sources + +When building distro packages it is very important that you do not +embed any sources. Some distros have a rule forbidding embedded +dependencies so your project must be buildable without them or +otherwise the packager will hate you. + +Here's how you would use system libraries and fall back to embedding sources +if the dependency is not available. + +```meson +project('my_project', 'cpp') + +libsimple_dep = dependency('libsimple', required : false) + +if not libsimple_dep.found() + libsimple_proj = subproject('libsimple') + libsimple_dep = libsimple_proj.get_variable('libsimple_dep') +endif + +executable('my_project', + 'my_project.cpp', + dependencies : libsimple_dep, + install : true) +``` + +Because this is such a common operation, Meson provides a shortcut for +this use case. + +```meson +dep = dependency('foo', fallback : [subproject_name, variable_name]) +``` + +The `fallback` keyword argument takes two items, the name of the +subproject and the name of the variable that holds the dependency. If +you need to do something more complicated, such as extract several +different variables, then you need to do it yourself with the manual +method described above. + +Using this shortcut the build definition would look like this. + +```meson +project('my_project', 'cpp') + +libsimple_dep = dependency('libsimple', fallback : ['libsimple', 'libsimple_dep']) + +executable('my_project', + 'my_project.cpp', + dependencies : libsimple_dep, + install : true) +``` + +With this setup when libsimple is provided by the system, we use it. When +that is not the case we use the embedded version (the one from subprojects). + +Note that `libsimple_dep` can point to an external or an internal dependency but +you don't have to worry about their differences. Meson will take care +of the details for you. + +### Subprojects depending on other subprojects Subprojects can use other subprojects, but all subprojects must reside in the top level `subprojects` directory. Recursive use of subprojects is not allowed, though, so you can't have subproject `a` that uses subproject `b` and have `b` also use `a`. -# Command-line options +## Obtaining subprojects + +Meson ships with a dependency system to automatically obtain +dependency subprojects. It is documented in the [Wrap dependency +system manual](Wrap-dependency-system-manual.md). + +## Command-line options The usage of subprojects can be controlled by users and distros with the following command-line options: @@ -101,13 +196,7 @@ the following command-line options: want to specifically build against the library sources provided by your subprojects. -# Obtaining subprojects - -Meson ships with a dependency system to automatically obtain -dependency subprojects. It is documented in the [Wrap dependency -system manual](Wrap-dependency-system-manual.md). - -# Why must all subprojects be inside a single directory? +## Why must all subprojects be inside a single directory? There are several reasons. diff --git a/docs/markdown/Syntax.md b/docs/markdown/Syntax.md index efb12e4..22b8be3 100644 --- a/docs/markdown/Syntax.md +++ b/docs/markdown/Syntax.md @@ -283,6 +283,17 @@ Note appending to an array will always create a new array object and assign it to `my_array` instead of modifying the original since all objects in Meson are immutable. +Since 0.49.0, you can check if an array contains an element like this: +```meson +my_array = [1, 2] +if 1 in my_array +# This condition is true +endif +if 1 not in my_array +# This condition is false +endif +``` + #### Array methods The following methods are defined for all arrays: @@ -316,6 +327,20 @@ Dictionaries are available since 0.47.0. Visit the [Reference Manual](Reference-manual.md#dictionary-object) to read about the methods exposed by dictionaries. +Since 0.49.0, you can check if a dictionary contains a key like this: +```meson +my_dict = {'foo': 42, 'foo': 43} +if 'foo' in my_dict +# This condition is true +endif +if 42 in my_dict +# This condition is false +endif +if 'foo' not in my_dict +# This condition is false +endif +``` + Function calls -- @@ -354,11 +379,34 @@ else endif opt = get_option('someoption') -if opt == 'foo' +if opt != 'foo' do_something() endif ``` +Logical operations +-- + +Meson has the standard range of logical operations which can be used in +`if` statements. + +```meson +if a and b + # do something +endif +if c or d + # do something +endif +if not e + # do something +endif +if not (f or g) + # do something +endif +``` + +Logical operations work only on boolean values. + ## Foreach statements To do an operation on all elements of an iterable, use the `foreach` @@ -409,28 +457,24 @@ foreach name, sources : components endforeach ``` -Logical operations --- +### Foreach `break` and `continue` -Meson has the standard range of logical operations. +Since 0.49.0 `break` and `continue` keywords can be used inside foreach loops. ```meson -if a and b - # do something -endif -if c or d - # do something -endif -if not e - # do something -endif -if not (f or g) - # do something -endif +items = ['a', 'continue', 'b', 'break', 'c'] +result = [] +foreach i : items + if i == 'continue' + continue + elif i == 'break' + break + endif + result += i +endforeach +# result is ['a', 'b'] ``` -Logical operations work only on boolean values. - Comments -- diff --git a/docs/markdown/Tutorial.md b/docs/markdown/Tutorial.md index c555abc..c4436d0 100644 --- a/docs/markdown/Tutorial.md +++ b/docs/markdown/Tutorial.md @@ -9,6 +9,19 @@ definition for a simple project. Then we expand it to use external dependencies to show how easily they can be integrated into your project. +This tutorial has been written mostly for Linux usage. It assumes that +you have GTK development libraries available on the system. On +Debian-derived systems such as Ubuntu they can be installed with the +following command: + +``` +sudo apt install libgtk-3-dev +``` + +It is possible to build the GUI application On other platforms such as +Windows and macOS but it requires for you to install the dependency +libraries using a dependendy provider of your choice. + The humble beginning ----- diff --git a/docs/markdown/Users.md b/docs/markdown/Users.md index d328b97..57257f9 100644 --- a/docs/markdown/Users.md +++ b/docs/markdown/Users.md @@ -9,13 +9,14 @@ listed in the [`meson` GitHub topic](https://github.com/topics/meson). - [AQEMU](https://github.com/tobimensch/aqemu), a Qt GUI for QEMU virtual machines, since version 0.9.3 - [Arduino sample project](https://github.com/jpakkane/mesonarduino) - - [bolt](https://gitlab.freedesktop.org/bolt/bolt) Userpsace daemon to enable security levels for Thunderboltâ„¢ 3 on Linux + - [bolt](https://gitlab.freedesktop.org/bolt/bolt) Userspace daemon to enable security levels for Thunderboltâ„¢ 3 on Linux - [Budgie Desktop](https://github.com/budgie-desktop/budgie-desktop), a desktop environment built on GNOME technologies - [casync](https://github.com/systemd/casync), Content-Addressable Data Synchronization Tool - [cinnamon-desktop](https://github.com/linuxmint/cinnamon-desktop), the cinnamon desktop library - [dbus-broker](https://github.com/bus1/dbus-broker), Linux D-Bus Message Broker - [Dpdk](http://dpdk.org/browse/dpdk), Data plane development kit, a set of libraries and drivers for fast packet processing - [DXVK](https://github.com/doitsujin/dxvk), a Vulkan-based Direct3D 11 implementation for Linux using Wine + - [elementary OS](https://github.com/elementary/), Linux desktop oriented distribution - [Emeus](https://github.com/ebassi/emeus), Constraint based layout manager for GTK+ - [ESP8266 Arduino sample project](https://github.com/trilader/arduino-esp8266-meson) Sample project for using the ESP8266 Arduino port with Meson - [Fractal](https://wiki.gnome.org/Apps/Fractal/), a Matrix messaging client for GNOME diff --git a/docs/markdown/Videos.md b/docs/markdown/Videos.md index d9ea34d..65fccfe 100644 --- a/docs/markdown/Videos.md +++ b/docs/markdown/Videos.md @@ -4,9 +4,16 @@ short-description: Videos about Meson # Videos + - [Compiling Multi-Million Line C++ Code Bases Effortlessly with the + Meson Build system](https://www.youtube.com/watch?v=SCZLnopmYBM), + CppCon 2018 + - [The Meson Build System, 4+ years of work to become an overnight success](https://www.youtube.com/watch?v=gHdTzdXkhRY), Linux.conf.au 2018 + - [Power through simplicity, using Python in the Meson Build + System](https://youtu.be/3jF3oVsjIEM), Piter.py, 2017 + - [Meson and the changing Linux build landscape](https://media.ccc.de/v/ASG2017-111-meson_and_the_changing_linux_build_landscape), All Systems Go 2017 diff --git a/docs/markdown/Wrap-dependency-system-manual.md b/docs/markdown/Wrap-dependency-system-manual.md index 38e1ab2..619492a 100644 --- a/docs/markdown/Wrap-dependency-system-manual.md +++ b/docs/markdown/Wrap-dependency-system-manual.md @@ -27,10 +27,24 @@ itself in a way that makes it easy to use (usually this means as a static library). To use this kind of a project as a dependency you could just copy and -extract it inside your project's `subprojects` directory. However -there is a simpler way. You can specify a Wrap file that tells Meson -how to download it for you. An example wrap file would look like this -and should be put in `subprojects/foobar.wrap`: +extract it inside your project's `subprojects` directory. + +However there is a simpler way. You can specify a Wrap file that tells Meson +how to download it for you. If you then use this subproject in your build, +Meson will automatically download and extract it during build. This makes +subproject embedding extremely easy. + +All wrap files must have a name of `<project_name>.wrap` form and be in `subprojects` dir. + +Currently Meson has three kinds of wraps: +- wrap-file +- wrap-file with Meson build patch +- wrap-git + +## wrap-file + +An example wrap file for `libfoobar` would have a name `libfoobar.wrap` +and would look like this: ```ini [wrap-file] @@ -41,16 +55,22 @@ source_filename = foobar-1.0.tar.gz source_hash = 5ebeea0dfb75d090ea0e7ff84799b2a7a1550db3fe61eb5f6f61c2e971e57663 ``` -If you then use this subproject in your build, Meson will -automatically download and extract it during build. This makes -subproject embedding extremely easy. +`source_hash` is *sha256sum* of `source_filename`. + +Since *0.49.0* if `source_filename` is found in project's +`subprojects/packagecache` directory, it will be used instead of downloading the +source, even if `--wrap-mode` option is set to `nodownload`. The file's hash will +be checked. + +## wrap-file with Meson build patch Unfortunately most software projects in the world do not build with Meson. Because of this Meson allows you to specify a patch URL. This works in much the same way as Debian's distro patches. That is, they are downloaded and automatically applied to the subproject. These -files contain a Meson build definition for the given subproject. A -wrap file with an additional patch URL would look like this. +files contain a Meson build definition for the given subproject. + +A wrap file with an additional patch URL would look like this: ```ini [wrap-file] @@ -76,7 +96,14 @@ thousands of lines of code. Once you have a working build definition, just zip up the Meson build files (and others you have changed) and put them somewhere where you can download them. -## Branching subprojects directly from git +Since *0.49.0* if `patch_filename` is found in project's +`subprojects/packagecache` directory, it will be used instead of downloading the +patch, even if `--wrap-mode` option is set to `nodownload`. The file's hash will +be checked. + +## wrap-git + +This type of wrap allows branching subprojects directly from git. The above mentioned scheme assumes that your subproject is working off packaged files. Sometimes you want to check code out directly from @@ -85,9 +112,9 @@ slightly different wrap file. ```ini [wrap-git] -directory=samplesubproject -url=https://github.com/jpakkane/samplesubproject.git -revision=head +directory = samplesubproject +url = https://github.com/jpakkane/samplesubproject.git +revision = head ``` The format is straightforward. The only thing to note is the revision @@ -106,84 +133,26 @@ these cases you can specify the upload URL by adding the following at the end of your wrap file: ```ini -push-url=git@git.example.com:projects/someproject.git # Supported since version 0.37.0 -``` - -## Using wrapped projects - -To use a subproject simply do this in your top level `meson.build`. - -```meson -foobar_sp = subproject('foobar') +push-url = git@git.example.com:projects/someproject.git # Supported since version 0.37.0 ``` -Usually dependencies consist of some header files plus a library to -link against. To do this you would declare this internal dependency -like this: +If the git repo contains submodules, you can tell Meson to clone them +automatically by adding the following *(since 0.48.0)*: -```meson -foobar_dep = declare_dependency(link_with : mylib, - include_directories : myinc) -``` - -Then in your main project you would use them like this: - -```meson -executable('toplevel_exe', 'prog.c', - dependencies : foobar_sp.get_variable('foobar_dep')) -``` - -Note that the subproject object is *not* used as the dependency, but -rather you need to get the declared dependency from it with -`get_variable` because a subproject may have multiple declared -dependencies. - -## Toggling between distro packages and embedded source - -When building distro packages it is very important that you do not -embed any sources. Some distros have a rule forbidding embedded -dependencies so your project must be buildable without them or -otherwise the packager will hate you. - -Doing this with Meson and Wrap is simple. Here's how you would use -distro packages and fall back to embedding if the dependency is not -available. - -```meson -foobar_dep = dependency('foobar', required : false) - -if not foobar_dep.found() - foobar_subproj = subproject('foobar') - # the subproject defines an internal dependency with - # the command declare_dependency(). - foobar_dep = foobar_subproj.get_variable('foobar_dep') -endif - -executable('toplevel_exe', 'prog.c', - dependencies : foobar_dep) +```ini +clone-recursive = true ``` -Because this is such a common operation, Meson provides a shortcut for -this use case. +## Using wrapped projects -```meson -foobar_dep = dependency('foobar', fallback : ['foobar', 'foobar_dep']) -``` +Wraps provide a convenient way of obtaining a project into your subproject directory. +Then you use it as a regular subproject (see [subprojects](Subprojects.md)). -The `fallback` keyword argument takes two items, the name of the -subproject and the name of the variable that holds the dependency. If -you need to do something more complicated, such as extract several -different variables, then you need to do it yourself with the manual -method described above. +## Getting wraps -With this setup when foobar is provided by the system, we use it. When -that is not the case we use the embedded version. Note that -`foobar_dep` can point to an external or an internal dependency but -you don't have to worry about their differences. Meson will take care -of the details for you. +Usually you don't want to write your wraps by hand. -## Getting wraps +There is an online repository called [WrapDB](https://wrapdb.mesonbuild.com) that provides +many dependencies ready to use. You can read more about WrapDB [here](Using-the-WrapDB.md). -Usually you don't want to write your wraps by hand. There is an online -repository called [WrapDB](Using-the-WrapDB.md) that provides many -dependencies ready to use. +There is also a Meson subcommand to get and manage wraps (see [using wraptool](Using-wraptool.md)). diff --git a/docs/markdown/index.md b/docs/markdown/index.md index cffd488..e57cd69 100644 --- a/docs/markdown/index.md +++ b/docs/markdown/index.md @@ -33,13 +33,13 @@ developers. The first one is the mailing list, which is hosted at The second way is via IRC. The channel to use is `#mesonbuild` at [Freenode](https://freenode.net/). -### [Projects using Meson](http://mesonbuild.com/Users.html) +### [Projects using Meson](Users.md) Many projects out there are using Meson and their communities are also a great resource for learning about what (and what not too!) do when trying to convert to using Meson. -[A short list of Meson users can be found here](http://mesonbuild.com/Users.html) +[A short list of Meson users can be found here](Users.md) but there are many more. We would love to hear about your success stories too and how things could be improved too! diff --git a/docs/markdown/snippets/add_release_note_snippets_here b/docs/markdown/snippets/add_release_note_snippets_here index e69de29..bc4039c 100644 --- a/docs/markdown/snippets/add_release_note_snippets_here +++ b/docs/markdown/snippets/add_release_note_snippets_here @@ -0,0 +1,3 @@ +## Added `cpp_std` option for the Visual Studio C++ compiler +Allows the use of C++17 features and experimental not-yet-standardized +features. Valid options are `c++11`, `c++14`, `c++17`, and `c++latest`. diff --git a/docs/markdown/snippets/buildopts_section.md b/docs/markdown/snippets/buildopts_section.md new file mode 100644 index 0000000..74cf8a1 --- /dev/null +++ b/docs/markdown/snippets/buildopts_section.md @@ -0,0 +1,14 @@ +## New `section` key for the buildoptions introspection + +Meson now has a new `section` key in each build option. This allows +IDEs to group these options similar to `meson configure`. + +The possible values for `section` are: + + - core + - backend + - base + - compiler + - directory + - user + - test diff --git a/docs/markdown/snippets/buildtype_toggles.md b/docs/markdown/snippets/buildtype_toggles.md deleted file mode 100644 index e6ae53d..0000000 --- a/docs/markdown/snippets/buildtype_toggles.md +++ /dev/null @@ -1,21 +0,0 @@ -## Toggles for build type, optimization and vcrt type - -Since the very beginning Meson has provided different project types to -use, such as *debug* and *minsize*. There is also a *plain* type that -adds nothing by default but instead makes it the user's responsibility -to add everything by hand. This works but is a bit tedious. - -In this release we have added new new options to manually toggle -e.g. optimization levels and debug info so those can be changed -independently of other options. For example by default the debug -buildtype has no optmization enabled at all. If you wish to use GCC's -`-Og` instead, you could set it with the following command: - -``` -meson configure -Doptimization=g -``` - -Similarly we have added a toggle option to select the version of -Visual Studio C runtime to use. By default it uses the debug runtime -DLL debug builds and release DLL for release builds but this can be -manually changed with the new base option `b_vscrt`. diff --git a/docs/markdown/snippets/ccrx_toolchain_support.md b/docs/markdown/snippets/ccrx_toolchain_support.md new file mode 100644 index 0000000..6bf7e5b --- /dev/null +++ b/docs/markdown/snippets/ccrx_toolchain_support.md @@ -0,0 +1,16 @@ +## CC-RX compiler for C and CPP + +Cross-compilation is now supported for Renesas RX targets with the CC-RX compiler. + +The environment path should be set properly for the CC-RX compiler executables. +The `-cpu` option with the appropriate value should be mentioned in the cross-file as shown in the snippet below. + +```ini +[properties] +c_args = ['-cpu=rx600'] +cpp_args = ['-cpu=rx600'] +``` + +The default extension of the executable output is `.abs`. +Other target specific arguments to the compiler and linker will need to be added explicitly from the cross-file(`c_args`/`c_link_args`/`cpp_args`/`cpp_link_args`) or some other way. +Refer to the CC-RX User's manual for additional compiler and linker options.
\ No newline at end of file diff --git a/docs/markdown/snippets/cmake.md b/docs/markdown/snippets/cmake.md new file mode 100644 index 0000000..8848c7b --- /dev/null +++ b/docs/markdown/snippets/cmake.md @@ -0,0 +1,19 @@ +## CMake `find_package` dependency backend + +Meson can now use the CMake `find_package` ecosystem to +detect dependencies. Both the old-style `<NAME>_LIBRARIES` +variables as well as imported targets are supported. Meson +can automatically guess the correct CMake target in most +cases but it is also possible to manually specify a target +with the `modules` property. + +```meson +# Implicitly uses CMake as a fallback and guesses a target +dep1 = dependency('KF5TextEditor') + +# Manually specify one or more CMake targets to use +dep2 = dependency('ZLIB', method : 'cmake', modules : ['ZLIB::ZLIB']) +``` + +CMake is automatically used after `pkg-config` fails when +no `method` (or `auto`) was provided in the dependency options. diff --git a/docs/markdown/snippets/compiler_argument_syntax.md b/docs/markdown/snippets/compiler_argument_syntax.md new file mode 100644 index 0000000..6ae32d4 --- /dev/null +++ b/docs/markdown/snippets/compiler_argument_syntax.md @@ -0,0 +1,22 @@ +## new compiler method `get_argument_syntax` + +The compiler object now has `get_argument_syntax` method, which returns a +string value of `gcc`, `msvc`, or an undefined value string value. This can be +used to determine if a compiler uses gcc syntax (`-Wfoo`), msvc syntax +(`/w1234`), or some other kind of arguments. + +```meson +cc = meson.get_compiler('c') + +if cc.get_argument_syntax() == 'msvc' + if cc.has_argument('/w1235') + add_project_arguments('/w1235', language : ['c']) + endif +elif cc.get_argument_syntax() == 'gcc' + if cc.has_argument('-Wfoo') + add_project_arguments('-Wfoo', language : ['c']) + endif +elif cc.get_id() == 'some other compiler' + add_project_arguments('--error-on-foo', language : ['c']) +endif +``` diff --git a/docs/markdown/snippets/configure_file_overwrite_warning.md b/docs/markdown/snippets/configure_file_overwrite_warning.md deleted file mode 100644 index 550407d..0000000 --- a/docs/markdown/snippets/configure_file_overwrite_warning.md +++ /dev/null @@ -1,39 +0,0 @@ -## Meson warns if two calls to configure_file() write to the same file - -If two calls to [`configure_file()`](#Reference-manual.md#configure_file) -write to the same file Meson will print a `WARNING:` message during -configuration. For example: -```meson -project('configure_file', 'cpp') - -configure_file( - input: 'a.in', - output: 'out', - command: ['./foo.sh'] - ) -configure_file( - input: 'a.in', - output: 'out', - command: ['./foo.sh'] -) - -``` - -This will output: - -``` -The Meson build system -Version: 0.47.0.dev1 -Source dir: /path/to/srctree -Build dir: /path/to/buildtree -Build type: native build -Project name: configure_file -Project version: undefined -Build machine cpu family: x86_64 -Build machine cpu: x86_64 -Configuring out with command -WARNING: Output file out for configure_file overwritten. First time written in line 3 now in line 8 -Configuring out with command -Build targets in project: 0 -Found ninja-1.8.2 at /usr/bin/ninja -``` diff --git a/docs/markdown/snippets/custom_target_console_pool.md b/docs/markdown/snippets/custom_target_console_pool.md deleted file mode 100644 index 8b9bb34..0000000 --- a/docs/markdown/snippets/custom_target_console_pool.md +++ /dev/null @@ -1,13 +0,0 @@ -## New kwarg `console` for `custom_target()` - -This keyword argument conflicts with `capture`, and is meant for -commands that are resource-intensive and take a long time to -finish. With the Ninja backend, setting this will add this target to -[Ninja's `console` -pool](https://ninja-build.org/manual.html#_the_literal_console_literal_pool), -which has special properties such as not buffering stdout and -serializing all targets in this pool. - -The primary use-case for this is to be able to run external commands -that take a long time to exeute. Without setting this, the user does -not receive any feedback about what the program is doing. diff --git a/docs/markdown/snippets/dependency_version.md b/docs/markdown/snippets/dependency_version.md deleted file mode 100644 index 4bbf346..0000000 --- a/docs/markdown/snippets/dependency_version.md +++ /dev/null @@ -1,14 +0,0 @@ -## `dependency(version:)` now applies to all dependency types - -Previously, version constraints were only enforced for dependencies found using -the pkg-config dependency provider. These constraints now apply to dependencies -found using any dependency provider. - -Some combinations of dependency, host and method do not currently support -discovery of the version. In these cases, the dependency will not be found if a -version constraint is applied, otherwise the `version()` method for the -dependency object will return `'unknown'`. - -(If discovering the version in one of these combinations is important to you, -and a method exists to determine the version in that case, please file an issue -with as much information as possible.) diff --git a/docs/markdown/snippets/dict_add.md b/docs/markdown/snippets/dict_add.md deleted file mode 100644 index cde5b57..0000000 --- a/docs/markdown/snippets/dict_add.md +++ /dev/null @@ -1,10 +0,0 @@ -## Dictionary addition - -Dictionaries can now be added, values from the second dictionary overrides values -from the first - -```meson -d1 = {'a' : 'b'} -d3 = d1 + {'a' : 'c'} -d3 += {'d' : 'e'} -``` diff --git a/docs/markdown/snippets/disabler.md b/docs/markdown/snippets/disabler.md new file mode 100644 index 0000000..76874f6 --- /dev/null +++ b/docs/markdown/snippets/disabler.md @@ -0,0 +1,6 @@ +## Return `Disabler()` instead of not-found object + +Functions such as `dependency()`, `find_library()`, `find_program()`, and +`python.find_installation()` have a new keyword argument: `disabler`. When set +to `true` those functions return `Disabler()` objects instead of not-found +objects. diff --git a/docs/markdown/snippets/distscript.md b/docs/markdown/snippets/distscript.md deleted file mode 100644 index 37d05fe..0000000 --- a/docs/markdown/snippets/distscript.md +++ /dev/null @@ -1,12 +0,0 @@ -## Dist scripts - -You can now specify scripts that are run as part of the `dist` -target. An example usage would go like this: - -```meson -project('foo', 'c') - -# other stuff here - -meson.add_dist_script('dist_cleanup.py') -``` diff --git a/docs/markdown/snippets/fatal_warnings.md b/docs/markdown/snippets/fatal_warnings.md deleted file mode 100644 index adf3334..0000000 --- a/docs/markdown/snippets/fatal_warnings.md +++ /dev/null @@ -1,6 +0,0 @@ -## Fatal warnings - -A new command line option has been added: `--fatal-meson-warnings`. When enabled, any -warning message printed by Meson will be fatal and raise an exception. It is -intended to be used by developers and CIs to easily catch deprecation warnings, -or any other potential issues. diff --git a/docs/markdown/snippets/function_attributes.md b/docs/markdown/snippets/function_attributes.md deleted file mode 100644 index 5514494..0000000 --- a/docs/markdown/snippets/function_attributes.md +++ /dev/null @@ -1,29 +0,0 @@ -## Helper methods added for checking GNU style attributes: __attribute__(...) - -A set of new helpers have been added to the C and C++ compiler objects for -checking GNU style function attributes. These are not just simpler to use, they -may be optimized to return fast on compilers that don't support these -attributes. Currently this is true for MSVC. - -```meson -cc = meson.get_compiler('c') -if cc.has_function_attribute('aligned') - add_project_arguments('-DHAVE_ALIGNED', language : 'c') -endif -``` - -Would replace code like: - -```meson -if cc.compiles('''into foo(void) __attribute__((aligned(32)))''') - add_project_arguments('-DHAVE_ALIGNED', language : 'c') -endif -``` - -Additionally, a multi argument version has been added: - -```meson -foreach s : cc.get_supported_function_attributes(['hidden', 'alias']) - add_project_arguments('-DHAVE_@0@'.format(s.to_upper()), language : 'c') -endforeach -``` diff --git a/docs/markdown/snippets/generate_gir_multiple_libraries.md b/docs/markdown/snippets/generate_gir_multiple_libraries.md deleted file mode 100644 index 3541b71..0000000 --- a/docs/markdown/snippets/generate_gir_multiple_libraries.md +++ /dev/null @@ -1,7 +0,0 @@ -## gnome.generate_gir() now optionally accepts multiple libraries - -The GNOME module can now generate a single gir for multiple libraries, which -is something `g-ir-scanner` supported, but had not been exposed yet. - -gnome.generate_gir() will now accept multiple positional arguments, if none -of these arguments are an `Executable` instance. diff --git a/docs/markdown/snippets/hotdoc_module.md b/docs/markdown/snippets/hotdoc_module.md deleted file mode 100644 index 4662ea2..0000000 --- a/docs/markdown/snippets/hotdoc_module.md +++ /dev/null @@ -1,22 +0,0 @@ -## Hotdoc module - -A new module has been written to ease generation of [hotdoc](https://hotdoc.github.io/) based -documentation. It supports complex use cases such as hotdoc subprojects (to create documentation -portals) and makes it straight forward to leverage full capabilities of hotdoc. - -Simple usage: - -``` meson -hotdoc = import('hotdoc') - -hotdoc.generate_doc( - 'foobar', - c_smart_index: true, - project_version: '0.1', - sitemap: 'sitemap.txt', - index: 'index.md', - c_sources: ['path/to/file.c'], - languages: ['c'], - install: true, -) -```
\ No newline at end of file diff --git a/docs/markdown/snippets/i18n_variable_substitution.md b/docs/markdown/snippets/i18n_variable_substitution.md deleted file mode 100644 index b58f62a..0000000 --- a/docs/markdown/snippets/i18n_variable_substitution.md +++ /dev/null @@ -1,4 +0,0 @@ -## i18n.merge_file() now fully supports variable substitutions defined in custom_target() - -Filename substitutions like @BASENAME@ and @PLAINNAME@ were previously accepted but the name of the build target wasn't altered leading to colliding target names when using the substitution twice. -i18n.merge_file() now behaves as custom_target() in this regard. diff --git a/docs/markdown/snippets/introspect_projectinfo.md b/docs/markdown/snippets/introspect_projectinfo.md new file mode 100644 index 0000000..40558b8 --- /dev/null +++ b/docs/markdown/snippets/introspect_projectinfo.md @@ -0,0 +1,35 @@ +## `introspect --projectinfo` can now be used without configured build directory + +This allows IDE integration to get information about the project before the user has configured a build directory. + +Before you could use `meson.py introspect --projectinfo build-directory`. +Now you also can use `meson.py introspect --projectinfo project-dir/meson.build`. + +The output is similiar to the output with a build directory but additionally also includes information from `introspect --buildsystem-files`. + +For example `meson.py introspect --projectinfo test\ cases/common/47\ subproject\ options/meson.build` +This outputs (pretty printed for readability): +``` +{ + "buildsystem_files": [ + "meson_options.txt", + "meson.build" + ], + "name": "suboptions", + "version": null, + "descriptive_name": "suboptions", + "subprojects": [ + { + "buildsystem_files": [ + "subprojects/subproject/meson_options.txt", + "subprojects/subproject/meson.build" + ], + "name": "subproject", + "version": "undefined", + "descriptive_name": "subproject" + } + ] +} +``` + +Both usages now include a new `descriptive_name` property which always shows the name set in the project. diff --git a/docs/markdown/snippets/manpage_compression.md b/docs/markdown/snippets/manpage_compression.md new file mode 100644 index 0000000..8c96807 --- /dev/null +++ b/docs/markdown/snippets/manpage_compression.md @@ -0,0 +1,7 @@ +## Manpages are no longer compressed implicitly + +Earlier, the `install_man` command has automatically compressed installed +manpages into `.gz` format. This collided with manpage compression hooks +already used by various distributions. Now, manpages are installed uncompressed +and distributors are expected to handle compressing them according to their own +compression preferences. diff --git a/docs/markdown/snippets/native_args.md b/docs/markdown/snippets/native_args.md deleted file mode 100644 index 54c6de2..0000000 --- a/docs/markdown/snippets/native_args.md +++ /dev/null @@ -1,34 +0,0 @@ -## Projects args can be set separately for cross and native builds (potentially breaking change) - -It has been a longstanding bug (or let's call it a "delayed bug fix") -that if yo do this: - -```meson -add_project_arguments('-DFOO', language : 'c') -``` - -Then the flag is used both in native and cross compilations. This is -very confusing and almost never what you want. To fix this a new -keyword `native` has been added to all functions that add arguments, -namely `add_global_arguments`, `add_global_link_arguments`, -`add_project_arguments` and `add_project_link_arguments` that behaves -like the following: - -``` -## Added to native builds when compiling natively and to cross -## compilations when doing cross compiles. -add_project_arguments(...) - -## Added only to native compilations, not used in cross compilations. -add_project_arguments(..., native : true) - -## Added only to cross compilations, not used in native compilations. -add_project_arguments(..., native : false) -``` - -Also remember that cross compilation is a property of each -target. There can be target that are compiled with the native compiler -and some which are compiled with the cross compiler. - -Unfortunately this change is backwards incompatible and may cause some -projects to fail building. However this should be very rare in practice. diff --git a/docs/markdown/snippets/native_files.md b/docs/markdown/snippets/native_files.md new file mode 100644 index 0000000..7bc3644 --- /dev/null +++ b/docs/markdown/snippets/native_files.md @@ -0,0 +1,15 @@ +## Native config files + +Native files are the counterpart to cross files, and allow specifying +information about the build machine, both when cross compiling and when not. + +Currently the native files only allow specifying the names of binaries, similar +to the cross file, for example: + +```ini +[binaries] +llvm-config = "/opt/llvm-custom/bin/llvm-config" +``` + +Will override the llvm-config used for *native* binaries. Targets for the host +machine will continue to use the cross file. diff --git a/docs/markdown/snippets/new_syntax.md b/docs/markdown/snippets/new_syntax.md new file mode 100644 index 0000000..98eccd0 --- /dev/null +++ b/docs/markdown/snippets/new_syntax.md @@ -0,0 +1,42 @@ +## Foreach `break` and `continue` + +`break` and `continue` keywords can be used inside foreach loops. + +```meson +items = ['a', 'continue', 'b', 'break', 'c'] +result = [] +foreach i : items + if i == 'continue' + continue + elif i == 'break' + break + endif + result += i +endforeach +# result is ['a', 'b'] +``` + +You can check if an array contains an element like this: +```meson +my_array = [1, 2] +if 1 in my_array +# This condition is true +endif +if 1 not in my_array +# This condition is false +endif +``` + +You can check if a dictionary contains a key like this: +```meson +my_dict = {'foo': 42, 'foo': 43} +if 'foo' in my_dict +# This condition is true +endif +if 42 in my_dict +# This condition is false +endif +if 'foo' not in my_dict +# This condition is false +endif +``` diff --git a/docs/markdown/snippets/overrideexe.md b/docs/markdown/snippets/overrideexe.md deleted file mode 100644 index 59213c5..0000000 --- a/docs/markdown/snippets/overrideexe.md +++ /dev/null @@ -1,8 +0,0 @@ -## More flexible `override_find_program()`. - -It is now possible to pass an `executable` to -`override_find_program()` if the overridden program is not used during -configure. - -This is particularly useful for fallback dependencies like Protobuf -that also provide a tool like protoc. diff --git a/docs/markdown/snippets/pathdivision.md b/docs/markdown/snippets/pathdivision.md new file mode 100644 index 0000000..6da6005 --- /dev/null +++ b/docs/markdown/snippets/pathdivision.md @@ -0,0 +1,15 @@ +## Joining paths with / + +Joining two paths has traditionally been done with the `join_paths` function. + +```meson +joined = join_paths('foo', 'bar') +``` + +Now you can use the simpler notation using the `/` operator. + +```meson +joined = 'foo' / 'bar' +``` + +This only works for strings. diff --git a/docs/markdown/snippets/pie.md b/docs/markdown/snippets/pie.md new file mode 100644 index 0000000..a9be174 --- /dev/null +++ b/docs/markdown/snippets/pie.md @@ -0,0 +1,6 @@ +## Position-independent executables + +When `b_pie` option, or `executable()`'s `pie` keyword argument is set to +`true`, position-independent executables are built. All their objects are built +with `-fPIE` and the executable is linked with `-pie`. Any static library they +link must be built with `pic` set to `true` (see `b_staticpic` option). diff --git a/docs/markdown/snippets/shared_library_darwin_versions.md b/docs/markdown/snippets/shared_library_darwin_versions.md deleted file mode 100644 index ad137f3..0000000 --- a/docs/markdown/snippets/shared_library_darwin_versions.md +++ /dev/null @@ -1,9 +0,0 @@ -## `shared_library()` now supports setting dylib compatibility and current version - -Now, by default `shared_library()` sets `-compatibility_version` and -`-current_version` of a macOS dylib using the `soversion`. - -This can be overriden by using the `darwin_versions:` kwarg to -[`shared_library()`](Reference-manual.md#shared_library). As usual, you can -also pass this kwarg to `library()` or `build_target()` and it will be used in -the appropriate circumstances. diff --git a/docs/markdown/snippets/test_setup_is_default.md b/docs/markdown/snippets/test_setup_is_default.md new file mode 100644 index 0000000..2274dc9 --- /dev/null +++ b/docs/markdown/snippets/test_setup_is_default.md @@ -0,0 +1,14 @@ +## New keyword argument `is_default` to `add_test_setup()` + +The keyword argument `is_default` may be used to set whether the test +setup should be used by default whenever `meson test` is run without +the `--setup` option. + +```meson +add_test_setup('default', is_default: true, env: 'G_SLICE=debug-blocks') +add_test_setup('valgrind', env: 'G_SLICE=always-malloc', ...) +test('mytest', exe) +``` + +For the example above, running `meson test` and `meson test +--setup=default` is now equivalent. diff --git a/docs/markdown/snippets/version_comparison.md b/docs/markdown/snippets/version_comparison.md deleted file mode 100644 index 861a3ee..0000000 --- a/docs/markdown/snippets/version_comparison.md +++ /dev/null @@ -1,15 +0,0 @@ -## Version comparison - -`dependency(version:)` and other version constraints now handle versions -containing non-numeric characters better, comparing versions using the rpmvercmp -algorithm (as using the `pkg-config` autoconf macro `PKG_CHECK_MODULES` does). - -This is a breaking change for exact comparison constraints which rely on the -previous comparison behaviour of extending the compared versions with `'0'` -elements, up to the same length of `'.'`-separated elements. - -For example, a version of `'0.11.0'` would previously match a version constraint -of `'==0.11'`, but no longer does, being instead considered strictly greater. - -Instead, use a version constraint which exactly compares with the precise -version required, e.g. `'==0.11.0'`. diff --git a/docs/markdown/snippets/visibility.md b/docs/markdown/snippets/visibility.md deleted file mode 100644 index bbb99f1..0000000 --- a/docs/markdown/snippets/visibility.md +++ /dev/null @@ -1,13 +0,0 @@ -## Keyword argument for GNU symbol visibility - -Build targets got a new keyword, `gnu_symbol_visibility` that controls -how symbols are exported from shared libraries. This is most commonly -used to hide implementation symbols like this: - -```meson -shared_library('mylib', ... - gnu_symbol_visibility: 'hidden') -``` - -In this case only symbols explicitly marked as visible in the source -files get exported. diff --git a/docs/sitemap.txt b/docs/sitemap.txt index 4ba1b90..f79eb05 100644 --- a/docs/sitemap.txt +++ b/docs/sitemap.txt @@ -9,6 +9,7 @@ index.md Using-with-Visual-Studio.md Meson-sample.md Syntax.md + Native-environments.md Build-targets.md Include-directories.md Installing.md @@ -69,6 +70,7 @@ index.md Shipping-prebuilt-binaries-as-wraps.md fallback-wraptool.md Release-notes.md + Release-notes-for-0.49.0.md Release-notes-for-0.48.0.md Release-notes-for-0.47.0.md Release-notes-for-0.46.0.md |