Create and manage builds. It also keeps note of
all builds in the build database BUILDS.DB.

The script takes one or mode commands and has a number of options. Single
character options always start with a single dash “-“, long options start with
a double dash “–”, commands are simple words on the command line.

Information on all known modules and module versions is kept in
the dependency database. This file also contains a source
specification for each module that may be a directory, tar file or url or a
repository specification.

When the support module is to be compiled “sumo build” creates a RELEASE file
from the known dependencies of the module. The RELEASE file contains variable
definitions, one for each dependency whose name is the module name and whose
value is the path of the compiled module. If a module needs a variable name
that is different from the module name, an alias must be defined. For each
dependency that is part of the alias map, the ALIASNAME of the alias map is
taken. The aliasdata map has this form:

This is a list of modules this module depends on. Note that we
do not store the versions of the modules here. Information on
which version is compatible with another version can be found
in the build database BUILDS.DB. This is the form of the
dependencies list:

This optional field is used to specify alternative make recipes for the
makefile that is generated to build the module. For each of the make targets
“all”, “clean”, “config” and “distclean” a list of lines can be defined that is
put in the generated makefile. In the make-recipes map, each of the map keys
“all”, “clean”, “config” and “distclean” is optional. For convenience, the
string “$DIR” is replaced with the special make variable $(@D) in every
line. This is the directory of the checked out module (see also documentation
of the “make” command). Note that you do not have to prepend each line with a
<TAB> character, sumo already does this.

Note that for the “all” target your last recipe line is usually
$(MAKE)-C$DIR.

source data describes where the sources of a module can be
found. It is a map with a single key. The key has one of the following values:

path: This specifies a directory with the sources. The sources are copied
from that location.

tar: This specifies a tar file with the sources. The tar file is fetched
and extracted.

darcs: This specifies a darcs repository.

hg: This specifies a mercurial repository.

git: This specifies a git repository.

svn This specifies a subversion repository.

cvs This specifies a cvs repository.

In the following description of source data, FILEURL means a string that is
either the path of a file on the local filesystem or an url of a file with
this form:

http://

ftp://

ssh://

file://

In the following description, COMMANDS means a list of strings that are
command lines which are executed in the given order inside the module directory
after the module was checked out. Possible patches (see below) are applied
after the commands. You may find the feature useful for git sub repositories
which must be initialized by an extra git command.

In the following description of source data, PATCHFILES means a list of
strings that are names of patchfiles. These are applied to the source with
the patch utility after the source is fetched. The strings specifying
patchfiles are FILEURLs.

The key “rev” is optional, if it is given it specifies the subversion revision
that is used to fetch the source. Note that “rev” and “tag” MUST NOT be given
both.

The key “tag” is also optional, if it is given it specifies the subversion tag
that is used to fetch the source. Note that “rev” and “tag” MUST NOT be given
both. If “tag” is given the string “tags” and the tag name are appended to the
repository url.

The key “url” is a subversion repository specification (see manual of
subversion for further information).

The key “tag” is also optional, if it is given it specifies the cvs tag
that is used to fetch the source.

The key “url” is the cvs repository specification. In the following “<cvsroot>”
means the path of your cvs repository and <module> is the directory within
“<cvsroot>” where the module is kept. “<user>” and “<host>” are the username
and hostname when you contact your cvs repository via ssh. There are three
formats you can use here:

When “sumo-scan all” is used to scan an existing
support directory it also gathers information on what version of a module
depends on what version of another module. In order to keep this information
although the dependency database doesn’t contain versions of dependencies, this
information is held in a separate file, the scan database or SCANDB.

For each dependency of a module this structure contains the version of the
dependency and a state. The state can be “stable” or “testing” or “scanned” but
is always “scanned” if the file was generated with sumo db.

moduledata is a map that maps modulenames to versionnames.
This specifies all the modules that are part of the build.
Since a build may reuse modules from another build not
all modules from this map may actually exist as separate directories of the
build. The moduledata has this form:

linkdata is a map that maps modulenames to buildtags. This map contains
all modules of the build that are reused from other
builds. If a build has no linkdata, the key “linked” in
builddata is omitted. The linkdata has this form:

Create a new configuration file from the options read from configuration files
and options from the command line. If FILENAME is ‘-‘ dump to the console.
OPTIONNAMES is an optional list of long option names. If OPTIONNAMES are
specified, only options from this list are saved in the configuration file.

This command is used to create a new sumo directory with a new build directory
and a new dependency database.

