Provided by: yotta_0.20.0-1_all 
NAME
yotta - build system for C/C++ projects focussed on reusable components
SYNOPSIS
yotta [GLOBAL_OPTION] COMMAND [OPTION]
yotta [COMMAND] --help
yotta --version
DESCRIPTION
yotta is a build system designed to help developers build better software for C-family
languages by making it easier to share and re-use software modules.
yotta supports project compilation with different compilers by specifying targets for
compilation. Each compilation target can have its own specific requirements.
OPTIONS
yotta supports both global arguments (that work for all yotta commands) and
command-specific options.
[GLOBAL_OPTION] COMMAND [OPTION]
run the specified COMMAND with the optional global and command-specific options
[COMMAND] --help
when no command is given, display help for yotta, including a list of subcommands;
when an optional command is given, display help for the specified subcommand
--version
display the current version and exit
GLOBAL OPTIONS
yotta supports the following global arguments for all commands listed below:
--plain subcomman>
don’t use coloured output
--noninteractive subcommand
don’t wait for user input
--target targetname
override currently-set target for this command (useful when isolating several
instances of yotta)
--config configfile|JSON
override target and application-defined configuration; this is useful in CI
infrastructure to easily change the configuration for a particular build
MODULES
yotta can use two types of modules:
Library Modules
Executable Modules
Library Modules
Library modules are reusable code, which provide functionality useful to lots of different
apps such as network stacks, drivers and encoders/decoders. Anyone can publish a library
module to the yotta registry where other people can find useful modules and reuse them.
Executable Modules
Executable modules compile into a binary. Executable modules should not generally be
published to the yotta registry because they cannot be reused by other applications, and
instead are typically made available on code-hosting sites such as Gitlab and Github.
TARGETS
Targets describe which platform you are building for, and how the compiler should be run.
SEMANTIC VERSIONING
yotta modules use semantic versioning. A 0.x.y version number indicates a module that
does not yet have a stable API. When the API is stable the version number is incremented
to 1.0.0.
For modules with a major version >= 1, the major version number must be incremented
whenever backwards-incompatible changes are made. The minor and patch versions are used
for new backwards-compatible features and bug-fixes respectively.
COMMANDS
init
yotta init
Create a new module.json module-description file based on a set of questions. If a
module.json file already exists, the values in it will be used as defaults, and it will
not delete anything from the file.
build
yotta build [--generate-only] [--debug-build] [--cmake-generator <cmake-generator-name>] [name ... ]
yotta build [ ... ] -- [ build-tool arguments ]
Build the current module and its dependencies. Missing dependencies will be automatically
installed first.
If no name arguments are specified then the current module’s tests will be built, but not
the tests for any other module. Use yotta build all_tests to build the tests for all
dependency modules.
yotta uses CMake to control the build. The basic process is:
1. yotta installs the target description for the build target
2. yotta installs all module dependencies (which may depend on which target is being built
for)
3. yotta generates CMakeLists.txt describing the libraries and executables to build
4. yotta instructs CMake to generate the make files / ninja files / IDE project file
(depending on --cmake-generator)
5. yotta instructs CMake to execute the build. The compiler used depends on the CMake
Toolchain file provided by the active yotta target.
For more information on the yotta build process, see the build system reference.
Options
--generate-only, -g
only generate CMakeLists, don’t build
--debug-build, -d
build a debug (less-optimised) build. The effects depend on the target (this
selects CMake build type Debug), but generally this means no optimisation, and
NDEBUG is not defined.
--release-build, -r
build a release (optimised) build (deprecated). The effects depend on the target
(this selects CMake build type RelWithDebInfo). This option is deprecated because
it is now the default, unless --debug-build is specified.
--cmake-generator, -G
specify the CMake Generator. CMake can generate project files for various editors
and IDEs
name ...
one or more modules may be specified, in which case only these modules and their
dependencies will be built. Use all_tests to cause all tests to be built.
-- option1, option2, ...
any options specified after -- are passed unmodified on to the tool being used for
building (e.g. Ninja, or make)
Generating IDE Project Files
The -G/--cmake-generator option can be used to generate project files for various IDE and
text editors. This option is passed through to CMake, but note that only IDE project
files which use Ninja or Makefile build systems will correctly support cross-compilation
for yotta targets.
To see the CMake generators available on your platform see cmake --help.
Examples
Build this module and its tests:
yotta build
Build the tests for all dependencies:
yotta build -d all_tests
Generate IDE project files:
yotta build -d -G "Sublime Text 2 - Ninja"
yotta build -d -G "Eclipse CDT4 - Ninja"
Pass options through to the build system:
yotta build -G "Unix Makefiles" -- -j 4
yotta build -- -v
search
yotta search <string> [--keyword=<keyword>] [--limit=<N>]
yotta search module <string> [--keyword=<keyword>] [--limit=<N>]
yotta search target <string> [--keyword=<keyword>] [--limit=<N>]
Search for open-source yotta modules and build targets that have been published to the
yotta registry.
The results will be listed in combined order of search relevance and popularity.
Options
--keyword, -k
specify keywords to constrain the search (use multiple times for multiple keywords,
modules returned will have all of the specified keywords)
--limit, -l
limit the number of results returned
Examples
yotta search logging
yotta search module logging
yotta search target -k mbed-official -k mbed-target:k64f
test
yotta test [--list] [--no-build] [ build-arguments ] [tests-to-run ...]
Run tests. If no arguments are specified, then the tests for the current module will be
run, use yotta test all to run the tests for all modules.
The target description provides support for the test command if it is a cross-compiling
target (no support is necessary to run tests natively).
The scripts.test value in the target description is executed with $program expanded to the
path to the binary, it should be a wrapper script that loads the binary at the specified
path onto the target device, runs it, and prints output on standard output.
Options
--list, -l
list the tests that would be run, rather than running them. Implies --no-build.
--no-build, -n
don’t build anything, try to run already-built tests. Things will fail if all the
specified tests are not built!
This command also accepts the options to yotta build, which are used if building.
Examples
yotta test
yotta test --list all
yotta test -n my-test
yotta test --config="path/to/test-config.json"
debug
yotta debug <program>
If the target description supports it, launch a debugger attached to the specified
executable.
Examples
yotta debug test/simplelog-test
yotta debug source/helloyotta
target
yotta target
yotta target <targetname>[@url-or-version-spec] [-g] [-n]
Display or set the current target. yotta will look for and install a target description
from the yotta registry when building or installing dependencies. If you run yotta target
in an existing module yotta will attempt to download the target description immediately,
unless -n is specified.
Targets define the options and commands that yotta uses to compile modules and
executables.
A target must define a CMake Toolchain file describing all of the rules that yotta uses to
build software; it may also define commands to launch a debugger (used by yotta debug).
If -g is specified when setting the target, it will be saved globally (in the user
settings file). Otherwise the specified target will be saved for the current module only,
in a .yotta.json file.
If the target is set both locally and globally, the locally-set target takes precedence.
Examples
yotta target x86-osx-native
yotta target frdm-k64f-gcc@^2.0.0
install
Synonyms: yotta in
# in a module directory:
yotta install
yotta install <module>[@<version>]
# GitHub usage
yotta install <username>/<reponame>
yotta install <username>/<reponame>#<version|tagname|branchname|commit>
# anywhere:
yotta install <module>[@<version>] [--global]
Install a module, including the modules that it depends on.
Typical usage is:
yotta install <module>
which installs <module> and its dependencies, and saves it in the current module’s
description file.
A <module> is one of:
• a name, in which case the module is installed from the public yotta registry
(https://yottabuild.org)
• a github spec (username/reponame), in which case the module is installed directly from
github. This can include private github URLs.
yotta install (no arguments, in a module folder)
In a module directory, yotta install will check for and install any missing dependencies
of the current module.
Options:
--install-linked
also traverse into any linked modules, and install their dependencies. By default
linked modules are not modified. Note that without this option all the required
dependencies to build may not be installed.
yotta install (in a module folder)
In a module directory, yotta install <module> will install the specified module, and any
missing dependencies for it.
The installed version of the module will be saved as a dependency into the current
module’s module.json file. This uses the ^ semantic-version specifier to specify that
only minor version updates are allowed to be installed, unless the module has a 0.x.x
version number, in which case the ~ semantic-version specifier is used restrict updates to
patch versions only.
yotta install /
Install the specified module and any missing dependencies in a similar manner to above,
using GitHub as the source.
When a version isn’t specified, yotta will attempt to select the latest release version
from the tags available on the repository. If none are found, the master branch will be
installed.
yotta install /#<version|tagname|branchname|commit>
Install the specified module and any missing dependencies in a similar manner to above,
using GitHub as the source.
An optional version specification (which tries to match repository tags using semver), tag
name, branch name or commit ID can be specified to install the repository using that
marker.
yotta install (anywhere)
Download the specified dependency, and install it in a subdirectory of the current
directory.
Options:
--global
install the specified module into the global modules directory instead.
Examples
yotta install simpleog
yotta install ARM-RD/simplelog
update
Synonyms: yotta up
yotta update
yotta update <module>
Update all of the current modules dependencies to the latest matching versions. Or, if a
module is specified, update only that module and its dependencies.
Options
--update-linked
update the dependencies of linked modules too.
version
Synonyms: yotta v
yotta version [patch | minor | major | <version>]
Bump the current module’s version, set a new version, or display the current version.
patch, minor and major declare which part of the major.minor.patch version number to bump.
If the current module is version-controlled by mercurial or git, then the new version is
tagged. If the module is version controlled but the working directory is not clean, then
an error message is printed.
login
yotta login
Authenticate with the yotta registry. yotta will open a browser to an OAuth login page on
the yotta registry, where you can then log in with either GitHub or mbed. This process
generates a secret access token that is saved in your yotta configuration file, and which
yotta can use to pull from private repositories that you have access to on GitHub or mbed.
You must log in before you can publish modules. Access control for publishing is based on
email addresses verified by GitHub/mbed, you can see the email address of the owners with
permission to publish a given module using the yotta owners command.
No information other than your email address, and a public key generated by your yotta
client, is stored by the yotta registry. Even someone with access to the yotta registry’s
database would not be able to publish modules in your name without stealing information
that never leaves your computer!
logout
yotta logout
Remove all saved authentication information from the current computer. Does not revoke
access tokens, as GitHub returns the same access token for each computer that you log into
yotta on. If you wish to revoke access tokens you can do so on your GitHub account page.
whoami
yotta whoami
yotta who
Display the primary email address(es) that you are currently authenticated to. If you are
not logged in then this will return a non-zero status code, otherwise the status code is
0.
Examples
$ yotta whoami
friend@example.com
$ yotta logout
$ yotta whoami
not logged in
publish
yotta publish
Publish the current module or target to the public yotta registry
(https://yottabuild.org), where other people will be able to search for and install it.
Any files matching lines in the .yotta_ignore file (if present) are ignored, and will not
be included in the published tarball.
link
Synonyms: yotta ln
yotta link (in a module directory)
yotta link <modulename>
yotta link /path/to/a/module
Module linking allows you to use local versions of modules when building other modules –
it’s useful when fixing a bug in a dependency that is most easily reproduced when that
dependency is used by another module.
To link a module there are two steps. First, in the directory of the dependency:
yotta link
This will create a symlink from the global modules directory to the current module.
Then, in the module that you would like to use the linked version of the dependency, run:
yotta link <depended-on-module-name>
When you run yotta build it will then pick up the linked module.
This works for direct and indirect dependencies: you can link to a module that your module
does not use directly, but a dependency of your module does.
The variant of the command which takes a path to an existing module (e.g. yotta link
../path/to/a/module) performs both steps in sequence, for convenience.
Directories
When you run yotta link, links are created in a system-wide directory under YOTTA_PREFIX,
and the links in that directory are then picked up by subsequent yotta link <modulename>
commands.
On Linux this defaults to /usr/local. To change this directory (e.g. to make yotta link
things into your home directory), set the YOTTA_PREFIX environment variable.
link-target
yotta link-target (in a target directory)
yotta link-target <targetename>
yotta link-target /path/to/a/target
To link a target you need to perform two steps. First, in the directory of the target:
yotta link-target
This will create a symlink from the global targets directory to the current target.
Then, in the module that you would like to use the linked version of the target, run:
yotta link-target <targetename>
When you run yotta build (provided you’ve set yotta target to <targetname>), the linked
target description will be used.
The variant of the command which takes a path to an existing module (e.g. yotta link
../path/to/a/module) performs both steps in sequence, for convenience.
See also yotta link.
list
Synonyms: yotta ls
yotta list [--all]
yotta list [--json]
List the installed dependencies of the current module, including information on the
installed versions. Unless --all is specified, dependencies are only listed under the
modules that first use them, with --all dependencies that are used my multiple modules are
listed multiple times (but all modules will use the same installed instance of the
dependency).
The --json option will cause the list to be output in JSON format, for example:
{
"modules": [
{
"name": "toplevel-module-name",
"version": "1.0.0",
"path": "/some/path/on/disk/toplevel-module-name",
"specifications": [
{
"version": "~0.11.0",
"name": "some-dependency-name"
}
]
},
{
"name": "some-dependency-name",
"version": "0.11.7",
"path": "/some/path/on/disk/yotta_modules/some-dependency-name",
"linkedTo": "/some/path/on/disk/some-dependency-name",
"specifications": [
{
"version": "ARMmbed/some-test-dependency#^1.2.3",
"name": "some-test-dependency",
"testOnly": true
}
]
},
{
"name": "some-test-dependency",
"version": "1.5.6",
"path": "/some/path/on/disk/yotta_modules/some-test-dependency",
"errors": [
"a description of some error with this module"
]
}
}
uninstall
Synonyms: yotta unlink, yotta rm, yotta un
yotta uninstall <module>
Remove the specified dependency of the current module (or destroy the symlink if it was
linked).
owners
Synonyms: yotta owner
yotta owners list [<modulename>]
yotta owner add <email> [<modulename>]
yotta owner remove <email> [<modulename>]
List, add, or remove owners from the specified module or target. Owners are people with
permission to publish new versions of a module, and to add/remove other owners.
If the current directory is a module or target, then the module name is optional, and
defaults to the current module.
licenses
yotta licenses [--all]
List the licenses of all of the modules that the current module depends on. If --all is
specified, then each unique license is listed for each module it occurs in, instead of
just once.
NOTE: while yotta can list the licenses that modules have declared in their module.json
files, it can make no warranties about whether modules contain code under other licenses
that have not been declared.
config
yotta config
Display the merged config data for the current target (and application, if the current
module defines an executable application).
The config data is produced by merging the json config data defined by the application,
the current target, and any targets the current target inherits from recursively. Values
defined by the application will override those defined at the same path by targets, and
values defined in targets will override values defined by targets they inherit from.
The config data displayed is identical to the data that will be available to modules when
they are built.
See the yotta config system reference for more details.
outdated
yotta outdated
List modules for which newer versions are available from the yotta registry.
shrinkwrap
yotta shrinkwrap
Create a yotta-shrinkwrap.json file in the current module, which specifies the exact
versions of dependencies and target descriptions currently being used.
When a module with a yotta-shrinkwrap.json file is installed, the versions specified in
the shrinkwrap will be downloaded from the public yotta registry, instead of the latest
versions that satisfy the specifications from module.json files. When a shrinkwrap file
is present, dependencies will always be downloaded from the registry, not from git/other
URLs.
In practise this allows an application or module to specify a known-good set of
dependencies that it should be used with.
Note that generally publishing modules with a yotta-shrinkwrap.json file to the yotta
registry should be avoided. The exact versions specified in the shrink-wrap could easily
cause version conflicts with other modules which depend on the same modules.
The format of the yotta-shrinkwrap.json file is:
{
"modules": [
{
"version": "1.0.0",
"name": "first-module-name"
},
{
"version": "0.11.7",
"name": "a-dependency-name"
},
...
],
"targets": [
{
"version": "1.2.3",
"name": "some-target-name"
},
...
]
}
FILES
yotta targets:
target.json
.yotta_ignore
.yotta.json
yotta modules:
config.json
module.json
.yotta_ignore
.yotta.json
ENVIRONMENT VARIABLES
yotta behaviour can be customised using the following environment variables:
YOTTA_PREFIX
YOTTA_GITHUB_AUTHTOKEN
REPORTING BUGS
Upstream bug tracker: https://github.com/ARMmbed/yotta/issues
COPYRIGHT
Copyright (c) 2014-15 ARM Limited
AUTHOR
This manual page is based on the yotta command reference. It was created by Nick Morrott
<knowledgejunkie@gmail.com> for the Debian GNU/Linux system, but may be used by others
SEE ALSO
mbed_test_wrapper(1), mbedhtrun(1), mbedls(1), valinor(1), progen(1), progendef(1)