DOC: Update documentation for Meson change

Author: QuLogic

.gitignore

@@ -29,10 +29,10 @@
 
 # Python files #
 ################
-# setup.py working directory
+# meson-python working directory
 build
 
-# setup.py dist directory
+# meson-python/build frontend dist directory
 dist
 # Egg metadata
 *.egg-info
@@ -41,9 +41,6 @@ dist
 pip-wheel-metadata/*
 # tox testing tool
 .tox
-mplsetup.cfg
-# generated by setuptools_scm
-lib/matplotlib/_version.py
 # build subproject files
 subprojects/*/
 !subprojects/packagefiles/

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

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

doc/devel/contribute.rst

@@ -266,7 +266,7 @@ A brief overview of the workflow is as follows.
 
 #. Install the local version of Matplotlib with::
 
-     python -m pip install -e .
+     python -m pip install --no-build-isolation --editable .[dev]
 
    See :ref:`installing_for_devs` for detailed instructions.
 
@@ -476,9 +476,8 @@ take particular care when adding new API:
 New modules and files: installation
 -----------------------------------
 
-* If you have added new files or directories, or reorganized existing
-  ones, make sure the new files are included in the match patterns in
-  in *package_data* in :file:`setupext.py`.
+* If you have added new files or directories, or reorganized existing ones, make sure the
+  new files are included in the :file:`meson.build` in the corresponding directories.
 * New modules *may* be typed inline or using parallel stub file like existing modules.
 
 C/C++ extensions

doc/devel/dependencies.rst

@@ -100,7 +100,8 @@ Matplotlib brings its own copies of the following libraries:
 Additionally, Matplotlib depends on:
 
 - FreeType_ (>= 2.3): a font rendering library
-- QHull_ (>= 2020.2): a library for computing triangulations
+- QHull_ (>= 8.0.2): a library for computing triangulations (note that this version is
+  also known as 2020.2)
 
 .. _FreeType: https://www.freetype.org/
 .. _Qhull: http://www.qhull.org/
@@ -113,24 +114,16 @@ defaults to the system version of FreeType on AIX.
 Use system libraries
 ^^^^^^^^^^^^^^^^^^^^
 
-To force Matplotlib to use a copy of FreeType or Qhull already installed in
-your system, create a :file:`mplsetup.cfg` file with the following contents:
-
-.. code-block:: cfg
-
-   [libs]
-   system_freetype = true
-   system_qhull = true
-
-before running
+To force Matplotlib to use a copy of FreeType or Qhull already installed in your system,
+you must `pass configuration settings to Meson via meson-python
+<https://meson-python.readthedocs.io/en/stable/how-to-guides/config-settings.html>`_:
 
 .. code-block:: sh
 
-   python -m pip install .
-
-
-You can also use the :envvar:`MPLSETUPCFG` to specify the path to a cfg file when
-installing from pypi.
+   python -m pip install \
+     --config-settings=setup-args="-Dsystem-freetype=true" \
+     --config-settings=setup-args="-Dsystem-qhull=true" \
+     .
 
 
 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::
 Manual Download
 ^^^^^^^^^^^^^^^
 
-
-If the automatic download does not work (for example on air-gapped systems) it
-is preferable to instead use system libraries.  However you can manually
-download and unpack the tarballs into::
-
-  build/freetype-2.6.1  # on all platforms but windows ARM64
-  build/freetype-2.11.1 # on windows ARM64
-  build/qhull-2020.2
-
-at the top level of the checkout repository.  The expected sha256 hashes of
-the downloaded tarballs is in :file:`setupext.py` if you wish to verify
-before unpacking.
+If the automatic download does not work (for example, on air-gapped systems) it is
+preferable to instead use system libraries. However you can manually download the
+tarballs into :file:`subprojects/packagecache` at the top level of the checkout
+repository. The expected SHA256 hashes of the downloaded tarballs are in
+:file:`subprojects/*.wrap` if you wish to verify them, but they will also be checked by
+the build system before unpacking.
 
 
 Minimum pip / manylinux support (linux)
@@ -207,7 +194,7 @@ Minimum pip / manylinux support (linux)
 Matplotlib publishes `manylinux wheels <https://github.com/pypa/manylinux>`_
 which have a minimum version of pip which will recognize the wheels
 
-- Python 3.9+: ``manylinx2014`` / pip >= 19.3
+- Python 3.9+: ``manylinux2014`` / pip >= 19.3
 
 In all cases the required version of pip is embedded in the CPython source.
 
@@ -223,12 +210,18 @@ Dependencies for building Matplotlib
 Setup dependencies
 ------------------
 