It creates a new configuration for sumo. DIRECTORY must not yet exist and is created by this command. This command takes all settings and command line options
but sets dbdir to DIRECTORY/database. It also sets
builddir to DIRECTORY/build. TEMPLATE determines how the dependency databasse file is created. Currently 2 values are known:

empty

Create an empty dependency database.

github

Create a sample dependency database file with some entries for EPICS base,
ASYN and the sequencer. In this sample all module repositories are fetched
from the internet, mostly github.

If there is a file “sumo.config” in the current working directory it is copied
to “sumo.config.bak”. A new file “sumo.config” is then created in the current
working directory.

This command is used to create a new sumo directory with an independent build
directory and an independent copy of the dependency database.

It creates a new configuration for “standalone” builds. DIRECTORY is created if
it does not yet exist. This command takes all settings and command line options
but sets dbrepomode to “pull” and dbdir to DIRECTORY/database. It also sets
builddir to DIRECTORY/build. Option dbrepo must be set, this is used to create
a local copy of the dependency database in DIRECTORY/database. If there is a
file “sumo.config” in the current working directory it is copied to
“sumo.config.bak”. A new file “sumo.config” is then created in the current
working directory.

This command is used to create a new sumo directory with a new build directory
but using existing builds from your current build directory. It also creates an
independent copy of the dependency database.

DIRECTORY is created if it does not yet exist. This command takes all settings
and command line options but sets dbrepomode to “pull” and dbdir to
DIRECTORY/database. It also sets localbuilddir to DIRECTORY/build. Option
dbrepo must be set, this is used to create a local copy of the dependency
database in DIRECTORY/database. If there is a file “sumo.config” in the current
working directory it is copied to “sumo.config.bak”. A new file “sumo.config”
is then created in the current working directory.

Convert a scanfile that was created by by
“sumo-scan all” to a new dependency database. If
SCANFILE is a dash “-“, the program expects the scanfile on stdin. Note that
options --dbdir and --scandb are mandatory here. With --dbdir you
specify the drectory where the new created
dependency database file is
stored, with --scandb you specify the name of the scan database file. The
scan database file contains information on what moduleversion can be used with
what dependency version.

Convert a dependency database
file OLDDB from old to new format. The old format had architecture data
(“arch”) for each moduleversion. In the new format this data is removed. Note
that this command IGNORES option --dbrepo" it directly operates on the
dependency database file in the directory given with option --dbdir.

Convert a scanfile that was created by applying
“sumo-scan all” to an application to a list of
aliases and modulespecs in JSON
format. If SCANFILE is a dash “-” the program expects the scanfile on stdin.
The result is printed to the console.

Convert a scanfile that was created by applying
“sumo-scan all” to the
dependency database
format for all the selected modules. If SCANFILE is a dash “-” the program
expects the scanfile on stdin. The result is printed to the console. This data
can be added to the dependency database using the command db edit.

Start the editor specified by option --editor or the environment variables
“VISUAL” or “EDITOR” to edit the dependency database file. This command first
aquires a file-lock on the file, that prevents other users from acessing the
file at the same time. When the editor program is terminated, sumo checks if
the file is still a valid JSON file. If not, you can
start the editor again or abort the program. If the file is valid
JSON, sumo commits the changes if option --dbrepo
was specified. If option --logmsg was given, this is used as commit log
message, otherwise an editor is started where you can enter a log message.
Finally the file lock is released. If you want to edit the dependency database
file you should always do it with this command.

Just load and save the
dependency database.
This ensures that the file is formatted in the standard sumo format. This is
useful when the file was edited and you want to ensure that key sort order and
indentation are restored. If you specified a repository with --dbrepo, the
command will commit the changes. If you want a log message different from “db
format” use option --logmsg

Set the weight factor for modules. A weight determines where a module is placed
in the generated RELEASE file. Modules there are sorted first by weight, then
by dependency. Parameter MODULES is a list of modulespecs. Use
modulename:{+-}versionname to select more versions of a module.

Note that this command does not use the --modules command line option.

This command defines an alternative filename for the RELEASE file of the
module. Usually the RELEASE file is generated as “configure/RELEASE”.
You can specify a different filename for the given module with this
command. This may be useful for support modules that have no regular
EPICS makefile system or for some special configurations of the EPICS base. If
you set the RELEASEFILENAME to an empty string or “configure/RELEASE”, the
special entry for the filename is removed for this module in the
dependency database.

This command replaces a version of a module with a new
version. MODULE here is just the name of the module since the version
follows as a separate argument. All the data of the module is copied.
If sourcespec is given, the command changes the source part according to this
parameter. A sourcespec has the form “path PATH”, “tar TARFILE”, “REPOTYPE URL”
or “REPOTYPE URL TAG”. REPOTYPE may be “darcs”, “hg” or “git”. Both, URL or
TAG may be “.”, in this case the original URL or TAG remains unchanged.

