Usage

This page should give you an overview of different tasks that can be performed using robot_folders. It is kind of an inverse documentation to the command documentation that comes with the command line interface.

What is an environment?

An “environment” inside robot_folders consists of a set of workspaces. At the moment the following types of workspaces ares supported:

1. catkin_ws (ROS Workspace): Modeled after the standard ROS (Robot Operating System) workspace, catkin_ws adheres to ROS tutorials and conventions, serving as a standardized environment for ROS-related development.

1. colcon_ws (ROS 2 Workspace): Modeled after the standard ROS 2 (Robot Operating System) workspace, colcon_ws adheres to ROS tutorials and conventions, serving as a standardized environment for ROS 2 related development.

1. misc_ws: The misc_ws adds the ability to add custom packages to your workspace. It simply adds its export paths to your environment. You’ll have to take care to make sure the targets are built and exported there, yourself. See Misc Workspace for details.

After installation, open up a new terminal to use robot_folders. The main command for using robot_folders is fzirob. To get an overview of all available commands type

fzirob --help

To utilize any command, adhere to the general syntax:

fzirob command 'argument'

Creating an Environment

To create a new environment called ENV_NAME, simply run

fzirob add_environment ENV_NAME

This will ask which types of workspaces should be generated for the new environment.

One of the questions will be which underlay you’d like to use. If you don’t know what underlays are and what to use them for, you can just leave the selection empty and press enter. If you want to know more, see Using underlay environments.

Depending on your specific setup further questions may be asked:

• When creating a catkin or colcon workspace with multiple installed ROS versions, you will be prompted for the ROS version being used for that workspace.

• If you use an automatic backup strategy for your machine you probably do not want to backup the build and install artifacts from your workspaces, but only the sources. For that purpose robot_folders allows building and installing outside of your checkout tree and creating symlinks at the respecitve places instead. Whenever the configured backup location exists on the system (By default that’s $HOME/no_backup, that can be changed in the Configuration.) you will be prompted whether you want to build inside the checkout tree or in the no-backup folder.

