Plain references, also referred to as direct references, are the most basic form of referencing external APIs and libraries from an Elements project.
While Project References and Package References exist as more high-level form of referencing dependencies, these too, get eventually resolved down to one or more plain references as part of the build process.
A plain reference points to a single file (the type of which depends on the target platform) that contains the necessary code and metadata needed by the compiler and the build chain in order to make the types and APIs from that reference available to the code in your project.
On the .NET platform, libraries take the form of regular
.dll files containing IL (.NET) code, along with the metadata required to consume it.
.dll files can be referenced directly and will be handled immediately by the compiler.
The .NET platform also supports
.winmd files, which contain API metadata for operating system-provided APIs, but no actual code. Like regular
.winmd files can simply be referenced and the compiler will handle them directly.
On the Java platform, code and metadata are provided in the form of
.jar files, essentially renamed zip files that contain the individual classes exposed by the library. The compiler will handle
.jar files directly.
Starting with JDK 9, the Java platform also uses
.jmod files to provide metadata for base runtime files without embedding the code itself, like
,jar files do. The compiler will handle
.jmod files directly and make their types available to your project.
For Java-based Android SDK projects,
.aar (Android Archive) files are another form of reference.
.aar files can contain a collection of
.jar files, resources and even native NDK binaries. As part of the build process, EBuild will automatically extract
.aar references, pass any contained
.jar files to the compiler, and also make sure resources and JNI binaries will be processed correctly, as well.
.fx (Cocoa and Island)
On both Cocoa and Island, the Elements-specific
.fx file format is used for referencing libraries.
.fx files contain meta-data only, and they can represent types from the core OS runtime (such as
rtl.fx, or the standard SDK framework .fx files like
Foundation.fx on Cocoa), or they can be accompanied by binary files (dynamic libraries, static libraries or, on Cocoa, frameworks) that contain the actual implementation. You can read more about
.fx files here.
.gx (All Platforms)
Finally, projects on all platforms can reference
.gx files, which are cross-platform libraries that contain metadata and can optionally also contain intermediate code or be accompanied by platform-specific binaries.
.gx files are created using Elements' new Gotham meta platform.
Finding (Resolving) References
Plain references are typically referenced by name only, and EBuild employs a sophisticated pipeline for resolving a name to the actual file that represents the reference. This includes checking in several well-known and user-configurable standard locations (see References XML Paths). The reference resolving logic is handled by the
ElementsResolveReferences task, and documented in more detail here.
For .NET and Java, each reference resolves to a single file. For Cocoa and Island, each reference actually resolves to one or more
On Cocoa for iOS, tvOS and watchOS, a separate
.fxfile is resolved for the Device and the Simulator build destination, respectively.
On Island, a separate
.fxfile is resolved for each active architecture the project is compiled for (e.g. i386 and x86_64).
EBuild uses folder naming conventions to find the right file for each architecture or build target.
For references that cannot be found automatically (or to override which version of the reference will used), an optional
HintPath meta data field can be provided on a reference. When present and referring to a file that exists on disk, the Hint Path will take precedence and any further resolving logic will be skipped.
Note that an invalid Hint path is not an error, and will simply be ignored, defaulting back to regular reference resolving as described above.
On Cocoa and Island, EBuild will automatically back-resolve from the hint path to find the corresponding references for other architectures or for Device vs. Simulator, of the reference is in an appropriately named subfolder.
For Island, if the folder containing the reference is named after one of the valid architectures for the platform, EBuild will automatically check parallel folders for the other architectures. E.g. if you reference
../Somewhere/i386/foo.fx in your Hint Path, EBuild will automatically find
../Somewhere/x86_64/foo.fx as well.
For Coco, if the folder containing the reference is named after the subplatform, EBuild will assume it is for the Device, and automatically check parallel folders for the Simulator reference. If the folder is named after the subplatform with a
Simulator suffix, it will assume the reference is for the Simulator, conversely. E.g if you reference
../Somewhere/iOS/libFoo.fx in your Hint Path, EBuild will automatically find
../Somewhere/iOS Simulator/libFoo.fx, and vice versa.
Fire and Water indicate the presence of a hint path by showing
X:\... behind the reference name. This also indicates whether the hint path is relative to the project, or absolute. You can remove a hint path, or change it from relative to absolute and vice versa, via the reference's right-click menu.
Copy Local References
References can be marked with the
CopyLocal (or, for backwards compatibility, the
Private) meta data value. If set to
True, and supported by the platform and reference type, a copy of the reference and related binaries will automatically be copied along the final executable.
On .NET, any
.dllfiles can be marked copy-local; corresponding
.mdbdebug symbol files will also be copied.
.winmdfiles cannot be copy-local.
.jarfiles can be marked as copy-local, and will be copied alongside the main executable (plain Java) or packaged into the
.jmodfiles cannot be copy-local.
.fxfiles can be marked as copy-local when they represent a non-system
.frameworkor a dynamic library (
.dylibs will be copied alongside the executable, and both
.frameworks will be included in the
.appbundle, if one is being created as part of the build.
.fxfiles can be marked as copy-local when they represent a dynamic library (
.so, etc, depending on the target platform). The libraries will be copied alongside the executable.