11 KiB
Contents
- CMake Basics
- Mac OS X
- Windows
- CMake Build Configuration
- Android Studio Project Integration
- Native Android Builds
- vcpkg
Building
For all platforms, you must first generate the project/make files and then compile the examples.
CMake Basics
To generate project/make files for the default toolchain on your system, run
cmake
from a directory where you would like to generate build files, and pass
it the path to your Draco repository.
E.g. Starting from Draco root.
$ mkdir build_dir && cd build_dir
$ cmake ../
On Windows, the above command will produce Visual Studio project files for the
newest Visual Studio detected on the system. On Mac OS X and Linux systems,
the above command will produce a makefile
.
To control what types of projects are generated, add the -G
parameter to the
cmake
command. This argument must be followed by the name of a generator.
Running cmake
with the --help
argument will list the available
generators for your system.
Mac OS X
On Mac OS X, run the following command to generate Xcode projects:
$ cmake ../ -G Xcode
Windows
On a Windows box you would run the following command to generate Visual Studio 2019 projects:
C:\Users\nobody> cmake ../ -G "Visual Studio 16 2019" -A Win32
To generate 64-bit Windows Visual Studio 2019 projects:
C:\Users\nobody> cmake ../ -G "Visual Studio 16 2019" -A x64
CMake Build Configuration
Transcoder
Before attempting to build Draco with transcoding support you must run an additional Git command to obtain the submodules:
# Run this command from within your Draco clone.
$ git submodule update --init
# See below if you prefer to use existing versions of Draco dependencies.
In order to build the draco_transcoder
target, the transcoding support needs
to be explicitly enabled when you run cmake
, for example:
$ cmake ../ -DDRACO_TRANSCODER_SUPPORTED=ON
The above option is currently not compatible with our Javascript or WebAssembly builds but all other use cases are supported. Note that binaries and libraries built with the transcoder support may result in increased binary sizes of the produced libraries and executables compared to the default CMake settings.
The following CMake variables can be used to configure Draco to use local copies of third party dependencies instead of git submodules.
DRACO_EIGEN_PATH
: this path must contain an Eigen directory that includes the Eigen sources.DRACO_FILESYSTEM_PATH
: this path must contain the ghc directory where the filesystem includes are located.DRACO_TINYGLTF_PATH
: this path must contain tiny_gltf.h and its dependencies.
When not specified the Draco build requires the presence of the submodules that
are stored within draco/third_party
.
Debugging and Optimization
Unlike Visual Studio and Xcode projects, the build configuration for make
builds is controlled when you run cmake
. The following examples demonstrate
various build configurations.
Omitting the build type produces makefiles that use release build flags by default:
$ cmake ../
A makefile using release (optimized) flags is produced like this:
$ cmake ../ -DCMAKE_BUILD_TYPE=Release
A release build with debug info can be produced as well:
$ cmake ../ -DCMAKE_BUILD_TYPE=RelWithDebInfo
And your standard debug build will be produced using:
$ cmake ../ -DCMAKE_BUILD_TYPE=Debug
To enable the use of sanitizers when the compiler in use supports them, set the sanitizer type when running CMake:
$ cmake ../ -DDRACO_SANITIZE=address
Googletest Integration
Draco includes testing support built using Googletest. The Googletest repository is included as a submodule of the Draco git repository. Run the following command to clone the Googletest repository:
$ git submodule update --init
To enable Googletest unit test support the DRACO_TESTS cmake variable must be turned on at cmake generation time:
$ cmake ../ -DDRACO_TESTS=ON
To run the tests execute draco_tests
from your build output directory:
$ ./draco_tests
Draco can be configured to use a local Googletest installation. The
DRACO_GOOGLETEST_PATH
variable overrides the behavior described above and
configures Draco to use the Googletest at the specified path.
Third Party Libraries
When Draco is built with transcoding and/or testing support enabled the project has dependencies on third party libraries:
- Eigen
- Provides various math utilites.
- Googletest
- Provides testing support.
- Gulrak/filesystem
- Provides C++17 std::filesystem emulation for pre-C++17 environments.
- TinyGLTF
- Provides GLTF I/O support.
These dependencies are managed as Git submodules. To obtain the dependencies run the following command in your Draco repository:
$ git submodule update --init
WebAssembly Decoder
The WebAssembly decoder can be built using the existing cmake build file by passing the path the Emscripten's cmake toolchain file at cmake generation time in the CMAKE_TOOLCHAIN_FILE variable and enabling the WASM build option. In addition, the EMSCRIPTEN environment variable must be set to the local path of the parent directory of the Emscripten tools directory.
# Make the path to emscripten available to cmake.
$ export EMSCRIPTEN=/path/to/emscripten/tools/parent
# Emscripten.cmake can be found within your Emscripten installation directory,
# it should be the subdir: cmake/Modules/Platform/Emscripten.cmake
$ cmake ../ -DCMAKE_TOOLCHAIN_FILE=/path/to/Emscripten.cmake -DDRACO_WASM=ON
# Build the WebAssembly decoder.
$ make
# Run the Javascript wrapper through Closure.
$ java -jar closure.jar --compilation_level SIMPLE --js draco_decoder.js --js_output_file draco_wasm_wrapper.js
WebAssembly Mesh Only Decoder
# cmake command line for mesh only WebAssembly decoder.
$ cmake ../ -DCMAKE_TOOLCHAIN_FILE=/path/to/Emscripten.cmake -DDRACO_WASM=ON -DDRACO_POINT_CLOUD_COMPRESSION=OFF
WebAssembly Point Cloud Only Decoder
# cmake command line for point cloud only WebAssembly decoder.
$ cmake ../ -DCMAKE_TOOLCHAIN_FILE=/path/to/Emscripten.cmake -DDRACO_WASM=ON -DDRACO_MESH_COMPRESSION=OFF
Javascript Encoder/Decoder
The javascript encoder and decoder can be built using the existing cmake build file by passing the path the Emscripten's cmake toolchain file at cmake generation time in the CMAKE_TOOLCHAIN_FILE variable. In addition, the EMSCRIPTEN environment variable must be set to the local path of the parent directory of the Emscripten tools directory.
Note The WebAssembly decoder should be favored over the JavaScript decoder.
# Make the path to emscripten available to cmake.
$ export EMSCRIPTEN=/path/to/emscripten/tools/parent
# Emscripten.cmake can be found within your Emscripten installation directory,
# it should be the subdir: cmake/Modules/Platform/Emscripten.cmake
$ cmake ../ -DCMAKE_TOOLCHAIN_FILE=/path/to/Emscripten.cmake
# Build the Javascript encoder and decoder.
$ make
iOS Builds
These are the basic commands needed to build Draco for iOS targets.
#arm64
$ cmake ../ -DCMAKE_TOOLCHAIN_FILE=../cmake/toolchains/arm64-ios.cmake
$ make
#x86_64
$ cmake ../ -DCMAKE_TOOLCHAIN_FILE=../cmake/toolchains/x86_64-ios.cmake
$ make
#armv7
$ cmake ../ -DCMAKE_TOOLCHAIN_FILE=../cmake/toolchains/armv7-ios.cmake
$ make
#i386
$ cmake ../ -DCMAKE_TOOLCHAIN_FILE=../cmake/toolchains/i386-ios.cmake
$ make
After building for each target the libraries can be merged into a single universal/fat library using lipo, and then used in iOS applications.
Native Android Builds
It's sometimes useful to build Draco command line tools and run them directly on Android devices via adb.
# This example is for armeabi-v7a.
$ cmake ../ -DCMAKE_TOOLCHAIN_FILE=../cmake/toolchains/android.cmake \
-DDRACO_ANDROID_NDK_PATH=path/to/ndk -DANDROID_ABI=armeabi-v7a
$ make
# See the android.cmake toolchain file for additional ANDROID_ABI options and
# other configurable Android variables.
After building the tools they can be moved to an android device via the use of
adb push
, and then run within an adb shell
instance.
Android Studio Project Integration
Tested on Android Studio 3.5.3.
Draco - Static Library
To include Draco in an existing or new Android Studio project, reference it
from the cmake
file of an existing native project that has a minimum SDK
version of 18 or higher. The project must support C++11.
To add Draco to your project:
-
Create a new "Native C++" project.
-
Add the following somewhere within the
CMakeLists.txt
for your project before theadd_library()
for your project's native-lib:# Note "/path/to/draco" must be changed to the path where you have cloned # the Draco sources. add_subdirectory(/path/to/draco ${CMAKE_BINARY_DIR}/draco_build) include_directories("${CMAKE_BINARY_DIR}" /path/to/draco)
-
Add the library target "draco" to the
target_link_libraries()
call for your project's native-lib. Thetarget_link_libraries()
call for an empty activity native project looks like this after the addition of Draco:target_link_libraries( # Specifies the target library. native-lib # Tells cmake this build depends on libdraco. draco # Links the target library to the log library # included in the NDK. ${log-lib} )
vcpkg
You can download and install Draco using the vcpkg dependency manager:
git clone https://github.com/Microsoft/vcpkg.git
cd vcpkg
./bootstrap-vcpkg.sh
./vcpkg integrate install
vcpkg install draco
The Draco port in vcpkg is kept up to date by Microsoft team members and community contributors. If the version is out of date, please create an issue or pull request on the vcpkg repository.