Skip to content

Forest Commands

Jump to bottom
Marco Ruzzon edited this page Feb 15, 2024 · 4 revisions

Command line interface

Forest's CLI is divided into four main verbs, i.e. init, add-recipes, grow and cut.

  • init
  • add-recipes
  • grow
  • cut

forest init

forest init iInitializes the current folder as a forest workspace, i.e. it creates

  • a src folder that will contain source code
  • a recipes folder that will contain forest's recipe files
  • a build folder to carry out compilation and store build artifacts
  • an install folder
  • a setup.bash file which makes installed items visible to the system
  • a .forest file which marks the current folder as the root of the workspace, forset commands must be called in the forest root folder

forest add-recipes

Adds recipes from a remote.

usage: forest add-recipes [-h] [--tag TAG] [--verbose] url

positional arguments:
 url                   url of the remote (e.g. git@github.com:<username>/<reponame>.git 
                       or https://github.com/<username>/<reponame>.git)

optional arguments:
 -h, --help            show this help message and exit
 --tag TAG, -t TAG
 --verbose, -v         print additional information

forest grow

usage: forest grow [-h] [--jobs JOBS] [--mode MODE [MODE ...]] [--config CONFIG [CONFIG ...]]
                   [--default-build-type {None,RelWithDebInfo,Release,Debug}] [--force-reconfigure] [--list-eval-locals]
                   [--clone-protocol {ssh,https}] [--clone-depth CLONE_DEPTH] [--cmake-args CMAKE_ARGS [CMAKE_ARGS ...]]
                   [--no-deps] [--clean] [--pwd PWD] [--verbose]
                   [RECIPE]

positional arguments:
  RECIPE                name of recipe with fetch and build information

options:
  -h, --help            show this help message and exit
  --jobs JOBS, -j JOBS  parallel jobs for building
  --mode MODE [MODE ...], -m MODE [MODE ...]
                        specify modes that are used to set conditional compilation flags (e.g., cmake args)
  --config CONFIG [CONFIG ...], -c CONFIG [CONFIG ...]
                        specify configuration variables that can be used inside recipes
  --default-build-type {None,RelWithDebInfo,Release,Debug}, -t {None,RelWithDebInfo,Release,Debug}
                        build type for cmake, it is overridden by recipe
  --force-reconfigure   force calling cmake before building with args from the recipe
  --list-eval-locals    print available attributes when using conditional build args
  --clone-protocol {ssh,https}
                        override clone protocol
  --clone-depth CLONE_DEPTH
                        set maximum history depth to save bandwidth
  --cmake-args CMAKE_ARGS [CMAKE_ARGS ...]
                        specify additional cmake args to be appended to each recipe (leading -D must be omitted)
  --no-deps, -n         skip dependency fetch and build step
  --clean               remove pkg build folder before grow
  --pwd PWD, -p PWD     user password to be used when sudo permission is required (if empty, user is prompted for password); note:
                        to be used with care, as exposing your password might be harmful!
  --verbose, -v         print additional information

Fetch policy

If a source package already exists in the source directory it is not cloned again by forest grow command. The rationale being not to overwrite modifications to sources after they were cloned the first time.

-m (--mode)

Inside recipes there might be conditional sections for fetching, building and specifying dependencies. Ususally the corresponding section key ends in _if (see Create and manage your own recipes). The -m allows to enable one or more of those section by specifying the corresponding mode.

For example:

example.yaml

clone:
  type: git
  server: <server_domain>   # e.g github.com, gitlab.com
  repository: <username>/<reponame>.git
  tag_if:   # optional
    stable: v1.0
    devel: v1.3

forest grow example -m stable will clone tag v1.0 while forest grow example -m devel will clone tag v1.3

--config flag (advanced)

Config parameter can be passed to forest grow command using the flag --config with the syntax name:=value. This way value will be available in the recipe and can be accessed using curly brakets {name}.

--clean flag (adavanced)

Be careful when using multiple forest workspaces or when installing the same package in different parts of the file system (binaries and sources). Once the CmakeCache.txt is created in the build folder, its cached values are not changed by subsequents run of cmake. It might be the case that the build folder of a specific package has to be deleted for clean build and install. Use forest grow <recipe_name> --clean to remove <recipe_name> build folder (not its dependencies) before forest builds it again.

From cmake find_package()

Config mode search attempts to locate a configuration file provided by the package to be found. A cache entry called _DIR is created to hold the directory containing the file.

From CMake Cache:

Once a variable is in the cache, its “cache” value cannot normally be modified from a CMakeLists file. The reasoning behind this is that once CMake has put the variable into the cache with its initial value, the user may then modify that value from the GUI. If the next invocation of CMake overwrote their change back to the set value, the user would never be able to make a change that CMake wouldn’t overwrite. A set(FOO ON CACHE BOOL "doc") command will typically only do something when the cache doesn’t have the variable in it. Once the variable is in the cache, that command will have no effect.

forest cut

Removes all files installed so far by a recipe (not its dependencies).

usage: forest cut [-h] [--verbose] [RECIPE]

positional arguments:
  RECIPE         name of recipe to cut

options:
  -h, --help     show this help message and exit
  --verbose, -v  print additional information

Forest stores information on all the files being installed by the forest grow command inside the install/.install_cache directory.

Clone this wiki locally