The build system for KinomaJS open source software supports building for Mac OS X, iOS, Android, Linux, and Windows targets. The build system runs on Mac OS X (Yosemite and later), Windows (7+) and Linux (Ubuntu 14.04). This document describes the host build environment required to build KinomaJS for each supported target platform, and the commands used to build an application.
KinomaJS applications are defined by a manifest.json
file that contains the build options, a list of the extensions required by the application, and packaging instructions.
The kprconfig6
tool generates build instructions from the application's manifest.json
file. kprconfig6
generates instructions for a command-line build for all targets, and an IDE project file for Windows, Mac OS X, and iOS.
The steps for building are:
-
Set up your host build environment.
-
Build the XS6 tools.
-
Build your KinomaJS application.
The host build environment is set up on the computer used to perform the build.
-
Building KinomaJS for Mac OS X, iOS, Android, Kinoma Element (MW302), or the Kinoma Code IDE requires a Mac OS X build host.
-
Building KinomaJS for Linux (for example, GTK desktop, Kinoma Create, or embedded Linux platforms) requires a Linux build host.
-
Building KinomaJS for Windows requires a Windows build host.
The host build environment is set up once. Instructions for setting up the host build environment for each target platform are provided below.
The XS6 tools built in the second step interpret the manifest.json
file that defines an application to generate build instructions.
The XS6 tool used to build applications is kprconfig6
.
To invoke kprconfig6
to build a KinomaJS application, use:
kprconfig6 -x -m -p <platform> <path-to-manifest.json>
To build a debug version of the application, use:
kprconfig6 -d -x -m -p <platform> <path-to-manifest.json>
where <platform>
identifies the target platform as indicated in the sections that follow (for example, mac
for Mac OS X or win
for Windows).
The package created by the build is located at {F_HOME}/bin/<platform>/<build-type>/<app-name>.tgz
(or .app
, .ipa
, .apk
, and so on, depending on the target platform).
Use -clean
to clean the target application and platform.
kprconfig6 -x -m -p <platform> <path-to-manifest.json> -clean
Use -cleanall
to clean all applications and all platforms.
kprconfig6 -cleanall
-
-a
: Application name -
-p
: Platform name -
-v
: Verbose -
-clean
: Clean the build for a particular application/platform -
-cleanall
: Clean the build for all platforms/applications
-
-c
: Debug or release configuration -
-d
: Debug build (same as-c debug
) -
-i
: Enable instrumentation -
-l
: Debug memory leaks -
-X
: Support xsdebug
-
-I
: Use the CMake-generated IDE (sets-x
) -
-g
: Sets CMake generator (build tool used) -
-m
: Build the application after generating the make files -
-x
: Use CMake build
-
-csi
: Code signing identity to use on iOS -
-pp
: Provisioning profile for iOS
-
-b
:bin
directory -
-o
: Output directory to place defaultbin
andtmp
directories -
-t
:tmp
directory
Building KinomaJS for Mac OS X uses a computer running Mac OS X as the build host.
On Mac OS X, the KinomaJS build uses Homebrew to manage installation and maintenance of CMake.
-
Install the current version of Xcode from Apple's App Store. (As of the writing of this document, the current version is 7.3.) After installing, run Xcode to accept the license agreement and install any required additional components.
-
Install Homebrew.
$ ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
$ brew install caskroom/cask/brew-cask
- Install CMake.
$ brew install cmake
- Get a copy of the KinomaJS source code. It can be downloaded using your web browser from the KinomaJS repository on GitHub or using the
git
command-line tool, as follows:
$ git clone https://github.com/kinoma/kinomajs.git
- Set up two environment variables to point to the source tree.
$ export F_HOME=/path/to/kinomajs
$ export XS6=${F_HOME}/xs6
- Build the XS6 tools as follows:
$ cd ${XS6}
$ mkdir tmp
$ cd tmp
$ cmake ${XS6}
$ cmake --build . --config Release
- Update the
PATH
environment variable to include the path to the XS6 tools.
$ export PATH=${PATH}:${XS6}/bin/mac/Release
- (Optional) Build
xsbug
, a graphical debugger used as an alternative to the Kinoma Studio debugger.
$ kprconfig6 -p mac -x -m ${XS6}/xsbug/manifest.json
The `xsbug` application is located at `${F_HOME}/bin/mac/Release/xsbug.app`.
Build the balls
sample application that is included in the KinomaJS repository.
$ cd ${F_HOME}
$ kprconfig6 -x -m -p mac ${F_HOME}/kinoma/kpr/applications/balls/manifest.json
The balls
application is located at ${F_HOME}/bin/mac/Release/Balls.app
.
Building KinomaJS for Linux/GTK requires a Linux build host. We use Ubuntu 14.04 on VirtualBox (on Mac OS X); other similar distributions have also been successfully used.
- Install the developer tools and CMake.
$ sudo apt-get install build-essential checkinstall
$ sudo apt-get install libgtk-3-dev libasound2-dev zlib1g-dev
$ sudo apt-get install cmake
- If you are using a 64-bit Linux distribution as a build host, install 32-bit libraries.
$ sudo apt-get install zlib1g:i386 lib32stdc++6
- Get a copy of the KinomaJS source code. It can be downloaded using your web browser from the KinomaJS repository on GitHub or using the
git
command-line tool, as follows:
$ git clone https://github.com/kinoma/kinomajs.git
- Set up two environment variables to point to the source tree.
$ export F_HOME=/path/to/kinomajs
$ export XS6=${F_HOME}/xs6
- Build the XS6 tools as follows:
$ cd ${XS6}
$ mkdir tmp
$ cd tmp
$ cmake ${XS6}
$ cmake --build . --config Release
- Update the
PATH
environment variable to include the path to the XS6 tools.
$ export PATH=${PATH}:${XS6}/bin/linux/$(uname -m)/Release
- (Optional) Build
xsbug
, a graphical debugger used as an alternative to the Kinoma Studio debugger.
$ kprconfig6 -p linux/gtk -x -m ${XS6}/xsbug/manifest.json
The `xsbug` application is located at `${F_HOME}/bin/linux/gtk/Release/xsbug/xsbug`.
Build the balls
sample application that is included in the KinomaJS repository.
$ cd ${F_HOME}
$ kprconfig6 -x -m -p linux/gtk ${F_HOME}/kinoma/kpr/applications/balls/manifest.json
The balls
application is located at ${F_HOME}/bin/linux/gtk/Release/Balls/Balls
.
Building KinomaJS for Windows builds uses a computer running Windows as the build host.
Building KinomaJS for Windows requires a machine running Windows 7 or greater. It is built with the Visual Studio development tools. We have used Visual Studio 2013 Express and Visual Studio 2015 Express.
-
Install the developer tools (Visual Studio Express):
-
Download Visual Studio Express from the Visual Studio Community download page.
-
Select the Custom install method to install the following packages:
-
Common Tools for Visual C++ 2015
-
Windows XP Support for C++
-
Git for Windows
-
-
-
Install CMake: on the CMake download page, click the "Windows (Win32 Installer)" link.
-
Update the
PATH
environment variable to include the paths for Git and CMake:-
Windows 32-bit --
C:\Program Files\Git\cmd;C:\Program Files\CMake\bin
-
Windows 64-bit --
C:\Program Files (x86)\Git\cmd;C:\Program Files (x86)\CMake\bin
-
-
Get a copy of the KinomaJS source code. It can be downloaded using your web browser from the KinomaJS repository on GitHub or using the
git
command-line tool, as follows:
> git clone https://github.com/kinoma/kinomajs.git
- Set up two environment variables to point to the source tree. Use
Start > Control Panel > System > Advanced system settings > Advanced > Environment Variables
to set the following:
- `F_HOME=\path\to\kinomajs` (example: `F_HOME=c:\Users\me\kinomajs`)
- `XS6=\path\to\kinomajs\xs6` (example: `XS6=c:\Users\me\kinomajs\xs6`)
-
Launch a Visual Studio Command Prompt.
Start > All Programs > Visual Studio Command Prompt (2013)
-
Build the XS6 tools.
> cd %XS6%
> mkdir tmp
> cd tmp
> cmake %XS6%
> cmake --build . --config Release
- Update the
PATH
environment variable to include the path to the XS6 tools.
> set PATH=%PATH%;%XS6%\bin\win\Release
- (Optional) Build
xsbug
, a graphical debugger used as an alternative to the Kinoma Studio debugger.
> kprconfig6 -p win -x -m %XS6%\xsbug\manifest.json
The `xsbug` application is located at `%F_HOME%\bin\win\Release\xsbug\xsbug.exe`.
Build the balls
sample application that is included in the KinomaJS repository.
$ cd %F_HOME%
$ kprconfig6 -x -m -p win %F_HOME%\kinoma\kpr\applications\balls\manifest.json
The balls
application is located at %F_HOME%\bin\win\Release\balls\balls.exe
.
iOS applications are built on a Mac OS X build host. If you have already set up your Mac OS X build host and XS6 tools, skip to the Build Your KinomaJS Application section.
On Mac OS X, the KinomaJS build uses Homebrew to manage installation and maintenance of CMake.
-
Install the current version of Xcode from Apple's App Store. (As of the writing of this document, the current version is 7.3.) After installing, run Xcode to accept the license agreement and install any required additional components.
-
Install Homebrew.
$ ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
$ brew install caskroom/cask/brew-cask
- Install CMake.
$ brew install cmake
- Get a copy of the KinomaJS source code. It can be downloaded using your web browser from the KinomaJS repository on GitHub or using the
git
command-line tool, as follows:
$ git clone https://github.com/kinoma/kinomajs.git
- Set up two environment variables to point to the source tree.
$ export F_HOME=/path/to/kinomajs
$ export XS6=${F_HOME}/xs6
- Build the XS6 tools as follows:
$ cd ${XS6}
$ mkdir tmp
$ cd tmp
$ cmake ${XS6}
$ cmake --build . --config Release
- Update the
PATH
environment variable to include the path to the XS6 tools.
$ export PATH=${PATH}:${XS6}/bin/mac/Release
- (Optional) Build
xsbug
, a graphical debugger used as an alternative to the Kinoma Studio debugger.
$ kprconfig6 -p mac -x -m ${XS6}/xsbug/manifest.json
The `xsbug` application is located at `${F_HOME}/bin/mac/Release/xsbug.app`.
Build the balls
sample application that is included in the KinomaJS repository.
$ cd ${F_HOME}
$ kprconfig6 -x -m -p ios ${F_HOME}/kinoma/kpr/applications/balls/manifest.json
The balls
application is located at ${F_HOME}/bin/ios/Release/Balls.ipa
.
If you have multiple developer accounts, you will be warned to include a codesign switch on the command line. To list the certificates you have installed, use:
$ security find-identity -v -p codesigning
Then add the switch -csi
to your build line with the ID of the certificate to use.
$ kprconfig6 -x -m -p ios -csi <ID> ${F_HOME}/kinoma/kpr/applications/balls/manifest.json
Building KinomaJS for Android uses Mac OS X as the build host.
In addition to the Mac OS X build host setup, KinomaJS for Android requires that you install the Android NDK and SDK.
On Mac OS X, the KinomaJS build uses Homebrew to manage installation and maintenance of CMake, Java, the Android SDK, and the Android NDK.
-
Install the current version of Xcode from Apple's App Store. (As of the writing of this document, the current version is 7.3.) After installing, run Xcode to accept the license agreement and install any required additional components.
-
Install Homebrew.
$ ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
$ brew install caskroom/cask/brew-cask
- Install CMake.
$ brew install cmake
- Install Java and the Android SDK and NDK.
$ brew cask install java
$ brew install android-sdk android-ndk
- Set up two environment variables to point to the Android SDK and Android NDK install locations.
$ export ANDROID_SDK=/usr/local/opt/android-sdk
$ export ANDROID_NDK=/usr/local/opt/android-ndk
- Update the Android tools.
$ android update sdk -u -t platform-tools
$ android update sdk -u -t android-17
$ android update sdk -u -t $(android list sdk -e | grep build-tools | sed -ne 's/.*"\(.*\)".*/\1/p' | head -1)
- Get a copy of the KinomaJS source code. It can be downloaded using your web browser from the KinomaJS repository on GitHub or using the
git
command-line tool, as follows:
$ git clone https://github.com/kinoma/kinomajs.git
- Set up two environment variables to point to the source tree.
$ export F_HOME=/path/to/kinomajs
$ export XS6=${F_HOME}/xs6
- Build the XS6 tools as follows:
$ cd ${XS6}
$ mkdir tmp
$ cd tmp
$ cmake ${XS6}
$ cmake --build . --config Release
- Update the
PATH
environment variable to include the path to the XS6 tools.
$ export PATH=${PATH}:${XS6}/bin/mac/Release
- (Optional) Build
xsbug
, a graphical debugger used as an alternative to the Kinoma Studio debugger.
$ kprconfig6 -p mac -x -m ${XS6}/xsbug/manifest.json
The `xsbug` application is located at `${F_HOME}/bin/mac/Release/xsbug.app`.
- Build the
balls
sample application that is included in the KinomaJS repository.
$ cd ${F_HOME}
$ kprconfig6 -x -m -p android ${F_HOME}/kinoma/kpr/applications/balls/manifest.json
The `balls` application `.apk` file is located at `$F_HOME/bin/android/Balls/Release/balls/balls.app`.
- Transfer to your Android device and run.
$ adb -d install -r ${F_HOME}/bin/android/Release/Balls/Balls.apk
Building KinomaJS for Linux/Aspen uses a Linux build host.
The build system uses linux/aspen
as the target platform to build Kinoma Create.
- Install the developer tools and CMake.
$ sudo apt-get install build-essential checkinstall
$ sudo apt-get install libgtk-3-dev libasound2-dev zlib1g-dev
$ sudo apt-get install cmake
- For a 64-bit Linux, install 32-bit libraries.
$ sudo apt-get install zlib1g:i386 lib32stdc++6
- Install the
linux/aspen
toolchain andsysroot
.
$ mkdir /your/buildtools/path
$ cd /your/buildtools/path
$ wget http://downloads.kinoma.com/aspen/sysroot.tbz
$ tar -jxvf sysroot.tbz
$ wget http://downloads.kinoma.com/aspen/toolchain.tbz
$ tar -jxvf toolchain.tbz
- Get a copy of the KinomaJS source code. It can be downloaded using your web browser from the KinomaJS repository on GitHub or using the
git
command-line tool, as follows:
$ git clone https://github.com/kinoma/kinomajs.git
- Set up two environment variables to point to the source tree.
$ export F_HOME=/path/to/kinomajs
$ export XS6=${F_HOME}/xs6
- Set up two environment variables to the linux/aspen cross-compiler and
sysroot
.
$ export ARM_MARVELL_LINUX_GNUEABI=/your/buildtools/path/arm-marvell-linux-gnueabi
$ export FSK_SYSROOT_LIB=/your/buildtools/path/arm-bin
- Build the XS tools as follows:
$ cd ${XS6}
$ mkdir tmp
$ cd tmp
$ cmake ${XS6}
$ cmake --build . --config Release
- Update the
PATH
environment variable to include the path to the XS6 tools.
$ export PATH=${PATH}:${XS6}/bin/linux/$(uname -m)/Release
- (Optional) Build the
xsbug
debugger:xsbug
is a graphical debugger used as an alternative to the Kinoma Studio debugger.
$ kprconfig6 -p linux/gtk -x -m ${XS6}/xsbug/manifest.json
The `xsbug` application is located at `${F_HOME}/bin/linux/gtk/Release/xsbug/xsbug`.
- Build the
balls
sample application that is included in the KinomaJS repository.
$ cd ${F_HOME}
$ kprconfig6 -x -m -p linux/aspen ${F_HOME}/kinoma/kpr/applications/balls/manifest.json
The `balls` application is located at `${F_HOME}/bin/linux/aspen/Release/Balls.tgz`.
- Transfer the
.tgz
file to your device and decompress.
When building for Mac OS X or iOS build targets, the Xcode IDE can be useful during development, particularly for debugging. The XS6 build tools can generate an Xcode project for Mac OS X and iOS targets.
- Add
-I
to the build line to create an Xcode project.
$ kprconfig6 -I -x -p ios ${F_HOME}/kinoma/kpr/applications/balls/manifest.json
-
From Xcode, choose the application and the simulator or iOS device.
-
Click the Play button. The iPhone simulator will launch with the
balls
app.
This also works with the mac
target.
$ kprconfig6 -I -x -p mac ${F_HOME}/kinoma/kpr/applications/balls/manifest.json
Building KinomaJS for Element uses a Mac OS X build host. Applications are built on a Mac OS X build host. If you have already set up your Mac OS X build host and XS6 tools, skip to the Build Your KinomaJS Application section.
The build system uses mc
as the target platform to build for Kinoma Element.
On Mac OS X, the KinomaJS build uses Homebrew to manage installation and maintenance of CMake.
-
Install the current version of Xcode from Apple's App Store. (As of the writing of this document, the current version is 7.3.) After installing, run Xcode to accept the license agreement and install any required additional components.
-
Install Homebrew.
$ ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
$ brew install caskroom/cask/brew-cask
- Install CMake.
$ brew install cmake
- Get a copy of the KinomaJS source code. It can be downloaded using your web browser from the KinomaJS repository on GitHub or using the
git
command-line tool, as follows:
$ git clone https://github.com/kinoma/kinomajs.git
- Set up two environment variables to point to the source tree.
$ export F_HOME=/path/to/kinomajs
$ export XS6=${F_HOME}/xs6
Building KinomaJS for Element currently requires a non-parallel build and setting the MAKEFLAGS
environment variable.
- Build the XS tools as follows:
$ export MAKEFLAGS=-j1
$ cd ${XS6}
$ mkdir tmp
$ cd tmp
$ cmake ${XS6}
$ cmake --build . --config Release
$ cmake --build . --target mc
- Update the
PATH
environment variable to include the path to the XS6 tools.
$ export PATH=${PATH}:${XS6}/bin/mac/Release
- (Optional) Build
xsbug
, a graphical debugger used as an alternative to the Kinoma Studio debugger.
$ kprconfig6 -p mac -x -m ${XS6}/xsbug/manifest.json
The `xsbug` application is located at `${F_HOME}/bin/mac/Release/xsbug.app`.
Build the Kinoma Element simulator that is included in the KinomaJS repository.
$ cd ${F_HOME}
$ kprconfig6 -d -x -m ${F_HOME}/kinoma/kpr/projects/element/manifest.json
The simulator application is located at ${F_HOME}/bin/mac/Debug/ElementShell.app
.
Building KinomaJS for the Kinoma Code IDE uses a Mac OS X build host. Applications are built on a Mac OS X build host. If you have already set up your Mac OS X build host and XS6 tools, skip to the Build Your Kinoma Code Application section.
On Mac OS X, the KinomaJS build uses Homebrew to manage installation and maintenance of CMake.
-
Install the current version of Xcode from Apple's App Store. (As of the writing of this document, the current version is 7.3.) After installing, run Xcode to accept the license agreement and install any required additional components.
-
Install Homebrew.
$ ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
$ brew install caskroom/cask/brew-cask
- Install CMake.
$ brew install cmake
- Get a copy of the KinomaJS source code. It can be downloaded using your web browser from the KinomaJS repository on GitHub or using the
git
command-line tool, as follows:
$ git clone https://github.com/kinoma/kinomajs.git
- Set up two environment variables to point to the source tree.
$ export F_HOME=/path/to/kinomajs
$ export XS6=${F_HOME}/xs6
- Build the XS6 tools as follows:
$ cd ${XS6}
$ mkdir tmp
$ cd tmp
$ cmake ${XS6}
$ cmake --build . --config Release
- Update the
PATH
environment variable to include the path to the XS6 tools.
$ export PATH=${PATH}:${XS6}/bin/mac/Release
Build the Kinoma Code
application that is included in the KinomaJS repository.
$ cd ${F_HOME}
$ kprconfig6 -x -m ${XS6}/xsedit/manifest.json
The Kinoma Code
application is located at ${F_HOME}/bin/mac/Release/Kinoma Code.app
. You can move the application somewhere else, or run it directly with:
$ open ${F_HOME}/bin/mac/Release/Kinoma\ Code.app
Building KinomaJS for embedded Linux uses a Linux build host.
The build system uses linux/beaglebone
, linux/edison
, linux/pi_gl
, linux/pi
, linux/linkit7688
, or linux/pine64
as the target platform to build for the respective platform. The examples in this section use linux/beaglebone
.
- Install the developer tools and CMake.
$ sudo apt-get install build-essential checkinstall
$ sudo apt-get install libgtk-3-dev libasound2-dev zlib1g-dev
$ sudo apt-get install cmake
- For a 64-bit Linux, install 32-bit libraries.
$ sudo apt-get install zlib1g:i386 lib32stdc++6
-
Install the toolchain and
sysroot
.To set up the cross-compilation environment and libraries for your build target:
-
For BeagleBone, Raspberry Pi or Edison, see the document Setup for Building for Embedded Devices
-
For Pine64, see the document Setup for Building for Pine64
-
For Linkit7688, see the document Setup for Building for Linkit7688
-
-
Get a copy of the KinomaJS source code. It can be downloaded using your web browser from the KinomaJS repository on GitHub or using the
git
command-line tool, as follows:
$ git clone https://github.com/kinoma/kinomajs.git
- Set up two environment variables to point to the source tree.
$ export F_HOME=/path/to/kinomajs
$ export XS6=${F_HOME}/xs6
- Build the XS tools as follows:
$ cd ${XS6}
$ mkdir tmp
$ cd tmp
$ cmake ${XS6}
$ cmake --build . --config Release
- Update the
PATH
environment variable to include the path to the XS6 tools.
$ export PATH=${PATH}:${XS6}/bin/linux/$(uname -m)/Release
- (Optional) Build the
xsbug
debugger:xsbug
is a graphical debugger used as an alternative to the Kinoma Studio debugger.
$ kprconfig6 -p linux/gtk -x -m ${XS6}/xsbug/manifest.json
The `xsbug` application is located at `${F_HOME}/bin/linux/gtk/Release/xsbug/xsbug`.
The target platform specifiers are as follows:
linux/pi
- Raspberry Pilinux/pi_gl
- Raspberry Pi, using OpenGLlinux/beaglebone
- BeagleBonelinux/edison
- Intel Edisonlinux/pine64
- Pine64linux/linkit7688
- Linkit7688
- Build the
balls
sample application that is included in the KinomaJS repository.
$ cd ${F_HOME}
$ kprconfig6 -x -m -p linux/beaglebone ${F_HOME}/kinoma/kpr/applications/balls/manifest.json
The `balls` application is located at `${F_HOME}/bin/linux/beaglebone/Release/Balls.tgz`.
- Transfer the
.tgz
file to your device and decompress.
- Build the
EmbedShell
application
$ cd $(F_HOME)
$ kprconfig6 -x -m -p linux/pine64 $(F_HOME)/kinoma/kpr/projects/embed/manifest.json
The `EmbedShell` application is located at `${F_HOME}/bin/linux/pine64/Release/EmbedShell `.
-
Transfer the
EmbedShell.tgz
file to your device and decompress. -
Run the
mdnsd
if Avahi or other mdns is not running on your target. This will allow EmbedShell to advertise itself to your local network../EmbedShell/lib/mdnsd
-
Run the EmbedShell
./EmbedShell/EmbedShell
Note: Depending on your user permissions, you may have to run mdnsd and EmbedShell as root using the sudo command.
sudo ./EmbedShell/EmbedShell