-- `certifi <https://pypi.org/project/certifi/>`_ (>= 2020.06.20).  Used while
-  downloading the freetype and QHull source during build.  This is not a
-  runtime dependency.
+By default, ``pip`` will build packages using build isolation, and the following
+dependencies will be automatically installed in the isolated environment to build
+Matplotlib. However, for development, you may wish to make an editable install, which
+will require disabling build isolation, so these build dependencies should be installed
+in your target environment manually:
+
+- `meson-python <https://meson-python.readthedocs.io/>`_ (>= 0.13.1).
+- `ninja <https://ninja-build.org/>`_ (>= 1.8.2). This may be available in your package
+  manager or bundled with Meson, but may be installed via ``pip`` if otherwise not
+  available.
 - `PyBind11 <https://pypi.org/project/pybind11/>`_ (>= 2.6). Used to connect C/C++ code
   with Python.
-- `setuptools <https://pypi.org/project/setuptools/>`_ (>= 64).
 - `setuptools_scm <https://pypi.org/project/setuptools-scm/>`_ (>= 7).  Used to
   update the reported ``mpl.__version__`` based on the current git commit.
   Also a runtime dependency for editable installs.
@@ -288,8 +281,6 @@ Xcode, VS Code or Linux package manager. Choose **one** compiler from this list:
      - Linux, macOS, Windows
      - `gcc 4.8.1 <https://gcc.gnu.org/projects/cxx-status.html#cxx11>`_,
        `GCC: Binaries <https://gcc.gnu.org/install/binaries.html>`_,
-
-       For gcc <6.5 you will need to set ``$CFLAGS=-std=c++11`` to enable C++11 support.
    * - Clang (LLVM)
      - **3.3**
      - Linux, macOS
@@ -330,8 +321,8 @@ testing the following will be used if they are installed.
 - pytest-xvfb_ to run tests without windows popping up (Linux)
 - pytz_ used to test pytz int
 - sphinx_ used to test our sphinx extensions
-- WenQuanYi Zen Hei and `Noto Sans CJK <https://fonts.google.com/noto/use>`_
-  fonts for testing font fallback and non-western fonts
+- `WenQuanYi Zen Hei`_ and `Noto Sans CJK`_ fonts for testing font fallback and
+  non-Western fonts
 - xarray_ used to test compatibility with xarray
 
 If any of these dependencies are not discovered, then the tests that rely on
@@ -359,6 +350,8 @@ them will be skipped by pytest.
 .. _pytest-xvfb: https://pypi.org/project/pytest-xvfb/
 .. _pytest: http://doc.pytest.org/en/latest/
 .. _sphinx: https://pypi.org/project/Sphinx/
+.. _WenQuanYi Zen Hei: http://wenq.org/en/
+.. _Noto Sans CJK: https://fonts.google.com/noto/use
 .. _xarray: https://pypi.org/project/xarray/
 
 

doc/devel/development_setup.rst

@@ -157,34 +157,36 @@ must be installed separately. For a full list, see :ref:`dependencies`.
 Install Matplotlib in editable mode
 ===================================
 
-Install Matplotlib in editable mode from the :file:`matplotlib` directory
-using the command ::
+Install Matplotlib in editable mode from the :file:`matplotlib` directory using the
+command ::
 
-    python -m pip install -ve .
+    python -m pip install --verbose --no-build-isolation --editable .[dev]
 
-The 'editable/develop mode', builds everything and places links in your Python
-environment so that Python will be able to import Matplotlib from your
-development source directory.  This allows you to import your modified version
-of Matplotlib without re-installing after every change. Note that this is only
-true for ``*.py`` files.  If you change the C-extension source (which might
-also happen if you change branches) you will have to re-run
-``python -m pip install -ve .``
+The 'editable/develop mode' builds everything and places links in your Python environment
+so that Python will be able to import Matplotlib from your development source directory.
+This allows you to import your modified version of Matplotlib without re-installing after
+every change. Note that before the merging of the `Meson port
+<https://github.com/matplotlib/matplotlib/pull/26621>`_, this is only true for ``*.py``
+files. If you change the C-extension source based on a commit before the change to the
+Meson build system (which might also happen if you change branches), you will have to
+re-run the above command.
 
 Verify the Installation
 =======================
 
-Run the following command to make sure you have correctly installed Matplotlib in editable mode.
-The command should be run when the virtual environment is activated ::
+Run the following command to make sure you have correctly installed Matplotlib in
+editable mode. The command should be run when the virtual environment is activated::
 
     python -c "import matplotlib; print(matplotlib.__file__)"
 
 This command should return : ``<matplotlib_local_repo>\lib\matplotlib\__init__.py``
 
-We encourage you to run tests and build docs to verify that the code installed correctly and that the docs build cleanly,
-so that when you make code or document related changes you are aware of the existing issues beforehand.
+We encourage you to run tests and build docs to verify that the code installed correctly
+and that the docs build cleanly, so that when you make code or document related changes
+you are aware of the existing issues beforehand.
 
