Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit 241b7cc

Browse files
QuLogicissamarabi
QuLogic
authored and
issamarabi
committed
DOC: Update documentation for Meson change
1 parent 115f286 commit 241b7cc

File tree

11 files changed

+126
-81
lines changed

11 files changed

+126
-81
lines changed

‎.gitignore

Lines changed: 2 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -29,10 +29,10 @@
2929

3030
# Python files #
3131
################
32-
# setup.py working directory
32+
# meson-python working directory
3333
build
3434

35-
# setup.py dist directory
35+
# meson-python/build frontend dist directory
3636
dist
3737
# Egg metadata
3838
*.egg-info
@@ -41,9 +41,6 @@ dist
4141
pip-wheel-metadata/*
4242
# tox testing tool
4343
.tox
44-
mplsetup.cfg
45-
# generated by setuptools_scm
46-
lib/matplotlib/_version.py
4744
# build subproject files
4845
subprojects/*/
4946
!subprojects/packagefiles/

‎doc/api/next_api_changes/development/26621-ES.rst

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
Build system ported to Meson
2+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3+
4+
The build system of Matplotlib has been ported from setuptools to `meson-python
5+
<https://meson-python.readthedocs.io>`_ and `Meson <https://mesonbuild.com>`_.
6+
Consequently, there have been a few changes for development and packaging purposes.
7+
8+
1. Installation by ``pip`` of packages with ``pyproject.toml`` use `build isolation
9+
<https://pip.pypa.io/en/stable/reference/build-system/pyproject-toml/#build-isolation>`_
10+
by default, which interferes with editable installation. Thus for developers using
11+
editable installs, it is now necessary to pass the ``--no-build-isolation`` flag to
12+
``pip install``. This means that all build-time requirements must be available in the
13+
environment for an editable install.
14+
2. Build configuration has moved from a custom :file:`mplsetup.cfg` (also configurable
15+
via ``MPLSETUP`` environment variable) to Meson options. These may be specified using
16+
`meson-python's build config settings
17+
<https://meson-python.readthedocs.io/en/stable/how-to-guides/config-settings.html>`_
18+
for ``setup-args``. See :file:`meson_options.txt` for all options. For example, a
19+
:file:`mplsetup.cfg` containing the following::
20+
21+
[rc_options]
22+
backend=Agg
23+
24+
[libs]
25+
system_qhull = True
26+
27+
may be replaced by passing the following arguments to ``pip``::
28+
29+
--config-settings=setup-args="-DrcParams-backend=Agg" \
30+
--config-settings=setup-args="-Dsystem-qhull=true"
31+
32+
Note that you must use ``pip`` >= 23.1 in order to pass more than one setting.
33+
3. Relatedly, Meson's `builtin options <https://mesonbuild.com/Builtin-options.html>`_
34+
are now used instead of custom options, e.g., the LTO option is now ``b_lto``.
35+
4. On Windows, Meson activates a Visual Studio environment automatically. However, it
36+
will not do so if another compiler is available. See `Meson's documentation
37+
<https://mesonbuild.com/Builtin-options.html#details-for-vsenv>`_ if you wish to
38+
change the priority of chosen compilers.
39+
5. Installation of test data was previously controlled by :file:`mplsetup.cfg`, but has
40+
now been moved to Meson's install tags. To install test data, add the ``tests``
41+
tag to the requested install (be sure to include the existing tags as below)::
42+
43+
--config-settings=install-args="--tags=data,python-runtime,runtime,tests"
44+
6. Checking typing stubs with ``stubtest`` does not work easily with editable install.
45+
For the time being, we suggest using a normal (non-editable) install if you wish to
46+
run ``stubtest``.

‎doc/devel/contribute.rst

Lines changed: 3 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -266,7 +266,7 @@ A brief overview of the workflow is as follows.
266266

267267
#. Install the local version of Matplotlib with::
268268

