Move rebuild instructions to project/README.md.
There are too many details to put in the top-level readme.
This commit is contained in:
Joseph Cloutier
32
README.md
32
README.md
@@ -53,36 +53,24 @@ To install a development build, use the "haxelib local" command:
|
||||
Building from Source
|
||||
====================
|
||||
|
||||
Clone the Lime repository, as well as the submodules:
|
||||
1. Clone the Lime repository, as well as the submodules:
|
||||
|
||||
git clone --recursive https://github.com/openfl/lime
|
||||
haxelib git lime https://github.com/openfl/lime
|
||||
|
||||
Tell haxelib where your development copy of Lime is installed:
|
||||
2. Install required dependencies:
|
||||
|
||||
haxelib dev lime lime
|
||||
haxelib install format
|
||||
haxelib install hxp
|
||||
|
||||
The first time you run the "lime" command, it will attempt to build the Lime standard binary for your desktop platform as the command-line tools. To build these manually, use the following command (using "mac" or "linux" if appropriate):
|
||||
3. Copy the ndll directory from the latest [Haxelib release](https://lib.haxe.org/p/lime/), or see [project/README.md](project/README.md) for details about building native binaries.
|
||||
|
||||
haxelib install format
|
||||
haxelib install hxp
|
||||
lime rebuild windows
|
||||
4. After any changes to the [tools](tools) or [lime/tools](src/lime/tools) directories, rebuild from source:
|
||||
|
||||
You can build additional binaries, or rebuild binaries after making changes, using "lime rebuild":
|
||||
lime rebuild tools
|
||||
|
||||
lime rebuild windows
|
||||
lime rebuild linux -64 -release -clean
|
||||
5. To switch away from a source build:
|
||||
|
||||
You can also rebuild the tools if you make changes to them:
|
||||
|
||||
lime rebuild tools
|
||||
|
||||
On a Windows machine, you should have Microsoft Visual Studio C++ (Express is just fine) installed. You will need Xcode on a Mac. To build on a Linux machine, you may need the following packages (or similar):
|
||||
|
||||
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
|
||||
|
||||
To switch away from a source build, use:
|
||||
|
||||
haxelib dev lime
|
||||
haxelib set lime [version number]
|
||||
|
||||
|
||||
Sample
|
||||
|
||||
@@ -1,34 +1,40 @@
|
||||
# C++ backend project
|
||||
Lime uses this C/C++ code to build its ndlls (shared object files) for native targets. Each target requires its own set of ndlls. Ndlls for common targets are included in the Haxelib download (stored in the [ndll directory](https://github.com/openfl/lime/tree/develop/ndll)), so you won't need to build those yourself unless you modify this directory's contents.
|
||||
Lime uses this C/C++ code to build reusable binaries for native targets, stored in the [ndll directory](https://github.com/openfl/lime/tree/develop/ndll). 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
|
||||
The backend project consists of two categories of code: Lime-specific code, and [included libraries](#submodule-projects) such as Cairo, SDL, and OpenAL.
|
||||
This directory contains two categories of code.
|
||||
|
||||
Lime-specific headers and source files can be found under [include](include) and [src](src), respectively. Of particular note is [`ExternalInterface`](src/ExternalInterface.cpp), as that exposes functions for use by [`NativeCFFI`](https://github.com/openfl/lime/blob/develop/src/lime/_internal/backend/native/NativeCFFI.hx).
|
||||
- Lime-specific headers and source files can be found under [include](include) and [src](src), respectively. [`ExternalInterface`](src/ExternalInterface.cpp) serves as the entry point into this code.
|
||||
- [Submodules](#submodule-projects) such as Cairo, SDL, and OpenAL can be found under [lib](lib).
|
||||
|
||||
Lime invokes hxcpp to compile the code, passing [Build.xml](Build.xml) so that it knows which sources and headers to include. Build.xml recursively includes all the xml files inside [lib](lib), each of which contains instructions to build one of the included libraries.
|
||||
### Prerequisites
|
||||
|
||||
- All platforms require [hxcpp](https://lib.haxe.org/p/hxcpp/).
|
||||
- Windows requires [Visual Studio C++ components](https://visualstudio.microsoft.com/vs/features/cplusplus/).
|
||||
- Mac requires [Xcode](https://developer.apple.com/xcode/).
|
||||
- Linux requires several packages (names may vary per distro).
|
||||
|
||||
```bash
|
||||
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
|
||||
Run `lime rebuild <target>` to perform an incremental rebuild, or add `-clean` to force it to build from scratch.
|
||||
Use `lime rebuild <target>` to build or rebuild a set of binaries. Once finished, you can find them in the [ndll directory](https://github.com/openfl/lime/tree/develop/ndll).
|
||||
|
||||
Possible targets:
|
||||
```bash
|
||||
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.
|
||||
```
|
||||
|
||||
- `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`](https://github.com/openfl/lime/blob/develop/src/lime/tools/Platform.hx)
|
||||
- All other cases listed in [`CommandLineTools`](https://github.com/openfl/lime/blob/50488aee5353c2918b7a00bbe2930c5cf51fe1c9/tools/CommandLineTools.hx#L233-L292)
|
||||
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 correct xml file. If the error happened inside [src](src), you can fix it by editing [Build.xml](Build.xml). Whereas if it happened in an included library, you'll want to [find that library's xml file](lib).
|
||||
Most build errors can be fixed by updating the appropriate configuration file for that directory. [Build.xml](Build.xml) manages the [src](src) and [include](include) directories, while each submodule within [lib](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](lib/cairo-files.xml). (Though there are exceptions due to libraries referencing one another.)
|
||||
|
||||
Common problems and their solutions:
|
||||
|
||||
@@ -48,7 +54,7 @@ Common problems and their solutions:
|
||||
|
||||
- `'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-troubleshooting).
|
||||
See also [submodule troubleshooting](#submodule-troubleshooting).
|
||||
|
||||
## Submodule projects
|
||||
Lime includes code from several other C/C++ libraries, each of which is treated as a [submodule](https://git-scm.com/book/en/v2/Git-Tools-Submodules). For more details about the libraries, see [lib/README.md](lib/README.md).
|
||||
@@ -101,7 +107,18 @@ Here are some problems you might run into while attempting to build these submod
|
||||
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](#overrides).
|
||||
|
||||
- You've attempted to override a header, but it still uses the original:
|
||||
- The compiler ignores a header in the overrides folder:
|
||||
|
||||
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.
|
||||
1. Make sure the overrides folder is included first.
|
||||
|
||||
```xml
|
||||
<compilerflag value="-I${NATIVE_TOOLKIT_PATH}/overrides/cairo/src/" />
|
||||
<compilerflag value="-I${NATIVE_TOOLKIT_PATH}/cairo/src/" />
|
||||
```
|
||||
|
||||
2. If the header is in the same directory as the corresponding source files, find a different option. You simply can't override headers in that case. Instead, try setting compiler flags to make the changes you need.
|
||||
|
||||
```xml
|
||||
<compilerflag value="-DDISABLE_FEATURE" />
|
||||
<compilerflag value="-DENABLE_OTHER_FEATURE" />
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user