Skip to content

Commit 2d9ecff

Browse files
tobiasdieztobiasdiez
committed
Update meson instructions
1 parent d617df4 commit 2d9ecff

File tree

1 file changed

+179
-89
lines changed

1 file changed

+179
-89
lines changed

‎src/doc/en/installation/meson.rst

Lines changed: 179 additions & 89 deletions
Original file line numberDiff line numberDiff line change
@@ -9,106 +9,177 @@ This is a short guide on how to build the Sage from source using Meson.
99
Walkthrough
1010
===========
1111

12-
Assume we're starting from a clean repo and a fully set up conda environment
13-
(modify ``-linux`` according to your operating system):
14-
15-
.. tab:: Linux
12+
.. note::
1613

17-
.. code-block:: shell
14+
If you have previously build Sage in-place, you first have to delete the
15+
already compiled files, e.g. with ``shopt -s globstar`` followed by
16+
``rm src/**/*.so`` or ``for f in src/**/*.so ; do mv "$f" "$f.old"; done``.
17+
Moreover, remove the old generated files with
18+
``find src/sage/ext/interpreters -type f ! -name 'meson.build' -delete``.
19+
Also uninstall the 'old' sage packages with ``pip uninstall sage-conf sage-setup sagemath-standard``.
20+
21+
Sage relies on a number of external libraries, which have to be installed
22+
before building. The easiest way to install them is to use Conda.
23+
Alternatively, you can install them via your system package manager.
24+
Both methods are described below.
25+
26+
Using Conda
27+
~~~~~~~~~~~
28+
29+
- If you haven't already, download and install Miniforge for your platform
30+
following the `Miniforge instructions <https://github.com/conda-forge/miniforge?tab=readme-ov-file#install>`_.
31+
Other Conda distributions like Miniconda should work as well, but
32+
may require additional configuration (see :ref:`sec-installation-conda`).
33+
34+
- Create and activate a new conda environment with the dependencies of Sage
35+
and a few additional developer tools:
36+
37+
.. tab:: Linux
38+
39+
.. code-block:: shell
40+
41+
$ mamba env create --file environment-3.12-linux.yml --name sage-dev
42+
$ mamba activate sage-dev
43+
44+
.. tab:: macOS
45+
46+
.. code-block:: shell
47+
48+
$ mamba env create --file environment-3.12-macos.yml --name sage-dev
49+
$ mamba activate sage-dev
50+
51+
.. tab:: Windows
52+
53+
.. note::
54+
55+
Windows support is very experimental and many features are not working
56+
yet.
57+
58+
First you need to install the Microsoft Visual C++ compiler.
59+
You can download the
60+
`Visual Studio Build Tools <https://aka.ms/vs/17/release/vs_BuildTools.exe>`_.
61+
Make sure to select "VC++ 2022 version xx.x build tools" and "Windows SDK".
62+
If you prefer, you can also run the following command to install the necessary
63+
components:
64+
65+
.. code-block:: shell
66+
67+
$ winget install Microsoft.VisualStudio.2022.BuildTools --force --override "--wait --passive --add Microsoft.VisualStudio.Component.VC.Tools.x86.x64 --add Microsoft.VisualStudio.Component.Windows11SDK.22621"
68+
69+
Alternatively, you can use the compiler that comes bundled with Visual Studio.
70+
71+
If you haven't already, install the latest version of Conda from
72+
`Miniforge <https://github.com/conda-forge/miniforge?tab=readme-ov-file#windows>`_.
73+
It is strongly recommended to choose the option to add Conda to the `PATH`
74+
during installation (because we will not use the Miniforge prompt).
75+
76+
Open the "VS x64 Native Tools Command Prompt" (for 64bit) or
77+
"Developer Command Prompt for VS2022 (or 2019)" (for 32bit).
78+
79+
.. code-block:: shell
1880
19-
$ mamba env create --file environment-3.11-linux.yml --name sage-dev
20-
$ mamba activate sage-dev
81+
$ mamba env create --file environment-3.12-win.yml --name sage-dev
82+
$ conda activate sage-dev
83+
$ set LIB=%CONDA_PREFIX%\Library\lib;%LIB%
84+
$ set INCLUDE=%CONDA_PREFIX%\Library\include;%INCLUDE%
2185
22-
.. tab:: macOS
23-
24-
.. code-block:: shell
86+
Windows support is experimental and not fully working yet.
87+
In fact, the Sage prompt is not working at all, but you can use the Python
88+
prompt to run certain commands. For example, the following should work
89+
after building Sage:
2590