269-
python -m pip install -e .
269+
python -m pip install --no-build-isolation --editable .[dev]
270270

271271
See :ref:`installing_for_devs` for detailed instructions.
272272

@@ -476,9 +476,8 @@ take particular care when adding new API:
476476
New modules and files: installation
477477
-----------------------------------
478478

479-
* If you have added new files or directories, or reorganized existing
480-
ones, make sure the new files are included in the match patterns in
481-
in *package_data* in :file:`setupext.py`.
479+
* If you have added new files or directories, or reorganized existing ones, make sure the
480+
new files are included in the :file:`meson.build` in the corresponding directories.
482481
* New modules *may* be typed inline or using parallel stub file like existing modules.
483482

484483
C/C++ extensions

‎doc/devel/dependencies.rst

Lines changed: 30 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -100,7 +100,8 @@ Matplotlib brings its own copies of the following libraries:
100100
Additionally, Matplotlib depends on:
101101

102102
- FreeType_ (>= 2.3): a font rendering library
103-
- QHull_ (>= 2020.2): a library for computing triangulations
103+
- QHull_ (>= 8.0.2): a library for computing triangulations (note that this version is
104+
also known as 2020.2)
104105

105106
.. _FreeType: https://www.freetype.org/
106107
.. _Qhull: http://www.qhull.org/
@@ -113,24 +114,16 @@ defaults to the system version of FreeType on AIX.
113114
Use system libraries
114115
^^^^^^^^^^^^^^^^^^^^
115116

116-
To force Matplotlib to use a copy of FreeType or Qhull already installed in
117-
your system, create a :file:`mplsetup.cfg` file with the following contents:
118-
119-
.. code-block:: cfg
120-
121-
[libs]
122-
system_freetype = true
123-
system_qhull = true
124-
125-
before running
117+
To force Matplotlib to use a copy of FreeType or Qhull already installed in your system,
118+
you must `pass configuration settings to Meson via meson-python
119+
<https://meson-python.readthedocs.io/en/stable/how-to-guides/config-settings.html>`_:
126120

127121
.. code-block:: sh
128122
129-
python -m pip install .
130-
131-
132-
You can also use the :envvar:`MPLSETUPCFG` to specify the path to a cfg file when
133-
installing from pypi.
123+
python -m pip install \
124+
--config-settings=setup-args="-Dsystem-freetype=true" \
125+
--config-settings=setup-args="-Dsystem-qhull=true" \
126+
.
134127
135128
136129
In this case, you need to install the FreeType and Qhull library and headers.
@@ -187,18 +180,12 @@ remember to clear your artifacts before re-building::
187180
Manual Download
188181
^^^^^^^^^^^^^^^
189182

190-
191-
If the automatic download does not work (for example on air-gapped systems) it
192-
is preferable to instead use system libraries. However you can manually
193-
download and unpack the tarballs into::
194-
195-
build/freetype-2.6.1 # on all platforms but windows ARM64
196-
build/freetype-2.11.1 # on windows ARM64
197-
build/qhull-2020.2
198-
199-
at the top level of the checkout repository. The expected sha256 hashes of
200-
the downloaded tarballs is in :file:`setupext.py` if you wish to verify
201-
before unpacking.
183+
If the automatic download does not work (for example, on air-gapped systems) it is
184+
preferable to instead use system libraries. However you can manually download the
185+
tarballs into :file:`subprojects/packagecache` at the top level of the checkout
186+
repository. The expected SHA256 hashes of the downloaded tarballs are in
187+
:file:`subprojects/*.wrap` if you wish to verify them, but they will also be checked by
188+
the build system before unpacking.
202189

203190

204191
Minimum pip / manylinux support (linux)
@@ -207,7 +194,7 @@ Minimum pip / manylinux support (linux)
207194
Matplotlib publishes `manylinux wheels <https://github.com/pypa/manylinux>`_
208195
which have a minimum version of pip which will recognize the wheels
209196

