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.

Example File

{
  "name": "helloyotta",
  "version": "0.0.0",
  "description": "Hello yotta example module",
  "keywords": ["example"],
  "author": "James Crosby <james.crosby@arm.com>",
  "homepage": "http://github.com/ARMmbed/yotta",
  "repository": {
    "url": "git@github.com:ARMmbed/helloyotta.git",
    "type": "git"
  },
  "license": "Apache-2.0",
  "dependencies": {
    "simplelog": "~0.0.0"
  },
  "targetDependencies": {},
  "bin": "./source"
}

Properties

# name required

type: String

The unique name of your module. It’s got to be globally unique, so be adventurous!

Names can use only lowercase letters, numbers, and hyphens, but must start with a letter. (This reduces problems with case insensitive filesystems, and confusingly similar names.)

# version required

type: String (conforming to the semver specification)

yotta uses Semantic Versions for modules: your module’s version lets people who depend on your module know how it’s changed since they last updated.

The basic format is:

<major>.<minor>.<patch>

Optionally followed by -build-specifiers.

Whenever you publish a new version of your module, you must update the version number.

For 0.x.x versions, the module’s API may change in any way across version numbers.

Once the public API is relatively stable, the major version should be incremented to 1.

For 1+.x.x versions, semantic versioning defines the following rules:

  • The <major> version must be incremented whenever any backwards incompatible changes are made.

  • Otherwise, the <minor> version must be updated if new functionality is added which is backwards compatible.

  • Otherwise, the <patch> version must be updated if only backwards-compatible bugfixes have been made.

For a complete guide to semantic versioning, see semver.org.

# licenses deprecated

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.

licenses example:

  "licenses": [
    {
      "url": "https://spdx.org/licenses/Apache-2.0",
      "type": "Apache-2.0"
    }
  ],

# license required

type: String "<SPDX license identifier>"**

The license property in module.json should include all of the licenses that affect code in your module. For example:

  "license": "Apache-2.0"

The license identifiers are from the SPDX list. SPDX license expressions can be used for compound licenses.

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.

#dependencies

type: Object {"<modulename>": "<version specification or source>"}

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.

Example:

    "dependencies": {
		"usefulmodule": "^1.2.3",
		"simplelog": "ARMmbed/simplelog#~0.0.1"
	}

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:

  • "usefulmodule": "git+ssh://somwhere.com/anything/anywhere"
  • "usefulmodule": "git+ssh://somwhere.com/anything/anywhere#<version specification>"
  • "usefulmodule": "git+ssh://somwhere.com/anything/anywhere#<branch name>"
  • "usefulmodule": "git+ssh://somwhere.com/anything/anywhere#<tag name>"
  • "usefulmodule": "git+ssh://somwhere.com/anything/anywhere#<commit id>"
  • "usefulmodule": "<anything>://somwhere.git"
  • "usefulmodule": "<anything>://somwhere.git#<version spec, tag, branch name or commit id>"

Depending on hg Modules

To specify a module available from a mercurial server as a dependency, use a hg URL:

  • "usefulmodule": "hg+ssh://somwhere.com/anything/anywhere"
  • "usefulmodule": "hg+ssh://somwhere.com/anything/anywhere#<version specification>"
  • "usefulmodule": "<anything>://somwhere.hg"
  • "usefulmodule": "<anything>://somwhere.hg#<version specification>"
  • "usefulmodule": "hg+<anything>://somwhere"
  • "usefulmodule": "hg+<anything>://somwhere#<version specification>"

Where is a tag with a semantic version identifier.

Note that modules depending on github, ssh, or hg repositories cannot be published: they will be rejected by the yotta registry.

# targetDependencies

type: Object {"<target-identifier>": <dependencies object>}

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.

Example:

    "targetDependencies": {
        "k64f": {
            "mbed-hal-freescale": "^3.0.0",
            "mbed": "^3.0.0"
        },
        "/mbed/meshing/supported": {
            "mbed-meshing": "^1.2.3"
        }
	}

# testDependencies

type: Object {"<modulename>": "<version specification or source>"}

The testDependencies section can be used to list modules that are only depended on by tests. They will not normally be installed if your module is installed as a dependency of another.

See dependencies for a description of how to specify different sorts of dependencies.

# testTargetDependencies

type: Object {"<target-identifier>": <dependencies object>}

The testTargetDependencies section has the same format as the targetDependencies section, but only specifies dependencies needed to run unit tests.

# description

type: String

Brief of what your module does. This helps other people to find your module. Include a readme.md file with a longer description, API documentation and example code.

#keywords

type: Array of String

Keywords describe what your module does, and help other people to find it.

#homepage

type: String (url)

The URL of your module’s homepage (if any).

#repository

type: Object {"url":"<url>", "type": "<git, hg, or svn>"}

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.

# private

type: Boolean

If present, and set to true, then yotta publish will not allow you to publish this module to the public registry. This is useful to prevent accidental publication of private modules and applications.

# bugs

type: Object {"url":"<url>", "email": "<optional email>"}

Including a bugs section helps people who use your module to report problems, and suggest fixes.

Example:

  "bugs": {
    "url": "http://github.com/ARMmbed/helloyotta/issues",
    "email": "helloyotta-bugs@example.com"
  }

# bin

type: String (path relative to module root)

If present, the bin property specifies a subdirectory that should be built into an executable. Published modules should not normally use this property.

For example, to build an executable (instead of the default static library) out of the contents of the source directory, set:

  "bin": "./source"

# lib

type: String (path relative to module root)

If present, the lib property specifies a subdirectory that should be built into a library. If it isn’t specified, then the default behaviour is for the “source” directory to be built into a library.

For example, to build a library out of the contents of ./some/subdirectory instead of the default source directory, use:

  "lib": "./some/subdirectory"

# extraIncludes

type: Array of String (paths relative to module root)

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.

# scripts

type: hash of script-name to command

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:

   "scripts": {
      "testReporter": ["greentea", "--digest", "stdin", "-v", "-V"]
   }

# yotta

type: version specification

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.