matplotlib · tacaswell · Oct 29, 2019 · Oct 22, 2019
diff --git a/.appveyor.yml b/.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
 

diff --git a/.travis.yml b/.travis.yml
@@ -155,7 +155,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

diff --git a/INSTALL.rst b/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/
 

diff --git a/ci/azure-pipelines-steps.yml b/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"
 

diff --git a/doc/devel/contributing.rst b/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

diff --git a/doc/devel/testing.rst b/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:
 

diff --git a/doc/faq/environment_variables_faq.rst b/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.

diff --git a/doc/faq/installing_faq.rst b/doc/faq/installing_faq.rst
@@ -185,8 +185,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

diff --git a/lib/matplotlib/__init__.py b/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:

diff --git a/setup.cfg.template b/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 subpackages of Matplotlib that are considered

diff --git a/setupext.py b/setupext.py
@@ -158,16 +158,12 @@ def write_cache(local_fn, data):
 if os.path.exists(setup_cfg):
     config = configparser.ConfigParser()
     config.read(setup_cfg)
-    if config.has_option('rc_options', 'backend'):
-        options['backend'] = config.get("rc_options", "backend")
-    if config.has_option('test', 'local_freetype'):
-        options['local_freetype'] = config.getboolean("test", "local_freetype")
+    options['backend'] = config.get('rc_options', 'backend', fallback=None)
+    options['system_freetype'] = config.getboolean('libs', 'system_freetype',
+                                                   fallback=False)
 else:
     config = None
 
-lft = bool(os.environ.get('MPLLOCALFREETYPE', False))
-options['local_freetype'] = lft or options.get('local_freetype', False)
-
 
 if '-q' in sys.argv or '--quiet' in sys.argv:
     def print_raw(*args, **kwargs): pass  # Suppress our own output.
@@ -476,7 +472,17 @@ class FreeType(SetupPackage):
 
     def add_flags(self, ext):
         ext.sources.insert(0, 'src/checkdep_freetype2.c')
-        if options.get('local_freetype'):
+        if options.get('system_freetype'):
+            pkg_config_setup_extension(
+                # FreeType 2.3 has libtool version 9.11.3 as can be checked
+                # from the tarball.  For FreeType>=2.4, there is a conversion
+                # table in docs/VERSIONS.txt in the FreeType source tree.
+                ext, 'freetype2',
+                atleast_version='9.11.3',
+                alt_exec=['freetype-config'],
+                default_libraries=['freetype'])
+            ext.define_macros.append(('FREETYPE_BUILD_TYPE', 'system'))
+        else:
             src_path = pathlib.Path(
                 'build', f'freetype-{LOCAL_FREETYPE_VERSION}')
             # Statically link to the locally-built freetype.
@@ -489,20 +495,10 @@ def add_flags(self, ext):
             ext.extra_objects.insert(
                 0, str(src_path / 'objs' / '.libs' / libfreetype))
             ext.define_macros.append(('FREETYPE_BUILD_TYPE', 'local'))
-        else:
-            pkg_config_setup_extension(
-                # FreeType 2.3 has libtool version 9.11.3 as can be checked
-                # from the tarball.  For FreeType>=2.4, there is a conversion
-                # table in docs/VERSIONS.txt in the FreeType source tree.
-                ext, 'freetype2',
-                atleast_version='9.11.3',
-                alt_exec=['freetype-config'],
-                default_libraries=['freetype'])
-            ext.define_macros.append(('FREETYPE_BUILD_TYPE', 'system'))
 
     def do_custom_build(self):
         # We're using a system freetype
-        if not options.get('local_freetype'):
+        if options.get('system_freetype'):
             return
 
         src_path = pathlib.Path('build', f'freetype-{LOCAL_FREETYPE_VERSION}')

diff --git a/src/checkdep_freetype2.c b/src/checkdep_freetype2.c
@@ -1,8 +1,7 @@
 #ifdef __has_include
   #if !__has_include(<ft2build.h>)
     #error "FreeType version 2.3 or higher is required. \
-You may set the MPLLOCALFREETYPE environment variable to 1 to let Matplotlib \
-download it."
+You may unset the system_freetype entry in setup.cfg to let Matplotlib download it."
   #endif
 #endif
 
@@ -16,6 +15,5 @@ download it."
   XSTR(FREETYPE_MAJOR) "." XSTR(FREETYPE_MINOR) "." XSTR(FREETYPE_PATCH) ".")
 #if FREETYPE_MAJOR << 16 + FREETYPE_MINOR << 8 + FREETYPE_PATCH < 0x020300
   #error "FreeType version 2.3 or higher is required. \
-You may set the MPLLOCALFREETYPE environment variable to 1 to let Matplotlib \
-download it."
+You may unset the system_freetype entry in setup.cfg to let Matplotlib download it."
 #endif
diff --git a/tox.ini b/tox.ini
@@ -12,7 +12,6 @@ setenv =
     MPLCONFIGDIR={envtmpdir}/.matplotlib
     PIP_USER = 0
     PIP_ISOLATED = 1
-    MPLLOCALFREETYPE = 1
 usedevelop = True
 commands =
     pytest --pyargs matplotlib