Debian Codegraph @

subprojects/meson-docs/docs/markdown/Getting-meson.md

raw
1 # Getting Meson
2
3 Meson is implemented in Python 3, and requires 3.7 or newer. If your
4 operating system provides a package manager, you should install it
5 with that. For platforms that don't have a package manager, you need
6 to download it from [Python's home page]. See below for
7 [platform-specific Python3 quirks](#platformspecific-install-quirks).
8
9 ## Downloading Meson
10
11 Meson releases can be downloaded from the [GitHub release page], and
12 you can run `./meson.py` from inside a release or the git repository
13 itself without doing anything special.
14
15 On Windows, if you did not install Python with the installer options
16 that make Python scripts executable, you will have to run `python
17 /path/to/meson.py`, where `python` is Python 3.7 or newer.
18
19 The newest development code can be obtained directly from [Git], and
20 we strive to ensure that it will always be working and usable. All
21 commits go through a pull-request process that runs CI and tests
22 several platforms.
23
24 ### Packing Meson into a zipapp
25
26 After downloading the release, you can create a standalone single-file
27 executable for Meson by running the script:
28
29 ```
30 ./packaging/create_zipapp.py --outfile meson.pyz --interpreter '/usr/bin/env python3' <source checkout>
31 ```
32
33 This uses python's native support for [zipapp].
34
35 ## Installing Meson with pip
36
37 Meson is available in the [Python Package Index] and can be installed
38 with `pip3 install --user meson`. This does not require any special
39 privileges. This will install the package in `~/.local/`, so you will
40 have to add `~/.local/bin` to your `PATH`. If you are using Meson only
41 for local development this should be all you need.
42
43 If you need to install your project in system directories, this
44 approach will not work as executable installed in this way are not
45 available when `sudo` is used. You can install Meson so it can be used
46 by every user with `sudo pip3 install meson`. It is generally not
47 recommended to do this, but instead use the version provided by distro
48 packages.
49
50 If you must install Meson with `sudo pip3` make sure to uninstall any
51 distro version first. Having multiple versions of any program in
52 system directories can lead to problems.
53
54 ## Installing Meson and Ninja with the MSI installer
55
56 We provide an MSI installer on the [GitHub release page] that can be
57 used to install both Meson and Ninja at once for Windows. It also
58 contains an embedded copy of Python, so scripts that use the [Python
59 module](Python-module.md) and do not have any external dependencies
60 will continue to work as expected.
61
62 Please note that this is a new feature, so bug reports are expected
63 and welcome!
64
65 ## Dependencies
66
67 In the most common case, you will need the [Ninja executable] for
68 using the `ninja` backend, which is the default in Meson. This backend
69 can be used on all platforms and with all toolchains, including GCC,
70 Clang, Visual Studio, MinGW, ICC, ARMCC, etc.
71
72 You can use the version provided by your package manager if possible,
73 otherwise download the binary executable from the [Ninja project's
74 release page](https://github.com/ninja-build/ninja/releases).
75
76 If you will only use the Visual Studio backend (`--backend=vs`) to
77 generate Visual Studio solutions on Windows or the XCode backend
78 (`--backend=xcode`) to generate XCode projects on macOS, you do not
79 need Ninja.
80
81 # Platform-specific install quirks
82
83 ## Windows Python3 quirks
84
85 When installing Python 3, it is highly recommended (but not required)
86 that you select the installer options as follows:
87
88 ![installer step 1](images/py3-install-1.png "Enable 'Add Python 3.6 to PATH' and click 'Customize installation'")
89 ![installer step 2](images/py3-install-2.png "Optional Features: ensure 'pip' is enabled")
90 ![installer step 3](images/py3-install-3.png "Advanced Options: enable 'Install for all users'")
91
92 With this, you will have `python` and `pip` in `PATH`, and you can
93 install Meson with pip. You will also be able to directly run `meson`
94 in any shell on Windows instead of having to run `py -3` with the full
95 path to the `meson.py` script.
96
97 ## MSYS2 Python3 quirks
98
99 If you are using MSYS2 on Windows as your development environment,
100 please make sure that you **do not use** the `msys/python` package to
101 provide Python 3. Use either `mingw32/mingw-w64-i686-python3` or
102 `mingw64/mingw-w64-x86_64-python3` depending on which MinGW target you
103 are building for.
104
105 [GitHub release page]: https://github.com/mesonbuild/meson/releases
106 [zipapp]: https://docs.python.org/3/library/zipapp.html
107 [Python Package Index]: https://pypi.python.org/pypi/meson/
108 [Git]: https://github.com/mesonbuild/meson
109 [Python's home page]: https://www.python.org/downloads/
110 [Ninja executable]: https://ninja-build.org/