Skip to content

Latest commit

 

History

History
375 lines (273 loc) · 11.2 KB

BUILDING.md

File metadata and controls

375 lines (273 loc) · 11.2 KB
Raw

Contents

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:

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:

  1. Create a new "Native C++" project.

  2. Add the following somewhere within the CMakeLists.txt for your project before the add_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)

  3. Add the library target "draco" to the target_link_libraries() call for your project's native-lib. The target_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.