Plain/Direct References

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.

Reference Files

.dll (.NET)

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.

.winmd (.NET)

The .NET platform also supports .winmd files, which contain API metadata for operating system-provided APIs, but no actual code. Like regular .dll references, .winmd files can simply be referenced and the compiler will handle them directly.

.jar (Java)

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.

.jmod (Java)

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.

.aar (Java/Android)

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 .fx files:

  • On Cocoa for iOS, tvOS and watchOS, a separate .fx file is resolved for the Device and the Simulator build destination, respectively.

  • On Island, a separate .fx file 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.

Hint Paths

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 .../, /... or 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 .dll files can be marked copy-local; corresponding .pdb or .mdb debug symbol files will also be copied. .winmd files cannot be copy-local.

  • On Java, .jar files can be marked as copy-local, and will be copied alongside the main executable (plain Java) or packaged into the .apk (for Android). .jmod files cannot be copy-local.

  • On Cocoa, .fx files can be marked as copy-local when they represent a non-system .framework or a dynamic library (.dylib). .dylibs will be copied alongside the executable, and both .dylibs and .frameworks will be included in the .app bundle, if one is being created as part of the build.

  • On Island, .fx files can be marked as copy-local when they represent a dynamic library (.dll, .so, etc, depending on the target platform). The libraries will be copied alongside the executable.

See Also