Skip to content

Latest commit

 

History

History
217 lines (185 loc) · 9.54 KB

README.md

File metadata and controls

217 lines (185 loc) · 9.54 KB
Raw

Building and Using Jolt Physics

Build Types

Each platform supports multiple build targets

  • Debug - Debug version of the library, turns on asserts
  • Release - Release version of the library, no asserts but includes profiling support and can draw the world and simulation properties
  • ReleaseASAN - As Release but turns on Address Sanitizer (clang only) to find bugs
  • ReleaseUBSAN - As Release but turns on Undefined Behavior Sanitizer (clang only) to find bugs
  • ReleaseCoverage - As Release but turns on Coverage reporting (clang only) to find which areas of the code are not executed
  • Distribution - Shippable version of the library, turns off all debugging support

Includes

The Jolt headers don't include Jolt/Jolt.h. Always include Jolt/Jolt.h before including any other Jolt header. You can use Jolt/Jolt.h in your precompiled header to speed up compilation.

Defines

There are a number of user configurable defines that turn on/off certain features:

General Options (click to see more)
  • JPH_PROFILE_ENABLED - Turns on the internal profiler.
  • JPH_EXTERNAL_PROFILE - Turns on the internal profiler but forwards the information to a user defined external system (see Profiler.h).
  • JPH_DEBUG_RENDERER - Adds support to draw lines and triangles, used to be able to debug draw the state of the world.
  • JPH_DISABLE_TEMP_ALLOCATOR - Disables the temporary memory allocator, used mainly to allow ASAN to do its job.
  • JPH_DISABLE_CUSTOM_ALLOCATOR - Disables the ability to override the memory allocator.
  • JPH_FLOATING_POINT_EXCEPTIONS_ENABLED - Turns on division by zero and invalid floating point exception support in order to detect bugs (Windows only).
  • JPH_CROSS_PLATFORM_DETERMINISTIC - Turns on behavior to attempt cross platform determinism. If this is set, JPH_USE_FMADD is ignored.
  • JPH_DOUBLE_PRECISION - Compiles the library so that all positions are stored in doubles instead of floats. This makes larger worlds possible.
CPU Instruction Sets (click to see more)
  • JPH_USE_SSE4_1 - Enable SSE4.1 CPU instructions (default: on, x86/x64 only)
  • JPH_USE_SSE4_2 - Enable SSE4.2 CPU instructions (default: on, x86/x64 only)
  • JPH_USE_F16C - Enable half float CPU instructions (default: on, x86/x64 only)
  • JPH_USE_LZCNT - Enable the lzcnt CPU instruction (default: on, x86/x64 only)
  • JPH_USE_TZCNT - Enable the tzcnt CPU instruction (default: on, x86/x64 only)
  • JPH_USE_AVX - Enable AVX CPU instructions (default: on, x86/x64 only)
  • JPH_USE_AVX2 - Enable AVX2 CPU instructions (default: on, x86/x64 only)
  • JPH_USE_AVX512 - Enable AVX512F+AVX512VL CPU instructions (default: off, x86/x64 only)
  • JPH_USE_FMADD - Enable fused multiply add CPU instructions (default: on, x86/x64 only)

Logging & Asserting

To override the default trace and assert mechanism install your own custom handlers in Trace and AssertFailed (see IssueReporting.h).

Custom Memory Allocator

To implement your custom memory allocator override Allocate, Free, AlignedAllocate and AlignedFree (see Memory.h).

Building

