module.json Reference

The module.json file is used to describe all yotta modules and executables,
it lists the dependencies, specifies the license under which the module can be
used, and provides other information about the module.

To create a new module, you can either write a module.json file manually, or
use yotta init to populate the file by answering a sequence of questions.

See also: license. The licenses property was formerly a method
of specifying that multiple licenses applied to a module. It’s now preferred to
use a single license field containing a SPDX license expression.

According to SPDX v2.0, custom licenses in a file should be entered as:

"license":"LicenseRef-LICENSE.pdf"

If you’re starting a completely new module, and have freedom to choose the
license yourself, yotta’s preferred license is
Apache-2.0, a permissive OSI-approved
open source license which provides clarity over the scope of patent grants.
yotta itself is also licensed under Apache-2.0.

When you run yotta init to initialise a new module, yotta will suggest some
licenses, and automatically fill in the license field for those options.

Remember: some people will find it much harder to use your module if you
don’t use a standard permissive license.

While not required (since your module may not depend on anything), the
dependencies section is one of the most important in your module’s
description. It describes which other modules your code needs in order to run
and which versions of them should be used.

yotta uses this information to automatically download the modules when you
build.

Depending on Modules in the yotta Registry

If only a version specification is provided, yotta will look for the specified module
in the public yotta registry. (To publish a module to the registry use
yotta publish).

Version specifications can take any of the following forms:

1.2.3: an exact version number. Use only this exact version (not
recommended)

^1.2.3: any compatible version (exact version for 0.x.x versions, or any
version greater than the specified version with the same major version
number for versions > 1.

~1.2.3: any version with the same major and minor versions, and an equal
or greater patch version.

>1.2.3: any version greater than 1.2.3. >=, <, and <= are also
possible.

*: any version (useful for development)

The ^ and ~ specifiers are recommended, as these provide some guarantee of
compatibility without rigidly constraining the version (which would cause
problems if two separate modules depend on different versions).

Depending on Modules in Github

yotta has built-in support for depending on modules from Github, including
private repositories (run yotta login to authorise yotta for the private
repositories you have access to).

To specify a dependency on a github module, use one of the following forms:

"usefulmodule": "username/repositoryname"

Uses the latest version tagged with a semantic version identifier, or
the head of the default branch if no tagged versions are available.

"usefulmodule": "username/repositoryname#^1.2.3"

Uses the highest tagged version matching the version specification.

"usefulmodule": "username/repositoryname#tag-name"

Uses the specific tagged version.

"usefulmodule": "username/repositoryname#branch-name"

Uses the latest committed version on the specified branch.

"usefulmodule": "username/repositoryname#commit-id"

Uses the specified commit ID.

Depending on git Modules

To specify a module available from a non-Github git server as a dependency, use
a git URL:

The modules in the dependencies property are always installed and used, no
matter what the compilation target is. Sometimes it’s useful to depend on
different modules when the compilation target is different – e.g. if compiling
for different embedded devices that have different ways of connecting to the
internet.

The targetDependencies property makes this possible.

Each value in the targetDependencies is a target identifier defining a set of
dependencies with the same format as the dependencies property.

When calculating the dependencies to install, yotta uses all sections
from targetDependencies that matches one of the identifiers in the current
target’s similarTo list, or which match
properties that are defined to a truthy value in the configuration
data.

To test nested values from config data, use JSON pointer syntax,
"/mbed/meshing/supported" in the following example tests that the “supported”
value is truthy in config data that looks like this:

{"mbed":{"meshing":{"supported":true}}}

A “truthy” json config value is any object or string, or non-zero numbers, or a
literal true boolean value.

NOTE: in the future support for evaluating simple expressions on config
values may be added, but this is not currently possible. To choose which
one-of-n dependencies to use you must define N config values that are either
true or false, and require that they are set appropriately.

The repository section helps other people to contribute to your module by
making it easy for them to clone their own copy and suggest improvements.

The URL of your module’s source code repository and the type of the repository
should be included.

Note: this repository field is intended as a place where people can find
and contribute back to your module. It is never used by yotta to download code.
See the dependencies section for information on how to depend
on modules from source control repositories, instead of from the public modules
registry.

WARNING do not use this property in released modules. It exists only to
simplify the porting of existing software modules to yotta.

Array of additional paths to be included in the header search path. By default
the module’s root directory will be in the header search path when compiling
anything that depends on it (directly or indirectly).

The convention of using the module’s name for the directory in the module root
that contains the public header files means that public header files can be
included as:

#include "modulename/headername.h"

without specifying any additional include paths. This almost completely
eliminates any possibility of header name collision, as published module names
are forced to be unique by the yotta module registry.

Each command is either an array of the separate command arguments, or a single
string which yotta will split into parts based on normal shell command
splitting rules.

Any script which is a .py file will be invoked using the python interpreter
which is running yotta.

The supported scripts are:

preVersion: Runs before the yotta
version
command increments the version number. The old and new version numbers are
available as environment variables YOTTA_OLD_VERSION and
YOTTA_NEW_VERSION. Can return non-zero to prevent continuing.

postVersion: Runs after the version has been bumped by yotta
version, but before any changes have been committed or tagged in VCS
(returning non-zero will prevent
anything from being committed).

prePublish: Runs before the module is
published. Can return non-zero to
prevent publishing.

postPublish: Runs after the module has been published. Tweet here.

postInstall: Runs once after a module is downloaded into
yotta_modules, or downloaded as a top-level module.

preGenerate: Runs before generating CMake for any build including this
module.

preBuild: Runs immediately before each build including this module.

postBuild: Runs after everything has been built. This script will be
run whether or not this module was actually re-built (so don’t do slow
things here!): consider using a .cmake file to define post-build rules
instead.

preTest: Runs before tests from this module are loaded by the target’s
scripts.test script.

preDebug: Runs before this module (if it is an application), or one of
its tests is loaded by the target’s scripts.debug script.

preStart: Runs before this module (if it is an application) is loaded
by the target’s scripts.start script.

testReporter: this command is run for the tests of each module, and is
piped the output of the tests. It may display information about the
success/failure of a test, and should exit with a status 0 if the test
passed, or a status 1 if the test failed.

The preGenerate, preBuild and postBuild scripts have the merged config
information available to them in a file indicated by the
YOTTA_MERGED_CONFIG_FILE environment variable.

Examples

A module that uses the greentea test
framework, would use the greentea helper program to parse and verify the test
output might use this testReporter script:

A version specification for the version of yotta that this module requires. For
example:

"yotta":">=0.13.0"

"yotta":">=0.10.0, !0.12.0"

If your module requires functionality that was introduced in a specific yotta
version, then you can use this property so that older versions of yotta report
a clear error message to the user that they need to upgrade before using your
module.