assimp/contrib/draco/BUILDING.md

_**Contents**_

- [Building](#building)
  - [CMake Basics](#cmake-basics)
  - [Mac OS X](#mac-os-x)
  - [Windows](#windows)
  - [CMake Build Configuration](#cmake-build-configuration)
  - [Transcoder](#transcoder)
  - [Debugging and Optimization](#debugging-and-optimization)
  - [Googletest Integration](#googletest-integration)
  - [Third Party Libraries](#third-party-libraries)
  - [WebAssembly Decoder](#webassembly-decoder)
  - [WebAssembly Mesh Only Decoder](#webassembly-mesh-only-decoder)
  - [WebAssembly Point Cloud Only Decoder](#webassembly-point-cloud-only-decoder)
  - [Javascript Encoder/Decoder](#javascript-encoderdecoder)
  - [iOS Builds](#ios-builds)
  - [Native Android Builds](#native-android-builds)
  - [Android Studio Project Integration](#android-studio-project-integration)
  - [Draco - Static Library](#draco---static-library)
  - [vcpkg](#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.

~~~~~ bash
$ 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:

~~~~~ bash
$ cmake ../ -G Xcode
~~~~~

Windows
-------

On a Windows box you would run the following command to generate Visual Studio
2019 projects:

~~~~~ bash
C:\Users\nobody> cmake ../ -G "Visual Studio 16 2019" -A Win32
~~~~~

To generate 64-bit Windows Visual Studio 2019 projects:

~~~~~ bash
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:

~~~~~ bash
# 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:

~~~~~ bash
$ 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:

~~~~~ bash
$ cmake ../
~~~~~

A makefile using release (optimized) flags is produced like this:

~~~~~ bash
$ cmake ../ -DCMAKE_BUILD_TYPE=Release
~~~~~

A release build with debug info can be produced as well:

~~~~~ bash
$ cmake ../ -DCMAKE_BUILD_TYPE=RelWithDebInfo
~~~~~

And your standard debug build will be produced using:

~~~~~ bash
$ 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:

~~~~~ bash
$ 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:

~~~~~ bash
$ git submodule update --init
~~~~~

To enable Googletest unit test support the DRACO_TESTS cmake variable must be
turned on at cmake generation time:

~~~~~ bash
$ cmake ../ -DDRACO_TESTS=ON
~~~~~

To run the tests execute `draco_tests` from your build output directory:

~~~~~ bash
$ ./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](https://eigen.tuxfamily.org/)
  - Provides various math utilites.
- [Googletest](https://github.com/google/googletest)
  - Provides testing support.
- [Gulrak/filesystem](https://github.com/gulrak/filesystem)
  - Provides C++17 std::filesystem emulation for pre-C++17 environments.
- [TinyGLTF](https://github.com/syoyo/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:

~~~~~ bash
$ 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.

~~~~~ bash
# 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
-----------------------------

~~~~~ bash

# 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
-----------------------------

~~~~~ bash

# 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.

~~~~~ bash
# 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.
~~~~~ bash

#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.

~~~~~ bash
# 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 at least.
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:

     ~~~~~ cmake
     # 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:

     ~~~~~ cmake
     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](https://github.com/Microsoft/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](https://github.com/Microsoft/vcpkg) on the
vcpkg repository.