Windows 10+
  • MSVC CL (default compiler)
    • Download Visual Studio 2022 (Community or other edition)
    • Download CMake 3.15+ (https://cmake.org/download/)
    • Run cmake_vs2022_cl.bat
    • Open the resulting project file VS2022_CL\JoltPhysics.sln
    • Compile and run either 'Samples' or 'UnitTests'
    MSVC CL - 32 bit
    • Download Visual Studio 2022 (Community or other edition)
    • Download CMake 3.15+ (https://cmake.org/download/)
    • Run cmake_vs2022_cl_32bit.bat
    • Open the resulting project file VS2022_CL_32BIT\JoltPhysics.sln
    • Compile and run either 'Samples' or 'UnitTests'
    MSVC Clang compiler
    • Download Visual Studio 2022 (Community or other edition)
    • Make sure to install "C++ Clang Compiler for Windows 11.0.0+" and "C++ Clang-cl for v142+ build tools (x64/x86)" using the Visual Studio Installer
    • Download CMake 3.15+ (https://cmake.org/download/)
    • Run cmake_vs2022_clang.bat
    • Open the resulting project file VS2022_Clang\JoltPhysics.sln
    • Compile and run either 'Samples' or 'UnitTests'
    MSVC Universal Windows Platform
    • Download Visual Studio 2022+ (Community or other edition)
    • Make sure to install "Universal Windows Platform development" using the Visual Studio Installer
    • Download CMake 3.15+ (https://cmake.org/download/)
    • Run cmake_vs2022_uwp.bat
    • Open the resulting project file VS2022_UWP\JoltPhysics.sln
    • Compile and run 'UnitTests'
    MinGW
    • Follow download instructions for MSYS2 (https://www.msys2.org/)
    • From the MSYS2 MSYS app run: pacman -S --needed mingw-w64-x86_64-toolchain mingw-w64-x86_64-cmake
    • From the MSYS2 MINGW x64 app, in the Build folder run: ./cmake_windows_mingw.sh
    • Run: cmake --build MinGW_Debug
    • Run: MinGW_Debug/UnitTests.exe
Linux
  • Debian flavor, x64 or ARM64
    • Install clang (apt-get install clang)
    • Install cmake (apt-get install cmake)
    • Run: ./cmake_linux_clang_gcc.sh
    • Go to the Linux_Debug folder
    • Run: make -j$(nproc) && ./UnitTests
    Debian flavor, MinGW Cross Compile
    • This setup can be used to run samples on Linux using wine and vkd3d. Tested on Ubuntu 22.04
    • Graphics card must support Vulkan and related drivers must be installed
    • Install mingw-w64 (apt-get install mingw-w64)
    • Run: update-alternatives --config x86_64-w64-mingw32-g++ (Select /usr/bin/x86_64-w64-mingw32-g++-posix)
    • Install cmake (apt-get install cmake)
    • Install wine64 (apt-get install wine64)
    • Run: export WINEPATH="/usr/x86_64-w64-mingw32/lib;/usr/lib/gcc/x86_64-w64-mingw32/10-posix" (change it based on your environment)
    • Run: ./cmake_linux_mingw.sh Release (Debug doesn't work)
    • Go to the MinGW_Release folder
    • Run: make -j$(nproc) && wine UnitTests.exe
    • Run: wine Samples.exe
Android
  • Install Android Studio 2020.3.1+ (https://developer.android.com/studio/)
  • Open the 'Android' folder in Android Studio and wait until gradle finishes
  • Select 'Run' / 'Run...' and 'UnitTests'
  • If the screen turns green after a while the unit tests succeeded, when red they failed (see the android log for details)
macOS
  • Install XCode
  • Download CMake 3.23+ (https://cmake.org/download/)
  • Run: ./cmake_xcode_macos.sh
  • This will open XCode with a newly generated project
  • Build and run the project
  • Note that you can also follow the steps in the 'Linux' section if you wish to build without XCode.
iOS
  • Install XCode
  • Download CMake 3.23+ (https://cmake.org/download/)
  • Run: ./cmake_xcode.ios.sh
  • This will open XCode with a newly generated project
  • Build and run the project (note that this will only work in the simulator as the code signing information is not set up)

Other Build Tools

  • A vcpkg package is available here.
  • A xmake package is available here.
  • Jolt has been verified to build with ninja through CMake.

Link Errors

If you receive the following error when linking:

/usr/bin/ld: libJolt.a: error adding symbols: file format not recognized

Then you have not enabled interprocedural optimizations (link time optimizations) for your own application. See the INTERPROCEDURAL_OPTIMIZATION option in CMakeLists.txt.

Illegal Instruction Error

If your CPU doesn't support all of the instructions you'll get an Illegal instruction exception.

On Linux to see what instructions your CPU supports run lscpu and then look at the flags section, on Windows you can use a program like coreinfo. Once you know what instructions your cpu supports you can configure the project through cmake and for example disable all special instructions:

./cmake_linux_clang_gcc.sh Release clang++ -DUSE_SSE4_1=OFF -DUSE_SSE4_2=OFF -DUSE_AVX=OFF -DUSE_AVX2=OFF -DUSE_AVX512=OFF -DUSE_LZCNT=OFF -DUSE_TZCNT=OFF -DUSE_F16C=OFF -DUSE_FMADD=OFF

Note that this example is for Linux but the cmake settings work on Windows too.

Doxygen on Windows

Documentation can be generated through doxygen: