From 55e6d3c35e6a70c0294a15e8fa5be1ecdecefb27 Mon Sep 17 00:00:00 2001 From: Alistair Thomas Date: Wed, 9 Jan 2019 17:41:22 +0000 Subject: docs: Re-wrap Running-Meson.md from 70 to 80 columns [skip ci] --- docs/markdown/Running-Meson.md | 177 +++++++++++++++++++---------------------- 1 file changed, 84 insertions(+), 93 deletions(-) (limited to 'docs/markdown') diff --git a/docs/markdown/Running-Meson.md b/docs/markdown/Running-Meson.md index 426e87d..c1e95f1 100644 --- a/docs/markdown/Running-Meson.md +++ b/docs/markdown/Running-Meson.md @@ -4,26 +4,24 @@ short-description: Building a project with Meson # Running Meson -There are two different ways of invoking Meson. First, you can run it -directly from the source tree with the command -`/path/to/source/meson.py`. Meson may also be installed in which case -the command is simply `meson`. In this manual we only use the latter -format for simplicity. +There are two different ways of invoking Meson. First, you can run it directly +from the source tree with the command `/path/to/source/meson.py`. Meson may +also be installed in which case the command is simply `meson`. In this manual +we only use the latter format for simplicity. -Additionally, the invocation can pass options to meson. -The list of options is documented [here](Builtin-options.md). +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". +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". Configuring the source == -Let us assume that we have a source tree that has a Meson build -system. This means that at the topmost directory has a file called -`meson.build`. We run the following commands to get the build started. +Let us assume that we have a source tree that has a Meson build system. This +means that at the topmost directory has a file called `meson.build`. We run the +following commands to get the build started. cd /path/to/source/root @@ -31,22 +29,20 @@ system. This means that at the topmost directory has a file called cd builddir meson .. -First we create a directory to hold all files generated during the -build. Then we go into it and invoke Meson, giving it the location of -the source root. +First we create a directory to hold all files generated during the build. Then +we go into it and invoke Meson, giving it the location of the source root. -Hint: The syntax of meson is `meson [options] [srcdir] [builddir]`, -but you may omit either `srcdir` or `builddir`. Meson will deduce the -`srcdir` by the location of `meson.build`. The other one will be your -`pwd`. +Hint: The syntax of meson is `meson [options] [srcdir] [builddir]`, but you may +omit either `srcdir` or `builddir`. Meson will deduce the `srcdir` by the +location of `meson.build`. The other one will be your `pwd`. -Meson then loads the build configuration file and writes the -corresponding 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. +Meson then loads the build configuration file and writes the corresponding +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. -You can specify a different type of build with the `--buildtype` -command line argument. It can have one of the following values. +You can specify a different type of build with the `--buildtype` command line +argument. It can have one of the following values. | value | meaning | | ------ | -------- | @@ -55,94 +51,88 @@ command line argument. It can have one of the following values. | `debugoptimized` | debug info is generated and the code is optimized (on most compilers this means `-g -O2`) | | `release` | full optimization, no debug info | -The build directory is mandatory. The reason for this is that it -simplifies the build process immensely. Meson will not under any -circumstances write files inside the source directory (if it does, it -is a bug and should be fixed). This means that the user does not need -to add a bunch of files to their revision control's ignore list. It -also means that you can create arbitrarily many build directories for -any given source tree. If we wanted to test building the source code -with the Clang compiler instead of the system default, we could just -type the following commands. +The build directory is mandatory. The reason for this is that it simplifies the +build process immensely. Meson will not under any circumstances write files +inside the source directory (if it does, it is a bug and should be fixed). This +means that the user does not need to add a bunch of files to their revision +control's ignore list. It also means that you can create arbitrarily many build +directories for any given source tree. If we wanted to test building the source +code with the Clang compiler instead of the system default, we could just type +the following commands. cd /path/to/source/root mkdir buildclang cd buildclang CC=clang CXX=clang++ meson .. -This separation is even more powerful if your code has multiple -configuration options (such as multiple data backends). You can create -a separate subdirectory for each of them. You can also have build -directories for optimized builds, code coverage, static analysis and -so on. They are all neatly separated and use the same source -tree. Changing between different configurations is just a question of -changing to the corresponding directory. +This separation is even more powerful if your code has multiple configuration +options (such as multiple data backends). You can create a separate +subdirectory for each of them. You can also have build directories for +optimized builds, code coverage, static analysis and so on. They are all neatly +separated and use the same source tree. Changing between different +configurations is just a question of changing to the corresponding directory. -Unless otherwise mentioned, all following command line invocations are -meant to be run in the build directory. +Unless otherwise mentioned, all following command line invocations are meant to +be run in the build directory. -By default Meson will use the Ninja backend to build your project. If -you wish to use any of the other backends, you need to pass the -corresponding argument during configuration time. As an example, here -is how you would use Meson to generate a Visual studio solution. +By default Meson will use the Ninja backend to build your project. If you wish +to use any of the other backends, you need to pass the corresponding argument +during configuration time. As an example, here is how you would use Meson to +generate a Visual studio solution. meson --backend=vs2010 -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`. +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. +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. +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 == 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. +system](https://ninja-build.org/) to actually build the code. To start the +build, simply type the following command. ninja -The main usability difference between Ninja and Make is that Ninja -will automatically detect the number of CPUs in your computer and -parallelize itself accordingly. You can override the amount of -parallel processes used with the command line argument `-j `. - -It should be noted that after the initial configure step `ninja` is -the only command you ever need to type to compile. No matter how you -alter your source tree (short of moving it to a completely new -location), Meson will detect the changes and regenerate itself -accordingly. This is especially handy if you have multiple build -directories. Often one of them is used for development (the "debug" -build) and others only every now and then (such as a "static analysis" -build). Any configuration can be built just by `cd`'ing to the -corresponding directory and running Ninja. +The main usability difference between Ninja and Make is that Ninja will +automatically detect the number of CPUs in your computer and parallelize itself +accordingly. You can override the amount of parallel processes used with the +command line argument `-j `. + +It should be noted that after the initial configure step `ninja` is the only +command you ever need to type to compile. No matter how you alter your source +tree (short of moving it to a completely new location), Meson will detect the +changes and regenerate itself accordingly. This is especially handy if you have +multiple build directories. Often one of them is used for development (the +"debug" build) and others only every now and then (such as a "static analysis" +build). Any configuration can be built just by `cd`'ing to the corresponding +directory and running Ninja. Running tests == -Meson provides native support for running tests. The command to do -that is simple. +Meson provides native support for running tests. The command to do that is +simple. ninja test -Meson does not force the use of any particular testing framework. You -are free to use GTest, Boost Test, Check or even custom executables. +Meson does not force the use of any particular testing framework. You are free +to use GTest, Boost Test, Check or even custom executables. Installing == @@ -152,25 +142,26 @@ Installing the built software is just as simple. ninja install Note that Meson will only install build targets explicitly tagged as -installable, as detailed in the [installing targets documentation](Installing.md). +installable, as detailed in the [installing targets +documentation](Installing.md). -By default Meson installs to `/usr/local`. This can be changed by -passing the command line argument `--prefix /your/prefix` to Meson -during configure time. Meson also supports the `DESTDIR` variable used -in e.g. building packages. It is used like this: +By default Meson installs to `/usr/local`. This can be changed by passing the +command line argument `--prefix /your/prefix` to Meson during configure time. +Meson also supports the `DESTDIR` variable used in e.g. building packages. It +is used like this: DESTDIR=/path/to/staging ninja install Command line help == -Meson has a standard command line help feature. It can be accessed -with the following command. +Meson has a standard command line help feature. It can be accessed with the +following command. meson --help Exit status == -Meson exits with status 0 if successful, 1 for problems with the command line or -meson.build file, and 2 for internal errors. +Meson exits with status 0 if successful, 1 for problems with the command line +or meson.build file, and 2 for internal errors. -- cgit v1.1 From fb05733983fb06ee3d808c945d4df0050fd3e7bf Mon Sep 17 00:00:00 2001 From: Alistair Thomas Date: Wed, 9 Jan 2019 17:44:18 +0000 Subject: docs: Change sub-headings in Running-Meson.md from == to ## [skip ci] --- docs/markdown/Running-Meson.md | 21 +++++++-------------- 1 file changed, 7 insertions(+), 14 deletions(-) (limited to 'docs/markdown') diff --git a/docs/markdown/Running-Meson.md b/docs/markdown/Running-Meson.md index c1e95f1..1931bb3 100644 --- a/docs/markdown/Running-Meson.md +++ b/docs/markdown/Running-Meson.md @@ -16,8 +16,7 @@ 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". -Configuring the source -== +## Configuring the source Let us assume that we have a source tree that has a Meson build system. This means that at the topmost directory has a file called `meson.build`. We run the @@ -85,8 +84,7 @@ generate a Visual studio solution. 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 --- +## 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 @@ -100,8 +98,7 @@ 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 -== +## Building 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 @@ -123,8 +120,7 @@ multiple build directories. Often one of them is used for development (the build). Any configuration can be built just by `cd`'ing to the corresponding directory and running Ninja. -Running tests -== +## Running tests Meson provides native support for running tests. The command to do that is simple. @@ -134,8 +130,7 @@ simple. Meson does not force the use of any particular testing framework. You are free to use GTest, Boost Test, Check or even custom executables. -Installing -== +## Installing Installing the built software is just as simple. @@ -152,16 +147,14 @@ is used like this: DESTDIR=/path/to/staging ninja install -Command line help -== +## Command line help Meson has a standard command line help feature. It can be accessed with the following command. meson --help -Exit status -== +## Exit status Meson exits with status 0 if successful, 1 for problems with the command line or meson.build file, and 2 for internal errors. -- cgit v1.1 From 1b9e00f506113897ee9c29779854aa9033519b56 Mon Sep 17 00:00:00 2001 From: Alistair Thomas Date: Wed, 9 Jan 2019 18:05:57 +0000 Subject: docs: update RunningMeson.md to show Meson's setup command [skip ci] --- docs/markdown/Running-Meson.md | 67 +++++++++++++++++++++++++----------------- 1 file changed, 40 insertions(+), 27 deletions(-) (limited to 'docs/markdown') diff --git a/docs/markdown/Running-Meson.md b/docs/markdown/Running-Meson.md index 1931bb3..910513c 100644 --- a/docs/markdown/Running-Meson.md +++ b/docs/markdown/Running-Meson.md @@ -16,24 +16,25 @@ 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". -## Configuring the source +## Configuring the build directory Let us assume that we have a source tree that has a Meson build system. This means that at the topmost directory has a file called `meson.build`. We run the following commands to get the build started. +```sh +cd /path/to/source/root +meson setup builddir +``` - cd /path/to/source/root - mkdir builddir - cd builddir - meson .. +We invoke Meson with the `setup` command, giving it the location of the build +directory. Meson uses [out of source +builds](http://voices.canonical.com/jussi.pakkanen/2013/04/16/why-you-should-consider-using-separate-build-directories/). -First we create a directory to hold all files generated during the build. Then -we go into it and invoke Meson, giving it the location of the source root. - -Hint: The syntax of meson is `meson [options] [srcdir] [builddir]`, but you may -omit either `srcdir` or `builddir`. Meson will deduce the `srcdir` by the -location of `meson.build`. The other one will be your `pwd`. +Hint: The syntax of meson is `meson [command] [arguments] [options]`. The +`setup` command takes a `builddir` and a `srcdir` argument. If no `srcdir` is +given Meson will deduce the `srcdir` based on `pwd` and the location of +`meson.build`. Meson then loads the build configuration file and writes the corresponding build backend in the build directory. By default Meson generates a *debug @@ -55,14 +56,16 @@ build process immensely. Meson will not under any circumstances write files inside the source directory (if it does, it is a bug and should be fixed). This means that the user does not need to add a bunch of files to their revision control's ignore list. It also means that you can create arbitrarily many build -directories for any given source tree. If we wanted to test building the source -code with the Clang compiler instead of the system default, we could just type -the following commands. +directories for any given source tree. + +For example, if we wanted to test building the source code with the Clang +compiler instead of the system default, we could just type the following +commands: - cd /path/to/source/root - mkdir buildclang - cd buildclang - CC=clang CXX=clang++ meson .. +```sh +cd /path/to/source/root +CC=clang CXX=clang++ meson setup buildclang +``` This separation is even more powerful if your code has multiple configuration options (such as multiple data backends). You can create a separate @@ -72,19 +75,21 @@ separated and use the same source tree. Changing between different configurations is just a question of changing to the corresponding directory. Unless otherwise mentioned, all following command line invocations are meant to -be run in the build directory. +be run in the source directory. By default Meson will use the Ninja backend to build your project. If you wish to use any of the other backends, you need to pass the corresponding argument during configuration time. As an example, here is how you would use Meson to generate a Visual studio solution. - meson --backend=vs2010 +```sh +meson setup --backend=vs2010 +``` 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`. +the usual way. A list of backends can be obtained with `meson setup --help`. -## Environment Variables +## 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 @@ -98,13 +103,15 @@ 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 +## 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. - ninja +```sh +ninja -C builddir +``` The main usability difference between Ninja and Make is that Ninja will automatically detect the number of CPUs in your computer and parallelize itself @@ -125,7 +132,9 @@ directory and running Ninja. Meson provides native support for running tests. The command to do that is simple. - ninja test +```sh +ninja -C builddir test +``` Meson does not force the use of any particular testing framework. You are free to use GTest, Boost Test, Check or even custom executables. @@ -134,7 +143,9 @@ to use GTest, Boost Test, Check or even custom executables. Installing the built software is just as simple. - ninja install +```sh +ninja -C builddir install +``` Note that Meson will only install build targets explicitly tagged as installable, as detailed in the [installing targets @@ -145,7 +156,9 @@ command line argument `--prefix /your/prefix` to Meson during configure time. Meson also supports the `DESTDIR` variable used in e.g. building packages. It is used like this: - DESTDIR=/path/to/staging ninja install +```sh +DESTDIR=/path/to/staging ninja -C builddir install +``` ## Command line help -- cgit v1.1