setup.py and pyproject.toml

setup.py

Projects that use robotpy-build must use the setup function provided by robotpy-build. Your project’s setup.py should look like this:

#!/usr/bin/env python3
from robotpy_build.setup import setup
setup()

pyproject.toml

Projects that use robotpy-build must add a pyproject.toml to the root of their project as specified in PEP 518.

It is recommended that projects include the standard build-system section to tell pip to install robotpy-build (and any other dependencies) before starting a build.

[build-system]
requires = ["robotpy-build>=2020.1.0,<2021.0.0"]

Projects must include robotpy-build specific sections in their pyproject.toml. robotpy-build takes pyproject.toml and converts it to a python dictionary using toml.load. The resulting dictionary is given to pydantic, which validates the structure of the dictionary against the objects described below.

Required sections:

Optional sections:

Note

For a complete example pyproject.toml file, see tests/cpp/pyproject.toml.tmpl

Overrides

You can define ‘override’ sections that will be grafted onto the configuration if they match a particular platform. For example, to change the dependencies for a wrapper section on Windows:

[tool.robotpy-build.wrappers."PACKAGENAME".override.os_windows]
depends = ["windows-thing"]

Any element in the robotpy-build section of pyproject.toml can be overridden by specifying the identical section as ‘.override.KEYNAME’. If the key matches the current configuration, the override will be written to the original section. The matched keys are generated at runtime. Current supported platform override keys are:

  • arch_{platform_arch}

  • os_{platform_os}

  • platform_{platform_os}_{platform_arch}

To get information about the current platform, you can run:

robotpy-build platform-info

To show the available platforms:

robotpy-build platform-info --list

To process a pyproject.toml and see the result of applying various overrides, you can use this tool to process for the current platform:

robotpy-build show-override

To show what would be processed for a different platform:

robotpy-build show-override -p linux-athena

Current supported platform/os/arch combinations are:

  • OS: windows/osx/linux

  • Arch: x86/x86-64/armv7l/aarch64

For ARM linux distributions we support:

  • armv7l + nilrt (RoboRIO)

  • armv7l + raspbian (Raspbian 10)

  • aarch64 + bionic (Ubuntu 18.04)

Reference

class robotpy_build.config.pyproject_toml.DistutilsMetadata

Configures the metadata that robotpy-build passes to setuptools when the project is installed. The keys in this section match the standard arguments passed to the setuptools.setup function.

[tool.robotpy-build.metadata]
name = "my-awesome-dist"
description = "Cool thing"
license = "MIT"

robotpy-build will automatically detect/set the following keys:

  • cmdclass

  • ext_modules

  • include_package_data - True

  • long_description - Contents of README.md/README.rst

  • long_description_content_type - If required

  • packages

  • python_requires - >=3.6

  • version - via setuptools_scm

  • zip_safe - False

Note

This section is required

author: str

The name of the package author

author_email: str

The email address of the package author

description: Optional[str] = None

A single line describing the package

install_requires: List[str]

A string or list of strings specifying what other distributions need to be installed when this one is. If the requirement is ==THIS_VERSION, the requirement is set to be the same version as this package

license: str

The license for the package

name: str

The name of the package

url: str

A URL for the package (homepage)

class robotpy_build.config.pyproject_toml.Download

Download sources/libs/includes from a single file

[[tool.robotpy-build.wrappers."PACKAGENAME".download]]
url = "https://my/url/something.zip"
incdir = "include"
libs = ["mylib"]
dlopenlibs: Optional[List[str]] = None

If specified, names of contained shared link only libraries (in loading order). If None, set to name. If empty list, link only libs will not be downloaded.

extra_includes: List[str] = []

Extra include paths, relative to the include directory

{{ARCH}} and {{OS}} are replaced with the architecture/os name

header_patches: Optional[List[PatchInfo]] = None

Patches to downloaded header files in incdir. Patches must be in unified diff format.

incdir: Optional[str] = None

Directory that contains include files.

{{ARCH}} and {{OS}} are replaced with the architecture/os name

libdir: str = ''

Directory that contains library files

{{ARCH}} and {{OS}} are replaced with the architecture/os name

libexts: Dict[str, str] = {}

Library extensions map

libs: Optional[List[str]] = None

If specified, names of contained shared libraries (in loading order)

linkexts: Dict[str, str] = {}

Compile time extensions map

patches: Optional[List[PatchInfo]] = None

If sources is set, apply the following patches to the sources. Patches must be in unified diff format.

sources: Optional[List[str]] = None

List of sources to compile

url: str

URL of zipfile to download

{{ARCH}} and {{OS}} are replaced with the architecture/os name

class robotpy_build.config.pyproject_toml.MavenLibDownload

Used to download artifacts from a maven repository. This can download headers, shared libraries, and sources.

[tool.robotpy-build.wrappers."PACKAGENAME".maven_lib_download]
artifact_id = "mything"
group_id = "com.example.thing"
repo_url = "http://example.com/maven"
version = "1.2.3"

Note

For FIRST Robotics libraries, the information required can be found in the vendor JSON file

artifact_id: str

Maven artifact ID

dlopenlibs: Optional[List[str]] = None

Names of contained shared link only libraries (in loading order). If None, set to name. If empty list, link only libs will not be downloaded.

group_id: str

Maven group ID

header_patches: Optional[List[PatchInfo]] = None

Patches to downloaded header files. Patches must be in unified diff format.

libexts: Dict[str, str] = {}

Library extensions map

libs: Optional[List[str]] = None

Names of contained shared libraries (in loading order). If None, set to artifact_id.