26-
$ mamba env create --file environment-3.11-macos.yml --name sage-dev
27-
$ mamba activate sage-dev
91+
.. code-block:: python
2892
29-
.. tab:: Windows
30-
31-
.. note::
93+
>>> from sage.rings.integer import Integer
94+
>>> Integer(5)
95+
5
96+
>>> Integer(5) + 2.0
97+
7.0
3298
33-
Windows support is very experimental and many features are not working
34-
yet.
99+
A different Python version can be selected by replacing ``3.12`` with the
100+
desired version.
35101

36-
First you need to install the Microsoft Visual C++ compiler.
37-
You can download the
38-
`Visual Studio Build Tools <https://aka.ms/vs/17/release/vs_BuildTools.exe>`_.
39-
Make sure to select "VC++ 2022 version xx.x build tools" and "Windows SDK".
40-
If you prefer, you can also run the following command to install the necessary
41-
components:
42-
43-
.. code-block:: shell
102+
- To compile and install Sage in editable install, just use:
103+
.. code-block:: shell-session
44104
45-
$ winget install Microsoft.VisualStudio.2022.BuildTools --force --override "--wait --passive --add Microsoft.VisualStudio.Component.VC.Tools.x86.x64 --add Microsoft.VisualStudio.Component.Windows11SDK.22621"
46-
47-
Alternatively, you can use the compiler that comes bundled with Visual Studio.
105+
$ pip install --no-build-isolation --editable .
48106
49-
If you haven't already, install the latest version of Conda from
50-
`Miniforge <https://github.com/conda-forge/miniforge?tab=readme-ov-file#windows>`_.
51-
It is strongly recommended to choose the option to add Conda to the `PATH`
52-
during installation (because we will not use the Miniforge prompt).
107+
This will install Sage in the current Conda environment.
108+
The ``--no-build-isolation`` flag is necessary to allow the build system
109+
to reuse the already installed build dependencies.
53110

54-
Open the "VS x64 Native Tools Command Prompt" (for 64bit) or
55-
"Developer Command Prompt for VS2022 (or 2019)" (for 32bit).
111+
- You can then start Sage from the command line with ``./sage``
112+
or run the tests with ``./sage -t``.
56113

57-
.. code-block:: shell
114+
Using system package manager
115+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
58116

59-
$ mamba env create --file environment-3.11-win.yml --name sage-dev
60-
$ conda activate sage-dev
61-
$ set LIB=%CONDA_PREFIX%\Library\lib;%LIB%
62-
$ set INCLUDE=%CONDA_PREFIX%\Library\include;%INCLUDE%
117+
You can also install the dependencies via your system package manager.
118+
Note, however, that not all dependencies may be available for your system,
119+
and that the versions may be outdated.
120+
In this case, Meson will try to build certain dependencies from source,
121+
or it will fail with an error message.
122+
In this case, you can either install the missing dependencies manually,
123+
or use Conda to install them.
63124

64-
Windows support is experimental and not fully working yet.
65-
In fact, the Sage prompt is not working at all, but you can use the Python
66-
prompt to run certain commands. For example, the following should work:
125+
Depending on your distribution, install the following packages:
67126

68-
.. code-block:: python
127+
.. tab:: Debian/Ubuntu
69128

70-
>>> from sage.rings.integer import Integer
71-
>>> Integer(5)
72-
5
73-
>>> Integer(5) + 2.0
74-
7.0
129+
Not yet supported.
75130

131+
.. .. literalinclude:: debian.txt
76132
77-
Alternatively, install all build requirements as described in section
78-
:ref:`section-prereqs`. In the likely case that you have to install some
79-
dependencies manually, set the correct environment variables to point
80-
to the installed libraries:
133+
.. tab:: Fedora
81134

