How to correctly find and link RL on Windows (DLLs + CMake integration)

[gsisinna]

Hi, and thanks for your work on the Robotics Library!

I'm trying to use RL in a custom C++ project on Windows and would like to ask a few questions about the correct setup process:

Finding the RL package:
Is there an official or recommended way to find the RL installation on Windows via CMake (find_package() or similar)? Should I rely on environment variables, CMake config files, or manually specify paths?

Linking the DLLs:
After building or downloading RL, what is the best way to link against the generated DLLs in a Windows environment? Are there import libraries (.lib files) provided alongside the DLLs that I should use when linking?

Precompiled binaries:
I noticed that there may be binaries available from the official site. Are these intended for use in custom projects, and if so, is there any guidance or documentation on integrating them?

Any guidance or best practices for setting up RL in a Windows-based project would be greatly appreciated!

Thanks again!

[rickertm]

The recommended way to find the RL installation via CMake is via find_package(RL), which uses the rl-config.cmake package configuration file in the installation directory to setup the targets (rl::math, rl::mdl, rl::plan, etc.) as well as a variable ${RL_LIBRARIES} with a list of all available targets.

To make sure CMake is able to find the package configuration file, you can include RL's installation directory in the environment variable CMAKE_PREFIX_PATH. You can also setup an environment variable RL_DIR to point to this directory.

Adding the corresponding targets as dependency to your own target in your CMake file will make sure to link against the correct library and add the correct include directories and definitions:

find_package(RL)
target_link_libraries(MyTarget PUBLIC ${RL_LIBRARIES})

On windows with MSVC, the default setting is to build static libraries. You can modify this to build DLLs (including import libraries) via the option BUILD_SHARED_LIBS - you might want to disable warning C4251 due to STL members.

The 0.7 binary installer is a bit outdated and does not include the Qt binaries. With MSVC, we recommend to use the latest binaries for the third-party dependencies (including Qt) from our rl-3rdparty repository and build the current RL version on the master branch. You can also get the matching RL binary artifacts (release build) from the CI workflow (requires GitHub login) if you prefer not to build the library yourself.

[gsisinna]

Thank you @rickertm for the detailed explanation, that's very helpful!

To simplify integration and improve reproducibility across projects, I’m considering opening a new ticket to create a vcpkg port for this library. Many of the dependencies already exist as official vcpkg ports, so it would help standardize and streamline consumption of RL and its components through a widely adopted C++ package manager.

Since there are already CI-generated binary artifacts available, we could also explore the possibility of producing a binary port for vcpkg. This could significantly reduce build times and lower the barrier for new users integrating the library.

Thanks again for the guidance and for maintaining this library!

[rickertm]

Getting the correct third-party dependencies is often an issue, especially for MSVC. We've spent some effort in improving this by providing prebuilt binaries and adding missing dependencies to various package managers, including vcpkg. Adding RL itself to package managers can only improve this experience even further and any help with this is very welcome.

The GitHub artifacts are only retained for a limited time and only include the release builds. To make sure the vcpkg dependencies match the RL build it is probably better to build this from source with the available versions. I also think most of them are already included in vcpkg and a lot of them are optional anyway. If you also want to include the GUI demos, an update of the SoQt port to v1.6.3 can help with Qt6 support.

A new tag is also long overdue, in particular due to recent CMake changes. We can look into this again to make packaging easier.

[gsisinna]

Thanks again, @rickertm! I've opened an initial "new port" issue here in the official microsoft/vcpkg repository.

Next, I'll begin exploring how to integrate this library with vcpkg to enhance its usability and streamline dependency management.

[gsisinna]

I'm happy to report that I successfully built RL on Windows using vcpkg for dependency management. With some minor adjustments, the process was fairly smooth, and using vcpkg really helped standardize the setup across different machines. Most of RL's dependencies are already available in the vcpkg registry. However, I did encounter a few exceptions:

• ATIDAQ
• cifX
• libdc1394

This reinforces the idea that better integration with package managers like vcpkg can significantly reduce the friction of building RL, especially on Windows where dependency resolution can be challenging. Adding RL itself to vcpkg would be a natural next step, and I'd be happy to contribute or collaborate on that effort.

Let me know how I can help with any of the above—especially vcpkg integration or testing future tags on Windows.

I leave here the vcpkg.json and vcpkg_configuration.json that I used to download and install the necessary dependencies:

vcpkg.json

{
  "name": "rl",
  "version-string": "0.7.0",
  "description": "A self-contained C++ library for rigid body kinematics and dynamics, motion planning, and control",
  "dependencies": [
    "boost",
    "eigen3",
    "libxml2",
    "libxslt",
    "nlopt",
    "bullet3",
    "coin",
    "ccd",
    "fcl",
    "ode",
    "pqp",
    "solid3",
    "soqt",
    "simage",
    "vcpkg-tool-ninja"
  ]
}

You can also override the versions for each individual library and freeze them by using the current tag.

vcpkg_configuration.json

{
  "default-registry": {
    "kind": "git",
    "baseline": "984f9232b2fe0eb94f5e9f161d6c632c581fff0c",
    "repository": "https://github.com/microsoft/vcpkg"
  },
  "registries": [
    {
      "kind": "artifact",
      "location": "https://github.com/microsoft/vcpkg-ce-catalog/archive/refs/heads/main.zip",
      "name": "microsoft"
    }
  ]
}

You can easily automate vcpkg integration in your CMake to test this:

if(WIN32)
  if(DEFINED ENV{VCPKG_ROOT})
    set(CMAKE_POLICY_DEFAULT_CMP0077 NEW)
    set(X_VCPKG_APPLOCAL_DEPS_INSTALL ON)
    message(STATUS "Using Vcpkg from: $ENV{VCPKG_ROOT}")
    set(CMAKE_TOOLCHAIN_FILE
        "$ENV{VCPKG_ROOT}/scripts/buildsystems/vcpkg.cmake"
        CACHE STRING "")
  else()
    message(WARNING "Vcpkg not found. Set VCPKG_ROOT environment variable.")
  endif()
endif()

[rickertm]

Thank you for testing RL against the current vcpkg dependencies. The missing dependencies are only used for selected hardware support (force/torque sensors, fieldbus, firewire camera) and likely not required for most users.

We'll look into creating a new tag, that should make packaging a bit easier.