Should environment variables in Delphi .dproj search paths be used for repeatable builds given IDE auto‑modifications?

Answer first

No. Storing environment variables in .dproj search paths does not by itself prevent the Delphi IDE from overwriting entries with absolute paths, so repeatability is not guaranteed. A repeatable baseline is possible only with macro-based relative paths kept in version control and per-user overrides kept out of the committed file.

Confirmed facts

• .dproj is MSBuild XML. Search paths are stored as literal strings under DelphiProject/PropertyGroup/DelphiOptions/DelphiCompiler/SearchPath and similar nodes.
• Built-in MSBuild macros such as $(BDS), $(ProjectDir) and $(SolutionDir) are preserved as text and resolved at build time by MSBuild/IDE.
• Command-line msbuild and dcc resolve $(BDS) and user environment variables when they are defined in the build environment.

Likely explanation for IDE rewrites

Auto-modifications happen when options are edited via dialogs, when a path is added with Browse, or when a project is opened on a machine where an environment variable is undefined. In those cases the IDE writes an absolute, resolved path and can duplicate entries. Undefined variables are often replaced with empty strings or resolved to absolute paths on project open, and the Browse dialog converts any entry to an absolute path on save.

Stable baseline that survives IDE edits

Use relative paths anchored to $(ProjectDir) or $(SolutionDir) for all intra-repository units. Reserve environment variables only for machine-specific toolchain roots, and keep machine-specific values out of the committed .dproj. Relative + macro paths are identical across machines and minimize diffs.

Steps for this case

1. Commit a shared Directory.Build.props with common relative paths and shared MSBuild properties. Keep the committed .dproj free of absolute paths.
2. Add *.dproj.local and Directory.Build.props.user to .gitignore and use per-user overrides for local tweaks.
3. Define a small, documented set of environment variables for SDK roots only. Do not use them for repo-internal paths.
4. Avoid the Browse dialog for repository paths. Edit SearchPath entries as text with macros, e.g. $(ProjectDir)Lib;$(SolutionDir)Common.

Verification

• Inspect the committed .dproj for absolute paths or expanded values in SearchPath, UnitOutputDirectory and similar nodes.
• Make a benign change in Project Options, save, and diff the .dproj to see if macro entries were rewritten to absolute paths.
• Clone on a second machine with the documented env vars set, run msbuild /t:Build and confirm success without editing .dproj.

Missing diagnostic that changes the recommendation

Which Delphi version is in use and whether .dproj.local support is available in your release. Per-user override viability is version-dependent and affects whether the .dproj.local strategy can be used.