# skbuild.platform_specifics package

This package provides `get_platform()` allowing to get an instance of `abstract.CMakePlatform` matching the current platform.

This folder contains files the define CMake’s defaults for given platforms. Any of them can be overridden by either command line or by environment variables.

class skbuild.platform_specifics.CMakeGenerator(name: str, env: Mapping[str, str] | None = None, toolset: str | None = None, arch: str | None = None, args: Iterable[str] | None = None)

  Bases: `object`

  Represents a CMake generator.

  __init__(name: str, env: Mapping[str, str] | None = None, toolset: str | None = None, arch: str | None = None, args: Iterable[str] | None = None) → None

    Instantiate a generator object with the given `name`.

    By default, `os.environ` is associated with the generator. Dictionary passed as `env` parameter will be merged with `os.environ`. If an environment variable is set in both `os.environ` and `env`, the variable in `env` is used.

    Some CMake generators support a `toolset` specification to tell the native build system how to choose a compiler. You can also include CMake arguments.

  property architecture: str | None

    Architecture associated with the CMake generator.

  property description: str

    Name of CMake generator with properties describing the environment (e.g toolset)

  property name: str

    Name of CMake generator.

  property toolset: str | None

    Toolset specification associated with the CMake generator.

skbuild.platform_specifics.get_platform() → CMakePlatform

  Return an instance of `abstract.CMakePlatform` corresponding to the current platform.

## Submodules

## skbuild.platform_specifics.abstract module

This module defines objects useful to discover which CMake generator is supported on the current platform.

class skbuild.platform_specifics.abstract.CMakeGenerator(name: str, env: Mapping[str, str] | None = None, toolset: str | None = None, arch: str | None = None, args: Iterable[str] | None = None)

  Bases: `object`

  Represents a CMake generator.

  __init__(name: str, env: Mapping[str, str] | None = None, toolset: str | None = None, arch: str | None = None, args: Iterable[str] | None = None) → None

    Instantiate a generator object with the given `name`.

    By default, `os.environ` is associated with the generator. Dictionary passed as `env` parameter will be merged with `os.environ`. If an environment variable is set in both `os.environ` and `env`, the variable in `env` is used.

    Some CMake generators support a `toolset` specification to tell the native build system how to choose a compiler. You can also include CMake arguments.

  property architecture: str | None

    Architecture associated with the CMake generator.

  property description: str

    Name of CMake generator with properties describing the environment (e.g toolset)

  property name: str

    Name of CMake generator.

  property toolset: str | None

    Toolset specification associated with the CMake generator.

class skbuild.platform_specifics.abstract.CMakePlatform

  Bases: `object`

  This class encapsulates the logic allowing to get the identifier of a working CMake generator.

  Derived class should at least set `default_generators`.

  static cleanup_test() → None

    Delete test project directory.

  static compile_test_cmakelist(cmake_exe_path: str, candidate_generators: Iterable[CMakeGenerator], cmake_args: Iterable[str] = ()) → CMakeGenerator | None

    Attempt to configure the test project with each `CMakeGenerator` from `candidate_generators`.

    Only cmake arguments starting with `-DCMAKE_` are used to configure the test project.

    The function returns the first generator allowing to successfully configure the test project using `cmake_exe_path`.

  property default_generators: list[CMakeGenerator]

    List of generators considered by `get_best_generator()`.

  property generator_installation_help: str

    Return message guiding the user for installing a valid toolchain.

  get_best_generator(generator_name: str | None = None, skip_generator_test: bool = False, languages: Iterable[str] = ('CXX', 'C'), cleanup: bool = True, cmake_executable: str = '/usr/bin/cmake', cmake_args: Iterable[str] = (), architecture: str | None = None) → CMakeGenerator

    Loop over generators to find one that works by configuring and compiling a test project.

    Parameters:

      - generator_name (str | None) – If provided, uses only provided generator, instead of trying `default_generators`.

      - skip_generator_test (bool) – If set to True and if a generator name is specified, the generator test is skipped. If no generator_name is specified and the option is set to True, the first available generator is used.

      - languages (tuple) – The languages you’ll need for your project, in terms that CMake recognizes.

      - cleanup (bool) – If True, cleans up temporary folder used to test generators. Set to False for debugging to see CMake’s output files.

      - cmake_executable (str) – Path to CMake executable used to configure and build the test project used to evaluate if a generator is working.

      - cmake_args (tuple) – List of CMake arguments to use when configuring the test project. Only arguments starting with `-DCMAKE_` are used.

    Returns:

      CMake Generator object

    Return type:

      `CMakeGenerator` or None

    Raises:

      skbuild.exceptions.SKBuildGeneratorNotFoundError –

  get_generator(generator_name: str) → CMakeGenerator

    Loop over generators and return the first that matches the given name.

  get_generators(generator_name: str) → list[CMakeGenerator]

    Loop over generators and return all that match the given name.

  static write_test_cmakelist(languages: Iterable[str]) → None

    Write a minimal `CMakeLists.txt` useful to check if the requested `languages` are supported.

