From c092ecda6dbcb2fd7be91bad0fcf33183199c257 Mon Sep 17 00:00:00 2001 From: Antony Lee Date: Tue, 22 Oct 2019 12:02:16 +0200 Subject: [PATCH] Default to local_freetype builds. 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. --- .appveyor.yml | 2 -- .travis.yml | 2 +- INSTALL.rst | 43 ++++++++------------------- ci/azure-pipelines-steps.yml | 2 +- doc/devel/contributing.rst | 29 ++++-------------- doc/devel/testing.rst | 3 +- doc/faq/environment_variables_faq.rst | 5 ---- doc/faq/installing_faq.rst | 2 -- lib/matplotlib/__init__.py | 14 ++++----- setup.cfg.template | 11 ++++--- setupext.py | 34 ++++++++++----------- src/checkdep_freetype2.c | 6 ++-- tox.ini | 1 - 13 files changed, 49 insertions(+), 105 deletions(-) diff --git a/.appveyor.yml b/.appveyor.yml index b466404a50c2..971b24fd8334 100644 --- 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 index e86ec6991888..ca92e485f86b 100644 --- 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 index a725d24f4751..ae910dfcc010 100644 --- 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 index 75114b535eab..e27e0952b209 100644 --- 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 index 0cba0ecd2716..6b4eaf3a027d 100644 --- 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 index 68b91eb5b503..71a65150e6e9 100644 --- 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 index 04e7bccaef96..9f044a8d5a0e 100644 --- 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 index 7777a98eb957..bff08192c24a 100644 --- 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 index c0d3d1a00344..fb00267fa53f 100644 --- 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 index 45f448af4d93..11674c84bfb9 100644 --- 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 index e3680e929d5a..26624a6578e1 100644 --- 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 index eca50d22e8d1..d0e8fd34fbe9 100644 --- a/src/checkdep_freetype2.c +++ b/src/checkdep_freetype2.c @@ -1,8 +1,7 @@ #ifdef __has_include #if !__has_include() #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 index f48969ecc28b..c6fa928105cd 100644 --- 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