DART 6 vs DART 7 API Changes: A Complete Migration Guide

DART 7.0.0 requires C++20, introduces umbrella headers like dart/all.hpp, renames DartLoader to UrdfParser, converts RootJointType enums to PascalCase, and removes every API deprecated during the 6.x series while replacing pybind11 with nanobind for Python.

The Dynamic Animation and Robotics Toolkit (DART) underwent significant architectural changes between the 6.x and 7.0.0 releases. This guide examines the DART 6 vs DART 7 API changes using source code analysis from the dartsim/dart repository, providing specific file paths and migration patterns for robotics developers.

Build Requirements and Compiler Support

The foundational toolchain requirements changed substantially between versions.

C++ Standard and Compiler Versions

DART 7 mandates C++20 minimum, upgrading from DART 6's C++17 requirement. According to the changelog at CHANGELOG.md lines 7-9, this change enables modern language features used throughout the new API surface.

Compiler minimums have also increased:

• GCC: 7.3+ (DART 6) → 11+ (DART 7)
• Clang: 6.0+ → 12+
• MSVC: 16.0 → 19.40+ (Visual Studio 2022)

These requirements are documented in CHANGELOG.md lines 23-27.

CMake Configuration Changes

While the minimum CMake version remains 3.10.2, DART 7 introduces new boolean options such as DART_BUILD_GUI (replacing the old OSG-specific toggle) and changes the default for DART_ENABLE_SIMD from ON to OFF as noted in CHANGELOG.md lines 34-36 and 84-85.

Modernized Header Structure

DART 7 replaces granular component headers with a unified include system designed to reduce boilerplate.

The Umbrella Header Pattern

All component headers were renamed to All.hpp, and a top-level dart/all.hpp was added to pull in the entire public API. The old <Component>.hpp files still exist but forward to the new structure while emitting deprecation warnings, as documented in CHANGELOG.md lines 10-13.

// DART 6 approach (still works but deprecated)
#include <dart/dynamics/BodyNode.hpp>
#include <dart/collision/CollisionObject.hpp>

// DART 7 preferred approach
#include <dart/all.hpp>               // Entire public API
// Or selective component includes:
#include <dart/collision/All.hpp>      // All collision headers

The new dart/all.hpp and component-specific All.hpp files (e.g., dart/collision/All.hpp) represent the canonical include path for new development.

Parser and Enum API Changes

The parsing utilities underwent both class renaming and enum value capitalization changes to enforce consistent code style.

PascalCase Enum Values

The RootJointType enumeration values changed from camelCase/snake_case to PascalCase across all parsers. In dart/utils/urdf/urdf_parser.hpp line 80, the definition now reads:

// DART 7 definition
enum class RootJointType { Floating, Fixed, Planar, ... };

Compare this to DART 6, which used lowercase values like floating and fixed. The same change applies to dart/utils/sdf/sdf_parser.hpp line 52 and the generic I/O layer at dart/io/read.hpp line 76.

Migration requirement: Update any code referencing RootJointType::floating to RootJointType::Floating, and similarly for fixed → Fixed and planar → Planar.

DartLoader Renamed to UrdfParser

The primary URDF parsing class was renamed for clarity. According to CHANGELOG.md lines 15-16, dart::utils::DartLoader is now dart::utils::UrdfParser.

// DART 6
dart::utils::DartLoader loader;
auto robot = loader.parseSkeleton("robot.urdf");

// DART 7
dart::utils::UrdfParser parser;
auto robot = parser.parseSkeleton("robot.urdf");

The SdfParser class name remains unchanged, though it adopts the new PascalCase enum values described above.

Python Bindings Architecture

DART 7 replaces the binding technology and package structure entirely.

nanobind Replaces pybind11

The Python bindings migrated from pybind11 to nanobind, resulting in a flattened namespace and slimmer API surface as noted in CHANGELOG.md lines 16-17. Legacy camelCase symbols remain available behind the DARTPY_ENABLE_LEGACY_MODULES flag but emit DeprecationWarning and will be removed in DART 8.0.

Package Name Change

The installable wheel changed from dartpy to dartpy7 (the experimental dartpy8 was removed), documented in CHANGELOG.md lines 41-44.

# DART 6

import dartpy as dart

# DART 7

import dartpy7 as dart  # Or import dart if installed as default

Python developers should migrate from camelCase to snake_case methods (e.g., load_urdf() instead of loadURDF()) to avoid deprecation warnings.

Deprecated API Removal

DART 7 eliminated every API marked deprecated during the 6.x series, as detailed in CHANGELOG.md lines 121-134. Key removals include:

