search

OSVR / OSVR-Android-Build

Repo with submodules for building OSVR for Android
Apache License 2.0
24 stars 17 forks source link

readme

OSVR-Android-Build

Super-build and submodules for building OSVR for Android.

This repository should be cloned with --recursive, or you need to run

git submodule update --init --recursive

in the root directory. (You may want to do the latter after updating this repo, as well, to make sure the submodules are all up to date - make sure that any changes you've made in those repos has been committed on a named branch first.)

Requirements

Build Overview

This repository's primary contents, besides the submodules, is a CMake build system using the ExternalProject functionality to control nested configuration and build processes - the so-called "super-build". You should configure it using your standard, native platform build platform (Visual Studio, MinGW, Unix Makefiles, Ninja, whatever suits you). With the correct setting of things like the ANDROID_NDK variable in the super-build's CMake configuration (command line or GUI), the build will automatically set up the cross-compilation toolchain of nested builds as required.

Essentially, the super-build is a sort of meta-project or outer shell around the nested builds, with configuration, build, and install of the nested builds as targets in the super-build.

A bit more details: The OSVR build process requires a host-format (that is, not cross-compiled for Android) tool binary (osvr_json_to_c). On non-cross-compilation builds, it's just built as part of the standard build process then used, but this of course does not work when cross-compiling. This super-project includes a nested build just for that tool and its dependency, which uses whatever CMake generator you use for the super-build which of course assumes that it can build binaries that your machine can run. The Android nested builds automatically have their CMAKE_TOOLCHAIN_FILE and related options set appropriately by the super-build, as well as having this native tool substituted in.

Important development note: As with all Git repos with submodules, if you are going to make changes to a submodule's contents, be sure to check out/create a named branch first, as the submodule process checks out a specific commit (a "detached HEAD").

Build/usage instructions

Build scripts

Windows

Running some configure script followed by build.cmd results in a complete build of the OSVR-Core and dependencies, with the binary tree in the build directory. For the inner Android builds, Ninja will be used if it is found on your path, otherwise makefiles compatible with the make included in the NDK will be used.

Since these are scripts, your Android NDK needs to be findable somehow: primarily either setting the environment variable %ANDROID_NDK% in the console you use to build or passing -DANDROID_NDK=c:/myndkpath as a command line argument to configure.

All configure scripts set up a Release-mode build unless you specify otherwise. Ninja is the fastest, in this case because it's the only system that will take advantage of parallelism without contortions.

Configure scripts

Post-configure scripts

Once you've run a configure script, you can proceed to run these scripts, as desired, in the same console for safety's sake.

Not Windows

"Not Windows" systems are expected to have an NDK, as well as some suitable host compiler and make installed (by default).

On-device convenience scripts

The build includes some simple scripts intended for running on the device that are optional but make testing/usage easier. They require Busybox to be installed and in the path. If you can't/don't want to use them, you can just read them to see what they're doing.