Pillow/docs/INSTALL.txt

--------------------------------------------------------------------
Build instructions (all platforms)
--------------------------------------------------------------------

For a list of changes in this release, see the CHANGES document.

0. If you're in a hurry, try this::

        $ tar xvfz Imaging-1.1.7.tar.gz
        $ cd Imaging-1.1.7
        $ python setup.py install

   If you prefer to know what you're doing, read on.


1. Prerequisites.

   If you need any of the features described below, make sure you
   have the necessary libraries before building PIL.

   +----------------------+---------------------------------------------+
   |  feature             |library                                      |
   +----------------------+---------------------------------------------+
   |  JPEG support        |libjpeg (6a or 6b)                           |
   |                      |                                             |           
   |                      |http://www.ijg.org                           |
   |                      |http://www.ijg.org/files/jpegsrc.v6b.tar.gz  |
   |                      |ftp://ftp.uu.net/graphics/jpeg/              |
   +----------------------+---------------------------------------------+
   |                      |                                             |           
   |  PNG support         |zlib (1.2.3 or later is recommended)         |
   |                      |                                             |           
   |                      |http://www.gzip.org/zlib/                    |
   +----------------------+---------------------------------------------+
   |                      |                                             |           
   |  OpenType/TrueType   |freetype2 (2.3.9 or later is recommended)    |
   |  support             |                                             |
   |                      |http://www.freetype.org                      |
   |                      |http://freetype.sourceforge.net              |
   +----------------------+---------------------------------------------+
   |                      |                                             |           
   |  CMS support         |littleCMS (1.1.5 or later is recommended)    |
   |                      |http://www.littlecms.com/                    |
   +----------------------+---------------------------------------------+

   If you have a recent Linux version, the libraries provided with the
   operating system usually work just fine.  If some library is
   missing, installing a prebuilt version (jpeg-devel, zlib-devel,
   etc) is usually easier than building from source.  For example, for
   Ubuntu 9.10 (karmic), you can install the following libraries::

       sudo apt-get install libjpeg62-dev
       sudo apt-get install zlib1g-dev
       sudo apt-get install libfreetype6-dev
       sudo apt-get install liblcms1-dev

   If you're using Mac OS X, you can use the 'fink' tool to install
   missing libraries (also see the Mac OS X section below).

   Similar tools are available for many other platforms.


2. To build under Python 1.5.2, you need to install the stand-alone
   version of the distutils library:

       http://www.python.org/sigs/distutils-sig/download.html

   You can fetch distutils 1.0.2 from the Python source repository:
   
       svn export http://svn.python.org/projects/python/tags/Distutils-1_0_2/Lib/distutils/

   For newer releases, the distutils library is included in the
   Python standard library.

   NOTE: Version 1.1.7 is not fully compatible with 1.5.2.  Some
   more recent additions to the library may not work, but the core
   functionality is available.
   

3. If you didn't build Python from sources, make sure you have
   Python's build support files on your machine.  If you've down-
   loaded a prebuilt package (e.g. a Linux RPM), you probably
   need additional developer packages.  Look for packages named
   "python-dev", "python-devel", or similar.  For example, for
   Ubuntu 9.10 (karmic), use the following command:

       sudo apt-get install python-dev


4. When you have everything you need, unpack the PIL distribution
   (the file Imaging-1.1.7.tar.gz) in a suitable work directory::

        $ cd MyExtensions # example
        $ gunzip Imaging-1.1.7.tar.gz
        $ tar xvf Imaging-1.1.7.tar


5. Build the library.  We recommend that you do an in-place build,
   and run the self test before installing::

        $ cd Imaging-1.1.7
        $ python setup.py build_ext -i
        $ python selftest.py

   During the build process, the setup.py will display a summary
   report that lists what external components it found.  The self-
   test will display a similar report, with what external components
   the tests found in the actual build files::

        --------------------------------------------------------------------
        Pillow 1.5 ( PIL fork based on PIL 1.1.7 ) SETUP SUMMARY
        --------------------------------------------------------------------
        platform  darwin 2.6.6 (r266:84292, Nov 26 2010, 16:24:16)
          [GCC 4.2.1 (Apple Inc. build 5664)]
        --------------------------------------------------------------------
        --- TKINTER support available
        --- JPEG support available
        --- ZLIB (PNG/ZIP) support available
        *** FREETYPE2 support not available
        *** LITTLECMS support not available
        --------------------------------------------------------------------

   Make sure that the optional components you need are included.

   If the build script won't find a given component, you can edit the
   setup.py file and set the appropriate ROOT variable.  For details,
   see instructions in the file.

   If the build script finds the component, but the tests cannot
   identify it, try rebuilding *all* modules::

        $ python setup.py clean
        $ python setup.py build_ext -i


6. If the setup.py and selftest.py commands finish without any
   errors, you're ready to install the library::

        $ python setup.py install

   (depending on how Python has been installed on your machine,
   you might have to log in as a superuser to run the 'install'
   command, or use the 'sudo' command to run 'install'.)


Additional notes for Mac OS X
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

On Mac OS X you will usually install additional software such as
libjpeg or freetype with the "fink" tool, and then it ends up in
"/sw".  If you have installed the libraries elsewhere, you may have
to tweak the "setup.py" file before building.


Additional notes for Windows
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

On Windows, you need to tweak the ROOT settings in the "setup.py"
file, to make it find the external libraries.  See comments in the
file for details.

Make sure to build PIL and the external libraries with the same
runtime linking options as was used for the Python interpreter
(usually /MD, under Visual Studio).


Note that most Python distributions for Windows include libraries
compiled for Microsoft Visual Studio.  You can get the free Express
edition of Visual Studio from:

    http://www.microsoft.com/Express/

To build extensions using other tool chains, see the "Using
non-Microsoft compilers on Windows" section in the distutils handbook:

    http://www.python.org/doc/current/inst/non-ms-compilers.html

For additional information on how to build extensions using the
popular MinGW compiler, see:

    http://mingw.org (compiler)
    http://sebsauvage.net/python/mingw.html (build instructions)
    http://sourceforge.net/projects/gnuwin32 (prebuilt libraries)