Package: colcon-poetry-ros
colcon-poetry-rosAn extension forcolcon-corethat adds support for Python
packages that usePoetrywithin ROS. This extension is a replacement
for Colcon's built-insetup.cfgbased Python support and the Python-related
bits incolcon-ros.We use this extension with Foxy and Humble, but other versions should work as
well. Please create an issue if you see problems!Getting StartedStart by install this extension with Pip:pip3installcolcon-poetry-rosThen, add apyproject.tomlin the root of your package's directory. Each
package should have its ownpyproject.tomlfile. It should look something
like this:[tool.poetry]name="my_package"version="0.1.0"description="Does something cool"authors=["John Smith <johnny@urbanmachine.build>"]license="BSD-3-Clause"[tool.poetry.dependencies]python="^3.8"[tool.poetry.scripts]node_a="my_package.node_a:main"node_b="my_package.node_b:main"[tool.colcon-poetry-ros.data-files]"share/ament_index/resource_index/packages"=["resource/my_package"]"share/my_package"=["package.xml"][build-system]requires=["poetry-core>=1.0.0"]build-backend="poetry.core.masonry.api"Finally, run your build like normal:colconbuildTestingThis extension currently supports projects based on PyTest. Run the following
command to start tests:colcontestNode EntrypointsIf you want to be able to run your nodes usingros2 run, add your node's
entrypoint to thetool.poetry.scriptstable. SeePoetry's documentationfor details.[tool.poetry.scripts]node_a="my_package.node_a:main"node_b="my_package.node_b:main"Data FilesPoetry has only limited support for including data files in an installation,
and the current implementation is not flexible enough to be used with ROS.
Instead, this extension consults a custom section in yourpyproject.toml,
calledtool.colcon-poetry-ros.data-files.The format is intended to be mostly identical to thedata_filesfield used
bysetuptools. The main differences are that copying
entire directories is supported, and globbing is not yet implemented.All ROS packages must have, at minimum, these entries in thetool.colcon-poetry-ros.data-filessection (with{package_name}replaced
with the name of your package):[tool.colcon-poetry-ros.data-files]"share/ament_index/resource_index/packages"=["resource/{package_name}"]"share/{package_name}"=["package.xml"]These entries take care of adding the package index marker andpackage.xmlfile to the installation.Installing DependenciesPoetry dependencies are not installed as part of the build process, but they
can be installed using a separate tool that's included in this package.python3-mcolcon_poetry_ros.dependencies.install--base-paths<pathtoyournodes>This command installs each package's dependencies to Colcon's base install
directory. This means that your dependencies live alongside your package's
code after it's built, isolated from the rest of your system.If you customizecolcon buildwith the--install-baseor--merge-installflags, make sure to provide those to this tool as well.Communicating Dependencies to ColconColcon expects extensions to report their dependencies as dependency
descriptors so that they can be shown in tools likecolcon graph. The
following sections describe how each dependency type is sourced from yourpyproject.toml.Build DependenciesThis extension uses therequiresfield in thebuild-systemtable to source
build dependencies. Seethe section in PEP 518for
details. This section might only be needed if you're using a compiler like
Cython that runs during package installation. Since these packages are not
locked by Poetry, the version specifications in therequiresfield will be
used as-is.Runtime DependenciesRuntime dependencies are pulled from thetool.poetry.dependenciestable. SeePoetry's documentationfor details. Dependency
versions are defined by thepoetry.lockfile.You can include extras by setting thePOETRY_RUN_DEPENDS_EXTRASenvironment variable. Multiple extras can be
provided and are separated by commas. By default, no extras are included.Test DependenciesPoetry currently has no official way of defining test dependencies, so test
dependencies are instead expected to be in an extra called "test". Dependency
versions are defined by thepoetry.lockfile.You can change which extras are used for test dependencies by setting thePOETRY_TEST_DEPENDS_EXTRASenvironment variable. Multiple extras can be
provided and are separated by commas. As mentioned above, this value is set to
"test" by default.