82-
.. CODE-BLOCK:: shell-session
135+
At least Fedora 41 is required.
136+
137+
.. literalinclude:: fedora.txt
138+
139+
140+
.. tab:: Arch Linux
141+
142+
.. literalinclude:: arch.txt
143+
144+
.. tab:: Void Linux
145+
146+
.. literalinclude:: void.txt
147+
148+
149+
In the case that you want to install some dependencies manually, set the
150+
correct environment variables to point to the installed libraries:
151+
152+
.. code-block:: shell-session
83153
84154
$ export C_INCLUDE_PATH=$C_INCLUDE_PATH:/your/path/to/include
85155
$ export CPLUS_INCLUDE_PATH=$CPLUS_INCLUDE_PATH:/your/path/to/include
86156
$ export LIBRARY_PATH=$LIBRARY_PATH:/your/path/to/lib
87157
88-
.. NOTE::
158+
We also recommend to install the Python package manager
159+
`uv <https://docs.astral.sh/uv/getting-started/installation/>`_.
89160

90-
If you have previously build Sage in-place, you first have to delete the
91-
already compiled files, e.g. with ``shopt -s globstar`` followed by
92-
``rm src/**/*.so`` or ``for f in src/**/*.so ; do mv "$f" "$f.old"; done``.
93-
Moreover, remove the old generated files with
94-
``find src/sage/ext/interpreters -type f ! -name 'meson.build' -delete``.
95-
Also uninstall the 'old' sage packages with ``pip uninstall sage-conf sage-setup sagemath-standard``.
96-
97-
To compile and install the project in editable install, just use:
161+
To compile and install Sage in editable install, then just use:
98162

99-
.. CODE-BLOCK:: shell-session
163+
.. code-block:: shell-session
100164
101-
$ pip install --no-build-isolation --editable .
102-
103-
This will install Sage in the current Python environment.
104-
In a Conda environment, the ``--no-build-isolation`` flag is necessary to
105-
allow the build system to reuse the already installed build dependencies.
106-
If you don't use Conda, you can omit this flag.
165+
$ uv pip install \
166+
meson-python \
167+
"cypari2 >=2.2.1" \
168+
"cysignals >=1.11.2, != 1.12.0" \
169+
"cython >=3.0, != 3.0.3" \
170+
"gmpy2 ~=2.1.b999" \
171+
memory_allocator \
172+
"numpy >=1.25" \
173+
jinja2
174+
$ uv sync --frozen --inexact
107175
108176
You can then start Sage from the command line with ``./sage``
109177
or run the tests with ``./sage -t``.
110178

111-
.. NOTE::
179+
Remarks
180+
~~~~~~~
181+
182+
.. note::
112183

113184
By using ``pip install --editable`` in the above steps, the Sage library
114185
is installed in editable mode. This means that when you only edit source
@@ -117,13 +188,13 @@ or run the tests with ``./sage -t``.
117188
automatically), so you no longer need to manually compile after editing Cython
118189
files.
119190

120-
.. NOTE::
191+
.. note::
121192

122193
Note that ``make`` is not used at all, nor is ``configure``.
123194
This means that any Sage-the-distribution commands such as ``sage -i``
124195
will not work.
125196

126-
.. NOTE::
197+
.. note::
127198

128199
By default, Meson will automatically determine the number of jobs to
129200
run in parallel based on the number of CPU available. This can be adjusted
@@ -132,6 +203,21 @@ or run the tests with ``./sage -t``.
132203
``--verbose`` can be passed to ``pip install``, then the meson commands
133204
internally used by pip will be printed out.
134205

206+
.. note::
207+
208+
To build the documentation, use::
209+
210+
$ pip install --no-build-isolation -v -v --editable ./pkgs/sage-docbuild
211+
$ sage --docbuild all html
212+
213+
.. note::
214+
215+
You can update the conda lock files by running ``tools/update-conda.py``.
216+
In order to update the conda environment afterwards use::
217+
218+
$ mamba env update --file environment-3.12-linux.yml --name sage-dev
219+
220+
135221
Background information
136222
======================
137223

