Some time ago, we've introduced Import Projects to Elements. These let you import a set of C header files for Island and Cocoa. An import project produces an .fx that can be used from a regular Island or Cocoa project, depending on what the import project is targeting.

To expand on this, we've started working on a set of import definition "Recipes" on GitHub. The first two projects I've imported are libsangui, which is a library for webserver development and libui, a library for cross-platform GUI work.

An import project looks pretty much like a standard Elements EBuild project.

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<Project DefaultTargets="Build" xmlns="http://schemas.microsoft.com/developer/msbuild/2003" ToolsVersion="4.0">
  <PropertyGroup>
    <OutputType>Import</OutputType>
    <AssemblyName>libui</AssemblyName>
    <RootNamespace>libui</RootNamespace>
    <ImportSearchPaths>.</ImportSearchPaths>
    <ImportCodeGen>Oxygene</ImportCodeGen>
    <ConditionalDefines>LONG_PTR=intptr_t</ConditionalDefines>
  </PropertyGroup>
  <ItemGroup>
    <ImportFile Include="ui.h"/>
    <ImportIndirectFile Include="ui_windows.h"/>
    <Reference Include="rtl" />
    <SymbolMapping Include="libui.dll">
        <SymbolNames>*</SymbolNames>
    </SymbolMapping>
  </ItemGroup>
  <Import Project="$(MSBuildExtensionsPath)\RemObjects Software\Elements\RemObjects.Elements.Island.Windows.targets" />
</Project>

Some properties and items of note are:

  • OutputType: Set to Import, it makes this project an import project instead of compiling it.
  • RootNamespace: This forces the project to import under this namespace; in this case, all files will be in the libui namespace.
  • ImportSearchPaths: This is where we look for header files; since these are next to the project, we use ".".
  • ImportCodeGen: This is optional, but generates an Oxygene file from the imported info. While this file can't be used directly, it shows what was imported.
  • ConditionalDefines: Contains a list of defines that will be passed to the C parser; In this case, LONG_PTR wasn't predefined by the headers, so we define that.
  • ImportFile: This is a mask of files to import, we only need ui.h in this case.
  • ImportIndirectFile: This is a mask of files that should be imported, but indirectly, usually this is because the file requires that other files are imported first, and thus can't be imported directly.
  • SymbolMapping: This maps all (*) symbols in this project to libui.dll, so that when the symbols are used, the libui dll is referenced.
  • Regular Reference items are supported to bring any already imported dependencies – in this case just the default operating system rtl that contains info on the original headers of the Windows SDK, which are used indirectly by this project.

(All of these are covered in detail in our Import Projects docs topic.)

That's pretty much it. Once imported, the .fx file can be referenced from a regular project. If we put the right .dll next to it, the Elements compiler copies it to the target directory and the project can be used like any other library. Here's a "libui" sample project in action:

Water_2019-07-31_15-07-14

Also check out our previous blog post and video on Importing Cocoa Fameworks, which also uses Import Projects.