## skbuild.platform_specifics.bsd module

This module defines object specific to BSD platform.

class skbuild.platform_specifics.bsd.BSDPlatform

  Bases: `UnixPlatform`

  BSD implementation of `abstract.CMakePlatform`.

## skbuild.platform_specifics.cygwin module

This module defines object specific to Cygwin platform.

class skbuild.platform_specifics.cygwin.CygwinPlatform

  Bases: `CMakePlatform`

  Cygwin implementation of `abstract.CMakePlatform`.

  property generator_installation_help: str

    Return message guiding the user for installing a valid toolchain.

## skbuild.platform_specifics.linux module

This module defines object specific to Linux platform.

class skbuild.platform_specifics.linux.LinuxPlatform

  Bases: `UnixPlatform`

  Linux implementation of `abstract.CMakePlatform`

  static build_essential_install_cmd() → tuple[str, str]

    Return a tuple of the form `(distribution_name, cmd)`.

    `cmd` is the command allowing to install the build tools in the current Linux distribution. It set to an empty string if the command is not known.

    `distribution_name` is the name of the current distribution. It is set to an empty string if the distribution could not be determined.

  property generator_installation_help: str

    Return message guiding the user for installing a valid toolchain.

## skbuild.platform_specifics.osx module

This module defines object specific to OSX platform.

class skbuild.platform_specifics.osx.OSXPlatform

  Bases: `UnixPlatform`

  OSX implementation of `abstract.CMakePlatform`.

  property generator_installation_help: str

    Return message guiding the user for installing a valid toolchain.

## skbuild.platform_specifics.aix module

This module defines object specific to AIX platform.

class skbuild.platform_specifics.aix.AIXPlatform

  Bases: `UnixPlatform`

  AIX implementation of `abstract.CMakePlatform`.

  property generator_installation_help: str

    Return message guiding the user for installing a valid toolchain.

## skbuild.platform_specifics.platform_factory module

This modules implements the logic allowing to instantiate the expected `abstract.CMakePlatform`.

skbuild.platform_specifics.platform_factory.get_platform() → CMakePlatform

  Return an instance of `abstract.CMakePlatform` corresponding to the current platform.

## skbuild.platform_specifics.unix module

This module defines object specific to Unix platform.

class skbuild.platform_specifics.unix.UnixPlatform

  Bases: `CMakePlatform`

  Unix implementation of `abstract.CMakePlatform`.

## skbuild.platform_specifics.windows module

This module defines object specific to Windows platform.

class skbuild.platform_specifics.windows.CMakeVisualStudioCommandLineGenerator(name: str, year: str, toolset: str | None = None, args: Iterable[str] | None = None)

  Bases: `CMakeGenerator`

  Represents a command-line CMake generator initialized with a specific Visual Studio environment.

  __init__(name: str, year: str, toolset: str | None = None, args: Iterable[str] | None = None)

    Instantiate CMake command-line generator.

    The generator `name` can be values like Ninja, NMake Makefiles or NMake Makefiles JOM.

    The `year` defines the Visual Studio environment associated with the generator. See `VS_YEAR_TO_VERSION`.

    If set, the `toolset` defines the Visual Studio Toolset to select.

    The platform (32-bit or 64-bit or ARM) is automatically selected.

class skbuild.platform_specifics.windows.CMakeVisualStudioIDEGenerator(year: str, toolset: str | None = None)

  Bases: `CMakeGenerator`

  Represents a Visual Studio CMake generator.

  __init__(year: str, toolset: str | None = None) → None

    Instantiate a generator object with its name set to the Visual Studio generator associated with the given `year` (see `VS_YEAR_TO_VERSION`), the current platform (32-bit or 64-bit) and the selected `toolset` (if applicable).

class skbuild.platform_specifics.windows.CachedEnv

  Bases: `TypedDict`

  Stored environment.

  INCLUDE: str
  LIB: str
  PATH: str

skbuild.platform_specifics.windows.VS_YEAR_TO_VERSION = {'2017': 15, '2019': 16, '2022': 17}

  Describes the version of Visual Studio supported by `CMakeVisualStudioIDEGenerator` and `CMakeVisualStudioCommandLineGenerator`.

  The different version are identified by their year.

class skbuild.platform_specifics.windows.WindowsPlatform

  Bases: `CMakePlatform`

  Windows implementation of `abstract.CMakePlatform`.

  property generator_installation_help: str

    Return message guiding the user for installing a valid toolchain.

skbuild.platform_specifics.windows.find_visual_studio(vs_version: int) → str

  Return Visual Studio installation path associated with `vs_version` or an empty string if any.

  The `vs_version` corresponds to the Visual Studio version to lookup. See `VS_YEAR_TO_VERSION`.

  Note

  - Returns path based on the result of invoking `vswhere.exe`.