Getting Started

How to build an example

The following is a short outline of how to compile one of the examples (see apps/). If you have some experience in building software then this, and a few minutes, should be enough to build and run one of the examples. If you get stuck with something then continue reading this document.

Step 1: Clone the LambdaNative repository:

git clone https://github.com/part-cw/lambdanative.git 

Step 2: Create (and edit as needed) the files SETUP and PROFILE (see the provided *.template files):

cd lambdanative
cp SETUP.template SETUP
cp PROFILE.template PROFILE

Step 3: Configure an example app:

./configure Calculator
==> configured to build Calculator for macosx in normal mode
 == using source in /somewhere/lambdanative/apps/Calculator

Step 4: Start the build:

make

The first build will take a while, as the supporting libraries are downloaded and compiled for the first time. The build may also stop once a while and complain about missing dependencies. If so, just install what is missing and resume. The final executable will be generated in the LambdaNative cache directory, and can be installed to the desktop and launched with make install.

On a suitably configured platform, you can now do:

./configure DemoHelloWorld android
make

./configure DemoHelloWorld ios
make

and binaries for the specified platforms should be built and packaged. On the Mac, the packages will be placed in ~/Library/Caches/lambdanative/packages/ and on linux in ~/.cache/lambdanative/packages/.

Required SDKs

The minimum requirement for developing applications is the presence of a working gcc compiler.

Required tools and libraries

A number of tools are needed to support the framework. Please ensure that these are installed on your system:

Libraries

• libfreetype for rendering vector fonts
• OpenGL headers and libraries
• libasound for sound if developing on/for Linux
• libportaudio from ports if developing on OpenBSD

Tools

• wget for pulling library code from the net
• automake(aclocal) and autoconf for generating build files
• netpbm and ImageMagick for miscellaneous pixmap manipulation
• ghostscript and ps2eps for converting vector artwork
• xelatex (the unicode version of latex) for generating string textures (optional, but recommended)
• bc (if developing for android)
• cmake for generating XCode projects (only if developing for iOS)
• tgif for editing vector artwork (optional)
• fruitstrap for installing iOS apps (optional)

For example, on a clean Ubuntu install, the following command will install all necessary packages:

sudo apt install git autoconf build-essential libtool libgl1-mesa-dev libfreetype6-dev libasound2-dev netpbm imagemagick ghostscript ps2eps texlive-xetex

Note on using OSX to host builds

If using MacPorts, xelatex is available under the package texlive-xetex, and LambdaNative requires the tipa tex package, available from MacPorts under the package texlive-fonts-recommended.

Cross-compilation

Cross-compilation requires installation of the appropriate environments:

Android (macOS or Linux)

1. Install Java (7 or 8) JDK (on Debian based systems default-jdk is known to work).
2. Download Android SDK Tools revision 25.2.5 for macOS or linux.
3. Download Android NDK revision 13b for macOS or linux. (Other platforms and revisions are available here.)
4. Extract the contents of the SDK Tools archive to a new directory /usr/local/android-sdk-r25.2.5/ (so that in it should be a tools/ directory), and extract the contents of the NDK to /usr/local/ (so that in it should be a android-ndk-r13b/ directory). Then run the following to change the ownership of these directories to your current account <username>.

$ cd /usr/local
$ sudo chown -R <username> android-sdk-r25.2.5
$ sudo chown -R <username> android-ndk-r13b

5. Add the Android tools/ directory to your path by adding the following to your ~/.bash_profile file:

export PATH="$PATH:/usr/local/android-sdk-r25.2.5/tools"

6. Run android and install the following packages:

• Tools > Android SDK Platform-tools
• Tools > Android SDK Build-tools (Rev. 28.0.2 is known to work)
• Extras > Android Support Library
• The API for which you wish to develop; minimum supported API is API 21 (Android 5.0), as it is the first one to support arm64.

7. Optionally, if you do not have a physical Android device, run android avd to setup an Android virtual device with your desired API.
8. In the SETUP file, set ANDROIDAPI to the API version you have installed.
9. Edit PROFILE and in particular the fields SYS_PROFILE, SYS_ORGTLD, SYS_ORGSLD, and SYS_ANDROIDPW.
10. If you have an existing android.keystore file matching the values above, copy it into the same directory as PROFILE. You can also generate one using the following:

$ . PROFILE
$ keytool -genkey -v -keystore android.keystore -alias "$SYS_ORGTLD.$SYS_ORGSLD" -dname "cn=Your Name, ou=YourOrgUnit, o=YourOrg, c=US"  -keypass "$SYS_ANDROIDPW" -storepass "$SYS_ANDROIDPW" -keyalg RSA -keysize 4096 -validity 1000000

iOS (macOS)

1. Install Xcode 9 or higher and the corresponding command line tools, found under More Downloads for Apple Developers.
2. Follow the standard online procedures to create an iOS Development Certificate, and, optionally, an iOS Distribution Certificate, and register your device(s) for development.
3. Use Xcode to create and sync a Provisioning Profile onto your device(s). The Xcode build chain will not work properly if you do this step outside of Xcode.
4. Load the Keychain Access app on your Mac, search for "iPhone", then copy the full text of the title of iPhone Developer: XXX and iPhone Distribution: YYY into the PROFILE file in the appropriate spots.
5. In the SETUP file, set IOSVERSION to 6.0 or higher. (Xcode 10 requires IOSVERSION >7)

BlackBerry 10 (macOS or Linux)

1. Install the BlackBerry Native SDK.
2. Register as a BlackBerry developer and generate a BlackBerry ID token.
3. Use the SDK Wizard to generate certificates and setup a device for development; generating a debug token and installing it on the device.
4. Update SETUP and PROFILE with the relevant passwords and paths.

Linux cross-compilation (macOS)

Install a linux cross-compiler under /usr/local to create linux binaries.

Windows cross-compiler (macOS or Linux)

Install a windows cross-compiler under /usr/local to create windows binaries. For macOS CrossGCC works quite well.

OpenWrt cross-compilers (Linux)

Install the OpenWrt SDK for your target embedded platform and the system tools needed by the SDK. Note that only stand-alone (non-gui) applications can be built with OpenWrt. The OpenWrt SDK toolchains contain 32bit applications, so support for 32bit binaries are required on the host.

Windows development environment

If you are developing on a windows machine (not recommended) you have two options: MinGW and the MSYS development environment, or the Cygwin development environment.

Cygwin caution: Please note that the PATH environment can cause weird behaviour of the Cygwin system. This is especially true if a MinGW installation is present on the system. The best option to ensure that the environment is sane, is to limit PATH to cygwin directories only by editing /etc/profile.