
                                 Configuration


                                 Norman Feske


Goa can be configured using configuration files called _goarc_ or via
command-line arguments.


Configuration files
###################

Upon startup, Goa includes all files named _goarc_ found in the directory
hierarchy up to the project directory, starting with the root directory.
This way, different aspects of Goa can be configured at different scopes.
For example, settings that should be applied to any project of a given
user can be defined at the user's home directory at _~/goarc_, settings
shared by multiple Goa projects can be defined at the common parent directory
of those projects, and project-specific settings can live local to the
project directory.

Goa configuration files follow the syntax of Tcl. A configuration value
is defined as follows:

! set <variable-name> <value>

If <value> is a path name, the path can be specified relative to the location
of the _goarc_ file or relative to the user's home directory (_~/_).

By default, Goa prevents definition of path variables outside the current
working directory or project directory. A user may extend this policy by
adding a path to the list 'allowed_paths' as follows:

! lappend allowed_paths <path>

Note that this instruction is only effective within the privileged configuration
files at '~/goarc' and '/goarc'. It must also appear before setting any
path configuration variable.


Settings
########

Goa evaluates the following configuration variables.

:project_name:
  This variable overrides the default project name, which is the name of the
  project directory.

:arch:
  The CPU architecture used for building the software.
  Supported values are _x86_64_ and _arm_v8a_.
  It can be given via the optional *--arch* command-line argument.
  If not specified, Goa targets the CPU architecture of the host machine by
  default, probed via the *uname -m* command.

:cross_dev_prefix:
  The tool-chain prefix for the Genode cross compiler.
  The default value is "/usr/local/genode/tool/<toolchain_version>/bin/genode-x86-".

:rebuild:
  If set to 1 or if the command line argument *--rebuild* is specified,
  a complete rebuild of the software is enforced each time Goa invokes the
  build system. With the default value 0, Goa triggers partial builds.

:jobs:
  The amount of parallelism while building. If not defined, Goa determines
  a reasonable value that corresponds to the number of CPU cores according
  to the information of _/proc/cpuinfo_. This built-in heuristics can be
  overridden by assigning a number to the _jobs_ variable by specifying the
  number to the *--jobs <N>* command-line argument.

:ld_march:
  Architecture-specific linker arguments.
  The default value is "-melf_x86_64".

:olevel:
  Optimization level as passed to the compiler.
  The default value is "-O2".

:depot_dir: The location of the Genode depot. The default is _var/depot_
  within the project directory. If no such directory exists, Goa creates
  a new directory taking the content of _share/goa/default_depot/_ as
  starting point.

:public_dir: The location of the public directory used for downloading
  and publishing depot archives. The default is _var/public_ within the
  project directory.

:contrib_dir: The location where 3rd-party software imported via the *import*
  command should be installed. The default is _var/contrib_ within the
  project directory.

:contrib_cache_dir: The location where downloads of 3rd-party software archives
  are stored. The default is _var/contrib/cache_ within the project directory.

:build_dir: The build directory used by the build system. The default
  is _var/build/<arch>/_ within the project directory.

:abi_dir: The directory where Goa creates ABI stubs for any shared libraries
  used by the project. The default is _var/abi/<arch>/_ within the project
  directory.

:bin_dir: The directory containing the final build artifacts extracted from
  the build directory upon the completion of the build process. The
  default is _var/bin/<arch>/_ within the project directory.

:dbg_dir: The directory containing debug info files for the final build
  artifacts. The default is _var/dbg/<arch>/_ within the project directory.

:run_dir: The directory where Genode test scenarios are assembled when
  executing the *run* command. The default is _var/run/_ within the project
  directory.

:install_dir: The directory where additional build tools are downloaded and
  installed.

:common_var_dir:
  If defined, Goa places all generated files in the specified directory
  instead of creating a _var_ directory inside the project directory.
  Within the common var directory, the content of each project is created
  in a subdirectory named after the project.

  This option is useful to keep the source code of a project completely
  separate from any generated files.

:depot_overwrite:
  Whenever Goa encounters the situation where a *goa export* or *goa publish*
  command would overwrite existing depot content, it aborts the command.
  Usually, this is an indicator that the project version is due for an
  update. However, while iteratively testing a new version, it is often useful
  to overwrite existing depot content. This can be achieved by setting the
  value to 1 or by specifying the *--depot-overwrite* command-line argument.
  Note that _depot_overwrite_ will be implicitly set to 1 when _depot_user_ is
  set to "_".

:depot_retain:
  Whenever Goa encounters the situation where a *goa export* or *goa publish*
  command would overwrite existing depot content, it aborts the command.
  By setting the value to 1 or by specifying the *--depot-retain* command-line
  argument, Goa will not touch the existing depot content but continue the
  command.

:depot_user:
  Depot user name to use when exporting or publishing the project via the
  *export* or *publish* commands. In order to be able to publish software,
  the GPG keyring must contain a private key that matches the specified
  depot user's pubkey. Alternatively to setting the _depot_user_ variable,
  the name can be specified for the *export* or *publish* commands
  via the *--depot-user <name>* argument. The default _depot_user_ value is
  "_", which is treated as a wildcard user throughout Goa. More precisely,
  referenced archives with "_" as depot user will be replaced by the current
  _depot_user_ value. Vice versa, archive version specifications for depot
  user "_" will be used as a fallback for depot archives with the same type
  and name. Note that the *publish* command requires a depot user other than
  "_".

:run_as:
  The *goa run* command requires several archives from the official genodelabs
  depot. These archives are updated and published along with every Sculpt OS
  release. The archive versions stored in Goa are updated accordingly.
  By setting the *run_as* variable to your depot user name or by specifying
  the *--run-as <name>* argument, you may load the required archives from your
  own depot instead.

