Debian Codegraph @

subprojects/meson-docs/docs/markdown/Quick-guide.md

raw
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.