linkexts: Dict[str, str] = {}

Compile time extensions map

patches: Optional[List[PatchInfo]] = None

If use_sources is set, apply the following patches to the sources. Patches must be in unified diff format.

repo_url: str

Maven repository URL

sources: Optional[List[str]] = None

If use_sources is set, this is the list of sources to compile

sources_classifier: str = 'sources'

Configure the sources classifier

use_sources: bool = False

When set, download sources instead of downloading libraries. When using this, you need to manually add the sources to the configuration to be compiled via sources.

version: str

Version of artifact to download

class robotpy_build.config.pyproject_toml.PatchInfo

A unified diff to apply to downloaded source code before building a a wrapper.

[[tool.robotpy-build.wrappers."MY.PACKAGE.NAME".maven_lib_download.patches]]
patch = "path/to/my.patch"
strip = 0
patch: str

Name of patch file to apply

strip: int = 0

Number of directories to strip

class robotpy_build.config.pyproject_toml.RobotpyBuildConfig

Contains information for configuring the project

[tool.robotpy-build]
base_package = "my.package"

Note

This section is required

base_package: str

Python package to store version information and robotpy-build metadata in

supported_platforms: List[SupportedPlatform] = []

See also

SupportedPlatform

class robotpy_build.config.pyproject_toml.StaticLibConfig

Static libraries that can be consumed as a dependency by other wrappers in the same project. Static libraries are not directly installed, and as a result cannot be consumed by other projects.

[tool.robotpy-build.static_libs."MY.PACKAGE.NAME"]
download: Optional[List[Download]] = None

If this project depends on external libraries downloadable from some URL specify it here

ignore: bool = False

If True, skip this library; typically used in conjection with an override

maven_lib_download: Optional[MavenLibDownload] = None

If this project depends on external libraries stored in a maven repo specify it here

class robotpy_build.config.pyproject_toml.SupportedPlatform

Supported platforms for this project. Currently this information is merely advisory, and is used to generate error messages when platform specific downloads fail.

[tool.robotpy-build]
base_package = "my.package"
supported_platforms = [
    { os = "windows", arch = "x86-64" },
]

See also

List of supported platforms

arch: Optional[str] = None

Platform architecture

os: Optional[str] = None

Platform operating system name

class robotpy_build.config.pyproject_toml.TypeCasterConfig

Specifies type casters that this package exports. robotpy-build will attempt to detect these types at generation time and include them in generated wrappers.

[[tool.robotpy-build.wrappers."PACKAGENAME".type_casters]]
header = "my_type_caster.h"
types = ["foo_t", "ns::ins::bar_t"]

See also

Type Casters

default_arg_cast: bool = False

If a parameter type that requires this type caster requires a default argument, a C-style (type) cast is used on the default argument.

The default cast can be disabled via param_override’s disable_type_caster_default_cast

header: str

Header file to include when one of the types are detected in a wrapper

types: List[str]

Types to look for to indicate that this type caster header should be included.

class robotpy_build.config.pyproject_toml.WrapperConfig

Configuration for building a C++ python extension module, optionally using autogenerated wrappers around existing library code.

[tool.robotpy-build.wrappers."PACKAGENAME"]
name = "package_name"

The PACKAGENAME above is a python package (eg “example.package.name”). A robotpy-build project can contain many different wrappers and packages.

autogen_headers: Optional[Dict[str, str]] = None

Specifies header files that autogenerated pybind11 wrappers will be created for. Simple C++ headers will most likely ‘just work’, but complex headers will need to have an accompanying generation_data file specified that can customize the autogenerated files.

List of dictionaries: each dictionary key is used for the function name of the initialization function, the value is the header that is being wrapped. The header is first looked for relative to the package, then relative to each include directory (including downloaded and extracted packages).

[tool.robotpy-build.wrappers."PACKAGENAME".autogen_headers]
Name = "header.h"

See also

Automated C++ header wrapping

depends: List[str] = []

List of robotpy-build library dependencies. This affects this wrapper library in the following ways:

  • Any include file directories exported by the dependency will be added to the include path for any source files compiled by this wrapper

  • It will be linked to any libraries the dependency contains

  • The python module for the dependency will be imported in the _init{extension}.py file.

download: Optional[List[Download]] = None

If this project depends on external libraries downloadable from some URL specify it here

extension: Optional[str] = None

Name of extension to build. If None, set to _{name}

extra_includes: List[str] = []

List of extra include directories to export, relative to the project root.

generate: Optional[List[Dict[str, str]]] = None

DEPRECATED: Same as autogen_headers, but more complicated

generation_data: Optional[str] = None

Path to a single data.yml to use during code generation, or a directory of yaml files. If a directory, generation data will be looked up using the key in the generate dictionary.

These YAML files can be generated via the robotpy-build command line tool:

robotpy-build create-gen --write

See also

Generator Customization

ignore: bool = False

If True, skip this wrapper; typically used in conjection with an override.

libinit: Optional[str] = None

Name of generated file that ensures the shared libraries and any dependencies are loaded. Defaults to _init{extension}.py

Generally, you should create an __init__.py file that imports this module, otherwise your users will need to do so.

maven_lib_download: Optional[MavenLibDownload] = None

If this project depends on external libraries stored in a maven repo specify it here.

name: str

Name that other projects/wrappers use in their ‘depends’ list

pp_defines: List[str] = []

Preprocessor definitions to apply when compiling this wrapper.

sources: List[str] = []

Optional source files to compile. Path is relative to the root of the project.

type_casters: List[TypeCasterConfig] = []

Specifies type casters that this package exports.