• CollisionFilter::needCollision() — Deprecated in 6.3; use the modern collision query interface instead
• DART_COMMON_MAKE_SHARED_WEAK macro — Deprecated in 6.4
• Skeleton::clone() overloads and ConstraintSolver::set/getLCPSolver() — Deprecated in 6.7
• Joint::setPositionLimitEnforced() aliases — Deprecated in 6.10; use Joint::isPositionLimitEnabled and related accessors
• DartLoader::Flags and ResourceRetriever overloads — Deprecated in 6.11

Search your codebase for these symbols and replace them with their modern equivalents before upgrading.

Component and Target Renames

Several high-level components changed names to clarify their purpose.

GUI Target Simplification

The OpenSceneGraph-based GUI target renamed from gui-osg / dart-gui-osg to simply gui / dart-gui. The CMake option DART_BUILD_GUI_OSG became DART_BUILD_GUI per CHANGELOG.md lines 14-15. All GLUT-based examples were removed in favor of OSG/ImGui implementations.

Macro and Symbol Visibility Changes

Public macros now use the DART_ prefix (e.g., DART_ASSERT) to avoid conflicts, documented in CHANGELOG.md lines 62-63. Additionally, per-target Export.hpp files now define DART_<COMPONENT>_API macros instead of a monolithic DART_API symbol, as noted in lines 38-39.

Removed Components

The planning component (dropped in 6.14.0) and the integration and optimizer modules are absent from DART 7. The optimizer functionality moved to the separate dart-optimization package according to CHANGELOG.md lines 17-18 and 19-20.

Practical Migration Examples

Updating RootJointType Usage

When loading URDF files with specific root joint configurations:

// DART 6 (deprecated values)
parser.setDefaultRootJointType(dart::utils::RootJointType::floating);

// DART 7 (PascalCase)
parser.setDefaultRootJointType(dart::utils::RootJointType::Floating);

Replacing Collision Filter Calls

If your code used the old collision filter hook:

// DART 6 (removed in DART 7)
bool collide = filter.needCollision(bodyA, bodyB);

// DART 7
bool collide = filter.canCollide(bodyA, bodyB);  // Use current query API

CMakeLists.txt Updates

Replace old GUI and SIMD options:

# DART 6

set(DART_BUILD_GUI_OSG ON)
set(DART_ENABLE_SIMD ON)

# DART 7

set(DART_BUILD_GUI ON)

# Note: SIMD defaults to OFF; explicitly enable if needed

set(DART_ENABLE_SIMD ON)

Summary

• DART 7 requires C++20 and modern compilers (GCC 11+, Clang 12+, MSVC 19.40+)
• Umbrella headers (dart/all.hpp, dart/<component>/All.hpp) replace individual includes; old headers emit deprecation warnings
• Enum values in RootJointType are now PascalCase (Floating, Fixed, Planar)
• Class rename: DartLoader is now UrdfParser in dart::utils
• Python package changed from dartpy to dartpy7 with nanobind replacing pybind11
• All deprecated APIs from the 6.x series are removed, including CollisionFilter::needCollision and Skeleton::clone() overloads
• CMake variables updated: DART_BUILD_GUI replaces DART_BUILD_GUI_OSG, and SIMD defaults to OFF

Frequently Asked Questions

Do I need to change all include statements when migrating from DART 6 to DART 7?

While old-style includes like <dart/dynamics/BodyNode.hpp> still function, they emit deprecation warnings. The recommended approach is to include <dart/all.hpp> for the full API or <dart/<component>/All.hpp> for specific components. This change centralizes the header structure and reduces include boilerplate.

Why was DartLoader renamed to UrdfParser in DART 7?

The rename clarifies the class's specific purpose (URDF parsing) and aligns with the SDF parser naming convention. The change also accompanied a cleanup of the parser's internal namespace and removal of deprecated overloads that accepted ResourceRetriever objects and DartLoader::Flags.

How do I update Python code to work with DART 7?

Install the new wheel using pip install dartpy7 instead of dartpy. Update imports to use dartpy7 or the installed namespace. Remove reliance on camelCase methods (like loadURDF) in favor of snake_case (load_urdf), or enable DARTPY_ENABLE_LEGACY_MODULES temporarily while migrating, noting that this will raise deprecation warnings.

What happened to the optimizer and planning components in DART 7?

The planning component was removed in DART 6.14 and does not exist in DART 7. The optimizer and integration modules were extracted to a separate repository (dart-optimization). Applications depending on these must either migrate to the external package or vendor the old code, as the symbols are no longer present in the core dartsim/dart repository.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}