Source Resolution

This chapter describes how the GPR project model resolves source files: how sources are discovered, which basenames are valid, how conflicts are handled, and how project extension overrides inherited sources.

Source discovery

For each non-abstract, non-aggregate project view, GPR tools scan every directory listed in Source_Dirs in declaration order. The resulting candidate set is then filtered by:

  • Source_Files / Source_List_File - restrict to an explicit list.

  • Excluded_Source_Files / Excluded_Source_List_File - remove specific files.

  • The Naming package - controls which file name extensions and patterns identify sources of each language.

Sources inherited from an extended project are added to this set before filtering.

Basename uniqueness

Every source file is identified by its basename - the simple file name without directory components. When the same basename appears in more than one source directory, the outcome depends on how those directories entered the project:

  • Different values in ``Source_Dirs`` - the directory corresponding to the earlier value takes precedence; no error is reported. For example, if Source_Dirs is ("src/a", "src/b") and both contain util.adb, the file from src/a is used.

  • Same value in ``Source_Dirs`` - an error is reported. This can occur when a single value is a recursive pattern such as "src/**": if two subdirectories matched by that pattern both contain a file with the same basename, the conflict cannot be resolved by ordering and is flagged as an error.

Extending projects and source shadowing

When project B extends project A, B inherits all of A’s sources. If B also declares a source whose basename matches one inherited from A, B’s version shadows the inherited one - the extending project’s source always takes precedence. This is not treated as a basename clash: overloading an inherited source is the intended mechanism for selectively replacing individual source files in an extension without copying the entire project.

To remove an inherited source without providing a replacement, list it in Excluded_Source_Files or Excluded_Source_List_File.

extends all

With extends all, the extending project inherits sources from the full transitive import closure of the extended project, not only from the immediate extended project. The same shadowing rules apply: a source declared in the extending project overrides the corresponding inherited source from any project in the closure.

See Project Extension for a full description of extends all semantics.

Multi-unit Ada sources

A single Ada source file may contain more than one compilation unit (the separate construct, or an explicit Naming mapping via Spec / Body). The project model tracks sources at the basename level; unit-to-file mappings are resolved during source analysis. Basename uniqueness rules still apply at the file level regardless of how many units a file contains.