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:
RobotpyBuildConfig
- base project configurationDistutilsMetadata
- standard python distutils metadata
Optional sections:
WrapperConfig
- per-package configurationMavenLibDownload
- download per-package maven artifactsPatchInfo
- patch downloaded sources
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
-
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.
-
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.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.
-
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
-
dlopenlibs:
- 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
-
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
-
artifact_id:
- 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
-
strip:
int
= 0¶ Number of directories to strip
-
patch:
- 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
-
supported_platforms:
List
[SupportedPlatform
] = []¶ See also
-
base_package:
- 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
[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
-
download:
- 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
-
os:
Optional
[str
] = None¶ Platform operating system name
-
arch:
- class robotpy_build.pyproject_configs.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
-
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.
-
default_arg_cast:
- 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.
-
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
-
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
-
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.
-
autogen_headers: