| 1 |
--- |
| 2 |
title: Quickstart Guide |
| 3 |
short-description: Getting Started using Mesonbuild |
| 4 |
... |
| 5 |
|
| 6 |
# Using Meson |
| 7 |
|
| 8 |
Meson has been designed to be as simple to use as possible. This page |
| 9 |
outlines the initial steps needed for installation, troubleshooting, |
| 10 |
and standard use. |
| 11 |
|
| 12 |
For more advanced configuration please refer to the command line help |
| 13 |
`meson --help` or the Meson documentation located at the |
| 14 |
[Mesonbuild](https://mesonbuild.com) website. |
| 15 |
|
| 16 |
Table of Contents: |
| 17 |
* [Requirements](#requirements) |
| 18 |
* [Installation using package manager](#installation-using-package-manager) |
| 19 |
* [Installation using Python](#installation-using-python) |
| 20 |
* [Installation from source](#installation-from-source) |
| 21 |
* [Troubleshooting](#troubleshooting) |
| 22 |
* [Compiling a Meson project](#compiling-a-meson-project) |
| 23 |
* [Using Meson as a distro packager](#using-meson-as-a-distro-packager) |
| 24 |
|
| 25 |
Requirements |
| 26 |
-- |
| 27 |
|
| 28 |
* [Python 3](https://python.org) |
| 29 |
* [Ninja](https://github.com/ninja-build/ninja/) |
| 30 |
|
| 31 |
*Ninja is only needed if you use the Ninja backend. Meson can also |
| 32 |
generate native VS and Xcode project files.* |
| 33 |
|
| 34 |
|
| 35 |
Installation using package manager |
| 36 |
-- |
| 37 |
|
| 38 |
Ubuntu: |
| 39 |
|
| 40 |
```console |
| 41 |
$ sudo apt-get install python3 python3-pip python3-setuptools \ |
| 42 |
python3-wheel ninja-build |
| 43 |
``` |
| 44 |
*Due to our frequent release cycle and development speed, distro packaged software may quickly become outdated.* |
| 45 |
|
| 46 |
Installation using Python |
| 47 |
-- |
| 48 |
Requirements: **pip3** |
| 49 |
|
| 50 |
The best way to receive the most up-to-date version of Mesonbuild. |
| 51 |
|
| 52 |
Install as a local user (recommended): |
| 53 |
```console |
| 54 |
$ pip3 install --user meson |
| 55 |
``` |
| 56 |
Install as root: |
| 57 |
```console |
| 58 |
# pip3 install meson |
| 59 |
``` |
| 60 |
|
| 61 |
*If you are unsure whether to install as root or a local user, install |
| 62 |
as a local user.* |
| 63 |
|
| 64 |
|
| 65 |
Installation from source |
| 66 |
-- |
| 67 |
Requirements: **git** |
| 68 |
|
| 69 |
Meson can be run directly from the cloned git repository. |
| 70 |
|
| 71 |
```console |
| 72 |
$ git clone https://github.com/mesonbuild/meson.git /path/to/sourcedir |
| 73 |
``` |
| 74 |
Troubleshooting: |
| 75 |
-- |
| 76 |
Common Issues: |
| 77 |
```console |
| 78 |
$ meson setup builddir |
| 79 |
$ bash: /usr/bin/meson: No such file or directory |
| 80 |
``` |
| 81 |
|
| 82 |
**Description**: The default installation prefix for the python pip module |
| 83 |
installation might not be included in your shell environment `PATH`. |
| 84 |
The default install location varies depending on your OS, distro and |
| 85 |
Python version. |
| 86 |
|
| 87 |
**Resolution**: This issue can be resolved by altering the default shell |
| 88 |
environment `PATH` to include the path where Pip installed the |
| 89 |
binaries. This can be, e.g. ``/usr/local/bin`` or |
| 90 |
`/home/<username>/.local/bin`. |
| 91 |
|
| 92 |
**Note**: There are other ways of fixing this issue such as using |
| 93 |
symlinks or copying the binaries to a default path and these methods |
| 94 |
are not recommended or supported as they may break package management |
| 95 |
interoperability. |
| 96 |
|
| 97 |
|
| 98 |
Compiling a Meson project |
| 99 |
-- |
| 100 |
|
| 101 |
The most common use case of Meson is compiling code on a code base you |
| 102 |
are working on. The steps to take are very simple. |
| 103 |
|
| 104 |
```console |
| 105 |
$ cd /path/to/source/root |
| 106 |
$ meson setup builddir && cd builddir |
| 107 |
$ meson compile |
| 108 |
$ meson test |
| 109 |
``` |
| 110 |
|
| 111 |
The only thing to note is that you need to create a separate build |
| 112 |
directory. Meson will not allow you to build source code inside your |
| 113 |
source tree. All build artifacts are stored in the build directory. |
| 114 |
This allows you to have multiple build trees with different |
| 115 |
configurations at the same time. This way generated files are not |
| 116 |
added into revision control by accident. |
| 117 |
|
| 118 |
To recompile after code changes, just type `meson compile`. The build |
| 119 |
command is always the same. You can do arbitrary changes to source |
| 120 |
code and build system files and Meson will detect those and will do |
| 121 |
the right thing. If you want to build optimized binaries, just use the |
| 122 |
argument `--buildtype=debugoptimized` when running Meson. It is |
| 123 |
recommended that you keep one build directory for unoptimized builds |
| 124 |
and one for optimized ones. To compile any given configuration, just |
| 125 |
go into the corresponding build directory and run `meson compile`. |
| 126 |
|
| 127 |
Meson will automatically add compiler flags to enable debug |
| 128 |
information and compiler warnings (i.e. `-g` and `-Wall`). This means |
| 129 |
the user does not have to deal with them and can instead focus on |
| 130 |
coding. |
| 131 |
|
| 132 |
Using Meson as a distro packager |
| 133 |
-- |
| 134 |
|
| 135 |
Distro packagers usually want total control on the build flags |
| 136 |
used. Meson supports this use case natively. The commands needed to |
| 137 |
build and install Meson projects are the following. |
| 138 |
|
| 139 |
```console |
| 140 |
$ cd /path/to/source/root |
| 141 |
$ meson --prefix /usr --buildtype=plain builddir -Dc_args=... -Dcpp_args=... -Dc_link_args=... -Dcpp_link_args=... |
| 142 |
$ meson compile -C builddir |
| 143 |
$ meson test -C builddir |
| 144 |
$ DESTDIR=/path/to/staging/root meson install -C builddir |
| 145 |
``` |
| 146 |
|
| 147 |
The command line switch `--buildtype=plain` tells Meson not to add its |
| 148 |
own flags to the command line. This gives the packager total control |
| 149 |
on used flags. |
| 150 |
|
| 151 |
This is very similar to other build systems. The only difference is |
| 152 |
that the `DESTDIR` variable is passed as an environment variable |
| 153 |
rather than as an argument to `meson install`. |
| 154 |
|
| 155 |
As distro builds happen always from scratch, you might consider |
| 156 |
enabling [unity builds](Unity-builds.md) on your packages because they |
| 157 |
are faster and produce better code. However there are many projects |
| 158 |
that do not build with unity builds enabled so the decision to use |
| 159 |
unity builds must be done by the packager on a case by case basis. |