External libraries and applications More...

Detailed Description

External libraries and applications

What are packages? RIOT packages:

pull a specific tested version most often from the (a) origin source
patch them to match the RIOT architecture
provide a specific tested configuration (such configuration may enable or disable features)
integrate the packages build process into the RIOT one
they have RIOT tests and/or examples to test/build them

Using packages

To add a package to the list of compiled modules you have to add it to the USEPKG macro in your application's Makefile:

USEPKG += <pkg_name>

When the package can be built out-of-source, the source code of external packages is fetched in a global location in:

$(PKGDIRBASE)/$(PKG_NAME)

When out-of-source build is not possible (for example because the package build system doesn't allow it), the source code is fetched in the build directory of the application under:

$(BINDIR)/pkg/$(PKG_NAME)

In this case, the source and the build directory are the same (currently, this only applies to the micropython package).

Porting an external library

Structure of a package

This module provides porting information for libraries and applications to use with RIOT (to build an external module). If you'd like to add a package to RIOT you need to add a directory with the name of your package to this directory. This directory should contain at least one file:

Makefile: A Makefile describing how to get the upstream application, apply the patch and how to build the package as a RIOT module. A rough template for several methods of acquiring a package is provided in pkg/Makefile.git and pkg/Makefile.http.

If your port or the package provide header files, you need to update the INCLUDES variable in the package's Makefile.include:

INCLUDES += -I$(RIOTPKG)/<pkg_name>/include # headers provided by the port

INCLUDES += -I$(PKGDIRBASE)/<pkg_name> # headers provided by the package

Patch files can be included in a patches directory in the package dir. These are applied to the upstream package to make it build with RIOT.

Creating a patch with git

Assuming your upstream library resides in a git repository, you can create the patch files as follows:

checkout the targeted version of the upstream application
create a new branch (e.g. riot-port)
conduct necessary changes (e.g. edit, add, or remove some files)
commit your changes using git commit
create the patch files using git format-patch -n riot-port
move the resulting patch files to the patches directory of your package.

Packages outside of RIOTPKG

It can be beneficial to create packages outside of the RIOT tree. For example if one is working on new packages that aren't ready to be committed to upstream or if an application needs its own unique packages. For this, one can use the EXTERNAL_PKG_DIRS make variable. It works similar to the way external modules are handled. In your application's Makefile, in addition to adding the package name to USEPKG as shown above, add the path to a folder that contains your external packages:

EXTERNAL_PKG_DIRS += <PATH_TO_FOLDER_CONTAINING_PACKAGES>

The path is allowed to be relative to the application's directory.

NOTE: The name of an external package must be unique (both in regard to other external packages, as well to native RIOT packages). Additionally, the directory containing the packages must match the package name, e.g. package foomust be located in <PATH_IN_EXTERNAL_PKG_DIRS>/foo.

An example can be found in tests/build_system/external_pkg_dirs

RIOT welcomes new and useful packages. If you'd like to share your work, consider contributing.