Upon completion, you will receive the confirmation: “Environment setup for ‘ENV_NAME` is complete.”

Sourcing an environment

To activate or source an environment, use the fzirob change_environment ENV_NAME command. This command sources the appropriate setup scripts of the environment depending on its contents.

You can use tab completion on the environments so typing fzirob change_environment and then pressing Tab should list all environments present.

Executing fzirob change_environment without any environment specified will source the most recently sourced environment.

Note

Using fzirob change_environment will reset your shell environment before sourcing a robot_folders environment. Specifically, the following variables will be reset to the state they have been at the point when robot_folders was sourced (the rob_folders_source.sh file, usually sourced in the ~/.bashrc file).

• CMAKE_PATH

• PATH

• LD_LIBRARY_PATH

• QML_IMPORT_PATH

• PYTHONPATH

• AMENT_PREFIX_PATH

• COLCON_PREFIX_PATH

• PS1

Adding custom source commands

In addition to the environment’s workspace setup files, each environment contains a setup_local.sh file that will get sourced during the change_environment call after the workspaces in an environment have been sourced.

Using underlay environments

robot_folders supports using underlay environments that will be sourced during sourcing the current environment. With this it is possible to keep parts of your setup in another workspace. Imaging for example, you have two packages: “Application” and “Library”. “Application” is depending on “Library”, but there are also other packages in other environments depending on “Library”. You can reuse your local “Library” installation by putting it into its own environment and use that as an underlay for your environment containing “Application” (and for all the other environments with packages depending on “Library”).

This way, you’ll only have to keep “Library” up to date in one place.

Another use case is if you want to test your “Application” against different versions of “Library”. You could keep compiled versions of “Library” in separate environments and select the correct one as an underlay for your application’s environment. You’ll only have to recompile your application while with keeping “Library” inside your application environment you would have to go the to library package, switch branches and rebuild the library and application package.

When creating new environment you will be prompted for the underlays to be used.

Underlays will be stored in a underlays.txt file inside your environment’s folder. You can either edit that file manually or use the fzirob manage_underlays command to change the environment’s underlays.

Note

The underlay file will not get deleted by fzirob clean. Although you will be asked for the ROS distribution to use (if more than one is installed), underlay configuration persists.

Note

You can stack underlays. That means you can create dependency chains e.g. env1 -> env2 -> env3

Note

Currently, initial build isn’t supported when using underlay workspaces. When specifying an environment config when creating a new environment the user will have to manually trigger the build process after initially creating the environment. Usually, a simple fzirob make should do the trick.

Warning

Currently there is no check for cyclic environment dependency. Please make sure you do not run into this problem.

Warning

The order in which environments are sourced is depending on the order in which they are written into the underlays.txt file. That order might be alterd by the fzirob manage_underlays command. If you depend on an order, you may instead consider stacking underlays depending on each other.

Compiling an environment

To build an environment please use the fzirob make command. It has to be invoked on an already sourced environment but can be called from anywhwere.

Without any further options this will build all the workspace present which it knows how to build. So, if there is a catkin workspace present, it will build that, if there’s a colcon workspace this will be built.

You can also manually specify which workspace to build by using fzirob make ros or fzirob make colcon. When using fzirob make you don’t have to worry about the particular build command at all.

When building a colcon workspace, you can pass arguments to colcon using the --colcon-args option. For example to selectivly build a package called foobar and install it using symlinks you can call fzirob make --colcon-args --packages-select foobar --symlink-install.

Default options for building environments such as the builder for catkin workspaces or cmake arguments for a colcon workspace can be set in the Configuration.

Cleaning an environment

Sometimes you want to completely rebuild your environment. fziron clean provides a command that will delete all build and installation artifacts from your environment’s workspaces. Before actual deletion it will show a list of all the folders to be deleted with a safety prompt so you don’t accidentally delete things.

Navigating inside an environment

You can use the fzirob cd command to navigate around in an environment. The following examples show a couple of possible locations you can navigate to. For the examples we have sourced the environment env_name and environments are stored inside ~/checkout:

fzirob cd        # Env root folder e.g. ~/checkout/env_name
fzirob cd ros    # Env catkin folder e.g. ~/checkout/env_name/catkin_ws
fzirob cd colcon # Env colcon folder e.g. ~/checkout/env_name/colcon_ws
fzirob cd misc   # Env misc_ws folder e.g. ~/checkout/env_name/misc_ws

Again, tab completion will present the possible options for the currently sourced environment.

Start / Demo scripts

For easy interaction with unknown environments robot_folders provides the fzirob run command. With that any executable file inside the environment’s demos folder can be executed. So, if you’ve got an unknown environment and just want to startup a predefined demo, simply source the environment, type fzirob run <tab> which should list all the possible demo scripts.

Sharing environments

Often you’d like to share an environment with colleagues working on the same project. While for colcon workspaces there exist external tools such as vcstool2, robot_folders provides extended functionality to that:

• Contents of multiple workspaces can be exported and imported at once (e.g. colcon workspace and misc workspace).

• Startup scripts are stored inside the exchange format for easy interaction.

To export an environment, use the fzirob scrape_environment command. It scrapes an environment configuration into a config file, facilitating sharing with others. You’ll have to provide the environment name and the target file as arguments e.g.

fzirob scrape_environment env_name /tmp/env_name.yaml

In case you’ve got multiple remotes configured for repos inside your environments, you will be queried which remote should be used for each repository.

When providing --use_commit_id true, the exact commit IDs get scraped instead of branch names. which is rather useful if you want to save a “working state” of your whole environment.

If you’ve got provided an environment configuration from somebody you can create a new environment with that using

fzirob add_environment --config-file /tmp/env_name.yaml other_env

which will create an environment called other_env with the configuration from the previously exported env_name environment.

If you already have an environment but you want to update it to match a config file e.g. because some repositories have been added to the environment or some branch names have been changed you can do this using the fzirob adapt_environment command.

If there are repositories in your local environment that are not in the config file you will be prompted whether you want to keep those repositories. If branches or remotes in the config file differ from those present locally, you will also be asked. You can override that to a default behavior using the --local_delete_policy and --local_override_policy options.

Deleting an environment

If you want to delete an environment alltogether, you can use fzirob delete_environment <env_name. This will delete the conmplete environment folder from your checkout directory.