Merge pull request matplotlib#5306 from mdboom/local-freetype

Use a specific version of Freetype for testing

Author: jenshnielsen

.gitignore

@@ -39,6 +39,7 @@ dist
 .eggs
 # tox testing tool
 .tox
+setup.cfg
 
 # OS generated files #
 ######################

.travis.yml

@@ -82,7 +82,7 @@ install:
   # version since is it basically just a .ttf file
   # The current Travis Ubuntu image is to old to search .local/share/fonts so we store fonts in .fonts
 
-  # We install ipython to use the console highlighting. From IPython 3 this depends on jsonschema and misture.
+  # We install ipython to use the console highlighting. From IPython 3 this depends on jsonschema and mistune.
   # Neihter is installed as a dependency of IPython since they are not used by the IPython console.
   - |
     if [[ $BUILD_DOCS == true ]]; then
@@ -96,7 +96,11 @@ install:
       cp tmp/usr/share/fonts/truetype/humor-sans/Humor-Sans.ttf ~/.fonts
       cp Felipa-Regular.ttf ~/.fonts
       fc-cache -f -v
+    else
+      # Use the special local version of freetype for testing
+      cp .travis/setup.cfg .
     fi;
+
   - python setup.py install
 
 script:

.travis/setup.cfg

@@ -0,0 +1,2 @@
+[test]
+local_freetype=True

INSTALL

@@ -208,7 +208,7 @@ libpng 1.2 (or later)
 `pytz`
     Used to manipulate time-zone aware datetimes.
 
-:term:`freetype` 2.3 or later
+:term:`FreeType` 2.3 or later
     library for reading true type font files.
 
 ``cycler`` 0.9 or later

doc/devel/testing.rst

@@ -33,6 +33,22 @@ Optionally you can install:
 
   - `pep8 <http://pep8.readthedocs.org/en/latest>`_ to test coding standards
 
+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.
+
+Add the following content to a ``setup.cfg`` file at the root of the
+matplotlib source directory::
+
+  [test]
+  local_freetype = True
+
 Running the tests
 -----------------
 
@@ -185,17 +201,6 @@ decorator:
      If some variation is expected in the image between runs, this
      value may be adjusted.
 
-Freetype version
-----------------
-
-Due to subtle differences in the font rendering under different
-version of freetype some care must be taken when generating the
-baseline images.  Currently (early 2015), almost all of the images
-were generated using ``freetype 2.5.3-21`` on Fedora 21 and only the
-fonts that ship with ``matplotlib`` (regenerated in PR #4031 / commit
-005cfde02751d274f2ab8016eddd61c3b3828446) and travis is using
-``freetype 2.4.8`` on ubuntu.
-
 Known failing tests
 -------------------
 

doc/glossary/index.rst

@@ -22,8 +22,8 @@ Glossary
   EPS
       Encapsulated Postscript (`EPS <http://en.wikipedia.org/wiki/Encapsulated_PostScript>`_)
 
-  freetype
-      `freetype <http://www.freetype.org/>`_ is a font rasterization
+  FreeType
+      `FreeType <http://www.freetype.org/>`_ is a font rasterization
       library used by matplotlib which supports TrueType, Type 1, and
       OpenType fonts.
 

doc/users/screenshots.rst

@@ -252,7 +252,7 @@ Mathtext_examples
 
 Below is a sampling of the many TeX expressions now supported by matplotlib's
 internal mathtext engine.  The mathtext module provides TeX style mathematical
-expressions using `freetype2 <http://www.freetype.org/>`_
+expressions using `FreeType <http://www.freetype.org/>`_
 and the BaKoMa computer modern or `STIX <http://www.stixfonts.org>`_ fonts.
 See the :mod:`matplotlib.mathtext` module for additional details.
 

doc/users/text_intro.rst

@@ -8,7 +8,7 @@ expressions, truetype support for raster and vector outputs, newline
 separated text with arbitrary rotations, and unicode support.  Because
 we embed the fonts directly in the output documents, e.g., for postscript
 or PDF, what you see on the screen is what you get in the hardcopy.
-`freetype2 <http://www.freetype.org/>`_ support
+`FreeType <http://www.freetype.org/>`_ support
 produces very nice, antialiased fonts, that look good even at small
 raster sizes.  matplotlib includes its own
 :mod:`matplotlib.font_manager`, thanks to Paul Barrett, which

examples/pylab_examples/font_table_ttf.py

@@ -1,6 +1,6 @@
 # -*- noplot -*-
 """
-matplotlib has support for freetype fonts.  Here's a little example
+matplotlib has support for FreeType fonts.  Here's a little example
 using the 'table' command to build a font table that shows the glyphs
 by character code.
 

lib/matplotlib/__init__.py

@@ -1488,6 +1488,18 @@ def verify_test_dependencies():
     if not os.path.isdir(os.path.join(os.path.dirname(__file__), 'tests')):
         raise ImportError("matplotlib test data is not installed")
 
+    # The version of FreeType to install locally for running the
+    # tests.  This must match the value in `setupext.py`
+    LOCAL_FREETYPE_VERSION = '2.6.1'
+
+    from matplotlib import ft2font
+    if (ft2font.__freetype_version__ != LOCAL_FREETYPE_VERSION or
+        ft2font.__freetype_build_type__ != 'local'):
+        warnings.warn(
+            "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.")
+
     try:
         import nose
         try: