Pillow/winbuild/build.rst

111 lines
4.1 KiB
ReStructuredText
Raw Normal View History

2014-03-22 03:52:05 +04:00
Building Pillow on Windows
==========================
2018-02-09 12:56:10 +03:00
.. note:: For most people, the `installation instructions
<../docs/installation.rst#windows-installation>`_ should
be sufficient.
2014-03-22 03:52:05 +04:00
2020-01-01 23:08:51 +03:00
This page describes the steps necessary to build Pillow using the same
scripts used on GitHub Actions and AppVeyor CIs.
2014-03-22 03:52:05 +04:00
2015-06-17 02:02:32 +03:00
Prerequisites
2015-12-02 07:40:16 +03:00
-------------
2014-03-22 03:52:05 +04:00
2020-01-01 23:08:51 +03:00
Compilers
^^^^^^^^^
2014-04-05 04:05:42 +04:00
2020-01-01 23:08:51 +03:00
Download and install:
2014-03-22 03:52:05 +04:00
2020-02-25 02:00:57 +03:00
* `Microsoft Visual Studio 2017 or newer or Build Tools for Visual Studio 2017 or newer
<https://visualstudio.microsoft.com/downloads/>`_
(MSVC C++ build tools, and any Windows SDK version required)
2014-03-22 03:52:05 +04:00
* `CMake 3.12 or newer <https://cmake.org/download/>`_
2020-02-25 02:00:57 +03:00
(also available as Visual Studio component C++ CMake tools for Windows)
2014-03-22 03:52:05 +04:00
* x86/x64: `NASM <https://www.nasm.us/pub/nasm/releasebuilds/?C=M;O=D>`_
2014-03-22 03:52:05 +04:00
2020-01-01 23:08:51 +03:00
Any version of Visual Studio 2017 or newer should be supported,
2020-02-25 02:00:57 +03:00
including Visual Studio 2017 Community, or Build Tools for Visual Studio 2019.
2014-03-25 20:00:41 +04:00
2020-02-25 02:00:57 +03:00
Paths to CMake (if standalone) and NASM must be added to the ``PATH`` environment variable.
Visual Studio is found automatically with ``vswhere.exe``.
2014-03-22 03:52:05 +04:00
2020-01-01 23:08:51 +03:00
Build configuration
-------------------
2014-03-22 03:52:05 +04:00
2020-01-01 23:08:51 +03:00
The following environment variables, if set, will override the default
behaviour of ``build_prepare.py``:
2014-03-22 03:52:05 +04:00
2020-01-01 23:08:51 +03:00
* ``PYTHON`` + ``EXECUTABLE`` point to the target version of Python.
If ``PYTHON`` is unset, the version of Python used to run
``build_prepare.py`` will be used. If only ``PYTHON`` is set,
``EXECUTABLE`` defaults to ``python.exe``.
* ``ARCHITECTURE`` is used to select a ``x86``, ``x64`` or ``ARM64`` build.
By default, uses same architecture as the version of Python used to run ``build_prepare.py``.
2020-01-01 23:08:51 +03:00
* ``PILLOW_BUILD`` can be used to override the ``winbuild\build`` directory
path, used to store generated build scripts and compiled libraries.
**Warning:** This directory is wiped when ``build_prepare.py`` is run.
* ``PILLOW_DEPS`` points to the directory used to store downloaded
dependencies. By default ``winbuild\depends`` is used.
2014-03-22 03:52:05 +04:00
2020-02-25 02:00:57 +03:00
``build_prepare.py`` also supports the following command line parameters:
* ``-v`` will print generated scripts.
* ``--no-imagequant`` will skip GPL-licensed ``libimagequant`` optional dependency
2021-09-19 00:00:39 +03:00
* ``--no-fribidi`` or ``--no-raqm`` will skip optional LGPL-licensed dependency FriBiDi
(required for Raqm text shaping).
2020-02-25 02:00:57 +03:00
* ``--python=<path>`` and ``--executable=<exe>`` override ``PYTHON`` and ``EXECUTABLE``.
* ``--architecture=<arch>`` overrides ``ARCHITECTURE``.
* ``--dir=<path>`` and ``--depends=<path>`` override ``PILLOW_BUILD``
and ``PILLOW_DEPS``.
2014-03-22 03:52:05 +04:00
Dependencies
------------
2020-01-01 23:08:51 +03:00
Dependencies will be automatically downloaded by ``build_prepare.py``.
By default, downloaded dependencies are stored in ``winbuild\depends``;
set the ``PILLOW_DEPS`` environment variable to override this location.
2014-03-22 03:52:05 +04:00
2020-01-01 23:08:51 +03:00
To build all dependencies, run ``winbuild\build\build_dep_all.cmd``,
or run the individual scripts to build each dependency separately.
2014-03-22 03:52:05 +04:00
2014-04-05 04:05:42 +04:00
Building Pillow
---------------
2020-01-01 23:08:51 +03:00
Once the dependencies are built, run
``winbuild\build\build_pillow.cmd install`` to build and install
Pillow for the selected version of Python.
``winbuild\build\build_pillow.cmd bdist_wheel`` will build wheels
instead of installing Pillow.
2014-04-05 04:05:42 +04:00
2020-08-02 23:14:38 +03:00
You can also use ``winbuild\build\build_pillow.cmd --inplace develop`` to build
2020-10-29 14:41:29 +03:00
and install Pillow in develop mode (instead of ``python3 -m pip install --editable``).
2020-08-02 23:14:38 +03:00
2014-04-05 04:05:42 +04:00
Testing Pillow
2014-03-22 03:52:05 +04:00
--------------
Some binary dependencies (e.g. ``fribidi.dll``) will be stored in the
2020-01-01 23:08:51 +03:00
``winbuild\build\bin`` directory; this directory should be added to ``PATH``
before running tests.
Build and install Pillow, then run ``python3 -m pytest`` from the root Pillow
directory.
2020-01-01 23:08:51 +03:00
Example
-------
The following is a simplified version of the script used on AppVeyor::
2014-03-22 03:52:05 +04:00
2020-06-27 14:39:44 +03:00
set PYTHON=C:\Python38\bin
2020-01-01 23:08:51 +03:00
cd /D C:\Pillow\winbuild
2020-02-25 02:00:57 +03:00
C:\Python37\bin\python.exe build_prepare.py -v --depends=C:\pillow-depends
2020-01-01 23:08:51 +03:00
build\build_dep_all.cmd
build\build_pillow.cmd install
cd ..
path C:\Pillow\winbuild\build\bin;%PATH%
%PYTHON%\python.exe selftest.py
%PYTHON%\python.exe -m pytest -vx --cov PIL --cov Tests --cov-report term --cov-report xml Tests
build\build_pillow.cmd bdist_wheel