Build Configuration

Intro

Intel RealSense SDK is using CMake eco-system to offer useful customization to customers who wish to build the SDK from source.

For example, to generate makefile with BUILD_EXAMPLES flag turned-on, use the following command line:
cmake .. -DBUILD_EXAMPLES=true
Alternatively, use cmake-gui utility to configure and generate your build files.

Build Customization Flags

FlagDescriptionDefault
BUILD_EXAMPLESBuild SDK examplestrue
BUILD_GRAPHICAL_EXAMPLESControls the-subset of examples and tools dependent on OpenGL. Recommended to disable for headless systems without the graphic subsystemtrue
BUILD_TOOLSBuild SDK command-line utilities, such as the firmware updater (SDK v2.46.0+)true
BUILD_UNIT_TESTSBuild the full suite of unit-tests for the SDKfalse
BUILD_WITH_OPENMPWhen enabled, YUY to RGB conversion and Depth-Color spatial alignment will take advantage of multiple-cores using OpenMP. This can reduce latency at expense of greater CPU utilizationfalse
ENFORCE_METADATAHaving UVC per-frame metadata requires building with Windows SDK installed. When this flag is disabled, the resulting binary might not be capable of properly parsing UVC metadata if Windows SDK was not installed during the build. If this flag is true, not having Windows SDK install will break the buildfalse
BUILD_PYTHON_BINDINGSBuild Python bindings for the SDK. Requires Python to be installed. See wrapper page for more informationfalse
BUILD_MATLAB_BINDINGSBuild Matlab wrapper for the SDK. See wrapper page for more informationfalse
BUILD_OPENNI2_BINDINGSBuild OpenNi2 wrapper for the SDK. See wrapper page for more informationfalse
BUILD_NODEJS_BINDINGSBuild Node.js bindings for the SDK. Requires Node.js to be installed. See wrapper page for more informationfalse
BUILD_CSHARP_BINDINGSBuild .NET bindings for the SDK. See wrapper page for more informationfalse
DOTNET_VERSION_EXAMPLESSelect .NET framework version to be used for .NET examples4.0
DOTNET_VERSION_LIBRARYSelect .NET framework version to be used for .NET wrapper3.5
ENABLE_CCACHEEnable building the SDK with CCachetrue
BUILD_UNITY_BINDINGSBuild Unity sample scene using the SDK. See wrapper page for more informationfalse
FORCE_LIBUVCSetting this flag to true will configure the underlying backend to use libuvc. This backend is default for Mac OS, but can be configured on other OS-s as well. libuvc can serve as a more robust alternative to the native backend, however, it has well known limitations and is not recommended to be used in end-products (please use FORCE_RSUSB_BACKEND cmake flag instead)false
FORCE_WINUSB_UVCSetting this will configure librealsense to use Windows backend based on WinUSB rewrite of the UVC protocol, instead of Media Foundation. Requires installation of a special driver provided inside the Win7 SDK installer (use FORCE_RSUSB_BACKEND instead)false
TRACE_APIWhen this flag is enabled, all API-calls will be written to the log at INFO severity. This will include any errors, duration, input and output parameters as well as the return value. Entry and exit from API calls will be documented as well at DEBUG severity. Enabling this feature will result in severe performance penaltyfalse
HWM_OVER_XUWhen this option is enabled, hardware commands will be dispatched through extension-unit (XU) transfer protocol. When disabled (and assuming the hardware supports it) the SDK will talk to the hardware directly using libusb / WinUSBtrue
BUILD_SHARED_LIBSWhen enabled the output of the library will be a dynamic link library (DLL) or a shared object (SO). When disabled the output will be a static library (LIB/A)true
CMAKE_BUILD_TYPEDesired build time. To take advantage of compiler optimizations set to "Release" or "RelWithDebInfo"Debug
ENABLE_ZERO_COPYWhen enabled frames that do not require processing will not be mem-copied on arrival, rather the rs2::frame object will track native handle to the underlying OS resource (be it V4L2 video-buff or an ISample). This will reduce CPU utilization and save battery life, but can introduce unexpected latency or frame-drops, since the responsibility for buffer lifetime management falls on the application developer (deprecated)false
BUILD_EASYLOGGINGPPPerform cross-platform logging using EasyLogging++ 3rd-party librarytrue
BUILD_CV_EXAMPLESBuild computer vision examples requiring OpenCV. See wrappers/opencvfalse
BUILD_CV_KINFU_EXAMPLEBuild simple 3d-reconstruction example using Kinnect-Fussion implementation. Relies on OPENCV_ENABLE_NONFREE. See wrappers/opencv/kinfufalse
BUILD_PCL_EXAMPLESSearch for PCL 3rd-party library and include example under wrappers/pcl in the projectfalse
BUILD_WITH_TM2Assuming you received from Intel an engineering sample of T265(TM2) device, enable support for it in the SDKtrue
BUILD_WITH_CUDABuild the SDK using CUDA for color conversions and image alignmentfalse
BUILD_WITH_STATIC_CRTWhen enabled increases binary footprint but prevents the dependency on Visual C++ Redistributablestrue
BUILD_GLSL_EXTENSIONSBuild OpenGL Shading Language extensions APItrue
BUILD_INTERNAL_UNIT_TESTSBuild test package for components under librealsense namespace, requires BUILD_SHARED_LIBS=OFF and BUILD_UNIT_TESTS=ONfalse
BUILD_PYTHON_DOCSBuild Documentation for Python bindingsfalse
ANDROID_USB_HOST_UVCBuild UVC backend for Android (use FORCE_RSUSB_BACKEND instead)false
FORCE_RSUSB_BACKENDEquivalent to FORCE_LIBUVC, ANDROID_USB_HOST_UVC and FORCE_WINUSB_UVC. Renamed for consistency across platformsfalse
IMPORT_DEPTH_CAM_FWDownload the latest firmware for the depth camerastrue

Back End Recommended Configuration

Platform

OS

Configuration

Recommend build

Recommended Version

X86

Win10

Media Foundation (1)

Default cmake

All versions

X86

Win7

RSUSB

cmake .. -DFORCE_RSUSB_BACKEND

SDK 2.30+

X86

Linux/Ubuntu

V4L

Default cmake

Kernel 4.4+ (2)

ARM (Nvidia)

Linux/Ubuntu

V4L

Default cmake

jetPack4.2.3+

ARM (RaspberryPi)

Linux/Ubuntu

RSUSB (3)

cmake .. -DFORCE_RSUSB_BACKEND

SDK 2.30+

ARM (Rockchip)

Android

RSUSB

cmake .. -DFORCE_RSUSB_BACKEND

SDK 2.30+

Mac

MacOS

RSUSB

cmake .. -DFORCE_RSUSB_BACKEND

SDK 2.30+

Notes:
(1) RSUSB can be supported (not recommended)
(2) Metadata support is Kernel version dependent. Kernel <4.16 patches are required. Kernel >=4.16, basic metadata supported, extended require patches. Please refer to the Linux installation guide
(3) RSUSB supports metadata. But if multiple-camera is required, recommended to use V4L but without metadata.

📘

Comments:

  • RSUSB is compliant with UVC 1.5.
  • LibUVC and WinUSB are deprecated from the build in SDK 2.30+, replaced by RSUSB
  • Multi-user applications support is limited with RSUSB