C Runtime, Compiler and Build System Generator

scikit-build uses sensible defaults allowing to select the C runtime matching the official CPython recommendations. It also ensures developers remain productive by selecting an alternative environment if recommended one is not available.

The table below lists the different C runtime implementations, compilers and their usual distribution mechanisms for each operating systems.

	Linux	MacOSX	Windows
C runtime	GNU C Library (glibc)	libSystem library	Microsoft C run-time library
Compiler	GNU compiler (gcc)	clang	Microsoft C/C++ Compiler (cl.exe)
Provenance	Package manager	OSX SDK within XCode	Microsoft Visual Studio Microsoft Windows SDK

Build system generator

Since scikit-build simply provides glue between setuptools and CMake, it needs to choose a CMake generator to configure the build system allowing to build of CPython C extensions.

The table below lists the generator supported by scikit-build:

Operating System	Linux	MacOSX	Windows
CMake Generator	Ninja Unix Makefiles		Ninja Visual Studio NMake Makefiles NMake Makefiles JOM

When building a project, scikit-build iteratively tries each generator (in the order listed in the table) until it finds a working one.

For more details about CMake generators, see CMake documentation.

Ninja

• Supported platform(s): Linux, MacOSX and Windows

• If ninja executable is in the PATH, the associated generator is used to setup the project build system based on ninja files.

• In a given python environment, installing the ninja python package with pip install ninja will ensure that ninja is in the PATH.

Note

Automatic parallelism

An advantage of ninja is that it automatically parallelizes the build based on the number of CPUs. See Enabling parallel build.

Note

Ninja on Windows

When Ninja generator is used on Windows, scikit-build will make sure the project is configured and built with the appropriate [3] environment (equivalent of calling vcvarsall.bat x86 or vcvarsall.bat amd64).

When Visual Studio >= 2017 is used, ninja is available by default thanks to the Microsoft CMake extension:

C:/Program Files (x86)/Microsoft Visual Studio/2017/Professional/Common7/IDE/CommonExtensions/Microsoft/CMake/Ninja/ninja.exe

Unix Makefiles

• Supported platform(s): Linux, MacOSX

• scikit-build uses this generator to generate a traditional Makefile based build system.

Visual Studio IDE

• Supported platform(s): Windows

• scikit-build uses the generator corresponding to selected version of Visual Studio and generate a solution file based build system.

	Architecture
CPython Version	x86 (32-bit)	x64 (64-bit)
3.7 and above	Visual Studio 17 2022 Visual Studio 16 2019 Visual Studio 15 2017	Visual Studio 17 2022 Win64 Visual Studio 16 2019 Win64 Visual Studio 15 2017 Win64

Note

The Visual Studio generators can not be used when only alternative environments are installed, in that case Ninja or NMake Makefiles are used.

NMake Makefiles

• Supported platform(s): Windows

• scikit-build will make sure the project is configured and built with the appropriate [3] environment (equivalent of calling vcvarsall.bat x86 or vcvarsall.bat amd64).

Note

NMake Makefiles JOM

The NMake Makefiles JOM generator is supported but it is not automatically used by scikit-build (even if jom executable is in the PATH), it always needs to be explicitly specified. For example:

python setup.py build -G "NMake Makefiles JOM"

For more details, see scikit-build options.

Linux

scikit-build uses the toolchain set using CC (and CXX) environment variables. If no environment variable is set, it defaults to gcc.

To build compliant Linux wheels, scikit-build also supports the manylinux platform described in PEP-0513. We recommend the use of dockcross/manylinux-x64 and dockcross/manylinux-x86. These images are optimized for building Linux wheels using scikit-build.

MacOSX

scikit-build uses the toolchain set using CC (and CXX) environment variables. If no environment variable is set, it defaults to the Apple compiler installed with XCode.

Default Deployment Target and Architecture

Added in version 0.7.0.

The default deployment target and architecture selected by scikit-build are hard-coded for MacOSX and are respectively 10.9 and x86_64.

This means that the platform name associated with the bdist_wheel command is:

macosx-10.9-x86_64

and is equivalent to building the wheel using:

python setup.py bdist_wheel --plat-name macosx-10.9-x86_64

