diff options
author | TheQwertiest <qwertiest@mail.ru> | 2020-06-15 18:36:08 +0300 |
---|---|---|
committer | Jussi Pakkanen <jpakkane@gmail.com> | 2020-06-18 17:47:10 +0300 |
commit | 96609da8d26fc05be8845c1edf05c8aa38af047d (patch) | |
tree | b5e5dfdf414d9f9efac2c0743cc211082ef34498 /docs/markdown | |
parent | e191cbf6e990caa0e912996977584909aab21da8 (diff) | |
download | meson-96609da8d26fc05be8845c1edf05c8aa38af047d.zip meson-96609da8d26fc05be8845c1edf05c8aa38af047d.tar.gz meson-96609da8d26fc05be8845c1edf05c8aa38af047d.tar.bz2 |
docs: replaced `ninja` with appropriate `meson` commands [skip ci]
Diffstat (limited to 'docs/markdown')
23 files changed, 113 insertions, 85 deletions
diff --git a/docs/markdown/Commands.md b/docs/markdown/Commands.md index 3aecae1..615b302 100644 --- a/docs/markdown/Commands.md +++ b/docs/markdown/Commands.md @@ -183,21 +183,7 @@ optional arguments: --no-tests Do not build and test generated packages. ``` -This creates a file called `projectname-version.tar.xz` in the build -tree subdirectory `meson-dist`. This archive contains the full -contents of the latest commit in revision control including all the -submodules (recursively). All revision control metadata is removed. -Meson then takes -this archive and tests that it works by doing a full compile + test + -install cycle. If all these pass, Meson will then create a SHA-256 -checksum file next to the archive. - -**Note**: Meson behaviour is different from Autotools. The Autotools -"dist" target packages up the current source tree. Meson packages -the latest revision control commit. The reason for this is that it -prevents developers from doing accidental releases where the -distributed archive does not match any commit in revision control -(especially the one tagged for the release). +See [notes about creating releases](Creating-releases.md) for more info. #### Examples: @@ -310,7 +296,7 @@ meson introspect builddir $ meson install [-h] [-C WD] [--no-rebuild] [--only-changed] [--quiet] ``` -Installs the project to the prefix specified in `setup`. +Installs the project to the prefix specified in [`setup`](#setup). ``` optional arguments: @@ -325,7 +311,7 @@ See [the installation documentation](Installing.md) for more info. #### Examples: -Install project to `prefix` (see [`setup`](#setup)): +Install project to `prefix`: ``` meson install -C builddir ``` diff --git a/docs/markdown/Configuring-a-build-directory.md b/docs/markdown/Configuring-a-build-directory.md index 1387a46..330899f 100644 --- a/docs/markdown/Configuring-a-build-directory.md +++ b/docs/markdown/Configuring-a-build-directory.md @@ -109,11 +109,11 @@ you would issue the following command. meson configure -Dprefix=/tmp/testroot -Then you would run your build command (usually `ninja`), which would +Then you would run your build command (usually `meson compile`), which would cause Meson to detect that the build setup has changed and do all the work required to bring your build tree up to date. Since 0.50.0, it is also possible to get a list of all build options -by invoking `meson configure` with the project source directory or +by invoking [`meson configure`](Commands.md#configure) with the project source directory or the path to the root `meson.build`. In this case, meson will print the default values of all options similar to the example output from above. diff --git a/docs/markdown/Continuous-Integration.md b/docs/markdown/Continuous-Integration.md index 0846f2d..76a05a3 100644 --- a/docs/markdown/Continuous-Integration.md +++ b/docs/markdown/Continuous-Integration.md @@ -36,8 +36,8 @@ script: - if [[ "$TRAVIS_OS_NAME" == "linux" ]]; then echo FROM YOUR/REPO:eoan > Dockerfile; fi - if [[ "$TRAVIS_OS_NAME" == "linux" ]]; then echo ADD . /root >> Dockerfile; fi - if [[ "$TRAVIS_OS_NAME" == "linux" ]]; then docker build -t withgit .; fi - - if [[ "$TRAVIS_OS_NAME" == "linux" ]]; then docker run withgit /bin/sh -c "cd /root && TRAVIS=true CC=$CC CXX=$CXX meson builddir && ninja -C builddir test"; fi - - if [[ "$TRAVIS_OS_NAME" == "osx" ]]; then SDKROOT=$(xcodebuild -version -sdk macosx Path) meson builddir && ninja -C builddir test; fi + - if [[ "$TRAVIS_OS_NAME" == "linux" ]]; then docker run withgit /bin/sh -c "cd /root && TRAVIS=true CC=$CC CXX=$CXX meson builddir && meson test -C builddir"; fi + - if [[ "$TRAVIS_OS_NAME" == "osx" ]]; then SDKROOT=$(xcodebuild -version -sdk macosx Path) meson builddir && meson test -C builddir; fi ``` ## CircleCi for Linux (with Docker) @@ -69,7 +69,7 @@ jobs: steps: - checkout - run: meson setup builddir --backend ninja - - run: ninja -C builddir + - run: meson compile -C builddir - run: meson test -C builddir meson_debian_build: @@ -77,7 +77,7 @@ jobs: steps: - checkout - run: meson setup builddir --backend ninja - - run: ninja -C builddir + - run: meson compile -C builddir - run: meson test -C builddir meson_fedora_build: @@ -85,7 +85,7 @@ jobs: steps: - checkout - run: meson setup builddir --backend ninja - - run: ninja -C builddir + - run: meson compile -C builddir - run: meson test -C builddir workflows: @@ -138,10 +138,10 @@ install: build_script: - cmd: echo Building on %arch% with %compiler% - cmd: meson --backend=ninja builddir - - cmd: ninja -C builddir + - cmd: meson compile -C builddir test_script: - - cmd: ninja -C builddir test + - cmd: meson test -C builddir ``` ### Qt @@ -187,8 +187,8 @@ install: script: - meson builddir - - ninja -C builddir - - ninja -C builddir test + - meson compile -C builddir + - meson test -C builddir ``` ## GitHub Actions diff --git a/docs/markdown/Creating-OSX-packages.md b/docs/markdown/Creating-OSX-packages.md index bda06a3..849d5fd 100644 --- a/docs/markdown/Creating-OSX-packages.md +++ b/docs/markdown/Creating-OSX-packages.md @@ -39,7 +39,7 @@ $ meson --prefix=/tmp/myapp.app \ <other flags you might need> ``` -Now when we do `ninja install` the bundle is properly staged. If you +Now when we do `meson install` the bundle is properly staged. If you have any resource files or data, you need to install them into `Contents/Resources` either by custom install commands or specifying more install paths to the Meson command. diff --git a/docs/markdown/Creating-releases.md b/docs/markdown/Creating-releases.md index 45c4b4e..efaa85a 100644 --- a/docs/markdown/Creating-releases.md +++ b/docs/markdown/Creating-releases.md @@ -10,9 +10,17 @@ or zip format) of the source code. They do not contain any revision control metadata, only the source code. Meson provides a simple way of generating these. It consists of a -single command: +single command *(available since 0.52.0)*: - ninja dist +```sh +meson dist +``` + +or alternatively (on older meson versions with `ninja` backend): + +```sh +ninja dist +``` This creates a file called `projectname-version.tar.xz` in the build tree subdirectory `meson-dist`. This archive contains the full diff --git a/docs/markdown/Cross-compilation.md b/docs/markdown/Cross-compilation.md index 1c53dcf..d86d417 100644 --- a/docs/markdown/Cross-compilation.md +++ b/docs/markdown/Cross-compilation.md @@ -222,7 +222,7 @@ Once you have the cross file, starting a build is simple $ meson srcdir builddir --cross-file cross_file.txt ``` -Once configuration is done, compilation is started by invoking Ninja +Once configuration is done, compilation is started by invoking `meson compile` in the usual way. ## Introspection and system checks diff --git a/docs/markdown/Design-rationale.md b/docs/markdown/Design-rationale.md index 57aaee4..7121192 100644 --- a/docs/markdown/Design-rationale.md +++ b/docs/markdown/Design-rationale.md @@ -223,11 +223,11 @@ add_test('test library', exe) ``` First we build a shared library named foobar. It is marked -installable, so running `ninja install` installs it to the library +installable, so running `meson install` installs it to the library directory (the system knows which one so the user does not have to care). Then we build a test executable which is linked against the library. It will not be installed, but instead it is added to the list -of unit tests, which can be run with the command `ninja test`. +of unit tests, which can be run with the command `meson test`. Above we mentioned precompiled headers as a feature not supported by other build systems. Here's how you would use them. diff --git a/docs/markdown/FAQ.md b/docs/markdown/FAQ.md index 7b5c03a..7a41443 100644 --- a/docs/markdown/FAQ.md +++ b/docs/markdown/FAQ.md @@ -51,7 +51,7 @@ $ /path/to/meson.py <options> After this you don't have to care about invoking Meson any more. It remembers where it was originally invoked from and calls itself appropriately. As a user the only thing you need to do is to `cd` into -your build directory and invoke `ninja`. +your build directory and invoke `meson compile`. ## Why can't I specify target files with a wildcard? diff --git a/docs/markdown/Feature-autodetection.md b/docs/markdown/Feature-autodetection.md index c1b7659..a568313 100644 --- a/docs/markdown/Feature-autodetection.md +++ b/docs/markdown/Feature-autodetection.md @@ -34,6 +34,6 @@ also generated which will produce all 3 coverage report types, if possible. Note that generating any of the coverage reports described above -requires the tests (i.e. `ninja test`) to finish running so the +requires the tests (i.e. `meson test`) to finish running so the information about the functions that are called in the tests can be gathered for the report. diff --git a/docs/markdown/Gnome-module.md b/docs/markdown/Gnome-module.md index ced8a40..3d06233 100644 --- a/docs/markdown/Gnome-module.md +++ b/docs/markdown/Gnome-module.md @@ -223,7 +223,7 @@ directory. Note that this is not for installing schemas and is only useful when running the application locally for example during tests. * `build_by_default`: causes, when set to true, to have this target be - built by default, that is, when invoking plain `ninja`, the default + built by default, that is, when invoking plain `meson compile`, the default value is true for all built target types * `depend_files`: files ([`string`](Reference-manual.md#string-object), [`files()`](Reference-manual.md#files), or @@ -246,7 +246,7 @@ one XML file. * `annotations`: *(Added 0.43.0)* list of lists of 3 strings for the annotation for `'ELEMENT', 'KEY', 'VALUE'` * `docbook`: *(Added 0.43.0)* prefix to generate `'PREFIX'-NAME.xml` docbooks * `build_by_default`: causes, when set to true, to have this target be - built by default, that is, when invoking plain `ninja`, the default + built by default, that is, when invoking plain `meson compile`, the default value is true for all built target types * `install_dir`: (*Added 0.46.0*) location to install the header or bundle depending on previous options diff --git a/docs/markdown/IDE-integration.md b/docs/markdown/IDE-integration.md index f51075e..2cc4f4f 100644 --- a/docs/markdown/IDE-integration.md +++ b/docs/markdown/IDE-integration.md @@ -227,8 +227,8 @@ in the `meson.build`. ## 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 +Compilation and unit tests are done as usual by running the `meson compile` and +`meson 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 diff --git a/docs/markdown/IndepthTutorial.md b/docs/markdown/IndepthTutorial.md index dd93f82..d2e2662 100644 --- a/docs/markdown/IndepthTutorial.md +++ b/docs/markdown/IndepthTutorial.md @@ -79,12 +79,12 @@ With these four files we are done. To configure, build and run the test suite, w ```console $ meson builddir && cd builddir -$ ninja -$ ninja test +$ meson compile +$ meson test ``` To then install the project you only need one command. ```console -$ ninja install +$ meson install ``` diff --git a/docs/markdown/Installing.md b/docs/markdown/Installing.md index 5abfdd4..9dc2ad4 100644 --- a/docs/markdown/Installing.md +++ b/docs/markdown/Installing.md @@ -4,6 +4,18 @@ short-description: Installing targets # Installing +Invoked via the [following command](Commands.md#install) *(available since 0.47.0)*: + +```sh +meson install +``` + +or alternatively (on older meson versions with `ninja` backend): + +```sh +ninja install +``` + By default Meson will not install anything. Build targets can be installed by tagging them as installable in the definition. @@ -97,15 +109,13 @@ packages. This is done with the `DESTDIR` environment variable and it is used just like with other build systems: ```console -$ DESTDIR=/path/to/staging/area ninja install +$ DESTDIR=/path/to/staging/area meson install ``` ## Custom install behaviour -The default install target (executed via, e.g., `ninja install`) does -installing with reasonable default options. More control over the -install behaviour can be achieved with the `meson install` command, -that has been available since 0.47.0. +Installation behaviour can be further customized using +additional arguments. For example, if you wish to install the current setup without rebuilding the code (which the default install target always does) and diff --git a/docs/markdown/Meson-sample.md b/docs/markdown/Meson-sample.md index 6f26f36..f98e022 100644 --- a/docs/markdown/Meson-sample.md +++ b/docs/markdown/Meson-sample.md @@ -50,7 +50,7 @@ exe = executable('myexe', src) test('simple test', exe) ``` -Here we create a unit test called *simple test*, and which uses the built executable. When the tests are run with the `ninja test` command, the built executable is run. If it returns zero, the test passes. A non-zero return value indicates an error, which Meson will then report to the user. +Here we create a unit test called *simple test*, and which uses the built executable. When the tests are run with the `meson test` command, the built executable is run. If it returns zero, the test passes. A non-zero return value indicates an error, which Meson will then report to the user. A note to Visual Studio users ----- diff --git a/docs/markdown/Project-templates.md b/docs/markdown/Project-templates.md index 832cd1d..7ded318 100644 --- a/docs/markdown/Project-templates.md +++ b/docs/markdown/Project-templates.md @@ -16,8 +16,8 @@ $ meson init --language=c --name=myproject --version=0.1 ``` This would create the build definitions for a helloworld type -project. The result can be compiled as usual. For example compiling it -with Ninja could be done like this: +project. The result can be compiled as usual. For example it +could be done like this: ``` $ meson setup builddir diff --git a/docs/markdown/Qt5-module.md b/docs/markdown/Qt5-module.md index f1c2f6c..0d9a6b6 100644 --- a/docs/markdown/Qt5-module.md +++ b/docs/markdown/Qt5-module.md @@ -21,7 +21,7 @@ This method generates the necessary targets to build translation files with lrel - `ts_files`, the list of input translation files produced by Qt's lupdate tool. - `install` when true, this target is installed during the install step (optional). - `install_dir` directory to install to (optional). - - `build_by_default` when set to true, to have this target be built by default, that is, when invoking plain ninja; the default value is false (optional). + - `build_by_default` when set to true, to have this target be built by default, that is, when invoking `meson compile`; the default value is false (optional). ## has_tools diff --git a/docs/markdown/Quick-guide.md b/docs/markdown/Quick-guide.md index 0bed683..74636e5 100644 --- a/docs/markdown/Quick-guide.md +++ b/docs/markdown/Quick-guide.md @@ -93,8 +93,8 @@ are working on. The steps to take are very simple. ```console $ cd /path/to/source/root $ meson builddir && cd builddir -$ ninja -$ ninja test +$ meson compile +$ meson test ``` The only thing to note is that you need to create a separate build @@ -104,14 +104,14 @@ directory. This allows you to have multiple build trees with different configurations at the same time. This way generated files are not added into revision control by accident. -To recompile after code changes, just type `ninja`. The build command +To recompile after code changes, just type `meson compile`. The build command is always the same. You can do arbitrary changes to source code and build system files and Meson will detect those and will do the right thing. If you want to build optimized binaries, just use the argument `--buildtype=debugoptimized` when running Meson. It is recommended that you keep one build directory for unoptimized builds and one for optimized ones. To compile any given configuration, just go into the -corresponding build directory and run `ninja`. +corresponding build directory and run `meson compile`. Meson will automatically add compiler flags to enable debug information and compiler warnings (i.e. `-g` and `-Wall`). This means @@ -128,9 +128,9 @@ build and install Meson projects are the following. ```console $ cd /path/to/source/root $ meson --prefix /usr --buildtype=plain builddir -Dc_args=... -Dcpp_args=... -Dc_link_args=... -Dcpp_link_args=... -$ ninja -v -C builddir -$ ninja -C builddir test -$ DESTDIR=/path/to/staging/root ninja -C builddir install +$ meson compile -C builddir +$ meson test -C builddir +$ DESTDIR=/path/to/staging/root meson install -C builddir ``` The command line switch `--buildtype=plain` tells Meson not to add its @@ -139,7 +139,7 @@ on used flags. This is very similar to other build systems. The only difference is that the `DESTDIR` variable is passed as an environment variable -rather than as an argument to `ninja install`. +rather than as an argument to `meson install`. As distro builds happen always from scratch, you might consider enabling [unity builds](Unity-builds.md) on your packages because they diff --git a/docs/markdown/Running-Meson.md b/docs/markdown/Running-Meson.md index 910513c..326ecb9 100644 --- a/docs/markdown/Running-Meson.md +++ b/docs/markdown/Running-Meson.md @@ -9,13 +9,12 @@ from the source tree with the command `/path/to/source/meson.py`. Meson may also be installed in which case the command is simply `meson`. In this manual we only use the latter format for simplicity. -Additionally, the invocation can pass options to meson. The list of options is -documented [here](Builtin-options.md). - At the time of writing only a command line version of Meson is available. This means that Meson must be invoked using the terminal. If you wish to use the MSVC compiler, you need to run Meson under "Visual Studio command prompt". +All available meson commands are listed on the [commands reference page](Commands.md). + ## Configuring the build directory Let us assume that we have a source tree that has a Meson build system. This @@ -41,6 +40,9 @@ build backend in the build directory. By default Meson generates a *debug build*, which turns on basic warnings and debug information and disables compiler optimizations. +Additionally, the invocation can pass options to meson. The list of options is +documented [here](Builtin-options.md). + You can specify a different type of build with the `--buildtype` command line argument. It can have one of the following values. @@ -83,7 +85,7 @@ during configuration time. As an example, here is how you would use Meson to generate a Visual studio solution. ```sh -meson setup <build dir> --backend=vs2010 +meson setup <build dir> --backend=vs ``` You can then open the generated solution with Visual Studio and compile it in @@ -105,9 +107,18 @@ linker arguments needed. ## Building from the source -If you are not using an IDE, Meson uses the [Ninja build -system](https://ninja-build.org/) to actually build the code. To start the -build, simply type the following command. +To start the build, simply type the following command. + +```sh +meson compile -C builddir +``` + +See [`meson compile` description](Commands.md#compile) for more info. + +### Building directly with ninja + +By default Meson uses the [Ninja build system](https://ninja-build.org/) to +actually build the code. To start the build, simply type the following command. ```sh ninja -C builddir @@ -133,20 +144,29 @@ Meson provides native support for running tests. The command to do that is simple. ```sh -ninja -C builddir test +meson test -C builddir ``` +See [`meson test` description](Commands.md#test) for more info. + Meson does not force the use of any particular testing framework. You are free to use GTest, Boost Test, Check or even custom executables. +Note: it can be also invoked directly with ninja with the following command: +```sh +ninja -C builddir test +``` + ## Installing Installing the built software is just as simple. ```sh -ninja -C builddir install +meson install -C builddir ``` +See [`meson install` description](Commands.md#install) for more info. + Note that Meson will only install build targets explicitly tagged as installable, as detailed in the [installing targets documentation](Installing.md). @@ -157,7 +177,12 @@ Meson also supports the `DESTDIR` variable used in e.g. building packages. It is used like this: ```sh -DESTDIR=/path/to/staging ninja -C builddir install +DESTDIR=/path/to/staging meson install -C builddir +``` + +Note: it can be also invoked directly with ninja with the following command: +```sh +ninja -C builddir install ``` ## Command line help diff --git a/docs/markdown/Tutorial.md b/docs/markdown/Tutorial.md index 6b248b5..be6888d 100644 --- a/docs/markdown/Tutorial.md +++ b/docs/markdown/Tutorial.md @@ -124,12 +124,12 @@ or the like. Instead we just type the exact same command as if we were rebuilding our code without any build system changes. ``` -$ ninja +$ meson compile ``` Once you have set up your build directory the first time, you don't ever need to run the `meson` command again. You always just run -`ninja`. Meson will automatically detect when you have done changes to +`meson compile`. Meson will automatically detect when you have done changes to build definitions and will take care of everything so users don't have to care. In this case the following output is produced. diff --git a/docs/markdown/Unit-tests.md b/docs/markdown/Unit-tests.md index 06664db6..4f51d35 100644 --- a/docs/markdown/Unit-tests.md +++ b/docs/markdown/Unit-tests.md @@ -75,7 +75,7 @@ test machine. You can override this with the environment variable `MESON_TESTTHREADS` like this. ```console -$ MESON_TESTTHREADS=5 ninja test +$ MESON_TESTTHREADS=5 meson test ``` ## Priorities @@ -122,8 +122,7 @@ The goal of the meson test tool is to provide a simple way to run tests in a variety of different ways. The tool is designed to be run in the build directory. -The simplest thing to do is just to run all tests, which is equivalent to -running `ninja test`. +The simplest thing to do is just to run all tests. ```console $ meson test diff --git a/docs/markdown/Using-multiple-build-directories.md b/docs/markdown/Using-multiple-build-directories.md index 2455640..ab6cf3c 100644 --- a/docs/markdown/Using-multiple-build-directories.md +++ b/docs/markdown/Using-multiple-build-directories.md @@ -32,9 +32,9 @@ You can add cross builds, too. As an example, let's set up a Linux -> Windows cr mkdir buildwine meson --cross-file=mingw-cross.txt buildwine -The cross compilation file sets up Wine so that not only can you compile your application, you can also run the unit test suite just by issuing the command `ninja test`. +The cross compilation file sets up Wine so that not only can you compile your application, you can also run the unit test suite just by issuing the command `meson test`. -To compile any of these build types, just cd into the corresponding build directory and run `ninja` or instruct your IDE to do the same. Note that once you have set up your build directory once, you can just run Ninja and Meson will ensure that the resulting build is fully up to date according to the source. Even if you have not touched one of the directories in weeks and have done major changes to your build configuration, Meson will detect this and bring the build directory up to date (or print an error if it can't do that). This allows you to do most of your work in the default directory and use the others every now and then without having to babysit your build directories. +To compile any of these build types, just cd into the corresponding build directory and run `meson compile` or instruct your IDE to do the same. Note that once you have set up your build directory once, you can just run Ninja and Meson will ensure that the resulting build is fully up to date according to the source. Even if you have not touched one of the directories in weeks and have done major changes to your build configuration, Meson will detect this and bring the build directory up to date (or print an error if it can't do that). This allows you to do most of your work in the default directory and use the others every now and then without having to babysit your build directories. ## Specialized uses diff --git a/docs/markdown/Vs-External.md b/docs/markdown/Vs-External.md index add089e..ab3d191 100644 --- a/docs/markdown/Vs-External.md +++ b/docs/markdown/Vs-External.md @@ -23,9 +23,9 @@ as follows: | entry | value | | ----- | ----- | -|build | `ninja -C $(Configuration)` | -|clean | `ninja -C $(Configuration) clean` | -|rebuild| `ninja -C $(Configuration) clean all| +|build | `meson compile -C $(Configuration)` | +|clean | `meson compile -C $(Configuration) --clean` | +|rebuild| `meson compile -C $(Configuration) --clean && meson compile -C $(Configuration)` | |Output | `$(Configuration)\name_of_your_executable.exe| diff --git a/docs/markdown/howtox.md b/docs/markdown/howtox.md index 84546b7..b48aeab 100644 --- a/docs/markdown/howtox.md +++ b/docs/markdown/howtox.md @@ -148,8 +148,8 @@ $ meson <other flags> -Db_coverage=true Then issue the following commands. ```console -$ ninja -$ ninja test +$ meson compile +$ meson test $ ninja coverage-html (or coverage-xml) ``` @@ -209,8 +209,8 @@ operation. First we set up the project with profile measurements enabled and compile it. ```console -$ meson <Meson options, such as --buildtype=debugoptimized> -Db_pgo=generate -$ ninja -C builddir +$ meson setup <Meson options, such as --buildtype=debugoptimized> -Db_pgo=generate +$ meson compile -C builddir ``` Then we need to run the program with some representative input. This @@ -221,7 +221,7 @@ information and rebuild. ```console $ meson configure -Db_pgo=use -$ ninja +$ meson compile ``` After these steps the resulting binary is fully optimized. |