Copy all versions of the existing old module and add this with
the name of thew new module to the dependency database.
OLD-MODULE and NEW-MODULE here are just the module names since the versions may
follow as a separate argument. If there are no versions specified, the
command copies all existing versions. Note that this DOES NOT add the
new module as dependency to any other modules.

Define commands that are executed after a module is checked out. See
also “commands” in the chapter “The
dependency database”.

MODULE here is a modulespec of the form MODULE:VERSION that specifies a
single version of a module. LINES is a list of space separated strings. It is
recommended to enclose the line strings in single or double quotes.

Special variables and characters when you use double quotes:

\": (bash) A literal double quote character.

$(VAR): (make) Insert value of make or shell variable VAR.

$$: (make) A dollar character passed to the shell.

\\$$: (make, bash) A literal dollar character passed to the shell.

\\: (json, bash) At the end of the json string this means line continuation for bash.

Define special make recipes for a module. See also
“make-recipes” in the chapter “The
dependency database”.

MODULE here is a modulespec of the form MODULE:VERSION that specifies a
single version of a module. TARGET must be “all”, “clean”, “config” or
“distclean” and specifies the make target for which a recipe is defined. LINES
is a list of space separated strings. It is recommended to enclose the line
strings in single or double quotes. If LINES is not given, all special rules
for the TARGET are removed.

Special variables and characters when you use double quotes:

$DIR: (sumo) The directory of the MODULE.

\": (bash) A literal double quote character.

$(VAR): (make) Insert value of make or shell variable VAR.

$$: (make) A dollar character passed to the shell.

\\$$: (make, bash) A literal dollar character passed to the shell.

\\: (json, bash) At the end of the json string this means line continuation for bash.

This command is intended to help you create module specifications for
the “new” command.

Each MODULE here is a modulespec of the form MODULE or
MODULE:{+-}VERSION that specifies just a module name, a module and some
versions or a single version. You can specify an incomplete list of
modules.

The detail of the output is determined by option --detail which is an
integer between 0 and 3. 0, the default, gives the shortest, 3 gives the
longest report. The program then shows which modules you have to

In any case the command shows which modules are missing since they
depend on other modules of your specification and which ones are
missing an exact version.

If you converted an existing support directory to sumo you have a scan database
file which you can specify with option --scandb to this command.

This command creates a new build. Each module given in MODULES here is
a modulespec of the form MODULE:VERSION that specifies a single version
of a module. If the buildtag is not given as an option, the program
generates a buildtag in the form “AUTO-nnn”. A new build is
created according to the modulespecs. Your modulespecifications must be
complete and exact meaning that all dependencies are included and
all modules are specified with exactly a single version. Use
command “try” in order to create module specifications that can be used
with command “new”. This command calls “make” and, after successful
completion, sets the state of the build to “testing”. If you want to
skip this step, use option --no-make. In order to provide arbitrary options
to make use option --makeflags.

This command recreates a build by first calling “make clean” and
then “make all” with the build’s makefile. If you develop a support
module (see also “config standalone” and “config local”) you want to
recompile the build after changes in the sources. In order to provide
arbitrary options to make use option --makeflags.

This command is used to find matching builds for a given list of
modulespecs. Each module in MODULES here is a modulespec of the
form MODULE or MODULE:{+-}VERSION that specifies just a module name, a module
and some versions or a single version. The command prints a list of
buildtags of matching builds on the console. If option --brief
is given, the program just shows the buildtags.

This command creates a configure/RELEASE file for an application. Each module
given in MODULES here is a modulespec of the form MODULE:VERSION that
specifies a single version of a module. If option --buildtag is given, it
checks if this is compatible with the given modules. Otherwise it
looks for all builds that have the modules in the required
versions. If more than one matching build found it takes the
one with the alphabetically first buildtag. The RELEASE file created includes
only the modules that are specified. Output to another file or the
console can be specified with option ‘-o’.

This command is used to show or change the state of a build.
The buildtag must be given as an argument. If there is no new
state given, it just shows the current state of the
build. Otherwise the state of the build is changed to
the given value. If a build is set to state ‘disabled’, all
dependend builds are also set to this state. In this case, unless
option ‘-y’ or ‘–recursive’ are given, sumo asks for your confirmation.

The directories of the builds are removed and their entries in the
build database are deleted. If other builds depend on the
builds to be deleted, the command fails unless option ‘–recursive’ is
given. In this case all dependent builds are deleted, too. The
buildtags must be given as an argument.