210-
- Python 3.9+: ``manylinx2014`` / pip >= 19.3
197+
- Python 3.9+: ``manylinux2014`` / pip >= 19.3
211198

212199
In all cases the required version of pip is embedded in the CPython source.
213200

@@ -223,12 +210,18 @@ Dependencies for building Matplotlib
223210
Setup dependencies
224211
------------------
225212

226-
- `certifi <https://pypi.org/project/certifi/>`_ (>= 2020.06.20). Used while
227-
downloading the freetype and QHull source during build. This is not a
228-
runtime dependency.
213+
By default, ``pip`` will build packages using build isolation, and the following
214+
dependencies will be automatically installed in the isolated environment to build
215+
Matplotlib. However, for development, you may wish to make an editable install, which
216+
will require disabling build isolation, so these build dependencies should be installed
217+
in your target environment manually:
218+
219+
- `meson-python <https://meson-python.readthedocs.io/>`_ (>= 0.13.1).
220+
- `ninja <https://ninja-build.org/>`_ (>= 1.8.2). This may be available in your package
221+
manager or bundled with Meson, but may be installed via ``pip`` if otherwise not
222+
available.
229223
- `PyBind11 <https://pypi.org/project/pybind11/>`_ (>= 2.6). Used to connect C/C++ code
230224
with Python.
231-
- `setuptools <https://pypi.org/project/setuptools/>`_ (>= 64).
232225
- `setuptools_scm <https://pypi.org/project/setuptools-scm/>`_ (>= 7). Used to
233226
update the reported ``mpl.__version__`` based on the current git commit.
234227
Also a runtime dependency for editable installs.
@@ -288,8 +281,6 @@ Xcode, VS Code or Linux package manager. Choose **one** compiler from this list:
288281
- Linux, macOS, Windows
289282
- `gcc 4.8.1 <https://gcc.gnu.org/projects/cxx-status.html#cxx11>`_,
290283
`GCC: Binaries <https://gcc.gnu.org/install/binaries.html>`_,
291-
292-
For gcc <6.5 you will need to set ``$CFLAGS=-std=c++11`` to enable C++11 support.
293284
* - Clang (LLVM)
294285
- **3.3**
295286
- Linux, macOS
@@ -330,8 +321,8 @@ testing the following will be used if they are installed.
330321
- pytest-xvfb_ to run tests without windows popping up (Linux)
331322
- pytz_ used to test pytz int
332323
- sphinx_ used to test our sphinx extensions
333-
- WenQuanYi Zen Hei and `Noto Sans CJK <https://fonts.google.com/noto/use>`_
334-
fonts for testing font fallback and non-western fonts
324+
- `WenQuanYi Zen Hei`_ and `Noto Sans CJK`_ fonts for testing font fallback and
325+
non-Western fonts
335326
- xarray_ used to test compatibility with xarray
336327

337328
If any of these dependencies are not discovered, then the tests that rely on
@@ -359,6 +350,8 @@ them will be skipped by pytest.
359350
.. _pytest-xvfb: https://pypi.org/project/pytest-xvfb/
360351
.. _pytest: http://doc.pytest.org/en/latest/
361352
.. _sphinx: https://pypi.org/project/Sphinx/
353+
.. _WenQuanYi Zen Hei: http://wenq.org/en/
354+
.. _Noto Sans CJK: https://fonts.google.com/noto/use
362355
.. _xarray: https://pypi.org/project/xarray/
363356

364357

‎doc/devel/development_setup.rst

Lines changed: 18 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -157,34 +157,36 @@ must be installed separately. For a full list, see :ref:`dependencies`.
157157
Install Matplotlib in editable mode
158158
===================================
159159

160-
Install Matplotlib in editable mode from the :file:`matplotlib` directory
161-
using the command ::
160+
Install Matplotlib in editable mode from the :file:`matplotlib` directory using the
161+
command ::
162162

163-
python -m pip install -ve .
163+
python -m pip install --verbose --no-build-isolation --editable .[dev]
164164

165-
The 'editable/develop mode', builds everything and places links in your Python
166-
environment so that Python will be able to import Matplotlib from your
167-
development source directory. This allows you to import your modified version
168-
of Matplotlib without re-installing after every change. Note that this is only
169-
true for ``*.py`` files. If you change the C-extension source (which might
170-
also happen if you change branches) you will have to re-run
171-
``python -m pip install -ve .``
165+
The 'editable/develop mode' builds everything and places links in your Python environment
166+
so that Python will be able to import Matplotlib from your development source directory.
167+
This allows you to import your modified version of Matplotlib without re-installing after
168+
every change. Note that before the merging of the `Meson port
169+
<https://github.com/matplotlib/matplotlib/pull/26621>`_, this is only true for ``*.py``
170+
files. If you change the C-extension source based on a commit before the change to the
171+
Meson build system (which might also happen if you change branches), you will have to
172+
re-run the above command.
172173

173174
Verify the Installation
174175
=======================
175176

176-
Run the following command to make sure you have correctly installed Matplotlib in editable mode.
177-
The command should be run when the virtual environment is activated ::
177+
Run the following command to make sure you have correctly installed Matplotlib in
178+
editable mode. The command should be run when the virtual environment is activated::
178179

179180
python -c "import matplotlib; print(matplotlib.__file__)"
180181

181182
This command should return : ``<matplotlib_local_repo>\lib\matplotlib\__init__.py``
182183

183-
We encourage you to run tests and build docs to verify that the code installed correctly and that the docs build cleanly,
184-
so that when you make code or document related changes you are aware of the existing issues beforehand.
184+
We encourage you to run tests and build docs to verify that the code installed correctly
185+
and that the docs build cleanly, so that when you make code or document related changes
186+
you are aware of the existing issues beforehand.
185187

186-
* Run test cases to verify installation :ref:`testing`
187-
* Verify documentation build :ref:`documenting-matplotlib`
188+
* Run test cases to verify installation :ref:`testing`
189+
* Verify documentation build :ref:`documenting-matplotlib`
188190

189191
Install pre-commit hooks
190192
========================

‎doc/devel/min_dep_policy.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,7 @@ Matplotlib supports:
2222
- All minor versions of ``numpy`` released in the 24 months prior
2323
to the project, and at minimum the last three minor versions.
2424

25-
In ``setup.py``, the ``python_requires`` variable should be set to
25+
In :file:`pyproject.toml`, the ``requires-python`` variable should be set to
2626
the minimum supported version of Python. All supported minor
2727
versions of Python should be in the test matrix and have binary
2828
artifacts built for the release.

‎doc/users/faq.rst

