C++ backend project

Lime uses this C/C++ code to build reusable binaries for native targets, stored in the ndll directory. Binaries for common targets are included in the Haxelib download, so you won't need to build those yourself unless you make changes.

Tip: if you install Lime from Git, you can still copy the ndlls from Lime's latest Haxelib release.

Project overview

This directory contains two categories of code.

• Lime-specific headers and source files can be found under include and src, respectively. ExternalInterface serves as the entry point into this code.
• Submodules such as Cairo, SDL, and OpenAL can be found under lib.

Prerequisites

• All platforms require hxcpp.

• Windows requires Visual Studio C++ components.

• Mac requires Xcode.

• Linux requires several packages (names may vary per distro).

  sudo apt-get install libgl1-mesa-dev libglu1-mesa-dev g++ g++-multilib gcc-multilib libasound2-dev libx11-dev libxext-dev libxi-dev libxrandr-dev libxinerama-dev libpulse-dev

Rebuilding

Use lime rebuild <target> to build or rebuild a set of binaries. Once finished, you can find them in the ndll directory.

lime rebuild windows #Recompile the Windows binaries.
lime rebuild android -clean #Compile the Android binaries from scratch, even if no changes are detected.
lime rebuild mac -64 #Recompile only the x86-64 binary for Mac.

See lime help rebuild for details and additional options.

Note: even without an explicit rebuild command, running lime will automatically build a binary for your machine. Even if you don't use it, this binary will help with small tasks such as rendering icons.

Build troubleshooting

Most build errors can be fixed by updating the appropriate configuration file for that directory. Build.xml manages the src and include directories, while each submodule within lib has its own xml file. So for instance, if the error message points to lib/cairo/src/cairo.c, you most likely need to edit cairo-files.xml. (Though there are exceptions due to libraries referencing one another.)

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.)

See also submodule troubleshooting.

Submodule projects

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

Custom headers and source files

All submodules are used as-is, meaning Lime never modifies the contents of the submodule folder. When Lime needs to modify or add a file, the file goes in lib/custom.

Caution: overriding a file requires extra maintenance. Always try to find a different solution first. lib/custom should contain as few files as possible.

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:

1. Open the project's primary repo or GitHub mirror.

2. Browse the tags until you find the version you wish to update to. (Or browse commits, but that's discouraged.)

3. Copy the commit ID for your chosen version.

4. Open your local submodule folder on the command line. (From here, any git commands will affect the submodule instead of Lime.)

5. 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.)

6. 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 submodule-specific problems you might run into while rebuilding.

• All submodules are empty:

  git submodule init
  git submodule update

• Rebuilding fails after git pull, and git status reports changes to the submodules:

  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 custom folder.

• The compiler uses the submodule's original header instead of Lime's custom header:

  1. Make sure the custom folder is included first.

     <compilerflag value="-I${NATIVE_TOOLKIT_PATH}/custom/cairo/src/" />
     <compilerflag value="-I${NATIVE_TOOLKIT_PATH}/cairo/src/" />

  2. If the header is in the same directory as the corresponding source files, you cannot override it. Try setting compiler flags to get the result you want, or look for a different file to override.

     <compilerflag value="-DDISABLE_FEATURE" />
     <compilerflag value="-DENABLE_OTHER_FEATURE" />

  3. Approach the problem from a different angle. Upgrade or downgrade the submodule, or open an issue.