mirror of
https://github.com/RIOT-OS/RIOT.git
synced 2024-12-29 04:50:03 +01:00
5457014c4a
- Replace all users of `$(RIOTBASE)/build` with the already present `$(BUILD_DIR)` variable - Replace all users of `$(BUILD_DIR)/pkg` with the already present `$(PKGDIRBASE)` variable - Create a `CACHEDIR.TAG` file in the `$(BUILD_DIR)`
106 lines
4.4 KiB
Plaintext
106 lines
4.4 KiB
Plaintext
/**
|
|
* @defgroup pkg Packages
|
|
* @{
|
|
* @brief External libraries and applications
|
|
* @details 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:
|
|
*
|
|
* ~~~~~~~~ {.mk}
|
|
* 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:
|
|
*
|
|
* ~~~~~~~~ {.mk}
|
|
* $(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:
|
|
*
|
|
* ~~~~~~~~ {.mk}
|
|
* $(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`:
|
|
*
|
|
* ~~~~~~~~ {.mk}
|
|
* 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](src/creating-modules.html#modules-outside-of-riotbase) 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:
|
|
*
|
|
* ~~~~~~~~ {.mk}
|
|
* 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
|
|
* `foo`must be located in `<PATH_IN_EXTERNAL_PKG_DIRS>/foo`.
|
|
*
|
|
* An example can be found in
|
|
* [`tests/build_system/external_pkg_dirs`](https://github.com/RIOT-OS/RIOT/tree/master/tests/build_system/external_pkg_dirs)
|
|
*
|
|
* RIOT welcomes new and useful packages. If you'd like to share your work,
|
|
* consider [contributing](https://github.com/RIOT-OS/RIOT/tree/master/CONTRIBUTING.md).
|
|
*
|
|
* @}
|
|
*/
|