Building and Installing
=======================

Version Compatibility Table
---------------------------

First, make sure you are building a version of the plug-in that is compatible with
the version of USD you are targetting:

.. list-table::
   :widths: 25 25 25 25
   :header-rows: 1

   * - Plugin Version
     - USD 24.11
     - USD 25.02
     - USD 25.05
   * - 1.0.*
     - ✅
     - ✅
     - ✅


Toolchain Requirements
----------------------

Next, make sure you have the following software installed:

Linux and MacOS
^^^^^^^^^^^^^^^

* **Required**

  * An OpenUSD Installation (see version compatibility table)
  * CMake
  * GCC or Clang

* Code Formatting (when ``CLANG_FORMAT=on``)

  * Clang
  * Clang-format

* Documentation (when ``DOCUMENTATION=on``)

  * Doxygen
  * Python 3
  * Sphinx (``pip3 install sphinx``)
  * Breathe (``pip3 install breathe``)
  * ReadTheDocs Theme for Sphinx (``pip3 install sphinx-rtd-theme``)

* Testing

  * Valgrind (optional and only when ``VALGRIND=on``)


Windows
^^^^^^^

* **Required**

  * An OpenUSD Installation (see version compatibility table)
  * Visual Studio 2022 with the following components:
    * C++ CMake tools for Windows

* Code Formatting (when ``CLANG_FORMAT=on``)

  * Visual Studio 2022 with the following components:

    * C++ Clang Compiler for Windows (17.0.0 or above)
    * MSBuild support for LLVM (clang-cl) toolset

* Documentation (when ``DOCUMENTATION=on``)

  * Chocolatey and the following packages:

    * Doxygen (``choco install doxygen.install``)
    * Python 3 (``choco install python3``)
    * Sphinx (``pip3 install sphinx``)
    * Breathe (``pip3 install breathe``)
    * ReadTheDocs Theme for Sphinx (``pip3 install sphinx-rtd-theme``)


Build Instructions
------------------

Cloning The Repository
^^^^^^^^^^^^^^^^^^^^^^

This project uses an external build system, so when cloning the repository, make sure you also fetch submodules, e.g.

.. code-block::

    git clone --recurse-submodules https://github.com/jbrd/usdBVHAnim.git


Build Options
^^^^^^^^^^^^^

The following options can be specified on the command-line when configuring CMake via the ``-D`` argument:

.. list-table::
   :widths: 20 60 20
   :header-rows: 1

   * - Option
     - Description
     - Default Value
   * - ``CLANG_FORMAT``
     - Include Clang Format targets ``[on/off]``
     - ``on``
   * - ``CXX11_ABI``
     - On Linux if linking against libstdc++, explicitly turn CXX11_ABI ``[on/off]``. Uses compiler default if empty.
     - (empty)
   * - ``DOCUMENTATION``
     - Include documentation targets ``[on/off]``
     - ``on``
   * - ``STRICT``
     - Strict compilation (all warnings, warnings as errors) ``[on/off]``
     - ``on``
   * - ``VALGRIND``
     - Additionally run unit tests through Valgrind (if installed, Linux only) ``[on/off]``
     - ``on``

Contributors are encouraged to install the full set of toolchain requirements, leave all of these turned on by default, such that the entire toolchain is exercised.


Build Configurations
^^^^^^^^^^^^^^^^^^^^

To build this plugin, the build configuration you choose must match that of your OpenUSD distro,
otherwise you will get compiler and linker errors.

So, to build this plugin for production environments, against a Release build of OpenUSD, please
use ``--config Release`` (all instructions below will follow this, as its the most common use case).

Likewise, to build this plugin against a Debug build of OpenUSD, please use ``--config Debug``.

Building Locally
^^^^^^^^^^^^^^^^

* On Linux open a bash shell, on Windows open the x64 Native Tools Command Prompt
* Make a build directory and cd into that (e.g. ``mkdir build ; cd build``)
* Generate project files with: ``cmake ../``
* Build the project with: ``cmake --build ./ -- config Release``
* Build the documentation with: ``cmake --build ./ --config Release --target docs``
* Run the tests with: ``ctest -C Release ./``
* Validate source code formatting with: ``cmake --build ./ --target format-check``
* Automatically format source code with: ``cmake --build ./ --target format``

Testing Locally
^^^^^^^^^^^^^^^

* On Linux open a bash shell, on Windows open the x64 Native Tools Command Prompt
* Make a build directory and cd into that (e.g. ``mkdir build ; cd build``)
* Specify your deployment directory when generating project files: ``cmake -DCMAKE_INSTALL_PREFIX=./deploy ../``
* Install to a local deployment ``cmake --build ./ --target install --config Release``
* Add your local deployment to ``PXR_PLUGINPATH_NAME``, e.g: ``set PXR_PLUGINPATH_NAME=%cd%/deploy/bin`` on Windows 
* Run ``usdview`` to open a .bvh file

Permanently Installing Into an Existing USD Distro
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

* Make a build directory and cd into it (e.g. ``mkdir build ; cd build``)
* Set your install prefix to the path of your USD distro, e.g. ``cmake -DCMAKE_INSTALL_PREFIX=/opt/usd ../``
* Install with: ``cmake --build ./ --target install --config Release``

Your USD distro should already be set up to read plugins from its ``plugin/usd`` folder, in which case, no
further environment setup is required, and the plug-in will be available whenever you use USD.

Permanently Installing Into A Separate Location
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

* Make a build directory and cd into it (e.g. ``mkdir build ; cd build``)
* Set your install prefix to whatever you like, e.g. ``cmake -DCMAKE_INSTALL_PREFIX=/opt/usdBVHAnim ../``
* Install with: ``cmake --build ./ --target install --config Release``
* Ensure your environment always adds your chosen directory's ``plugin/usd`` folder to ``PXR_PLUGINPATH_NAME``, e.g: ``PXR_PLUGINPATH_NAME=/opt/usdBVHAnim/plugin/usd``

At this point, the plug-in should be available whenever you use USD.