Draco v1.4.0

Author: tomfinegan

BUILDING.md

@@ -7,6 +7,10 @@ _**Contents**_
     * [Debugging and Optimization](#debugging-and-optimization)
     * [Googletest Integration](#googletest-integration)
     * [Javascript Encoder/Decoder](#javascript-encoderdecoder)
+    * [WebAssembly Decoder](#webassembly-decoder)
+    * [WebAssembly Mesh Only Decoder](#webassembly-mesh-only-decoder)
+    * [WebAssembly Point Cloud Only Decoder](#webassembly-point-cloud-only-decoder)
+    * [iOS Builds](#ios-builds)
   * [Android Studio Project Integration](#android-studio-project-integration)
   * [Native Android Builds](#native-android-builds)
   * [vcpkg](#vcpkg)
@@ -52,16 +56,16 @@ Windows
 -------
 
 On a Windows box you would run the following command to generate Visual Studio
-2017 projects:
+2019 projects:
 
 ~~~~~ bash
-C:\Users\nobody> cmake ../ -G "Visual Studio 15 2017"
+C:\Users\nobody> cmake ../ -G "Visual Studio 16 2019" -A Win32
 ~~~~~
 
-To generate 64-bit Windows Visual Studio 2017 projects:
+To generate 64-bit Windows Visual Studio 2019 projects:
 
 ~~~~~ bash
-C:\Users\nobody> cmake ../ -G "Visual Studio 15 2017 Win64"
+C:\Users\nobody> cmake ../ -G "Visual Studio 16 2019" -A x64
 ~~~~~
 
 
@@ -85,49 +89,42 @@ $ cmake ../
 A makefile using release (optimized) flags is produced like this:
 
 ~~~~~ bash
-$ cmake ../ -DCMAKE_BUILD_TYPE=release
+$ cmake ../ -DCMAKE_BUILD_TYPE=Release
 ~~~~~
 
 A release build with debug info can be produced as well:
 
 ~~~~~ bash
-$ cmake ../ -DCMAKE_BUILD_TYPE=relwithdebinfo
+$ cmake ../ -DCMAKE_BUILD_TYPE=RelWithDebInfo
 ~~~~~
 
 And your standard debug build will be produced using:
 
 ~~~~~ bash
-$ cmake ../ -DCMAKE_BUILD_TYPE=debug
+$ 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 ../ -DSANITIZE=address
+$ cmake ../ -DDRACO_SANITIZE=address
 ~~~~~
 
 Googletest Integration
 ----------------------
 
 Draco includes testing support built using Googletest. To enable Googletest unit
-test support the ENABLE_TESTS cmake variable must be turned on at cmake
+test support the DRACO_TESTS cmake variable must be turned on at cmake
 generation time:
 
 ~~~~~ bash
-$ cmake ../ -DENABLE_TESTS=ON
+$ cmake ../ -DDRACO_TESTS=ON
 ~~~~~
 
-When cmake is used as shown in the above example the Draco cmake file assumes
-that the Googletest source directory is a sibling of the Draco repository. To
-change the location to something else use the GTEST_SOURCE_DIR cmake variable:
-
-~~~~~ bash
-$ cmake ../ -DENABLE_TESTS=ON -DGTEST_SOURCE_DIR=path/to/googletest
-~~~~~
-
-To run the tests just execute `draco_tests` from your toolchain's build output
-directory.
+When cmake is used as shown in the above example the googletest directory must
+be a sibling of the Draco repository root directory. To run the tests execute
+`draco_tests` from your build output directory.
 
 WebAssembly Decoder
 -------------------
@@ -144,7 +141,7 @@ $ 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 -DENABLE_WASM=ON
+$ cmake ../ -DCMAKE_TOOLCHAIN_FILE=/path/to/Emscripten.cmake -DDRACO_WASM=ON
 
 # Build the WebAssembly decoder.
 $ make
@@ -160,7 +157,7 @@ WebAssembly Mesh Only Decoder
 ~~~~~ bash
 
 # cmake command line for mesh only WebAssembly decoder.
-$ cmake ../ -DCMAKE_TOOLCHAIN_FILE=/path/to/Emscripten.cmake -DENABLE_WASM=ON -DENABLE_POINT_CLOUD_COMPRESSION=OFF
+$ cmake ../ -DCMAKE_TOOLCHAIN_FILE=/path/to/Emscripten.cmake -DDRACO_WASM=ON -DDRACO_POINT_CLOUD_COMPRESSION=OFF
 
 ~~~~~
 
@@ -170,7 +167,7 @@ WebAssembly Point Cloud Only Decoder
 ~~~~~ bash
 
 # cmake command line for point cloud only WebAssembly decoder.
-$ cmake ../ -DCMAKE_TOOLCHAIN_FILE=/path/to/Emscripten.cmake -DENABLE_WASM=ON -DENABLE_MESH_COMPRESSION=OFF
+$ cmake ../ -DCMAKE_TOOLCHAIN_FILE=/path/to/Emscripten.cmake -DDRACO_WASM=ON -DDRACO_MESH_COMPRESSION=OFF
 
 ~~~~~
 
@@ -199,8 +196,7 @@ $ make
 
 iOS Builds
 ---------------------
-To build Draco for different iOS architectures and simulators for iphone and the simulators
-
+These are the basic commands needed to build Draco for iOS targets.
 ~~~~~ bash
 
 #arm64
@@ -220,7 +216,8 @@ $ cmake ../ -DCMAKE_TOOLCHAIN_FILE=../cmake/toolchains/i386-ios.cmake
 $ make
 ~~~~~~
 
-After building the tools they can be merged into fat lib and used in Iphone applications.
+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
@@ -230,24 +227,13 @@ It's sometimes useful to build Draco command line tools and run them directly on
 Android devices via adb.
 
 ~~~~~ bash
-# All targets require CMAKE_ANDROID_NDK. It must be set in the environment.
-$ export CMAKE_ANDROID_NDK=path/to/ndk
-
-# arm
-$ cmake ../ -DCMAKE_TOOLCHAIN_FILE=../cmake/toolchains/armv7-android-ndk-libcpp.cmake
+# 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
 
-# arm64
-$ cmake ../ -DCMAKE_TOOLCHAIN_FILE=../cmake/toolchains/arm64-android-ndk-libcpp.cmake
-$ make
-
-# x86
-$ cmake ../ -DCMAKE_TOOLCHAIN_FILE=../cmake/toolchains/x86-android-ndk-libcpp.cmake
-$ make
-
-# x86_64
-$ cmake ../ -DCMAKE_TOOLCHAIN_FILE=../cmake/toolchains/x86_64-android-ndk-libcpp.cmake
-$ 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
@@ -300,12 +286,16 @@ To add Draco to your project:
 
 vcpkg
 ---------------------
-You can download and install Draco using the [vcpkg](https://github.com/Microsoft/vcpkg/) dependency manager:
+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.
+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.

CMAKE.md

@@ -0,0 +1,106 @@
+# CMake Build System Overview
+
+[TOC]
+
+This document provides a general layout of the Draco CMake build system.
+
+## Core Build System Files
+
+These files are listed in order of interest to maintainers of the build system.
+
+-   `CMakeLists.txt` is the main driver of the build system. It's responsible
+    for defining targets and source lists, surfacing build system options, and
+    tying the components of the build system together.
+
+-   `cmake/draco_build_definitions.cmake` defines the macro
+    `draco_set_build_definitions()`, which is called from `CMakeLists.txt` to
+    configure include paths, compiler and linker flags, library settings,
+    platform speficic configuration, and other build system settings that
+    depend on optional build configurations.
+
+-   `cmake/draco_targets.cmake` defines the macros `draco_add_library()` and
+    `draco_add_executable()` which are used to create all targets in the CMake
+    build. These macros attempt to behave in a manner that loosely mirrors the
+    blaze `cc_library()` and `cc_binary()` commands. Note that
+    `draco_add_executable()` is also used for tests.
+
+-   `cmake/draco_emscripten.cmake` handles Emscripten SDK integration. It
+    defines several Emscripten specific macros that are required to build the
+    Emscripten specific targets defined in `CMakeLists.txt`.
+
+-   `cmake/draco_flags.cmake` defines macros related to compiler and linker
+    flags. Testing macros, macros for isolating flags to specific source files,
+    and the main flag configuration function for the library are defined here.
+
+-   `cmake/draco_options.cmake` defines macros that control optional features
+    of draco, and help track draco library and build system options.
+
+-   `cmake/draco_install.cmake` defines the draco install target.
+
+-   `cmake/draco_cpu_detection.cmake` determines the optimization types to
+    enable based on target system processor as reported by CMake.
+
+-   `cmake/draco_intrinsics.cmake` manages flags for source files that use
+    intrinsics. It handles detection of whether flags are necessary, and the
+    application of the flags to the sources that need them when they are
+    required.
+
+## Helper and Utility Files
+
+-   `.cmake-format.py` Defines coding style for cmake-format.
+
+-   `cmake/draco_helpers.cmake` defines utility macros.
+
+-   `cmake/draco_sanitizer.cmake` defines the `draco_configure_sanitizer()`
+    macro, which implements support for `DRACO_SANITIZE`. It handles the
+    compiler and linker flags necessary for using sanitizers like asan and msan.
+
+-   `cmake/draco_variables.cmake` defines macros for tracking and control of
+    draco build system variables.
+
+## Toolchain Files
+
+These files help facilitate cross compiling of draco for various targets.
+
+-   `cmake/toolchains/aarch64-linux-gnu.cmake` provides cross compilation
+    support for arm64 targets.
+
+-   `cmake/toolchains/android.cmake` provides cross compilation support for
+    Android targets.
+
+-   `cmake/toolchains/arm-linux-gnueabihf.cmake` provides cross compilation
+    support for armv7 targets.
+
+-   `cmake/toolchains/arm64-ios.cmake`, `cmake/toolchains/armv7-ios.cmake`,
+    and `cmake/toolchains/armv7s-ios.cmake` provide support for iOS.
+
+-   `cmake/toolchains/arm64-linux-gcc.cmake` and
+    `cmake/toolchains/armv7-linux-gcc.cmake` are deprecated, but remain for
+    compatibility. `cmake/toolchains/android.cmake` should be used instead.
+
+-   `cmake/toolchains/arm64-android-ndk-libcpp.cmake`,
+    `cmake/toolchains/armv7-android-ndk-libcpp.cmake`,
+    `cmake/toolchains/x86-android-ndk-libcpp.cmake`, and
+    `cmake/toolchains/x86_64-android-ndk-libcpp.cmake` are deprecated, but
+    remain for compatibility. `cmake/toolchains/android.cmake` should be used
+    instead.
+
+-   `cmake/toolchains/i386-ios.cmake` and `cmake/toolchains/x86_64-ios.cmake`
+    provide support for the iOS simulator.
+
+-   `cmake/toolchains/android-ndk-common.cmake` and
+    `cmake/toolchains/arm-ios-common.cmake` are support files used by other
+    toolchain files.
+
+## Template Files
+
+These files are inputs to the CMake build and are used to generate inputs to the
+build system output by CMake.
+
+-   `cmake/draco-config.cmake.template` is used to produce
+    draco-config.cmake. draco-config.cmake can be used by CMake to find draco
+    when another CMake project depends on draco.
+
+-   `cmake/draco.pc.template` is used to produce draco's pkg-config file.
+    Some build systems use pkg-config to configure include and library paths
+    when they depend upon third party libraries like draco.