Merge pull request #6947 from nulano/winbuild-ninja

.github/workflows/test-windows.yml

@@ -97,7 +97,7 @@ jobs:
     - name: Prepare build
       if: steps.build-cache.outputs.cache-hit != 'true'
       run: |
-        & python.exe winbuild\build_prepare.py -v --python=$env:pythonLocation --srcdir
+        & python.exe winbuild\build_prepare.py -v --python $env:pythonLocation
       shell: pwsh
 
     - name: Build dependencies / libjpeg-turbo

winbuild/README.md

@@ -10,7 +10,7 @@ For more extensive info, see the [Windows build instructions](build.rst).
 
 * Requires Microsoft Visual Studio 2017 or newer with C++ component.
 * Requires NASM for libjpeg-turbo, a required dependency when using this script.
-* Requires CMake 3.12 or newer (available as Visual Studio component).
+* Requires CMake 3.15 or newer (available as Visual Studio component).
 * Tested on Windows Server 2016 with Visual Studio 2017 Community, and Windows Server 2019 with Visual Studio 2022 Community (AppVeyor).
 * Tested on Windows Server 2022 with Visual Studio 2022 Enterprise (GitHub Actions).
 

winbuild/build.rst

@@ -21,10 +21,13 @@ Download and install:
   <https://visualstudio.microsoft.com/downloads/>`_
   (MSVC C++ build tools, and any Windows SDK version required)
 
-* `CMake 3.12 or newer <https://cmake.org/download/>`_
+* `CMake 3.15 or newer <https://cmake.org/download/>`_
   (also available as Visual Studio component C++ CMake tools for Windows)
 
-* x86/x64: `NASM <https://www.nasm.us/pub/nasm/releasebuilds/?C=M;O=D>`_
+* `Ninja <https://ninja-build.org/>`_
+  (optional, use ``--nmake`` if not available; bundled in Visual Studio CMake component)
+
+* x86/x64: `Netwide Assembler (NASM) <https://www.nasm.us/pub/nasm/releasebuilds/?C=M;O=D>`_
 
 Any version of Visual Studio 2017 or newer should be supported,
 including Visual Studio 2017 Community, or Build Tools for Visual Studio 2019.
@@ -35,41 +38,50 @@ Visual Studio is found automatically with ``vswhere.exe``.
 Build configuration
 -------------------
 
-The following environment variables, if set, will override the default
-behaviour of ``build_prepare.py``:
-
-* ``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``.
-* ``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.
-
-``build_prepare.py`` also supports the following command line parameters:
-
-* ``-v`` will print generated scripts.
-* ``--no-imagequant`` will skip GPL-licensed ``libimagequant`` optional dependency
-* ``--no-fribidi`` or ``--no-raqm`` will skip optional LGPL-licensed dependency FriBiDi
-  (required for Raqm text shaping).
-* ``--python=<path>`` and ``--executable=<exe>`` override ``PYTHON`` and ``EXECUTABLE``.
-* ``--architecture=<arch>`` overrides ``ARCHITECTURE``.
-* ``--dir=<path>`` and ``--depends=<path>`` override ``PILLOW_BUILD``
-  and ``PILLOW_DEPS``.
+Run ``build_prepare.py`` to configure the build::
+
+    usage: winbuild\build_prepare.py [-h] [-v] [-d PILLOW_BUILD]
+                                     [--depends PILLOW_DEPS]
+                                     [--architecture {x86,x64,ARM64}]
+                                     [--python PYTHON] [--executable EXECUTABLE]
+                                     [--nmake] [--no-imagequant] [--no-fribidi]
+
+    Download dependencies and generate build scripts for Pillow.
+
+    options:
+      -h, --help            show this help message and exit
+      -v, --verbose         print generated scripts
+      -d PILLOW_BUILD, --dir PILLOW_BUILD, --build-dir PILLOW_BUILD
+                            build directory (default: 'winbuild\build')
+      --depends PILLOW_DEPS
+                            directory used to store cached dependencies (default:
+                            'winbuild\depends')
+      --architecture {x86,x64,ARM64}
+                            build architecture (default: same as host Python)
+      --python PYTHON       Python install directory (default: use host Python)
+      --executable EXECUTABLE
+                            Python executable (default: use host Python)
+      --nmake               build dependencies using NMake instead of Ninja
+      --no-imagequant       skip GPL-licensed optional dependency libimagequant
+      --no-fribidi, --no-raqm
+                            skip LGPL-licensed optional dependency FriBiDi
+
+    Arguments can also be supplied using the environment variables PILLOW_BUILD,
+    PILLOW_DEPS, ARCHITECTURE, PYTHON, EXECUTABLE. See winbuild\build.rst for more
+    information.
+
+**Warning:** The build directory is wiped when ``build_prepare.py`` is run.
 
 Dependencies
 ------------
 
 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.
+use the ``--depends`` argument or ``PILLOW_DEPS`` environment variable
+to override this location.
 
 To build all dependencies, run ``winbuild\build\build_dep_all.cmd``,
-or run the individual scripts to build each dependency separately.
+or run the individual scripts in order to build each dependency separately.
 
 Building Pillow
 ---------------
@@ -100,7 +112,7 @@ The following is a simplified version of the script used on AppVeyor::
 
     set PYTHON=C:\Python38\bin
     cd /D C:\Pillow\winbuild
-    C:\Python37\bin\python.exe build_prepare.py -v --depends=C:\pillow-depends
+    C:\Python37\bin\python.exe build_prepare.py -v --depends C:\pillow-depends
     build\build_dep_all.cmd
     build\build_pillow.cmd install
     cd ..