-   * Run test cases to verify installation :ref:`testing`
-   * Verify documentation build :ref:`documenting-matplotlib`
+* Run test cases to verify installation :ref:`testing`
+* Verify documentation build :ref:`documenting-matplotlib`
 
 Install pre-commit hooks
 ========================

doc/devel/min_dep_policy.rst

@@ -22,7 +22,7 @@ Matplotlib supports:
 - All minor versions of ``numpy`` released in the 24 months prior
   to the project, and at minimum the last three minor versions.
 
-In ``setup.py``, the ``python_requires`` variable should be set to
+In :file:`pyproject.toml`, the ``requires-python`` variable should be set to
 the minimum supported version of Python.  All supported minor
 versions of Python should be in the test matrix and have binary
 artifacts built for the release.

doc/users/faq.rst

@@ -355,17 +355,23 @@ provide the following information in your e-mail to the `mailing list
 
 If you compiled Matplotlib yourself, please also provide:
 
-* any changes you have made to ``setup.py`` or ``setupext.py``.
+* your compiler version -- e.g., ``gcc --version``.
 * the output of::
 
-     rm -rf build
-     python setup.py build
+     pip install --verbose
 
   The beginning of the build output contains lots of details about your
   platform that are useful for the Matplotlib developers to diagnose your
   problem.
 
-* your compiler version -- e.g., ``gcc --version``.
+If you compiled an older version of Matplotlib using the pre-Meson build system, instead
+provide:
+
+* any changes you have made to ``setup.py``/``setupext.py``,
+* the output of::
+
+     rm -rf build
+     python setup.py build
 
 Including this information in your first e-mail to the mailing list
 will save a lot of time.

lib/matplotlib/__init__.py

@@ -1307,17 +1307,17 @@ def _val_or_rc(val, rc_name):
 
 
 def _init_tests():
-    # The version of FreeType to install locally for running the
-    # tests.  This must match the value in `setupext.py`
+    # The version of FreeType to install locally for running the tests. This must match
+    # the value in `meson.build`.
     LOCAL_FREETYPE_VERSION = '2.6.1'
 
     from matplotlib import ft2font
     if (ft2font.__freetype_version__ != LOCAL_FREETYPE_VERSION or
             ft2font.__freetype_build_type__ != 'local'):
         _log.warning(
             f"Matplotlib is not built with the correct FreeType version to "
-            f"run tests.  Rebuild without setting system_freetype=1 in "
-            f"mplsetup.cfg.  Expect many image comparison failures below.  "
+            f"run tests.  Rebuild without setting system-freetype=true in "
+            f"Meson setup options.  Expect many image comparison failures below.  "
             f"Expected freetype version {LOCAL_FREETYPE_VERSION}.  "
             f"Found freetype version {ft2font.__freetype_version__}.  "
             "Freetype build type is {}local".format(

meson_options.txt

@@ -1,18 +1,20 @@
+# Options may be set by passing through `pip` or `build` via meson-python:
+# https://meson-python.readthedocs.io/en/stable/how-to-guides/config-settings.html
+
 # By default, Matplotlib downloads and builds its own copies of FreeType and of
-# Qhull.  You may set the following to True to instead link against a system
-# FreeType/Qhull.  As an exception, Matplotlib defaults to the system version
-# of FreeType on AIX.
+# Qhull. You may use the following options to instead link against a system
+# FreeType/Qhull. As an exception, Matplotlib defaults to the system version of
+# FreeType on AIX.
 option('system-freetype', type: 'boolean', value: false,
        description: 'Build against system version of FreeType')
 option('system-qhull', type: 'boolean', value: false,
        description: 'Build against system version of Qhull')
 
 # Some of Matplotlib's components are optional: the MacOSX backend (installed
-# by default on MacOSX; requires the Cocoa headers included with XCode), and
-# the test data (i.e., the baseline image files; not installed by default). You
-# can control whether they are installed by uncommenting the following lines.
-# Note that the MacOSX backend is never built on Linux or Windows, regardless
-# of the config value.
+# by default on MacOSX; requires the Cocoa headers included with XCode). You
+# can control whether they are installed using the following options. Note that
+# the MacOSX backend is never built on Linux or Windows, regardless of the
+# config value.
 option('macosx', type: 'boolean', value: true,
        description: 'Enable MacOSX backend (requires Cocoa)')
 

requirements/doc/doc-requirements.txt

@@ -2,7 +2,7 @@
 #
 # You will first need a matching Matplotlib installation
 # e.g (from the Matplotlib root directory)
-#     pip install -e .
+#     pip install --no-build-isolation --editable .[dev]
 #
 # Install the documentation requirements with:
 #     pip install -r requirements/doc/doc-requirements.txt