Default to local_freetype builds.

anntzer · anntzer · commit c81cc3d025c5 · 2019-10-22T18:41:33.000+02:00
This would make builds from source work straightforwardly (including
for testing purposes) and simplify the build instructions for new
contributors -- see changes in build instructions.

Note that there is intentionally no corresponding environment variable
because it is unclear whether e.g. a set but *empty* MPLSYSTEMFREETYPE
environment variable should override a system_freetype = True
in setup.cfg, and because this would make the error message in
checkdep_freetype.c more complex (do we tell the use to unset the
environment variable? or should setting it to "0" or "false" be the same
as unsetting it?).  The design here keeps things simple by having a
single "on" switch.

The config entry is under [libs] to allow for a future system_qhull
entry.
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
@@ -160,13 +160,11 @@ def write_cache(local_fn, data):
     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")
 else:
     config = None
 
-lft = bool(os.environ.get('MPLLOCALFREETYPE', False))
-options['local_freetype'] = lft or options.get('local_freetype', False)
+options['system_freetype'] = config.getboolean(
+    'libs', 'system_freetype', fallback=False)
 
 
 if '-q' in sys.argv or '--quiet' in sys.argv:
@@ -476,7 +474,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 +497,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