Lines changed: 10 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -355,17 +355,23 @@ provide the following information in your e-mail to the `mailing list
355355

356356
If you compiled Matplotlib yourself, please also provide:
357357

358-
* any changes you have made to ``setup.py`` or ``setupext.py``.
358+
* your compiler version -- e.g., ``gcc --version``.
359359
* the output of::
360360

361-
rm -rf build
362-
python setup.py build
361+
pip install --verbose
363362

364363
The beginning of the build output contains lots of details about your
365364
platform that are useful for the Matplotlib developers to diagnose your
366365
problem.
367366

368-
* your compiler version -- e.g., ``gcc --version``.
367+
If you compiled an older version of Matplotlib using the pre-Meson build system, instead
368+
provide:
369+
370+
* any changes you have made to ``setup.py``/``setupext.py``,
371+
* the output of::
372+
373+
rm -rf build
374+
python setup.py build
369375

370376
Including this information in your first e-mail to the mailing list
371377
will save a lot of time.

‎lib/matplotlib/__init__.py

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1307,17 +1307,17 @@ def _val_or_rc(val, rc_name):
13071307

13081308

13091309
def _init_tests():
1310-
# The version of FreeType to install locally for running the
1311-
# tests. This must match the value in `setupext.py`
1310+
# The version of FreeType to install locally for running the tests. This must match
1311+
# the value in `meson.build`.
13121312
LOCAL_FREETYPE_VERSION = '2.6.1'
13131313

13141314
from matplotlib import ft2font
13151315
if (ft2font.__freetype_version__ != LOCAL_FREETYPE_VERSION or
13161316
ft2font.__freetype_build_type__ != 'local'):
13171317
_log.warning(
13181318
f"Matplotlib is not built with the correct FreeType version to "
1319-
f"run tests. Rebuild without setting system_freetype=1 in "
1320-
f"mplsetup.cfg. Expect many image comparison failures below. "
1319+
f"run tests. Rebuild without setting system-freetype=true in "
1320+
f"Meson setup options. Expect many image comparison failures below. "
13211321
f"Expected freetype version {LOCAL_FREETYPE_VERSION}. "
13221322
f"Found freetype version {ft2font.__freetype_version__}. "
13231323
"Freetype build type is {}local".format(

‎meson_options.txt

Lines changed: 10 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,20 @@
1+
# Options may be set by passing through `pip` or `build` via meson-python:
2+
# https://meson-python.readthedocs.io/en/stable/how-to-guides/config-settings.html
3+
14
# By default, Matplotlib downloads and builds its own copies of FreeType and of
2-
# Qhull. You may set the following to True to instead link against a system
3-
# FreeType/Qhull. As an exception, Matplotlib defaults to the system version
4-
# of FreeType on AIX.
5+
# Qhull. You may use the following options to instead link against a system
6+
# FreeType/Qhull. As an exception, Matplotlib defaults to the system version of
7+
# FreeType on AIX.
58
option('system-freetype', type: 'boolean', value: false,
69
description: 'Build against system version of FreeType')
710
option('system-qhull', type: 'boolean', value: false,
811
description: 'Build against system version of Qhull')
912

1013
# Some of Matplotlib's components are optional: the MacOSX backend (installed
11-
# by default on MacOSX; requires the Cocoa headers included with XCode), and
12-
# the test data (i.e., the baseline image files; not installed by default). You
13-
# can control whether they are installed by uncommenting the following lines.
14-
# Note that the MacOSX backend is never built on Linux or Windows, regardless
15-
# of the config value.
14+
# by default on MacOSX; requires the Cocoa headers included with XCode). You
15+
# can control whether they are installed using the following options. Note that
16+
# the MacOSX backend is never built on Linux or Windows, regardless of the
17+
# config value.
1618
option('macosx', type: 'boolean', value: true,
1719
description: 'Enable MacOSX backend (requires Cocoa)')
1820

‎requirements/doc/doc-requirements.txt

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
#
33
# You will first need a matching Matplotlib installation
44
# e.g (from the Matplotlib root directory)
5-
# pip install -e .
5+
# pip install --no-build-isolation --editable .[dev]
66
#
77
# Install the documentation requirements with:
88
# pip install -r requirements/doc/doc-requirements.txt

‎src/_qhull_wrapper.cpp

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -162,7 +162,7 @@ delaunay_impl(npy_intp npoints, const double* x, const double* y,
162162
if (hide_qhull_errors) {
163163
/* qhull errors are ignored by writing to OS-equivalent of /dev/null.
164164
* Rather than have OS-specific code here, instead it is determined by
165-
* setupext.py and passed in via the macro MPL_DEVNULL. */
165+
* meson.build and passed in via the macro MPL_DEVNULL. */
166166
error_file = fopen(STRINGIFY(MPL_DEVNULL), "w");
167167
if (error_file == NULL) {
168168
throw std::runtime_error("Could not open devnull");

0 commit comments

Comments
 (0)