Lime uses this C/C++ code to build its ndlls (shared object files) for native targets. These shared objects only need to be compiled once, and can then be cached in the ndll directory, and can then be reused across arbitrarily many C++ apps.

Because these ndlls are included in the Haxelib download, you don't normally need to build them yourself. Even if you install Lime from Git, you can simply copy the ndlls from Lime's latest Haxelib release. You would only need to rebuild if you modify the C/C++ code, or you're targeting an unusual target.

Project overview

The backend project consists of two categories of code: Lime-specific code, and included libraries such as Cairo, SDL, and OpenAL. For more on these libraries, view submodule projects.

Lime-specific headers and source files can be found under include and src, respectively. Of particular note is ExternalInterface, as that exposes functions for use by NativeCFFI.

Lime invokes hxcpp to compile the code, passing Build.xml so that it knows which sources and headers to include. Build.xml recursively includes all the xml files inside lib, each of which contains instructions to build one of the included libraries.

Rebuilding

Run lime rebuild <target> to perform an incremental rebuild, or add -clean to force it to build from scratch.

Possible targets:

windows
mac / macos
linux
cpp (special case: maps to windows, mac, or linux, depending on your machine)
android
ios / iphone / iphoneos
rpi / raspberrypi
neko
hl / hashlink
All other strings in Platform
All other cases listed in CommandLineTools

Build troubleshooting

Most build errors can be fixed by updating the correct xml file. If the error happened inside src, you can fix it by editing Build.xml. Whereas if it happened in an included library, you'll want to find that library's xml file.

Common problems and their solutions:

[header].h: No such file or directory: Include the header.

<compilerflag value="-Iinclude/path/to/header/" />
<compilerflag value="-I${NATIVE_TOOLKIT_PATH}/path/to/another/header/" />

undefined reference to [symbol]: Locate the source file that defines the symbol, then add it.

<file name="src/path/to/file.cpp"/>
<file name="${NATIVE_TOOLKIT_PATH}/path/to/anotherfile.c"/>

'std::istringstream' has no member named 'swap': Your Android NDK is out of date; switch to version 20 or higher. (Version 21 recommended.)
Another problem related to an included library: see submodule troubleshooting.

Submodule projects

Lime includes code from several other C/C++ libraries, each of which is treated as a submodule. For more details about the libraries, see lib/README.md.

Overrides

The overrides folder contains a number of customized headers and source files, to be used instead of the equivalent file(s) in the submodule.

Caution: overridden files require extra maintenance. Avoid overriding if possible, and instead use -D flags to make the customizations you need.

When overriding a header, always include the overrides folder first.

<compilerflag value="-I${NATIVE_TOOLKIT_PATH}/overrides/sdl/include/" />
<compilerflag value="-I${NATIVE_TOOLKIT_PATH}/sdl/include/" />

Updating a submodule

Submodules are Git repositories in their own right, and are typically kept in "detached HEAD" state. Lime never modifies its submodules directly, but instead changes which commit the HEAD points to.

To update to a more recent version of a submodule:

Open the project's primary repo or GitHub mirror.
Browse the tags until you find the version you wish to update to. (Or browse commits, but that's discouraged.)
Copy the commit ID for your chosen version.
Open your local submodule folder on the command line. (From here, any git commands will affect the submodule instead of Lime.)
Update the library:
```
$ git checkout [commit ID]
Previous HEAD position was [old commit ID] [old commit message]
HEAD is now at [commit ID] [commit message]
```
If you get a "reference is not a tree" error, run git fetch --unshallow, then try again. (Lime downloads submodules in "shallow" mode to save time and space, and not all commits are fetched until you explicitly fetch them.)
If you exit the submodule and run git status, you'll find an unstaged change representing the update. Once you finish testing, you can commit this change and submit it as a pull request.

Submodule troubleshooting

Here are some problems you might run into while attempting to build these submodules, and their solutions.

All submodules are empty:

git submodule init
git submodule update

The project is missing a crucial header file, or has [header].h.in instead of the header you need:
1. Look for an autogen.sh file. If it exists, run it. (On Windows, you may need WSL, or you might be able to find a .bat file that does what you need.)
2. If step 1 fails, look for instructions on how to configure the project. This will often involving using make, cmake, and/or ./configure. (Again, Windows users may need WSL.)
3. One of the above steps should hopefully generate the missing header. Place the generated file inside the overrides folder.
You've attempted to override a header, but it still uses the original:
1. Double-check your xml files to ensure the override folder is included first. (Search more than one xml file, as libraries can include each other's headers.)
2. If a source file includes a header in its own directory, you can't override that header. (At least, not without overriding the source file too.) Instead, try setting compiler flags to make the changes you need.