diff --git a/docs/markdown/Adding-arguments.md b/docs/markdown/Adding-arguments.md index 80f02d978..606737731 100644 --- a/docs/markdown/Adding-arguments.md +++ b/docs/markdown/Adding-arguments.md @@ -1,3 +1,7 @@ +--- +short-description: Adding compiler arguments +... + # Adding arguments Often you need to specify extra compiler arguments. Meson provides two different ways to achieve this: global arguments and per-target arguments. diff --git a/docs/markdown/Build-options.md b/docs/markdown/Build-options.md index 64e2d384e..6029a2c99 100644 --- a/docs/markdown/Build-options.md +++ b/docs/markdown/Build-options.md @@ -1,3 +1,7 @@ +--- +short-description: Build options to configure project properties +... + # Build options Most non-trivial builds require user-settable options. As an example a program may have two different data backends that are selectable at build time. Meson provides for this by having a option definition file. Its name is `meson_options.txt` and it is placed at the root of your source tree. diff --git a/docs/markdown/Build-system-converters.md b/docs/markdown/Build-system-converters.md index f4ee50183..6c816581f 100644 --- a/docs/markdown/Build-system-converters.md +++ b/docs/markdown/Build-system-converters.md @@ -1,3 +1,7 @@ +--- +short-description: Converting other build systems to Meson +... + # Build system converters Moving from one build system into another includes a fair bit of work. To make things easier, Meson provides scripts to convert other build systems into Meson. At the time of writing, scripts for CMake and autotools exist. It can be found in the `tools` subdirectory in Meson's source tree. diff --git a/docs/markdown/Configuration.md b/docs/markdown/Configuration.md index 037bcbd62..70649d730 100644 --- a/docs/markdown/Configuration.md +++ b/docs/markdown/Configuration.md @@ -1,3 +1,7 @@ +--- +short-description: Build-time configuration options +... + # Configuration If there are multiple configuration options, passing them through compiler flags becomes very burdensome. It also makes the configuration settings hard to inspect. To make things easier, Meson supports the generation of configure files. This feature is similar to one found in other build systems such as CMake. diff --git a/docs/markdown/Configuring-a-build-directory.md b/docs/markdown/Configuring-a-build-directory.md index e887e9eee..c7aa91376 100644 --- a/docs/markdown/Configuring-a-build-directory.md +++ b/docs/markdown/Configuring-a-build-directory.md @@ -1,3 +1,7 @@ +--- +short-description: Configuring a pre-generated build directory +... + # Configuring a build directory Often you want to change the settings of your build after it has been generated. For example you might want to change from a debug build into a release build, set custom compiler flags, change the build options provided in your `meson_options.txt` file and so on. diff --git a/docs/markdown/Continuous-Integration.md b/docs/markdown/Continuous-Integration.md index 1dff200be..e57ea786b 100644 --- a/docs/markdown/Continuous-Integration.md +++ b/docs/markdown/Continuous-Integration.md @@ -33,8 +33,8 @@ script: - if [[ "$TRAVIS_OS_NAME" == "linux" ]]; then echo FROM YOUR/REPO:yakkety > 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 build && ninja -C build test"; fi - - if [[ "$TRAVIS_OS_NAME" == "osx" ]]; then SDKROOT=$(xcodebuild -version -sdk macosx Path) meson build && ninja -C build test; 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 ``` ## AppVeyor for Windows @@ -67,11 +67,11 @@ install: build_script: - cmd: echo Building on %arch% with %compiler% - - cmd: PATH=%cd%;%MESON_PYTHON_PATH%;%PATH%; && python meson.py --backend=ninja build - - cmd: PATH=%cd%;%MESON_PYTHON_PATH%;%PATH%; && ninja -C build + - cmd: PATH=%cd%;%MESON_PYTHON_PATH%;%PATH%; && python meson.py --backend=ninja builddir + - cmd: PATH=%cd%;%MESON_PYTHON_PATH%;%PATH%; && ninja -C builddir test_script: - - cmd: PATH=%cd%;%MESON_PYTHON_PATH%;%PATH%; && ninja -C build test + - cmd: PATH=%cd%;%MESON_PYTHON_PATH%;%PATH%; && ninja -C builddir test ``` ## Travis without Docker @@ -96,7 +96,7 @@ install: - pip3 install meson script: - - meson build - - ninja -C build - - ninja -C build test + - meson builddir + - ninja -C builddir + - ninja -C builddir test ``` diff --git a/docs/markdown/Creating-Linux-binaries.md b/docs/markdown/Creating-Linux-binaries.md index 29d68ec52..8e9fb6051 100644 --- a/docs/markdown/Creating-Linux-binaries.md +++ b/docs/markdown/Creating-Linux-binaries.md @@ -1,3 +1,7 @@ +--- +short-description: Creating universal Linux binaries +... + # Creating Linux binaries Creating Linux binaries that can be downloaded and run on any distro (like .dmg packages for OSX or .exe installers for Windows) has traditionally been difficult. This is even more tricky if you want to use modern compilers and features, which is especially desired in game development. There is still no simple turn key solution for this problem but with a bit of setup it can be relatively straightforward. diff --git a/docs/markdown/Creating-OSX-packages.md b/docs/markdown/Creating-OSX-packages.md index 8faf568cf..4a4612e05 100644 --- a/docs/markdown/Creating-OSX-packages.md +++ b/docs/markdown/Creating-OSX-packages.md @@ -1,3 +1,7 @@ +--- +short-description: Tools to create OS X packages +... + # Creating OSX packages Meson does not have native support for building OSX packages but it does provide all the tools you need to create one yourself. The reason for this is that it is a very hard task to write a system that provides for all the different ways to do that but it is very easy to write simple scripts for each application. diff --git a/docs/markdown/Cross-compilation.md b/docs/markdown/Cross-compilation.md index b5df8b3f6..21f418b7a 100644 --- a/docs/markdown/Cross-compilation.md +++ b/docs/markdown/Cross-compilation.md @@ -1,3 +1,7 @@ +--- +short-description: Setting up cross-compilation +... + # Cross compilation Meson has full support for cross compilation. Since cross compiling is more complicated than native building, diff --git a/docs/markdown/Custom-build-targets.md b/docs/markdown/Custom-build-targets.md index 0c34b1fe8..a425f8cbf 100644 --- a/docs/markdown/Custom-build-targets.md +++ b/docs/markdown/Custom-build-targets.md @@ -1,3 +1,7 @@ +--- +short-description: Build targets for custom languages or corner-cases +... + # Custom build targets While Meson tries to support as many languages and tools as possible, there is no possible way for it to cover all corner cases. For these cases it permits you to define custom build targets. Here is how one would use it. diff --git a/docs/markdown/Dependencies.md b/docs/markdown/Dependencies.md index c57b9d47f..3c07de9ba 100644 --- a/docs/markdown/Dependencies.md +++ b/docs/markdown/Dependencies.md @@ -1,3 +1,7 @@ +--- +short-description: Dependencies for external libraries and frameworks +... + # Dependencies Very few applications are fully self-contained, but rather they use external libraries and frameworks to do their work. Meson makes it very easy to find and use external dependencies. Here is how one would use the Zlib compression library. diff --git a/docs/markdown/External-commands.md b/docs/markdown/External-commands.md index af19794ad..f597b0cef 100644 --- a/docs/markdown/External-commands.md +++ b/docs/markdown/External-commands.md @@ -1,3 +1,7 @@ +--- +short-description: Running external commands +... + # External commands As a part of the software configuration, you may want to get extra data by running external commands. The basic syntax is the following. diff --git a/docs/markdown/Feature-autodetection.md b/docs/markdown/Feature-autodetection.md index b6a4f4186..8de4086f0 100644 --- a/docs/markdown/Feature-autodetection.md +++ b/docs/markdown/Feature-autodetection.md @@ -1,3 +1,7 @@ +--- +short-description: Auto-detection of features like ccache and code coverage +... + # Feature autodetection Meson is designed for high productivity. It tries to do as many things automatically as it possibly can. diff --git a/docs/markdown/Generating-sources.md b/docs/markdown/Generating-sources.md index 82b043dfb..630b7e9e7 100644 --- a/docs/markdown/Generating-sources.md +++ b/docs/markdown/Generating-sources.md @@ -1,3 +1,7 @@ +--- +short-description: Generation of source files before compilation +... + # Generating sources Sometimes source files need to be preprocessed before they are passed to the actual compiler. As an example you might want build an IDL compiler and then run some files through that to generate actual source files. In Meson this is done with [`generator()`](https://github.com/mesonbuild/meson/wiki/Reference-manual#generator) or [`custom_target()`](https://github.com/mesonbuild/meson/wiki/Reference-manual#custom_target). diff --git a/docs/markdown/Getting-meson.md b/docs/markdown/Getting-meson.md index f28a7e2d3..1dabe950e 100644 --- a/docs/markdown/Getting-meson.md +++ b/docs/markdown/Getting-meson.md @@ -20,9 +20,9 @@ Depending on your platform and backend you wish to use, you might need the [Ninja executable]. Again, use your distro-provided version if possible. Otherwise download it from Ninja project's web site. - [Github release page]: https://github.com/jpakkane/meson/releases + [Github release page]: https://github.com/mesonbuild/meson/releases [Python Package Index]: https://pypi.python.org/pypi/meson/ - [Git]: https://github.com/jpakkane/meson + [Git]: https://github.com/mesonbuild/meson [Python's home page]: https://www.python.org/downloads/ [Ninja executable]: https://ninja-build.org/ diff --git a/docs/markdown/IDE-integration.md b/docs/markdown/IDE-integration.md index 7e046c6f6..7258f567e 100644 --- a/docs/markdown/IDE-integration.md +++ b/docs/markdown/IDE-integration.md @@ -1,3 +1,7 @@ +--- +short-description: Meson's API to integrate Meson support into an IDE +... + # IDE integration Meson has exporters for Visual Studio and XCode, but writing a custom backend for every IDE out there is not a scalable approach. To solve this problem, Meson provides an API that makes it easy for any IDE or build tool to integrate Meson builds and provide an experience comparable to a solution native to the IDE. @@ -6,7 +10,7 @@ The basic tool for this is a script called `mesonintrospect.py`. Some distro pac The first thing to do when setting up a Meson project in an IDE is to select the source and build directories. For this example we assume that the source resides in an Eclipse-like directory called `workspace/project` and the build tree is nested inside it as `workspace/project/build`. First we initialise Meson by running the following command in the source directory. - meson build + meson builddir For the remainder of the document we assume that all commands are executed inside the build directory unless otherwise specified. @@ -32,7 +36,7 @@ The next thing to display is the list of options that can be set. These include To set the options, use the `mesonconf.py` binary. -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/build/meson-logs/testlog.json`. +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/Include-directories.md b/docs/markdown/Include-directories.md index 949bf2c5a..c1d4ac12d 100644 --- a/docs/markdown/Include-directories.md +++ b/docs/markdown/Include-directories.md @@ -1,3 +1,7 @@ +--- +short-description: Instructions on handling include directories +... + # Include directories Most `C`/`C++` projects have headers in different directories than sources. Thus you need to specify include directories. Let's assume that we are at some subdirectory and wish to add its `include` subdirectory to some target's search path. To create a include directory object we do this: diff --git a/docs/markdown/IndepthTutorial.md b/docs/markdown/IndepthTutorial.md index d67adf7c9..dd93f826b 100644 --- a/docs/markdown/IndepthTutorial.md +++ b/docs/markdown/IndepthTutorial.md @@ -78,7 +78,7 @@ At this point we can return to the pkg-config generator line. All shared librari With these four files we are done. To configure, build and run the test suite, we just need to execute the following commands (starting at source tree root directory). ```console -$ meson build && cd build +$ meson builddir && cd builddir $ ninja $ ninja test ``` diff --git a/docs/markdown/Installing.md b/docs/markdown/Installing.md index 40dcd8dcf..f18688902 100644 --- a/docs/markdown/Installing.md +++ b/docs/markdown/Installing.md @@ -1,3 +1,7 @@ +--- +short-description: Installing targets +... + # Installing By default Meson will not install anything. Build targets can be installed by tagging them as installable in the definition. diff --git a/docs/markdown/Java.md b/docs/markdown/Java.md index 8501bdfe0..9b893043d 100644 --- a/docs/markdown/Java.md +++ b/docs/markdown/Java.md @@ -1,5 +1,6 @@ --- title: Java +short-description: Compiling Java programs ... # Compiling Java applications diff --git a/docs/markdown/Localisation.md b/docs/markdown/Localisation.md index 9fde9701a..f342ecc72 100644 --- a/docs/markdown/Localisation.md +++ b/docs/markdown/Localisation.md @@ -1,3 +1,7 @@ +--- +short-description: Localization with GNU Gettext +... + # Localisation Localising your application with GNU Gettext takes a little effort but is quite straightforward. This documentation assumes that you have a `po` subdirectory at your project root directory that contains all the localisation info. diff --git a/docs/markdown/Modules.md b/docs/markdown/Modules.md index e59438346..c354169e6 100644 --- a/docs/markdown/Modules.md +++ b/docs/markdown/Modules.md @@ -1,3 +1,7 @@ +--- +short-description: Meson modules for common build operations +... + # Modules In addition to core language features, Meson also provides a module system aimed at providing helper methods for common build operations. Using modules is simple, first you import them: diff --git a/docs/markdown/Precompiled-headers.md b/docs/markdown/Precompiled-headers.md index a7bcbf819..cae0bd1d6 100644 --- a/docs/markdown/Precompiled-headers.md +++ b/docs/markdown/Precompiled-headers.md @@ -1,3 +1,7 @@ +--- +short-description: Using precompiled headers to reduce compilation time +... + # Precompiled headers Parsing header files of system libraries is surprisingly expensive. A typical source file has less than one thousand lines of code. In contrast the headers of large libraries can be tens of thousands of lines. This is especially problematic with C++, where header-only libraries are common and they may contain extremely complex code. This makes them slow to compile. diff --git a/docs/markdown/Quick-guide.md b/docs/markdown/Quick-guide.md index 39660847d..600120eb0 100644 --- a/docs/markdown/Quick-guide.md +++ b/docs/markdown/Quick-guide.md @@ -40,7 +40,7 @@ The most common use case of Meson is compiling code on a code base you are worki ```console $ cd /path/to/source/root -$ meson build && cd build +$ meson builddir && cd builddir $ ninja $ ninja test ``` @@ -58,10 +58,10 @@ Distro packagers usually want total control on the build flags used. Meson suppo ```console $ cd /path/to/source/root -$ CFLAGS=... CXXFLAGS=... LDFLAGS=.. meson --prefix /usr --buildtype=plain build -$ ninja -v -C build -$ ninja -C build test -$ DESTDIR=/path/to/staging/root ninja -C build install +$ CFLAGS=... CXXFLAGS=... LDFLAGS=.. meson --prefix /usr --buildtype=plain builddir +$ ninja -v -C builddir +$ ninja -C builddir test +$ DESTDIR=/path/to/staging/root ninja -C builddir install ```` The command line switch `--buildtype=plain` tells Meson not to add its own flags to the command line. This gives the packager total control on used flags. diff --git a/docs/markdown/Reference-manual.md b/docs/markdown/Reference-manual.md index dd99bde25..6265ea136 100644 --- a/docs/markdown/Reference-manual.md +++ b/docs/markdown/Reference-manual.md @@ -696,7 +696,7 @@ Provides information about the build machine — the machine that is doing the a - `system()` returns the operating system name, such as `windows` (all versions of Windows), `linux` (all Linux distros), `darwin` (all versions of OS X), etc. - `endian()` returns `big` on big-endian systems and `little` on little-endian systems. -Currently, these values are populated using the [`platform.system()`](https://docs.python.org/3.4/library/platform.html#platform.system) and [`platform.machine()`](https://docs.python.org/3.4/library/platform.html#platform.machine). If you think the returned values for any of these are incorrect for your system or CPU, please file [a bug report](/mesonbuild/meson/issues/new). +Currently, these values are populated using the [`platform.system()`](https://docs.python.org/3.4/library/platform.html#platform.system) and [`platform.machine()`](https://docs.python.org/3.4/library/platform.html#platform.machine). If you think the returned values for any of these are incorrect for your system or CPU, please file [a bug report](https://github.com/mesonbuild/meson/issues/new). ### `host_machine` object diff --git a/docs/markdown/Run-targets.md b/docs/markdown/Run-targets.md index 86639abd8..38129a6d2 100644 --- a/docs/markdown/Run-targets.md +++ b/docs/markdown/Run-targets.md @@ -1,3 +1,7 @@ +--- +short-description: Targets to run external commands +... + # Run targets Sometimes you need to have a target that just runs an external command. As an example you might have a build target that reformats your source code, runs `cppcheck` or something similar. In Meson this is accomplished with a so called *run target*. diff --git a/docs/markdown/Running-Meson.md b/docs/markdown/Running-Meson.md index 5ae407ebd..d9847ac05 100644 --- a/docs/markdown/Running-Meson.md +++ b/docs/markdown/Running-Meson.md @@ -15,8 +15,8 @@ Let us assume that we have a source tree that has a Meson build system. This mea cd /path/to/source/root - mkdir build - cd build + mkdir builddir + 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. diff --git a/docs/markdown/Subprojects.md b/docs/markdown/Subprojects.md index 0318e7956..b4e092502 100644 --- a/docs/markdown/Subprojects.md +++ b/docs/markdown/Subprojects.md @@ -1,3 +1,7 @@ +--- +short-description: Using meson projects as subprojects within other meson projects +... + # Subprojects Some platforms do not provide a native packaging system. In these cases it is common to bundle all third party libraries in your source tree. This is usually frowned upon because it makes it hard to add these kinds of projects into e.g. those Linux distributions that forbid bundled libraries. diff --git a/docs/markdown/Threads.md b/docs/markdown/Threads.md index d4f1bcae8..1bf9f830a 100644 --- a/docs/markdown/Threads.md +++ b/docs/markdown/Threads.md @@ -1,3 +1,7 @@ +--- +short-description: Enabling thread support +... + # Threads Meson has a very simple notational shorthand for enabling thread support on your build targets. First you obtain the thread dependency object like this: diff --git a/docs/markdown/Tutorial.md b/docs/markdown/Tutorial.md index 524861dcf..ae2e38165 100644 --- a/docs/markdown/Tutorial.md +++ b/docs/markdown/Tutorial.md @@ -30,7 +30,7 @@ executable('demo', 'main.c') That is all. We are now ready to build our application. First we need to initialise the build by going into the source directory and issuing the following commands. ```console -$ meson build +$ meson builddir ``` We create a separate build directory to hold all of the compiler output. Meson is different from some other build systems in that it does not permit in-source builds. You must always create a separate build directory. Common convention is to put the default build directory in a subdirectory of your toplevel source directory. @@ -40,7 +40,7 @@ When Meson is run it prints the following output. The Meson build system version: 0.13.0-research Source dir: /home/jpakkane/mesontutorial - Build dir: /home/jpakkane/mesontutorial/build + Build dir: /home/jpakkane/mesontutorial/builddir Build type: native build Project name is "tutorial". Using native c compiler "ccache cc". (gcc 4.8.2) @@ -49,7 +49,7 @@ When Meson is run it prints the following output. Now we are ready to build our code. ``` -$ cd build +$ cd builddir $ ninja ``` @@ -102,7 +102,7 @@ Once you have set up your build directory the first time, you don't ever need to The Meson build system version: 0.13.0-research Source dir: /home/jpakkane/mesontutorial - Build dir: /home/jpakkane/mesontutorial/build + Build dir: /home/jpakkane/mesontutorial/builddir Build type: native build Project name is "tutorial". Using native c compiler "ccache cc". (gcc 4.8.2) diff --git a/docs/markdown/Unit-tests.md b/docs/markdown/Unit-tests.md index d5ef77e1d..83c371293 100644 --- a/docs/markdown/Unit-tests.md +++ b/docs/markdown/Unit-tests.md @@ -1,3 +1,7 @@ +--- +short-description: Meson's own unit-test system +... + # Unit tests Meson comes with a fully functional unit test system. To use it simply build an executable and then use it in a test. diff --git a/docs/markdown/Unity-builds.md b/docs/markdown/Unity-builds.md index f1f718e55..9f939f5bd 100644 --- a/docs/markdown/Unity-builds.md +++ b/docs/markdown/Unity-builds.md @@ -1,3 +1,7 @@ +--- +short-description: Unity builds are a technique for reducing build times +... + # Unity builds Unity builds are a technique for cutting down build times. The way it works is relatively straightforward. Suppose we have source files `src1.c`, `src2.c` and `src3.c`. Normally we would run the compiler three times, once for each file. In a unity build we instead compile all these sources in a single unit. The simplest approach is to create a new source file that looks like this. diff --git a/docs/markdown/Using-multiple-build-directories.md b/docs/markdown/Using-multiple-build-directories.md index cabd64f4e..ac67f8418 100644 --- a/docs/markdown/Using-multiple-build-directories.md +++ b/docs/markdown/Using-multiple-build-directories.md @@ -14,13 +14,13 @@ Since a build directory is fully self contained and treats the source tree as a The first thing to do is to set up the default build, that is, the one we are going to use over 90% of the time. In this we use the system compiler and build with debug enabled and no optimizations so it builds as fast as possible. This is the default project type for Meson, so setting it up is simple. - mkdir build - meson build + mkdir builddir + meson builddir Another common setup is to build with debug and optimizations to, for example, run performance tests. Setting this up is just as simple. mkdir buildopt - meson --buildtype=debugoptimized + meson --buildtype=debugoptimized buildopt For systems where the default compiler is GCC, we would like to compile with Clang, too. So let's do that. diff --git a/docs/markdown/Using-with-Visual-Studio.md b/docs/markdown/Using-with-Visual-Studio.md index 2768ea4f2..339fda331 100644 --- a/docs/markdown/Using-with-Visual-Studio.md +++ b/docs/markdown/Using-with-Visual-Studio.md @@ -8,8 +8,8 @@ In order to generate Visual Studio projects, Meson needs to know the settings of 1. Click on start menu and select "Visual Studio 2015 Command Prompt" 1. cd into your source directory -1. mkdir build -1. python3 path/to/meson.py build --backend vs2015 +1. mkdir builddir +1. python3 path/to/meson.py builddir --backend vs2015 If you wish to use the Ninja backend instead of vs2015, pass `--backend ninja`. At the time of writing the Ninja backend is more mature than the VS backend so you might want to use it for serious work. diff --git a/docs/markdown/Vala.md b/docs/markdown/Vala.md index 0a6bc81b6..259ebd1a8 100644 --- a/docs/markdown/Vala.md +++ b/docs/markdown/Vala.md @@ -1,5 +1,6 @@ --- title: Vala +short-description: Compiling Vala programs ... # Compiling Vala applications