The Direct Answer
Use relative paths anchored to the project directory for anything inside your repository, and use environment variables (in $(VAR) form) only for machine-level locations such as third-party library roots. Never commit absolute paths like C:\Users\alice\libs into a .dproj file — that is precisely what produces 'file not found' errors on secondary workstations.
How RAD Studio Resolves These Paths
RAD Studio's build is MSBuild-based. When the compiler processes the Search Path, Unit Scope Names, and Library Path entries from Project Options, it expands MSBuild-style variables and environment variables at build time on the machine doing the build. Relative paths are resolved against the project directory (the folder containing the .dproj/.cbproj), not against the current working directory of the IDE. This behavior is consistent across modern versions (RAD Studio 10.x through 12.x), though the exact set of predefined variables has grown over time.
Commonly useful variables include:
$(PROJECTDIR) — the project's own directory.$(BDS), $(BDSLIB), $(BDSINCLUDE) — the RAD Studio installation folders, so product files resolve regardless of install drive.$(Platform) and $(Config) — for per-platform/per-configuration output folders.- Any system or user environment variable, e.g.
$(THIRDPARTY_ROOT), if you define one.
Recommended Configuration
- In-repo dependencies: keep them in a fixed layout next to the project (e.g.
libs\, thirdparty\) and reference them as ..\..\libs\someunit or $(PROJECTDIR)\..\libs in Project Options → Delphi Compiler → Search Path. Commit the whole layout to version control so a clone is self-contained.
- Machine-level SDKs or large vendor libraries: define a system environment variable on each workstation (e.g.
VENDOR_SDK=D:\SDKs\VendorX) and reference $(VENDOR_SDK)\source in the search path. Document the required variables in the repo README.
- Per-developer overrides: use Tools → Options → Environment Options → Environment Variables for IDE-level user overrides rather than editing the shared project file. Entries there can shadow system variables without dirtying the
.dproj.
- Third-party design-time packages: these must be installed on every workstation. A missing package surfaces as unresolved units that look like path problems. Compare the installed products/packages lists between machines.
Diagnosing an Existing Failure
Separate what you can confirm from what you suspect. Confirm first:
- Open the
.dproj in a text editor and search for the failing filename. Check whether the entry is absolute, relative, or variable-based.
- In Project Options, inspect the Search Path for the active build configuration and platform — paths set only on 'Base' may be overridden at the configuration level, and a Win32 entry won't apply to Win64.
- Build from the command line with MSBuild to see the fully expanded paths:
msbuild MyProject.dproj /t:Build /p:Config=Debug /p:Platform=Win32 /v:detailed
The detailed log shows the resolved search path, which immediately reveals whether a variable expanded to an empty string (undefined on that machine) or a relative path resolved to a nonexistent folder.
Caveats
Two assumptions worth verifying in your environment: first, that all workstations run the same RAD Studio version and update level, since variable definitions and default paths differ between releases; second, that mapped drives are not involved — a relative path that silently depends on a drive letter mapping (e.g. Z:\dev mapped differently per user) fails exactly like an absolute path. If the error message names a specific file, that filename and whether it lives in your repo or a third-party install would determine which of the two strategies above applies.
radstudio