1
0
mirror of https://github.com/RIOT-OS/RIOT.git synced 2025-01-18 12:52:44 +01:00

Merge pull request #14103 from aabadie/pr/doc/generator_doc

doc: document make generate-* in related sections
This commit is contained in:
Francisco 2020-05-26 12:17:21 +02:00 committed by GitHub
commit baeea442fa
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
4 changed files with 135 additions and 1 deletions

View File

@ -91,3 +91,52 @@ USEMODULE += gnrc_udp
~~~~~~~~~~~~~~~~~~~~~~~~~~~
Modules typically pull in all required dependencies.
# Helper tools
To help you start writing an application within RIOT, the build system provides
the `generate-example` `generate-test` make targets. These targets are wrappers
around the [riotgen](https://pypi.org/project/riotgen/) command line tool and
are helpful when starting to implement an application: all required files are
generated with copyright headers, doxygen groups, etc, so you can concentrate
on the module implementation.
For applications, the `Makefile` is generated with the dependencies (modules,
packages, required features) included.
**Usage:**
To generate an example application, e.g in the `examples` directory, from the
RIOT base directory, run:
```
make generate-example
```
To generate a test application, e.g in the `tests` directory, from the
RIOT base directory, run:
```
make generate-test
```
Then answer a few questions about the application:
- Application name: enter a name for your application. It will be used as both
the name of the application directory under `examples` or `tests` and by
the build system module (set in the `APPLICATION` variable).
- Application brief description: Describe in one line what is this application
about.
- Target board: select the default target board. The value is set to `native`
by default.
- Modules: give the list of dependency modules, separated by commas. For
example: ztimer,fmt
- Packages: give the list of dependency packages, separated by commas.
- Features required: give the list of CPU features (`periph_*`, etc) required
by the application, all separated by commas.
Other global information (author name, email, organization) should be retrieved
automatically from your git configuration.
Once completed, the application files are either located in
`examples/<application name>` or `tests/<application name>` depending on the
target used.
**Testrunner:** when using the `make generate-test`, you can also automatically
add a testrunner Python script. Just answer 'y' when prompted.

View File

@ -154,4 +154,34 @@ the only parts of compounded module names and only match against part of that na
See `sys/ztimer/Makefile` for an example in code.
`SUBMODULES` can also be true-pseudomodules.
`SUBMODULES` can also be true-pseudomodules.
# Helper tools
To help you start writing a module, the RIOT build system provides the
`generate-module` make target. It is a wrapper around the
[riotgen](https://pypi.org/project/riotgen/) command line tool that is helpful
when starting to implement a module: all required files are generated with
copyright headers, doxygen groups, etc, so you can concentrate on the module
implementation.
The module source files are created in the `sys` directory.
**Usage:**
From the RIOT base directory, run:
```
make generate-module
```
Then answer a few questions about the driver:
- Module name: enter a name for your module. It will be used as both the name
of the module directory under sys, where the source files are created, and
the build system module (used with `USEMODULE`).
- Module doxygen name: Enter the name of module, as displayed in the
Doxygen documentation.
- Brief doxygen description: Describe in one line what is this module about.
Other global information (author name, email, organization) should be retrieved
automatically from your git configuration.
Once completed, the module files are located in
`sys/<module name>/<module name>.c` and `sys/include/<module name>.h`.

View File

@ -263,6 +263,34 @@ enum {
- *MUST*: use `const devab_t *dev` when the device descriptor can be access
read-only
## Helper tools
To help you start writing a device driver, the RIOT build system provides the
`generate-driver` make target. It is a wrapper around the
[riotgen](https://pypi.org/project/riotgen/) command line tool that is helpful
when starting to implement a driver: all minimum files are generated with
copyright headers, doxygen groups, etc, so you can concentrate on the driver
implementation.
**Usage:**
From the RIOT base directory, run:
```
make generate-driver
```
Then answer a few questions about the driver:
- Driver name: enter a name for your driver. It will be used as both the name
of the driver directory where the source files are created and the build
system module.
- Driver doxygen group name: Enter the name of driver, as displayed in the
Doxygen documentation.
- Brief doxygen description: Describe in one line what is this driver about.
- Parent driver Doxygen group: Enter the Doxygen group the driver belongs to.
It can be `actuators`, `display`, `misc`, `netdev`, `sensors`, `storage`.
Other global information (author name, email, organization) should be retrieved
automatically from your git configuration.
# Sensors {#driver-guide-sensors}
## SAUL {#driver-guide-saul}

View File

@ -172,6 +172,33 @@ any browser.
*/
@endcode
# Helper tools
To help you start porting a board, the RIOT build system provides the
`generate-board` make target. It is a wrapper around the
[riotgen](https://pypi.org/project/riotgen/) command line tool that is helpful
when starting to port a board: all required files are generated with
copyright headers, doxygen groups, etc, so you can concentrate on the port.
The board source files are created in the `boards/<board name>` directory.
**Usage:**
From the RIOT base directory, run:
```
make generate-board
```
Then answer a few questions about the driver:
- Board name: Enter a name for your board. It will be used as the name
of the board directory under `boards`.
- Board displayed name: Enter the name of the board, as displayed in the
Doxygen documentation.
- CPU name: Enter the name of the CPU embedded on the board.
- CPU model name: Enter the precise model name of the CPU.
- Features provided: CPU features provided (and configured) for this board.
Other global information (author name, email, organization) should be retrieved
automatically from your git configuration.
# Using Common code {#common-board-code}
To avoid code duplication, common code across boards has been grouped in