-
Notifications
You must be signed in to change notification settings - Fork 945
Cinder CMake Documentation
#Overview
This document describes how you can build libcinder and your application using cmake. This is our officially supported way to build system on most Posix platforms, while in general you can use cinder's cmake system on any platform. See the section on platform-specific notes for details.
To build libcinder from the command line, first make sure you have CMake version 3.0 or later installed. Then the process is similar to most other cmake projects you may have used, for example you can do the following from within the main cinder repo path:
mkdir build
cd build
cmake ..
make -j4
Upon completion, this will deposit a static libcinder binary within the $(CINDER_PATH)/lib folder for your application to link against. By default you'll be building for Debug configuration, to build release you change the above cmake command to:
cmake -DCMAKE_BUILD_TYPE=Release ..
make -j4
The runtime output directory for different configurations will automatically end up within different folders (i.e. lib/macosx/Debug/libcinder.a and lib/macosx/Release/libcinder.a), so multiple configurations can live side by side.
There are a few project configuration settings you can change by either editing the CMakeCache.txt file (or using some GUI to do this), or from the command line with the -D option. All settings related to cinder are prefixed with CINDER_. Some of the more common settings are listed below, take a look in the CMakeCache.txt file for a full and updated list.
CINDER_VERBOSE: prints out verbose information from within cinder's CMake scripts during configuration.
CINDER_TARGET: Sets the target to compile to. This defaults to one appropriate for the current operating system, but in some cases, for example android, you must set it manually (i.e. cmake -DCINDER_TARGET=android ..).
CINDER_TARGET_GL: Sets the target OpenGL version. Usually defaults to ogl (desktop modern OpenGL), but other valid options are es2, es3, and es31`. These are useful when you are building for something like the Raspberry Pi.
CINDER_BUILD_TESTS: Builds the unit tests (You can then runt he tests from the command line with make test).
CINDER_BUILD_SAMPLE: Specify the name of a single sample to build, after libcinder successfully builds. It will end up in the current build folder. For example, adding the option -DCINDER_BUILD_SAMPLE=BasicApp will also build the BasicApp sample and place it at (for me currently) build/Debug/BasicApp/BasicApp.app.
CINDER_BUILD_ALL_SAMPLES: Specifying True here will tell CMake to try to build all of the samples within cinder's samples directory. Might take a while!
The best thing to do when adding cmake to your own project is to look at one of the samples, or start with a template from TinderBox. For both, you'll find that the CMakeLists.txt file to be at proj/cmake/CMakeListst.txt. You can still build it from the base directory of your project if you choose, with something like:
cd my_project
mkdir build
cd build
cmake ../proj/cmake
make -j4
To simplify configuring your project and the many necessities on different platforms, we use a utility function called ci_make_app(), which takes a number of arguments to build your application. For example, here is the CMakeLists.txt file used for building the _opengl/ObjLoader sample:
cmake_minimum_required( VERSION 3.0 FATAL_ERROR )
set( CMAKE_VERBOSE_MAKEFILE ON )
project( opengl-ObjLoader )
get_filename_component( CINDER_PATH "${CMAKE_CURRENT_SOURCE_DIR}/../../../../.." ABSOLUTE )
get_filename_component( APP_PATH "${CMAKE_CURRENT_SOURCE_DIR}/../../" ABSOLUTE )
include( "${CINDER_PATH}/proj/cmake/modules/cinderMakeApp.cmake" )
ci_make_app(
APP_NAME "ObjLoader"
CINDER_PATH ${CINDER_PATH}
SOURCES ${APP_PATH}/src/ObjLoaderApp.cpp
INCLUDES ${APP_PATH}/include
RESOURCES ${APP_PATH}/../../data/models/8lbs.obj
)It is quite brief, but you can see that we've specified a number of common things necessary when building a custom application, such as source files and include paths.
Arguments to ci_make_app() include:
APP_NAME: Defines the name of your application. Defaults to the current ${PROJECT_NAME}.
CINDER_PATH: Relative path to cinder's root directory, used to find the cinder module via CMake's find_package() system. Required.
SOURCES: list of source files. Required.
INCLUDES: list of include firectories
ASSETS_PATH: path to your assets folder (see explanation of assets here. This will automatically get found if you're starting with a standard application template created by TinderBox. Note that by default, this gets symlinked next to your built application, however specifying -DCINDER_COPY_ASSETS=On at the command line will cause the assets to be copied over instead.
RESOURCES: list of resources, which are handled in a platform specific manner (see explanation of resources here.
BLOCKS: list of CinderBlocks that your application depends on. These can be specified by either a relative or absolute path, or by providing the name of one of the blocks that ships with cinder (e.g. lives in the $(CINDER_PATH)/blocks folder).
LIBRARIES: list of lib files to be linked via target_lin_libraries.
ci_make_app() also listens to the CINDER_VERBOSE variable, so if that is on then you will see much more configuration information.
This section provides an overview of how we've structures the cmake build support within the cinder repo.