
                                   Overview


                                 Norman Feske
                                     and
                              Johannes Schlatow


Goa is a tool for streamlining the development of application software for the
Genode OS Framework. The work flow is project-centered. A project is a
directory that may contain source code, data, instructions how to download
source codes from a 3rd party, descriptions of system scenarios, or
combinations thereof. Goa is independent of Genode's regular build system.
It combines Genode's package management (depot) with commodity build systems
such a CMake. In addition to building and test-driving application software
directly on a Linux-based development system, Goa is able to aid the process
of exporting and packaging the software in the format expected by Genode
systems like Sculpt OS.


PROJECT
#######

A project is named after its directory.

It can have the following ingredients:

:import: A file that describes how 3rd-party software is downloaded and
  patched for the use with Genode. It follows the lines of Genode's
  time-tested _ports_ tool described at
  [https://genode.org/documentation/developer-resources/porting].
  Note, import may populate _src/_ and _raw/_. It will therefore overwrite
  any existing content in these directories.

:src/: A directory containing source code and build instructions. Goa
  automatically detects the kind of build system used. In particular,
  if the _src/_ directory contains a _CMakeLists.txt_ file, CMake is used.
  If a plain Makefile is encountered, Goa assumes the use of GNU Make.

:used_apis: A file containing a list of APIs used by the project.

:raw/: A directory containing raw data such as images or configurations.

:artifacts: A file that describes the build artifacts to be taken from
  the build directory after a successful build.

:api: A file that describes the header files that comprise the public
  interface of a library. It is only needed when building libraries.

:pkg/: A directory containing descriptions of runtime scenarios for
  test-driving the project.

:var/: A directory that contains files generated during the operation
  of Goa, e.g., the build directory.

:version: A file containing the current version string of the project.

:LICENSE: A file denoting the project's licensing terms, which is
  supplemented whenever a source-archive is exported from the project
  via the *export* or *publish* commands.

:index: A file that specifies a depot index. If an _index_ file is present,
  the *export* command will augment the archive names mentioned by the _index_
  file with the current depot user and known archive versions, and export the
  result as a depot index for the current Sculpt version.

:cmake_args: A file containing a list of project-specific arguments
  passed to CMake.

:make_args: A file containing a list of project-specific arguments
  passed to Make when using a plain Makefile project or an Autoconf
  project.

:meson_args: A file containing a list of project-specific arguments
  passed to Meson.

:configure_args: A file containing a list of project-specific arguments
  passed to the configure script of an Autoconf project.
!

Any given project may feature a subset of those files or directories.
For example, a plain port of a 3rd-party software package may contain
only _import_, _used_apis_, _artifacts_, _version_ and _LICENSE_ files.
As another extreme, a project may only feature a _pkg/_ directory with
scenarios that plug existing Genode components together.
Be aware, that a project must not contain a _src/_ or _raw/_ directory
along with an _import_ file and vice versa.


USAGE
#####

The Goa tool provides several commands to be performed on an particular project
directory. The simplest way is to change into the project directory and executing
the intended Goa command like, e.g., *goa run*.
!

Alternatively, when supplied with the *-r* switch, the tool recursively scans
for project directories and applies the supplied command to each project.
!

Moreover, Goa supports project hierarchies. Goa searches for related project
directories whenever the current project requires a depot archive that
could not be downloaded. By default, Goa uses the working directory as a
starting point for the search. This can be changed by defining the _search_dir_
variable; see *goa help config* for further details.

Overview
========

Typical goals when using the Goa tool are to test run an application project
or to package the same for a Genode system like Sculpt. Multiple actions need
to be taken along the way such as building the application software. Goa exposes
most intermediate actions as individual commands but also takes care of
automatically executing any prerequisite action. For instance, executing the
*publish* command implies the *import*, *depot_dir*, *build_dir*, *build* and
*export* commands.  The figure below illustrates the interdependencies of Goa's
commands.

!                         +---------+
!                         | import  |
!                         +----+----+
!                              |
!                              v
!                        +-----------+         +-----------+
!                        | build_dir |<--------+ depot_dir |
!                        +-----+-----+         +-----+-----+
!                              |                     |
!                              v                     v
!                        +-----------+        +--------------+
!                        |   build   |        |add_depot_user|
!                        +-+-------+-+        +--------------+
!                          |       |
!                          v       v
!                  +---------+   +---------+
!                  | run_dir |   | export  |
!                  +----+----+   +----+----+
!                       |             |
!                       v             v
!                  +---------+   +---------+
!                  |   run   |   | publish |
!                  +---------+   +---------+


Commands
========

:goa help [<topic>]:
  Show the documentation about the specified topic.
  Available topics are *overview* (this document), *config*, *artifacts*,
  *add-depot-user*, *api*, *build-systems*, *import*, *index*, *runtime*, *targets*.

:goa update-goa [<version>]:
  Update the Goa tool to the latest minor version if called without
  argument, or switch to the major version specified as argument.

:goa versions:
  Print available versions of the Goa tool.

:goa --version:
  Print current major version of the Goa tool.

:goa archive-versions [--archive <archive-name> [--archive ...]]:
  Print information about known depot-archive versions. By default, Goa
  acquires version information from the version definitions in the _goarc_
  files; see *goa help config* for more details. If no version definition is
  present for a particular depot archive, Goa tries to locate the
  corresponding project directory and evaluates the contained _version_ file.
  If this fails as well, Goa looks for version information published in the
  corresponding depot user's index. Note that Goa only downloads/updates a depot
  index if the '--update-index' option is present.
  If any <archive-name> is supplied, Goa only prints version information for
  the requested archives.

:goa info <user>/[pkg|src]/<name>[/<version>]:
  Show documentation about the specified pkg or src archive.

:goa bump-version [--if-needed [--pkg <pkg-name>] [--depot-user <user>]] [<version>]:
  Update version file of a Goa project. If <version> is not provided, the
  current date is taken. If the project version already matches the desired
  date, "-a" is added as a suffix and alphabetically incremented for every
  version bump. When provided with the --if-needed option, the version update
  is omitted if the exported/published version is already up-to-date.
  If <pkg-name> is supplied, only the scenario at pkg/<pkg-name> is compared
  against the corresponding exported/published archive.

:goa exported [--pkg <pkg-name>] [--depot-user <user>]:
  Compare project status with the archives exported for <user> and
  the currently set archive versions. If <pkg-name> is supplied, only the
  scenario at pkg/<pkg-name> is compared against the corresponding
  exported archive.

:goa published [--pkg <pkg-name>] [--depot-user <user>]:
  Implicies the *exported* command and additionally checks for the presence
  of the project's archives in the public_dir.

:goa import:
  Download and patch 3rd-party source code according to the rules given by
  an _import_ file.

:goa diff:
  Show local modifications of the imported 3rd-party software.

:goa install-toolchain [--keep-mounted]:
  Downloads and installs the Genode toolchain as a squashfs archive into
  the directory specified by the install_dir configuration variable
  (default: var/install/) if no system-wide installation was found. This
  command is executed as a prerequisite of the 'build-dir' command. During
  Goa's execution, the squashfs archive will be temporarily mounted using FUSE.
  When provided with the --keep-mounted option, the mount is kept persistent
  after Goa exited.

:goa depot-dir:
  Create a depot directory and install default depot users.

:goa build-dir:
  Create a build directory.

  This command implies the *depot-dir* command.

  If an _import_ file exists, this command automatically invokes the *import*
  command.

:goa build:
  Invoke the build system and extract the resulting build artifacts
  according to an _artifacts_ file. See 'goa help artifacts' for more
  information about the syntax of an _artifacts_ file.

  This command implies the *build-dir* command.

  Note that the building of libraries is supported only via cmake.

:goa extract-abi-symbols:
  Extract the abi symbols for a library project. This command is for the
  use of library maintainers only.
  The output is a file 'symbols/<library-name>'. For each library in the
  list of artifacts (recognized by the ending '.lib.so').
  You should review the files and add them to the repository.
  They are required by users of the library during the *build* step.

:goa run-dir [--pkg <pkg-name>]:
  Prepare the run directory for executing the system scenario defined at
  pkg/<pkg-name>. If no argument is supplied, <pkg-name> is assumed to
  correspond to the name of the project directory.

  This command implies the *build* command.

:goa run [--pkg <pkg-name>]:
  Execute a system scenario as prepared by the *run-dir* command.

  This command implies the *run-dir* command. The log of the scenario is stored
  in the project's run directory.

:goa backtrace [--pkg <pkg-name>] [--binary-name <name>]:
  Execute a system scenario with the *run* command.

  After the user cancelled the scenario, the log saved output is passed to the
  backtrace utility. The name of the top-level binary can be provided via the
  *--binary-name* argument.

:goa export [--depot-user <name>] [--pkg <pkg-name>]:
  Export entire project to a Genode depot. If <pkg-name> is supplied,
  only the scenario defined at pkg/<pkg-name> is exported.

  When Goa encounters dependencies to depot archives provided by
  projects located in subdirectories of the current working directory, it
  may run the export command recursively.

  This command implies the *build* command.

:goa publish [--depot-user <name>] [--pkg <pkg-name>]:
  Archive and sign depot archives generated via the *export* command.

  This command implies the *export* command.

:goa add-depot-user <name> --depot-url <url> --pubkey-file <file>:
  Make a new depot user known at a Genode depot as software source
  by specifying a URL and the public key as an ASCII-armored file.

  This command implies the *depot-dir* command.

:goa add-depot-user <name> --depot-url <url> --gpg-user-id <id>:
  Make a new depot user known at a Genode depot as software source
  by specifying a URL and the public key as GPG key ID, i.e., the
  email address. This command works only if the GPG keyring already
  contains the specified user ID.

  This command implies the *depot-dir* command.

Optional Arguments and Configuration Overrides
==============================================

:--verbose:
  Print diagnostic information about the operation of Goa.

:-C <dir>:
  Change into project directory <dir> before executing the command. The
  working directory before the change determines the scope in which Goa
  may locate dependent projects. This can be changed by setting the
  _search_dir_ variable; see *goa help config* for further details.

:-r:
  Recursively scan for project directories in the current working directory
  and execute the command for each project.

:--keep-going:
  Do not error out during recursive execution but keep going and print
  a list of failed project directories at the end.

Goa is further configured using configuration files called _goarc_. For most
configuration variables, there is also a command-line argument that overrides
the corresponding variable. Please refer to *goa help config* for further
details on these configuration-override arguments.

SEE ALSO
########

add-depot-user, api, artifacts, build-systems, config, import, index, runtime, targets
