Building with PhysX#

Generating projects with CMake#

PhysX uses CMake to generate build configuration files (e.g. Microsoft Visual Studio Solutions or Makefiles) for all supported platforms. The PhysX distribution comes with default CMake parameter sets called presets. The build configuration files can be generated with the script generate_projects in the distributions “physx/” directory. This script either prompts for a preset or accepts a preset as a command line parameter. The resulting build configuration files are generated under “physx/compiler/<preset-name>” for Windows and “physx/compiler/<preset-name>-<physx_build_type>” for Linux.

PhysX binaries (including static libraries) are placed into platform-specific directories:

  • Windows:

    • Structure: bin/<platform>.<target>.<compiler>.<runtime>/<configuration>/

    • Example: “bin/win.x86_64.vc142.mt/checked/”

  • Linux (x86_64 and aarch64):

    • Structure: bin/<platform>.<target>/<configuration>/

    • Examples:

      • “bin/linux.x86_64/checked/”

      • “bin/linux.aarch64/checked/”

Build Configurations#

The SDK has four build configurations available, designed for different stages of development and deployment.

  • the debug build can be useful for error analysis, but contains asserts used for SDK development which some customers may find too intrusive for daily use. Optimizations are turned off for this configuration.

  • the checked build contains code to detect invalid parameters, API race conditions, and other incorrect uses of the API which might cause otherwise surprising crashes or failures in simulation.

  • the profile build omits the checks, but still has PVD and memory instrumentation.

  • the release build is built for minimal footprint and maximum speed. It omits most checks and instrumentation.

Simulation works the same way in all of them, and all except the debug configuration are compiled with high optimization levels.

Note

We strongly recommend that you use the checked build as the primary configuration for day-to-day development and QA, as it includes runtime checks and debug symbols, but still provides good performance.

Note

PhysX libraries of different build configurations (e.g. the DEBUG version of PhysXExtensions and the CHECKED version of PhysXVisualDebuggerSDK) should never be mixed in an application because this will result a CRT conflict.

Building and linking against PhysX#

To build your own PhysX app, your build configuration should be set up such that the PhysX headers and libraries are discoverable at build and link time, respectively.

The following is a minimal example of a CMakeLists.txt project for a user project on Linux that links against all PhysX libraries:

CMakeLists.txt#
cmake_minimum_required (VERSION 3.16)
project (PhysX_Standalone_Snippet)

set(PHYSX_BUILD_TYPE "checked" CACHE STRING "The build type of PhysX")
set_property(CACHE PHYSX_BUILD_TYPE PROPERTY STRINGS debug checked profile release)

if(NOT CMAKE_BUILD_TYPE)
    if(PHYSX_BUILD_TYPE STREQUAL "debug" OR PHYSX_BUILD_TYPE STREQUAL "checked")
        set(CMAKE_BUILD_TYPE "Debug")
    endif()
endif()

include_directories(PhysX/include)
link_directories("PhysX/bin/linux.x86_64/${PHYSX_BUILD_TYPE}") # This is the path where PhysX libraries are installed

if(CMAKE_BUILD_TYPE STREQUAL "Debug")
    message("Building snippet in debug with PhysX ${PHYSX_BUILD_TYPE} configuration")
    add_compile_definitions(_DEBUG)
else()
    message("Building snippet in release configuration with PhysX ${PHYSX_BUILD_TYPE} configuration")
    add_compile_definitions(NDEBUG)
endif()

add_executable(Snippet
    main.cpp
)

target_link_libraries(Snippet
    -Wl,--start-group
    PhysXExtensions_static_64
    PhysX_static_64
    PhysXPvdSDK_static_64
    PhysXCommon_static_64
    PhysXFoundation_static_64
    -Wl,--end-group

    pthread
    dl
)

Within your source (main.cpp in the example above) it is easiest if the provided aggregate include header is used as:

#include "PxPhysicsAPI.h"

This will include the entire PhysX API including core, extensions, vehicles, etc. It is also possible to include subsets of the SDK if preferred, for example:

#include "vehicle2/PxVehicleAPI.h"

For examples on how to set up a scene, please refer to the Snippets, e.g., HelloWorld: PhysX Basics.

Redistribution#

On the Windows platform, you need to redistribute some of our DLLs to end users as part of your application:

  • PhysXCommon_*.dll - will always be needed.

  • PhysX_*.dll - will always be needed.

  • PhysXFoundation_*.dll - will always be needed.

  • PhysXCooking_*.dll - you only need to bundle if your application cooks geometry data on the fly.

  • PhysXGPU_*.dll - is only needed if your application runs some simulation on the GPU.

Where * is a platform specific suffix, e.g. 32 or 64. You will need one or the other depending on whether your application is built in 64 bit mode.

On Linux builds, everything that needs to be distributed will be in the corresponding install folder that is generated when running make install.

Customize CMake presets#

It is possible to customize the CMake presets, which are stored in physx/buildtools/presets/public/. Each XML file represents one preset, and several CMake switches can be toggled to alter the build behavior.

General switches:

  • PX_BUILDSNIPPETS - Add the PhysX Snippets to the build configuration.

  • PX_BUILDPVDRUNTIME - Generate the OmniPVD project.

  • PX_GENERATE_GPU_PROJECTS - Generate the GPU projects.

  • PX_GENERATE_GPU_PROJECTS_ONLY - Generate only the GPU projects.

  • PX_GENERATE_GPU_REDUCED_ARCHITECTURES - Generate SASS for a reduced number of GPU architectures for faster compilation.

  • PX_SCALAR_MATH - Disable SIMD math.

  • PX_GENERATE_STATIC_LIBRARIES - Build static libraries instead of DLLs (all except PhysXGPU).

  • PX_GENERATE_GPU_STATIC_LIBRARIES - Build a static PhysXGPU library instead of a DLL.

Windows-specific switches:

  • NV_USE_STATIC_WINCRT - Set static runtime usage.

  • NV_USE_DEBUG_WINCRT - Use debug CRT should be used.

  • PX_FLOAT_POINT_PRECISE_MATH - Switch to precise math rather than fast math, beneficial especially for robotics projects which require higher precision.

Some switches like PX_GENERATE_STATIC_LIBRARIES may require additional defines to be set in your application. In this case, you can include the PxConfig.h header in your application, which is generated during the project generation process.

On this page