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 and python (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  libxext-dev 

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.
2. Download the "Command Line Tools only" from near the bottom of the Android studio page.
3. Download latest Android NDK from Android developers NDK. For Mac, choose "Mac App Bundle".
4. Mac: Open the NDK .dmg and and drag the file beginning with "AndroidNDK" to your Applications folder.
   Linux: Extract the contents of the NDK to /usr/local/ (so that in it should be a android-ndk-[version]/ 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-ndk-[version]

5. Extract the contents of the Command Line tools, which will give a tools directory. Move this to a new directory so that the path to it is /usr/local/android-sdk-[platform]/cmdline-tools/ (so that in it should be a tools/ directory), then run the following to change the ownership of this directory to your current account [username].

$ cd /usr/local
$ sudo chown -R [username] android-sdk-[platform]

6. Navigate to folder /usr/local/android-sdk-[platform]/cmdline-tools/tools/bin.
7. Run ./sdkmanager --list to see all Android packages available for install. Install the following:

• ./sdkmanager "platform-tools"
• ./sdkmanager "build-tools;28.0.2"
• ./sdkmanager "extras;android;m2repository"
• 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. Example: ./sdkmanager "platforms;android-21"

8. Optionally, if you do not have a physical Android device, run ./avdmanager to setup an Android virtual device with your desired API.
9. In the SETUP file, set ANDROIDAPI to the API version you have installed.
10. Edit PROFILE and in particular the fields SYS_PROFILE, SYS_ORGTLD, SYS_ORGSLD, and SYS_ANDROIDPW.
11. If you have an existing android.keystore file matching the values above, copy it into the same directory as PROFILE, otherwise one will be generated for you.
12. Install additional system requirements as they are asked for.
    Linux: The command sudo apt install python ant clang ncurses5-compat-libs should install several necessary packages that may be missing.
13. macOS Version 10.14 (Mojave) and higher: When trying to make an app, you may get a dialog box that says a given tool (eg. clang) cannot be open because the developer cannot be verified. If there is an "Open" button, press it. Otherwise press "Cancel" and then open your System Preferences and then Security & Privacy. There should be a message about the same tool. Press the Allow Anyway button. Then make again. This time the "Open" button should appear in the dialog box. Keep the Security & Privacy window open as you may have to repeat this process many times (once per tool) over many attempts to build for Android.

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 Ubuntu, install mingw: $ sudo apt-get install mingw-w64
For macOS CrossGCC works quite well. On newer versions using homebrew brew install mingw-w64 and 'WIN32SDK=/usr/local/Cellar/mingw-w64/7.0.0_2/toolchain-i686' in SETUP also works.

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.