The Elements compiler uses references to pull in classes from external libraries – be it core framework libraries for the platform, third party libraries, or even your own libraries you created to contain code you are sharing between projects. Depending on the platform your project is targeting, references are to different file types, but the general concepts of references are the same.

  • On .NET, you can reference .dll files containing .NET code created by any .NET language — be it the Elements compiler, Visual C#, Visual Basic or a different .NET compiler.
  • On Cocoa, you can reference .fx files, which are pre-generated meta-data files generated by our FXGen tool that contain information about a framework or static library.
  • On Java, you can reference .jar files containing JVM byte code created by any JVM-compliant compiler, including Elements, the Java Language compiler, and other JVM languages.

Each project maintains a list of references, and once a library is listed as reference for a project, all public types defined in the library are available to code throughout the project (governed by the rules for accessing types across different Namespaces, of course.

Adding References

New references can be added to a project by right-clicking the "References" node of the project and choosing "Add Reference". In both Fire and Visual Studio, this brings up the Add References dialog, which gives you quick access to any standard references provided by the platform or registered with the compiler, but also lets you manually browse for a library to reference on disk:

In Fire, you can also drag reference-able libraries directly from Finder onto the "References" node to add references from disk.

Finding Referenced Libraries

References are listed for the project using only their name, with an optional "Hint Path" that may point to the referenced library on disk. The compiler toolchain will employ a number of different techniques for locating the referenced library, including looking for the reference among the platform's system libraries, in a range of search folders configured for the platform (see Reference Search Path XMLs), and finally using the Hint Path.

System and third party libraries will usually be located automatically, while custom libraries of your own creation will commonly rely on having hint path.

When building iOS applications using the Cocoa platform, the compiler will automatically switch between device and simulator versions of referenced libraries, if the provided hint path contains folders named either "iOS" or "iphoneos", by replacing those names with "iOS Simulator" or "iphonesimulator", respectively. When adding references to non-system libraries, make sure to always add the device version of the library, not the simulator version, to enable this automatic switching.

Project References

Elements also supports so-called project references. Rather than pointing to a pre-compiled library somewhere on disk, project references point to a second project (that needs to be open as part of the same Solution).

The compiler will automatically resolve project references, build the connected projects in the right order, and make sure the output of the referenced projects will be used when compiling the referencing project. This process also takes into account the current Configuration and device type (e.g. iOS Device vs. iOS Simulator on Cocoa).

You can add project references via the Add Reference dialog described above (Fire and Visual Studio) or simply by dragging a library project node onto the "References" node of a different project (Fire).

Copy-Local References

Some libraries you reference in your projects – such as base platform libraries – will already be available on the target system where your application runs by default. Other libraries – such as third party or custom libraries you created yourself – will need to de deployed alongside your application.

By setting the "Copy Local" flag of a reference to true (in the Properties pane in Visual Studio, or via the right-click menu on the reference in Fire), you tell the compiler tool chain to copy the library next to the finished executable during compilation and – where applicable – also include it when bundling up the application for deployment (as is done for Android, Mac or iOS).

References vs. Namespaces

It is important to not confuse references with Namespaces. While there is often a one-to-one mapping to which libraries contain which namespace, that overlap is arbitrary. A single referenced library can contain types in multiple namespaces (which may or may not be named the same as the library itself), and multiple libraries can contribute to the same namespace.

When using first or third party frameworks and libraries, it is important to know both what namespaces the types you want to use are in, but also which libraries need to be referenced in order to make the types available, as well. For example, all standard Cocoa SDK libraries ship with Elements in library files that match their namespace – Foundation.fx contains the Foundation namespace, UiKit.fx contains the UIKit namespace, and so on. On the other hand, on .NET many core namespaces are located in mscorlib.dll and System.dll.

See Aso