Respectively, the values associated with the corresponding CMAKE_OSX_DEPLOYMENT_TARGET and CMAKE_OSX_ARCHITECTURES CMake options that are automatically used to configure the project are the following:

CMAKE_OSX_DEPLOYMENT_TARGET:STRING=10.9
CMAKE_OSX_ARCHITECTURES:STRING=x86_64

As illustrated in the table below, choosing 10.9 as deployment target to build MacOSX wheels will allow them to work on System CPython, the Official CPython, Macports and also Homebrew installations of CPython.

List of platform names for each CPython distributions, CPython and OSX versions.

CPython Distribution	CPython Version	OSX Version	get_platform() [1]
Official CPython	3.9, 3.10	10.9	macosx-10.9-universal2
	3.8	11	macosx-11.0-universal2
	3.7, 3.8, 3.9, 3.10	10.9	macosx-10.9-x86_64
Macports CPython	3.x	Current	Depends on current macOS version.
Homebrew CPython	3.x	Current

The information above have been adapted from the excellent Spinning wheels article written by Matthew Brett.

Default SDK and customization

Added in version 0.7.0.

By default, scikit-build lets CMake discover the most recent SDK available on the system during the configuration of the project. CMake internally uses the logic implemented in the Platform/Darwin-Initialize.cmake CMake module.

Customizing SDK

Added in version 0.7.0.

If needed, this can be overridden by explicitly passing the CMake option CMAKE_OSX_SYSROOT. For example:

python setup.py bdist_wheel -- -DCMAKE_OSX_SYSROOT:PATH=/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX10.12.sdk

Customizing Deployment Target and Architecture

Added in version 0.11.0.

Deployment target can be customized by setting the MACOSX_DEPLOYMENT_TARGET environment variable.

Added in version 0.7.0.

Deployment target and architecture can be customized by associating the --plat-name macosx-<deployment_target>-<arch> option with the bdist_wheel command.

For example:

python setup.py bdist_wheel --plat-name macosx-10.9-x86_64

scikit-build also sets the value of CMAKE_OSX_DEPLOYMENT_TARGET and CMAKE_OSX_ARCHITECTURES option based on the provided platform name. Based on the example above, the options used to configure the associated CMake project are:

-DCMAKE_OSX_DEPLOYMENT_TARGET:STRING=10.9
-DCMAKE_OSX_ARCHITECTURES:STRING=x86_64

libstdc++ vs libc++

Before OSX 10.9, the default was libstdc++.

With OSX 10.9 and above, the default is libc++.

Forcing the use of libstdc++ on newer version of OSX is still possible using the flag -stdlib=libstdc++. That said, doing so will report the following warning:

clang: warning: libstdc++ is deprecated; move to libc++

• libstdc++:

  This is the GNU Standard C++ Library v3 aiming to implement the ISO 14882 Standard C++ library.

• libc++:

  This is a new implementation of the C++ standard library, targeting C++11.

Windows

Microsoft C run-time and Visual Studio version

On windows, scikit-build looks for the version of Visual Studio matching the version of CPython being used. The selected Visual Studio version also defines which Microsoft C run-time and compiler are used:

Python version	3.7 and above
Microsoft C run-time	ucrtbase.dll
Compiler version	MSVC++ 14.0
Visual Studio version	2017

Installing compiler and Microsoft C run-time

As outlined above, installing a given version of Visual Studio will automatically install the corresponding compiler along with the Microsoft C run-time libraries.

This means that if you already have the corresponding version of Visual Studio installed, your environment is ready.

Nevertheless, since older version of Visual Studio are not available anymore, this next table references links for installing alternative environments:

Download links for Windows SDK and Visual Studio.

CPython version	Download links for Windows SDK or Visual Studio
3.7 and above	Visual C++ Build Tools or Visual Studio (2017 or newer)

These links have been copied from the great article [2] of Steve Dower, engineer at Microsoft.

Footnotes

[1]

from distutils.util import get_platform; print(get_platform())

[2]

How to deal with the pain of “unable to find vcvarsall.bat”

[3] (1,2)

Implementation details: This is made possible by internally using the function query_vcvarsall from distutils._msvccompiler. To ensure, the environment associated with the latest compiler is properly detected, the distutils modules are systematically patched using setuptools.monkey.patch_for_msvc_specialized_compiler().