Isolated vs Merged Workspaces

Assuming you know what a workspace is, you know that by default colcon builds an isolated workspace. It can also build a merged workspace. These terms describe the layout of the install space, which is the directory software gets installed into.

This page describes the differences between the two.

Isolated Workspace

Colcon by default builds an isolated workspace.

Build the workspace from What is a Workspace? without any extra arguments.

colcon build

Now let’s look in the install folder.

install
├── COLCON_IGNORE
├── foo
│    ├── lib/...
│    └── share/...
├── local_setup.[bash|bat|ps1|sh|zsh|...]
├── _local_setup_util_[sh|ps1|...].py
└── setup.[bash|bat|ps1|sh|zsh|...]

Colcon created a directory install/foo and installed the package foo inside of it. Building an isolated workspace just means every software package is installed into its own directory.

An isolated workspace has some advantages. When colcon tests a package in an isolated workspace it will only give the tests access to the install artifacts of the dependencies it declares. This allows users to catch undeclared dependencies. An isolated workspace also allows removing a single package’s install artifacts by deleting its directory.

Merged Workspace

Delete the install directory and build the workspace again with the --merge-install option.

colcon build --merge-install

Let’s look in the install folder again.

install
    ├── COLCON_IGNORE
    ├── lib/..
    ├── share/..
    ├── local_setup.[bash|bat|ps1|sh|zsh|...]
    ├── _local_setup_util_[sh|ps1|...].py
    └── setup.[bash|bat|ps1|sh|zsh|...]

Notice how there’s no longer a foo folder. The lib and share directories are now directly in install.

Building a merged workspace just means every software package is installed into the same directory.

A merged workspace is advantageous on platforms where environment variables length is more tightly constrained, such as Windows 10. Environment variables set by the shell scripts, such as PYTHONPATH, will be shorter because there only needs to be one entry for all of the installed packages.