diff --git a/doc/devel/dependencies.rst b/doc/devel/dependencies.rst index 0ffdaf65696a..458fff51b82f 100644 --- a/doc/devel/dependencies.rst +++ b/doc/devel/dependencies.rst @@ -1,15 +1,17 @@ .. _dependencies: -============ +************ Dependencies -============ +************ + +.. _runtime_dependencies: Runtime dependencies ==================== -Mandatory dependencies ----------------------- +Required +-------- When installing through a package manager like ``pip`` or ``conda``, the mandatory dependencies are automatically installed. This list is mainly for @@ -31,8 +33,8 @@ reference. .. _optional_dependencies: -Optional dependencies ---------------------- +Optional +-------- The following packages and tools are not required but extend the capabilities of Matplotlib. @@ -106,10 +108,14 @@ Additionally, Matplotlib depends on: .. _FreeType: https://www.freetype.org/ .. _Qhull: http://www.qhull.org/ -By default, Matplotlib downloads and builds its own copies of FreeType (this is -necessary to run the test suite, because different versions of FreeType -rasterize characters differently) and of Qhull. As an exception, Matplotlib -defaults to the system version of FreeType on AIX. + +Download during install +^^^^^^^^^^^^^^^^^^^^^^^ + +By default, Matplotlib downloads and builds its own copies of Qhull and FreeType. +The vendored version of FreeType is necessary to run the test suite, because +different versions of FreeType rasterize characters differently. + Use system libraries ^^^^^^^^^^^^^^^^^^^^ @@ -176,9 +182,8 @@ remember to clear your artifacts before re-building:: git clean -xfd - -Manual Download -^^^^^^^^^^^^^^^ +From source files +^^^^^^^^^^^^^^^^^ 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 @@ -202,19 +207,23 @@ In all cases the required version of pip is embedded in the CPython source. .. _development-dependencies: -Dependencies for building Matplotlib -==================================== +Build dependencies +================== + .. _setup-dependencies: -Setup dependencies ------------------- +Python +------ + +By default, ``pip`` will build packages using build isolation, meaning that these +build dependencies are temporally installed by pip for the duration of the +Matplotlib build process. However, build isolation is disabled when :ref:`installing Matplotlib for development `; +therefore we recommend using one of our :ref:`virtual environment configurations ` to +create a development environment in which these packages are automatically installed. -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: +If you are developing Matplotlib and unable to use our environment configurations, +then you must manually install the following packages into your development environment: - `meson-python `_ (>= 0.13.1). - `ninja `_ (>= 1.8.2). This may be available in your package @@ -230,11 +239,13 @@ in your target environment manually: .. _compile-dependencies: -C++ compiler ------------- +Compiled extensions +------------------- Matplotlib requires a C++ compiler that supports C++17, and each platform has a development environment that must be installed before a compiler can be installed. +You may also need to install headers for various libraries used in the compiled extension +source files. .. tab-set:: @@ -261,6 +272,8 @@ development environment that must be installed before a compiler can be installe Alternatively, you can install a Linux-like environment such as `CygWin `_ or `Windows Subsystem for Linux `_. + If using `MinGW-64 `_, we require **v6** of the + ```Mingw-w64-x86_64-headers``. We highly recommend that you install a compiler using your platform tool, i.e., @@ -294,16 +307,19 @@ Xcode, VS Code or Linux package manager. Choose **one** compiler from this list: .. _test-dependencies: -Dependencies for testing Matplotlib -=================================== +Test dependencies +================= + This section lists the additional software required for :ref:`running the tests `. -Required: +Required +-------- - pytest_ (>= 7.0.0) -Optional: +Optional +-------- In addition to all of the optional dependencies on the main library, for testing the following will be used if they are installed. @@ -357,11 +373,12 @@ them will be skipped by pytest. .. _doc-dependencies: -Dependencies for building Matplotlib's documentation -==================================================== +Documentation dependencies +========================== + +Python +------ -Python packages ---------------- The additional Python packages required to build the :ref:`documentation ` are listed in :file:`doc-requirements.txt` and can be installed using :: @@ -373,13 +390,22 @@ The content of :file:`doc-requirements.txt` is also shown below: .. include:: ../../requirements/doc/doc-requirements.txt :literal: -Additional external dependencies --------------------------------- -Required: +External tools +-------------- + +The documentation requires LaTeX and Graphviz. These are not +Python packages and must be installed separately. The documentation can be +built without Inkscape and optipng, but the build process will raise various +warnings. If the build process warns that you are missing fonts, make sure +your LaTeX distribution bundles cm-super or install it separately. + +Required +^^^^^^^^ + +* `Graphviz `_ * a minimal working LaTeX distribution, e.g., `TeX Live `_ or `MikTeX `_ -* `Graphviz `_ * the following LaTeX packages (if your OS bundles TeX Live, the "complete" version of the installer, e.g. "texlive-full" or "texlive-all", will often automatically include these packages): @@ -388,18 +414,11 @@ Required: * `dvipng `_ * `underscore `_ -Optional, but recommended: +Optional +^^^^^^^^ * `Inkscape `_ * `optipng `_ * the font "Humor Sans" (aka the "XKCD" font), or the free alternative `Comic Neue `_ * the font "Times New Roman" - -.. note:: - - The documentation will not build without LaTeX and Graphviz. These are not - Python packages and must be installed separately. The documentation can be - built without Inkscape and optipng, but the build process will raise various - warnings. If the build process warns that you are missing fonts, make sure - your LaTeX distribution bundles cm-super or install it separately. diff --git a/doc/devel/development_setup.rst b/doc/devel/development_setup.rst index 0e7db431163f..a41a74351660 100644 --- a/doc/devel/development_setup.rst +++ b/doc/devel/development_setup.rst @@ -154,6 +154,8 @@ Most Python dependencies will be installed when :ref:`setting up the environment but non-Python dependencies like C++ compilers, LaTeX, and other system applications must be installed separately. For a full list, see :ref:`dependencies`. +.. _development-install: + Install Matplotlib in editable mode =================================== diff --git a/doc/users/installing/index.rst b/doc/users/installing/index.rst index c8c9ba549775..0d25ffbf76fa 100644 --- a/doc/users/installing/index.rst +++ b/doc/users/installing/index.rst @@ -31,7 +31,7 @@ precompiled wheel for your OS and Python. For support of other GUI frameworks, LaTeX rendering, saving animations and a larger selection of file formats, you can - install :ref:`optional_dependencies`. + install :ref:`optional dependencies `. Third-party distributions