Command completion means that you can press <TAB> on any incomplete sumo
command and you get a list of possibilities how to complete that command. By
pressing <TAB> several times you can try each possible completion.

Command completion works with bash or zsh (Z-Shell), you need to have one
of these installed. Your environment variable SHELL must be set to the binary
file of the shell, e.g. /usr/bin/bash or /usr/bin/zsh.

In any case the package bash-completion must be installed.

If you use the Z-Shell, the following commands must be executed at start up.
Add them for example to the file $HOME/.zshenv:

autoload-U+Xcompinit&&compinitautoload-U+Xbashcompinit&&bashcompinit

There are two ways to activate command completion, described in the following
chapters.

Sumo will create cache files in your home directory to speed up command
completion. These are the files “.dbcache.sumo” and “.buildcache.sumo”. If you
don’t want this set the environment variable “SUMOHELP” in a way that it
contains the string “nocache” like in:

exportSUMOHELP="nocache"

If there are other help options defined in SUMOHELP, you should seperate them
with commas “,”.

Load options from the given configuration file. You can specify more than
one of these. Unless –no-default-config is given, the program always
loads configuration files from several standard directories first before it
loads your configuration file. The contents of all configuration files are
merged.

If this option is not given and –no-default-config is not given, the
program tries to load the default configuration file sumo-scan.config from
several standard locations (see documentation on configuration files).

If an option with name OPTIONNAME is given here and it is a list option,
the list from the command line is appended to the list from the
configuration file. The default is that options from the command line
override option values from the configuration file.

Specify a an ‘#preload’ directive in the configuration file. This option
has only a meaning if a configuration file is created with the ‘makeconfig’
command. ‘#preload’ means that the following file(s) are loaded before the
rest of the configuration file.

Specify a an ‘#postload’ directive in the configuration file. This option
has only a meaning if a configuration file is created with the ‘makeconfig’
command. ‘#postload’ means that the following file(s) are loaded after the
rest of the configuration file.

Specify how sumo should use the dependency database repository. There are
three possible values: ‘get’, ‘pull’ and ‘push’. Mode ‘get’ is the default.
The meaning depends on the used version control system (VCS), if it is
distributed (git,mercurial,darcs) or centralized (subversion,cvs). There
are three possible operations on the dependency database:

Define a REPOSITORY for the db file. REPOSITORY must have the form
‘REPOTYPE URL’ or ‘type=REPOTYPE url=URL”. REPOTYPE may be ‘darcs’, ‘hg’ or
‘git’. Option –dbdir must specify a directory that will contain the
repository for the db file. Before reading the db file a ‘pull’ command
will be executed. When the file is changed, a ‘commit’ and a ‘push’ command
will be executed. If the repository doesn’t exist the program tries to
check out a working copy from the given URL. A default for this option can
be put in a configuration file.

Specify the stem of a buildtag. This option has only an effect on the
commands ‘new’ and ‘try’ if a buildtag is not specified. The program
generates a new tag in the form ‘stem-nnn’ where ‘nnn’ is the smallest
possible number that ensures that the buildtag is unique.

Specify a local support directory. Modules from the directory specifed
by –builddir are used but this directory is not modfied. All new builds
are created in the local build directory and only the build database file
there is modified.

Define an alias for the command ‘use’. An alias must have the form FROM:TO.
The path of module named ‘FROM’ is put in the generated RELEASE file as a
variable named ‘TO’. You can specify more than one of these by repeating
this option or by joining values in a single string separated by spaces. A
default for this option can be put in a configuration file.

Define a modulespec. If you specify modules with this option you
don’t have to put modulespecs after some of the commands. You can
specify more than one of these by repeating this option or by joining
values in a single string separated by spaces. A default for this option
can be put in a configuration file.

Specify a directory patchexpression. Such an expression consists of a tuple
of 2 python strings. The first is the match expression, the second one is
the replacement string. The regular expression is applied to every source
path generated. You can specify more than one patchexpression. A default
for this option can be put in a configuration file.

Specify a repository url patchexpression. Such an expression consists of a
tuple of 2 python strings. The first is the match expression, the second
one is the replacement string. The regular expression is applied to every
source url generated. You can specify more than one patchexpression. A
default for this option can be put in a configuration file.

Specify extra option strings for make You can specify more than one of
these by repeating this option or by joining values in a single string
separated by spaces. A default for this option can be put in a
configuration file.

Do not use multiprocessing in the program. This is mainly here to help
debugging the program. Currently multiprocessing is used when the sources
for modules of a build are created by checking out from version control
systems.