Resolve References

The Resolve References task makes sure that every reference in each project and target is resolved to a proper full path on disk, for all active architectures (Island) and for all device types (Device or Simulator, for Cocoa).

An unresolved reference, unlike in the old MSBuild build system, is a failing error. The task will attempt to resolve each reference, even when an error occurs, so that all reference problems will be reported in one go.

• Implemented in ElementsResolveReferences, runs once per project.

Pre-Tasks

• ElementsApplyLegacySettings
• ElementsPreparePlatforms
• ElementsCheckForTargetlessReferences

Execution

As it runs, the task loops over all active targets, and runs the appropriate platform-specific subtasks to perform the reference resolution:

• ElementsResolveEchoesReferencesForTarget
• ElementsResolveCooperReferencesForTarget
• ElementsResolveToffeeReferencesForTarget
• ElementsResolveIslandReferencesForTarget

First, regular references are resolved, followed by Project References.

The basic flow is identical for each platform. References are resolved using the following steps:

• If a reference has a HintPath metadata and a file exists at that path (absolute or relative to the project), it will be used.

• If the name of the reference itself refers to a valid file (absolute or relative to the project), it will be used.

If the name of the reference includes a valid reference file extension for the platform, it is stripped for the purpose of the remaining lookup. E.g. "Foundation.fx" becomes simply "Foundation", but otherwise dotted names are preserved, "System.Data.dll" becomes "System.Data", but "System.Core" remains untouched.

• If the reference can be located via the platform-specific XML Reference Files, it will be used (FindReferenceFromXml).

• Finally, platform-specific steps will be invoked to try and resolve the reference (FindPlatformSpecificReference).

  • For Full-Framework .NET, the CLRs reference folders matching the projects Target Framework Version will be searched for the reference, as well as relevant AssemblyFolder locations marked in the registry.

  • For Java, the reference is checked for either in the Java Runtime folder (Plain) or in the Android SDK folder and its extras subfolders (Android). For backwards compatibility, a reference to rt.jar will be resolved to classes.jar and ui.jar, instead.

  • For Cocoa, the project's active SDK folder will be checked for the reference. If a Deployment Target Version is set, the rtl.fx reference will get adjusted to the one matching the deployment target, if available. An unsupported deployment target is a warning, not a failing error. For non-macOS sub-platforms, the reference will be resolved for both the device SDK and the Simulator SDK.

  • For Island, the specified IslandFXFolder will be used to locate the reference, for each active architecture. If not specified, or not found there, it will be looked up via the [XML Reference Files]((/Projects/References/ReferencesXMLPaths).

If the reference was resolved successfully, additional platform-specific steps are run for Island and Cocoa, to make sure the reference covers all architectures (Island) or devices (Cocoa) (AdjustReferenceIfNeeded). If that fails, the reference is considered unresolved, and the task fails.

• For Cocoa, non-macOS: If the parent folder name of the resolved reference matches the SDK name ("iOS", "tvOS", "watchOS"), it will be marked as for-Device, and its sibling folders will be checked for a matching simulator reference. And vice versa. Failure to resolve the reference for both device and simulator will result in error.

• For Island: If the parent folder of the resolved reference matches a valid architecture for the sub-platform, its sibling folders will be checked to try and resolve the reference for all active architectures. Failure to do so will result in error.

If the reference was not resolved properly, the task fails.

Output

On success, each reference will have its ResolvedPath meta data set to the path of the resolved reference file.

For Island, ResolvedPath-* will be set, where * is each of the active architectures. The main resolved path will contain one of the architectures, but it is undefined which one.

For Island, ResolvedPath-Device and ResolvedPath-Simulator will be set to the respective paths. The main resolved path will contain the Device path, as well.

Caching

The result of reference resolving is cached in ResolveReferences.caches, subject only to the date of the project file.

Note: This means that subsequent incremental builds will not pick up changes in available references, unless the project file was touched.

After a cache restore, a special tasks is run to verify all files referenced by the cache are present, for Cocoa and Island projects.

• ElementsValidateCachedToffeeReferencesForTarget
• ElementsValidateCachedIslandReferencesForTarget