:license:
  When exporting a source archive to a depot, Goa supplements a license
  file to the source archive, which is expected to be located as a file
  named LICENSE in the project directory. If many Goa projects share the same
  license, it would be cumbersome to spill LICENSE files everywhere.
  In this case, a path to a license file can be supplied via the _license_
  configuration variable, or the *--license* command-line argument.

:debug:
  If set to 1, Goa may use debug build mode to produce binaries with debug
  information (details depend on the build system). Furthermore, Goa extracts
  debug info files from the produced binaries and adds corresponding
  .gnu_debuglink sections. The *goa run* command tries downloading required dbg
  archives and makes the contained debug info files available in the .debug
  subdirectory of run_dir. If set to 1, the *goa export* and *goa publish*
  commands are instructed to publish dbg archives along with the bin archives.
  Alternatively to defining the configuration variable, the debug build mode
  can be enabled via the *--debug* command-line argument.

:with_backtrace:
  If set to 1, Goa adds the flag '-fno-omit-frame-pointer' to the compiler
  options in order to enable the use of backtraces. Alternatively to defining
  the configuration variable, the option can be enabled via the
  *--with-backtrace* command-line argument.

:binary_name:
  Goa's backtrace command tries to identify the name of the binary from the log
  output. If the component's name is different than the name of its binary, you
  must set this configuration variable or use the *--binary-name* command-line
  argument.

:warn_strict:
  If set to 1, Goa passes Genode's default strict C++ warning flags to the
  build system. It is implicitly enabled whenever a project uses the Genode
  _base_ API. By explicitly defining the value, strict warnings can be
  disabled for a Genode-API-using project, or enabled for any non-Genode-API
  project. Alternatively to defining the configuration variable, the
  strict warnings can be enabled or disabled via the *--warn-strict* and
  *--no-warn-strict* command-line arguments.

:sculpt_version:
  Determines the Sculpt version for which a depot index is exported and
  published. The default value can either be overridden by setting this
  configuration variable in a custom _goarc_ file or via the
  *--sculpt-version* command-line argument.

:toolchain_version:
  Specifies the to-be-used version of the Genode toolchain.

:target:
  Specifies the run target used for *goa run*. The default value is "linux".
  The value can be overridden by setting this configuration variable or by
  providing the *--target* command-line argument. See *goa help targets* for
  more details.

:target_opt(<option>):
  The target_opt array stores target-specific configurations. Alternatively to
  setting this variable in a custom _goarc_ file, you may provide
  *--target-opt-<option>* command-line arguments. See *goa help targets* for
  more details.

:version(<user>/<type>/<name>):
  The version array is indexed with a depot-archive path and contains the
  version to be assumed for this archive.
  The <user> corresponds to a depot user (a software source).
  The <type> can be _src_, _raw_, _api_, or _pkg_.
  The <name> is the name of the archive.
  Goa comes with a data base of default versions, which can be found at
  share/goa/goarc.
  It is possible to instruct Goa to obtain version information directly
  from a Genode source tree by using the _versions_from_genode_dir_ variable.
  To display Goa's currently known version information, you may use the
  *goa archive-versions* command.
  Version information can also be provided via *--version-<user>/<type>/<name>*
  command-line arguments.
  Note that, for the currently operated-on project, the content of the project's
  _version_ file takes precedence over the version array.

:versions_from_genode_dir:
  If set to the root of a Genode source tree, Goa determines the package
  versions from the depot recipes stored in the Genode source tree.
  Since the corresponding archives are likely not available in the official
  genodelabs depot, you probably want to guide Goa to your personal depot by
  setting the _run_as_ variable.

:update_index:
  If set to 1, Goa downloads depot index files in order to acquire version
  information of depot archives. Alternatively to setting the _update_index_
  variable, the command-line argument *--update-index* can be supplied.

:search_dir:
  By default, Goa uses the original working directory for looking up versions
  of other Goa projects. This can be changed by setting the _search_dir_
  variable in a custom _goarc_ file or by using the *--search-dir <dir>*
  command-line argument.

:cc_cxx_opt_std:
  Overwrite C++ standard. The default is "-std=gnu++20".

:disable_sandbox:
  By default, Goa uses bubblewrap for sandboxing build commands. This can be
  disabled by setting this _disable_sandbox_ config variable to 1. Note that
  this is only effective in the privileged goarc files located at '~/goarc' or
  '/goarc'. Alternatively, you may set the environment variable DISABLE_SANDBOX.

:hid:
  By default, Goa generates the runtime config in XML syntax. By setting
  this config variable to 1, Goa will use HID syntax. Alternatively, HID
  generation can be disabled or enabled via the command-line switches
  *--no-hid* and *--hid*.


SECURITY
########

Since Goa configuration files are interpreted by Tcl, executing Goa projects
from untrusted sources could harm the integrity of your system. Goa, however,
uses a safe interpreter to load configuration files in order to hide sensitive
commands such as 'exec', 'open', 'cd', 'glob' and 'socket'. Moreover, Goa
restricts the 'set' command to only affect Goa's configuration variables. As
mentioned above, path variables are checked against a list of allowed paths
to make sure that untrusted configuration files cannot trick Goa into undesired
file operations.

Moreover, Goa checks the 'cross_dev_prefix' against a list of allowed tool paths.
By default, Goa allows tools to reside in any subdirectory of /usr/. Similar to
extending the 'allowed_paths' variable, a user may extend this policy by adding
a path to the list 'allowed_tools' list.

SEE ALSO
########

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

