Merge pull request matplotlib#15476 from anntzer/default-to-local-freetype

BLD: Default to local_freetype builds.

Author: tacaswell

.appveyor.yml

@@ -72,8 +72,6 @@ install:
     curl -sL https://github.com/python/cpython/pull/1224.patch |
     patch -fsup 1 -d %CONDA_PREFIX% ) || cmd /c "exit /b 0"
 
-  # enables the local freetype build
-  - set MPLLOCALFREETYPE=1
   # Show the installed packages + versions
   - conda list
 

.travis.yml

@@ -156,7 +156,7 @@ install:
       export CPPFLAGS=--coverage
     fi
   - |
-    MPLLOCALFREETYPE=1 python -mpip install -ve .  # Install Matplotlib.
+    python -mpip install -ve .  # Install Matplotlib.
   - |
     if [[ $TRAVIS_OS_NAME != 'osx' ]] && [[ $RUN_PYTEST == 1 ]]; then
       unset CPPFLAGS

INSTALL.rst

@@ -90,19 +90,8 @@ the latest *tar.gz* release file from `the PyPI files page
 develop Matplotlib or just need the latest bugfixed version, grab the
 latest git version, and see :ref:`install-from-git`.
 
-The standard environment variables :envvar:`CC`, :envvar:`CXX`,
-:envvar:`PKG_CONFIG` are respected.  This means you can set them if your
-toolchain is prefixed. This may be used for cross compiling. ::
+Matplotlib can be installed from the source directory with a simple ::
 
-  export CC=x86_64-pc-linux-gnu-gcc
-  export CXX=x86_64-pc-linux-gnu-g++
-  export PKG_CONFIG=x86_64-pc-linux-gnu-pkg-config
-
-Once you have satisfied the requirements detailed below (i.e., Python and
-FreeType), you can build Matplotlib.
-::
-
-  cd matplotlib
   python -m pip install .
 
 We provide a setup.cfg_ file which you can use to customize the build
@@ -168,29 +157,21 @@ etc., you can install the following:
 FreeType
 --------
 
-Matplotlib depends on FreeType, a font rendering library.  It can either
-download and build its own copy of the library, or use a copy of FreeType
-already installed in your system.
-
-The easiest option is to make Matplotlib download and build FreeType.  This is
-done by setting the :envvar:`MPLLOCALFREETYPE` environment variable to 1 -- on
-Linux and OSX:
-
-.. code-block:: sh
-
-   export MPLLOCALFREETYPE=1
+Matplotlib depends on FreeType, a font rendering library.  By default,
+Matplotlib downloads and builds its own copy of FreeType.
 
-and on Windows:
+To force Matplotlib to use a copy of FreeType already installed in your system,
+create a :file:`setup.cfg` file with the following contents:
 
-.. code-block:: bat
+.. code-block:: cfg
 
-   set MPLLOCALFREETYPE=1
+   [libs]
+   system_freetype = true
 
-and you can continue the installation (``python -m pip install .``), ignoring
-everything that follows.
+before running ``python -m pip install .``.
 
-If you wish, instead, to use the system FreeType, you need to install the
-FreeType library and headers.  This can be achieved using a package manager:
+In this case, you need to install the FreeType library and headers.  This can
+be achieved using a package manager:
 
 .. code-block:: sh
 
@@ -210,6 +191,8 @@ tool for locating FreeType:
    sudo dnf install pkgconf  # Fedora
    brew install pkg-config  # macOS with Homebrew
    conda install pkg-config  # conda
+   # Or point the PKG_CONFIG environment variable to the path to pkg-config:
+   export PKG_CONFIG=...
 
 .. _pkg-config: https://www.freedesktop.org/wiki/Software/pkg-config/
 

ci/azure-pipelines-steps.yml

@@ -54,7 +54,7 @@ steps:
   displayName: 'Install dependencies with pip'
 
 - bash: |
-    MPLLOCALFREETYPE=1 python -m pip install -ve . ||
+    python -m pip install -ve . ||
       [[ "$PYTHON_VERSION" = 'Pre' ]]
   displayName: "Install self"
 

doc/devel/contributing.rst

@@ -92,30 +92,11 @@ and might be easier to use if you are using 2-factor authentication.
 Building Matplotlib for image comparison tests
 ----------------------------------------------
 
-Matplotlib's test suite makes heavy use of image comparison tests,
-meaning the result of a plot is compared against a known good result.
-Unfortunately, different versions of FreeType produce differently
-formed characters, causing these image comparisons to fail.  To make
-them reproducible, Matplotlib can be built with a special local copy
-of FreeType.  This is recommended for all Matplotlib developers.
-
-Prior to compiling the C-extensions, copy :file:`setup.cfg.template` to
-:file:`setup.cfg` and edit it to contain::
-
-  [test]
-  local_freetype = True
-  tests = True
-
-or set the ``MPLLOCALFREETYPE`` environmental variable to any true
-value.  If you have previously built Matplotlib with a different
-version of Freetype, you will also need to remove the c/c++ build
-products.  Do this is to delete the ``build`` folder or ``git clean
--xfd``.  If you are going to be regularly working on Matplotlib,
-consider putting ::
-
-   export MPLLOCALFREETYPE=1
-
-in your shell start up files.
+Matplotlib's test suite makes heavy use of image comparison tests, meaning
+the result of a plot is compared against a known good result.  Unfortunately,
+different versions of FreeType produce differently formed characters, causing
+these image comparisons to fail.  To make them reproducible, Matplotlib is, by
+default, built with a special local copy of FreeType.
 
 
 Installing Matplotlib in developer mode

doc/devel/testing.rst

@@ -21,8 +21,7 @@ Requirements
 ------------
 
 Install the latest version of Matplotlib as documented in
-:ref:`installing_for_devs` In particular, follow the instructions to use a
-local FreeType build.
+:ref:`installing_for_devs`.
 
 The following software is required to run the tests:
 

doc/faq/environment_variables_faq.rst

@@ -34,11 +34,6 @@ Environment Variables
   is used to find a base directory in which the :file:`matplotlib` subdirectory
   is created.
 
-.. envvar:: MPLLOCALFREETYPE
-
-  If set, this environment variable directs Matplotlib's build script to
-  download and build its own copy of the FreeType library.
-
 .. envvar:: PATH
 
   The list of directories searched to find executable programs.

doc/faq/installing_faq.rst

@@ -182,8 +182,6 @@ or::
 and build and install with::
 
    cd matplotlib
-   export MPLLOCALFREETYPE=1  # on Linux and OSX.
-   set MPLLOCALFREETYPE=1  # on Windows.
    python -mpip install .
 
 If you want to be able to follow the development branch as it changes

lib/matplotlib/__init__.py

@@ -1316,14 +1316,12 @@ def _init_tests():
     if (ft2font.__freetype_version__ != LOCAL_FREETYPE_VERSION or
         ft2font.__freetype_build_type__ != 'local'):
         _log.warning(
-            "Matplotlib is not built with the correct FreeType version to run "
-            "tests.  Set local_freetype=True in setup.cfg and rebuild. "
-            "Expect many image comparison failures below. "
-            "Expected freetype version {0}. "
-            "Found freetype version {1}. "
-            "Freetype build type is {2}local".format(
-                LOCAL_FREETYPE_VERSION,
-                ft2font.__freetype_version__,
+            f"Matplotlib is not built with the correct FreeType version to "
+            f"run tests.  Rebuild without setting system_freetype=1 in "
+            f"setup.cfg.  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(
                 "" if ft2font.__freetype_build_type__ == 'local' else "not "))
 
     try:

setup.cfg.template

@@ -3,12 +3,11 @@
 
 [egg_info]
 
-[test]
-# If you plan to develop Matplotlib and run or add to the test suite,
-# set this to True.  It will download and build a specific version of
-# FreeType, and then use that to build the ft2font extension.  This
-# ensures that test images are exactly reproducible.
-#local_freetype = False
+[libs]
+# By default, Matplotlib downloads and builds its own copy of FreeType.  You
+# may set the following variable to True to instead link against a system
+# FreeType.
+#system_freetype = False
 
 [packages]
 # There are a number of data subpackages from Matplotlib that are