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.pyproject_configs.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

Type

str

author_email: str

The email address of the package author

Type

str

description: Optional[str] = None

A single line describing the package

Type

Optional[str]

install_requires: List[str]

A string or list of strings specifying what other distributions need to be installed when this one is.

Type

List[str]

license: str

The license for the package

Type

str

name: str

The name of the package

Type

str

url: str

A URL for the package (homepage)

Type

str

class robotpy_build.pyproject_configs.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.

Type

Optional[List[str]]

extra_includes: List[str] = []

Extra include paths, relative to the include directory

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

Type

List[str]

incdir: Optional[str] = None

Directory that contains include files.

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

Type

Optional[str]

libdir: str = ''

Directory that contains library files

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

Type

str

libexts: Dict[str, str] = {}

Library extensions map

Type

Dict[str, str]

libs: Optional[List[str]] = None

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

Type

Optional[List[str]]

linkexts: Dict[str, str] = {}

Compile time extensions map

Type

Dict[str, str]

patches: Optional[List[robotpy_build.pyproject_configs.PatchInfo]] = None

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

Type

Optional[List[PatchInfo]]

sources: Optional[List[str]] = None

List of sources to compile

Type

Optional[List[str]]

url: str

URL of zipfile to download

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

Type

str

class robotpy_build.pyproject_configs.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

Type

str

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.

Type

Optional[List[str]]

group_id: str

Maven group ID

Type

str

libexts: Dict[str, str] = {}

Library extensions map

Type

Dict[str, str]

libs: Optional[List[str]] = None

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

Type

Optional[List[str]]

linkexts: Dict[str, str] = {}

Compile time extensions map

Type

Dict[str, str]

patches: Optional[List[robotpy_build.pyproject_configs.PatchInfo]] = None

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

Type

Optional[List[PatchInfo]]

repo_url: str

Maven repository URL

Type

str

sources: Optional[List[str]] = None

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

Type

Optional[List[str]]

sources_classifier: str = 'sources'

Configure the sources classifier

Type

str

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.

Type

bool

version: str

Version of artifact to download

Type

str

class robotpy_build.pyproject_configs.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

Type

str

strip: int = 0

Number of directories to strip

Type

int

class robotpy_build.pyproject_configs.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

Type

str

supported_platforms: List[robotpy_build.pyproject_configs.SupportedPlatform] = []
Type

List[SupportedPlatform]

class robotpy_build.pyproject_configs.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[robotpy_build.pyproject_configs.Download]] = None

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

Type

Optional[List[Download]]

ignore: bool = False

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

Type

bool

maven_lib_download: Optional[robotpy_build.pyproject_configs.MavenLibDownload] = None

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

Type

Optional[MavenLibDownload]

class robotpy_build.pyproject_configs.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

Type

Optional[str]

os: Optional[str] = None

Platform operating system name

Type

Optional[str]

class robotpy_build.pyproject_configs.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.

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.

Type

List[str]

download: Optional[List[robotpy_build.pyproject_configs.Download]] = None

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

Type

Optional[List[Download]]

extension: Optional[str] = None

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

Type

Optional[str]

extra_includes: List[str] = []

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

Type

List[str]

generate: Optional[List[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"]
generate = [
  { Name = "header.h" },
]
Type

Optional[List[Dict[str, str]]]

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
Type

Optional[str]

ignore: bool = False

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

Type

bool

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.

Type

Optional[str]

maven_lib_download: Optional[robotpy_build.pyproject_configs.MavenLibDownload] = None

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

Type

Optional[MavenLibDownload]

name: str

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

Type

str

pp_defines: List[str] = []

Preprocessor definitions to apply when compiling this wrapper.

Type

List[str]

sources: List[str] = []

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

Type

List[str]

type_casters: Dict[str, List[str]] = {}

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."package-name".type_casters]
"namespace_type1_type_caster.h" = ["namespace::type1", .. ]

See also

Type Casters

Type

Dict[str, List[str]]