RIOT/pkg/doc.txt

/**
 * @defgroup pkg   Packages
 * @{
 * @brief          External libraries and applications
 *
 * 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. If the package provides
 * header files you might need to update the `INCLUDE` macro, too:
 *
 * ~~~~~~~~ {.mk}
 * USEPKG += <pkg_name>
 * INCLUDE += $(RIOTPKG)/<pkg_name>/...
 * ~~~~~~~~
 *
 * When the package can be build out-of-source, the source code of external
 * packages is fetched in a global location in
 * `$(RIOTBASE)/build/pkg/$(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 fetch in the build
 * directory of the application under `$(BINDIR)/pkg/$(PKG_NAME)`
 * and is the same as the build directory (this is the case for micropython
 * and openthread packages).
 *
 * 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`.
 *
 * 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.
 * @}
 */