Skip to content

Portable projects & Named Roots in CI

A .und records where its source files live. If those absolute paths differ between the machine that created the project and the CI agent (or another developer), the project won't resolve its files. Two mechanisms make a project portable:

  • Relative paths — record file paths relative to the project, for source that always sits at a fixed layout beneath it.
  • Named Roots — map a symbolic name (e.g. SRC) to a directory that can differ per machine, so files beneath that directory stay resolvable wherever the tree is checked out.

This matters for CI because the build agent almost never checks the source out to the same absolute path as your workstation.

What a Named Root is

A Named Root is a mapping of a name → a directory path. A file can use a Named Root if it resides beneath that directory. Each machine (or CI agent) can point the same root name at its own location.

Identifier rules (enforced by Understand):

  • ALL CAPS
  • two or more characters
  • begins with an alphabetic character
  • contains only alphabetic, numeric, $, or _ characters

A Named Root cannot be nested beneath another Named Root. Example: SRC=/work/src is valid for files inside /work/src/foobar.

From the command line

# Add a Named Root
und add -root SRC=/work/src myProject.und

# List roots, and find files that still need attention
und list roots myProject.und
und list -unmapped -unportable roots myProject.und
  • und list -unmapped roots — files whose Named Root is undefined on this machine.
  • und list -unportable roots — files not portable (not mapped to a root and not relative).
  • Full syntax: und roots and und list.
  • Named Roots can also be created and edited in the GUI: Project → Configure Project → Files → Portability, then Edit Named Roots….

Record new files as relative or absolute

When und add/und settings bring files in, the global -commandaddmode Absolute|Relative option controls whether their paths are stored absolute or relative — use Relative for portable projects.

Enforce portability

To stop non-portable (unmapped, absolute) files from creeping in, turn on the enforce-portability setting:

und settings -enforceportability on myProject.und

Sharing analysis data is different

und create -local stores the parsed analysis data in the project's local folder so it can be shared between machines — but it requires identical source, library, system, and compiler file paths on every machine. That is the opposite trade-off from Named Roots:

Goal Use Requirement
Resolve source when paths differ per machine/agent Named Roots (or relative paths) Each machine maps the root to its own path
Reuse the parsed analysis data without re-analyzing und create -local Identical absolute paths everywhere

For a shared CI project you generally want Named Roots for portability, and you re-run und analyze on the agent rather than depending on -local.

In a pipeline

  1. Create the project with relative recording (-commandaddmode Relative) and/or add Named Roots.
  2. Commit the .und (or a script that rebuilds it) to version control.
  3. On the agent, set each Named Root to the checkout path (GUI/und add -root), then und analyze -changed and run the rest of your pipeline.