@@ -140,52 +226,55 @@ We can also use meson directly as follows.
140226

141227
To configure the project, we need to run the following command:
142228

143-
.. CODE-BLOCK:: shell-session
229+
.. code-block:: shell-session
144230
145231
$ meson setup builddir
146232
147-
This will create a build directory ``builddir`` that will hold the build artifacts.
233+
This will create a build directory ``builddir`` that will hold the build
234+
artifacts.
148235

149236
If pip is used as above with ``--editable``, ``builddir`` is set to be
150-
``build/cp[Python major version][Python minor version]``, such as ``build/cp311``.
237+
``build/cp[Python major version][Python minor version]``, such as
238+
``build/cp311``.
151239

152240
To compile the project, run the following command:
153241

154-
.. CODE-BLOCK:: shell-session
242+
.. code-block:: shell-session
155243
156244
$ meson compile -C builddir
157245
158246
Installing is done with the following command:
159247

160-
.. CODE-BLOCK:: shell-session
248+
.. code-block:: shell-session
161249
162250
$ meson install -C builddir
163251
164-
This will install the project to currently active Python environment,
252+
This will install the project to currently active Python environment,
165253
or to the system Python environment if no environment is active.
166-
When editable install is used, it is not necessary to reinstall after each compilation.
254+
When editable install is used, it is not necessary to reinstall after each
255+
compilation.
167256

168-
.. NOTE::
257+
.. note::
169258

170259
If you want to install the project to a different directory, you can specify
171260
the ``--prefix`` option when running the ``meson setup`` command:
172261

173-
.. CODE-BLOCK:: shell-session
262+
.. code-block:: shell-session
174263
175264
$ meson setup builddir --prefix=/desired/install/path -Dpython.install_env=prefix
176265
177266
This will then install in the directory specified by ``--prefix``,
178267
in particular the root folder will be be installed to
179-
``/desired/install/path/lib/python3.11/site-packages/sage``.
268+
``/desired/install/path/lib/python3.12/site-packages/sage``.
180269
Usually, this directory is not on your Python path, so you have to use:
181270

182-
.. CODE-BLOCK:: shell-session
271+
.. code-block:: shell-session
183272
184273
$ PYTHONPATH=/desired/install/path ./sage
185274
186275
Alternatively, we can still use pip to install:
187276

188-
.. CODE-BLOCK:: shell-session
277+
.. code-block:: shell-session
189278
190279
$ pip install --no-build-isolation --config-settings=builddir=builddir --editable .
191280
@@ -195,7 +284,7 @@ Alternatively, we can still use pip to install:
195284
to install to a different directory than the install prefix.
196285
Both are supported naturally by Meson:
197286

198-
.. CODE-BLOCK:: shell-session
287+
.. code-block:: shell-session
199288
200289
$ meson setup builddir --prefix=/usr --libdir=... -Dcpp_args=...
201290
$ meson compile -C builddir
@@ -216,10 +305,11 @@ The environment variable ``MESONPY_EDITABLE_VERBOSE=1`` can be set while running
216305
so that when Cython files are recompiled a message is printed out.
217306
See `<https://mesonbuild.com/meson-python/how-to-guides/editable-installs.html#verbose-mode>`_.
218307

219-
If a new ``.pyx`` file is added, it need to be added to ``meson.build`` file in the
220-
containing directory.
308+
If a new ``.pyx`` file is added, it need to be added to ``meson.build`` file in
309+
the containing directory.
221310

222-
Unlike the ``make``-based build system which relies on header comments ``# distutils: language = c++``
223-
to determine whether C++ should be used, Meson-based build system requires specifying
311+
Unlike the ``make``-based build system which relies on header comments
312+
``# distutils: language = c++`` to determine whether C++ should be used,
313+
Meson-based build system requires specifying
224314
``override_options: ['cython_language=cpp']`` in the ``meson.build`` file.
225315
Similarly, dependencies need to be specified by ``dependencies: [...]``.

0 commit comments

Comments
 (0)