Out-of-Tree Builds

By default, GPR tools write build artifacts (object files, libraries, executables) to the directories declared in the project file (Object_Dir, Library_Dir, Exec_Dir). An out-of-tree build places all artifacts under a single external directory without modifying the project files, using --relocate-build-tree.

When --relocate-build-tree=dir is given, each artifact directory is mirrored under dir. For a project file at /src/workspace/app/app.gpr with Object_Dir = "obj", the relocated object directory becomes dir/src/workspace/app/obj.

This is useful to keep build artifacts separate from source files: to maintain a clean version-controlled source tree, to build a read-only source tree (third-party code, mounted file systems), or to run multiple independent builds of the same sources in parallel without interference.

Note

--relocate-build-tree has no effect on artifact directories declared with absolute paths in the project file. Only relative Object_Dir, Library_Dir, and Exec_Dir values are relocated.

When the project tree contains with clauses that reference projects outside the main project’s directory (for example with "../lib/lib.gpr"), their artifact directories would by default be relocated outside dir. Use --root-dir=root to declare the common ancestor of all project directories in the tree; the relocation then maps every artifact directory to a path strictly under dir.

Example: a tree rooted at /src/workspace with two projects:

/src/workspace/
├── app/
│   └── app.gpr      (with "../lib/lib.gpr")
└── lib/
    └── lib.gpr

Building out-of-tree:

$ gprbuild -P /src/workspace/app/app.gpr \
           --relocate-build-tree=/tmp/build \
           --root-dir=/src/workspace

Artifact directories are created under /tmp/build/app/ and /tmp/build/lib/, leaving the source tree untouched. Other GPR tools (gprclean, gprls, gprinstall) accept the same switches and operate on the relocated artifacts.

The --relocate-build-tree and --root-dir switches are documented in Common Command-Line Options.