AICA Package Template

A software development kit for creating custom components for AICA applications.

Full documentation for creating, testing and packaging custom components is available at https://docs.aica.tech/docs/category/custom-components.

You will need to have Docker installed in order to develop or build your component package (see Docker installation).

Create a custom package repository

To create a component package, create a new repository in GitHub using this repository as a template.

Alternatively, you can also clone this repository locally and create a new repository from it.

git clone [email protected]:aica-technology/component-template.git my_component_package

Initialize the template component package

This template repository uses the placeholder package name template_component_package and includes four different component types: C++ component, C++ lifecycle component, Python component, and Python lifecycle component.

The first step is to rename the package to a meaningful custom name and remove any unnecessary component types. You can accomplish this by using the included initialize_package script. In a terminal, run

./initialize_package.sh [--dry-run] [--help]

from the top level directory of the repository. The script prompts you with the name for the package and the component types that should be included.

If you want to include a second ROS package within the AICA package, create a new package folder in source and add it to your aica-package.toml file under [build.packages.name_of_new_package] accordingly.

Configure the package development environment

This template uses a devContainer configuration (devcontainer.json) with base AICA Docker images for a seamless integrated development experience.

Using VSCode and the Dev Containers extension, after creating and renaming the template package, simply open the repository in a devcontainer using the "Reopen in Container" command.

Other IDEs such as JetBrains can similarly be configured to use development containers.

If any changes are made to aica-package.toml (including any package names or dependencies), remember to rebuild the devcontainer.

Building your component package

You can build your package using the following command:

docker build -f aica-package.toml .

We use a custom Docker frontend instead of a Dockerfile, so all configuration of the build is stored in aica-package.toml. As we are using docker build to build you can pass any Docker argument, like -t <image_name> to tag the image or --platform <platform> to build for a specific platform. Note that you can only build one platform at a time at the moment.

Testing your component package

You can invoke any unit tests in your package by changing the docker build stage to test, e.g.:

docker build -f aica-package.toml --target test .

Package configuration with aica-package.toml

All build configurations, metadata and dependencies are defined in aica-package.toml. Refer to the docs for more details about the syntax.

CLI configuration

The aica-package.toml file contains the configuration of the build process but you can override it using the CLI.

In order to do so, you will need to pass --build-arg config.<key>=<value> to the docker build command.

Example:

docker build -f aica-package.toml --build-arg config.build.cmake_args.SOME_FLAG=Release .

Installing external dependencies

As the build is done in a Docker container, you will need to install external dependencies through aica-package.toml.

System libraries

You can add system libraries by adding the list of packages to install through apt:

[build.packages.component.dependencies.apt]
libyaml-cpp-dev = "*"

Note that the * is currently ignored but might be used in the future to specify a version.

Python packages

aica-package.toml will automatically install any Python packages specified in a requirements.txt file stored in your component package folder. However, you can change the name of that file or specify the packages to install directly in aica-package.toml:

[build.packages.component.dependencies.pip]
file = "requirements.txt"
# OR
[build.packages.component.dependencies.pip.packages]
numpy = "1.0.0"

Using your component package

After you have built and tagged your package as a docker image, you can use it in your application. See the AICA documentation for more details.