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

Use a specific version of Freetype for testing

.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:

lib/matplotlib/mathtext.py

@@ -113,7 +113,7 @@ class MathtextBackend(object):
       - :meth:`render_rect_filled`
       - :meth:`get_results`
 
-    And optionally, if you need to use a Freetype hinting style:
+    And optionally, if you need to use a FreeType hinting style:
 
       - :meth:`get_hinting_type`
     """
@@ -150,7 +150,7 @@ def get_results(self, box):
 
     def get_hinting_type(self):
         """
-        Get the Freetype hinting type to use with this particular
+        Get the FreeType hinting type to use with this particular
         backend.
         """
         return LOAD_NO_HINTING

matplotlibrc.template

@@ -195,10 +195,10 @@ backend      : %(backend)s
 
 #text.hinting : auto   # May be one of the following:
                        #   'none': Perform no hinting
-                       #   'auto': Use freetype's autohinter
+                       #   'auto': Use FreeType's autohinter
                        #   'native': Use the hinting information in the
                        #             font file, if available, and if your
-                       #             freetype library supports it
+                       #             FreeType library supports it
                        #   'either': Use the native hinting information,
                        #             or the autohinter if none is available.
                        # For backward compatibility, this value may also be
@@ -357,9 +357,9 @@ backend      : %(backend)s
 #image.lut    : 256               # the size of the colormap lookup table
 #image.origin : upper             # lower | upper
 #image.resample  : False
-#image.composite_image : True     # When True, all the images on a set of axes are 
-                                  # combined into a single composite image before 
-                                  # saving a figure as a vector graphics file, 
+#image.composite_image : True     # When True, all the images on a set of axes are
+                                  # combined into a single composite image before
+                                  # saving a figure as a vector graphics file,
                                   # such as a PDF.
 
 ### CONTOUR PLOTS

setup.cfg.template

@@ -8,6 +8,13 @@
 # This can be a single directory or a comma-delimited list of directories.
 #basedirlist = /usr
 
+[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
+
 [status]
 # To suppress display of the dependencies and their versions
 # at the top of the build log, uncomment the following line:

setup.py

@@ -9,6 +9,7 @@
 from distribute_setup import use_setuptools
 use_setuptools()
 from setuptools.command.test import test as TestCommand
+from setuptools.command.build_ext import build_ext as BuildExtCommand
 
 import sys
 
@@ -239,8 +240,19 @@ def run_tests(self):
                   argv=['nosetests'] + self.test_args,
                   exit=True)
 
+
+class BuildExtraLibraries(BuildExtCommand):
+    def run(self):
+        for package in good_packages:
+            package.do_custom_build()
+
+        return BuildExtCommand.run(self)
+
+
 cmdclass = versioneer.get_cmdclass()
 cmdclass['test'] = NoseTestCommand
+cmdclass['build_ext'] = BuildExtraLibraries
+
 
 # One doesn't normally see `if __name__ == '__main__'` blocks in a setup.py,
 # however, this is needed on Windows to avoid creating infinite subprocesses
@@ -303,8 +315,6 @@ def run_tests(self):
     # Now collect all of the information we need to build all of the
     # packages.
     for package in good_packages:
-        if isinstance(package, str):
-            continue
         packages.extend(package.get_packages())
         namespace_packages.extend(package.get_namespace_packages())
         py_modules.extend(package.get_py_modules())