Building Real-Sim FIXS

This document describes how to build Real-Sim FIXS from source. For general project information, see README.md.

Table of Contents

Quick Start

For a complete release build of all components:

dispatch.bat

This single command will:

  • Build external libraries (yaml-cpp, libevent)

  • Build core components (TrafficLayer, VirtualEnvironment)

  • Build VISSIM driver model DLLs

  • Build CarMaker executables for all detected versions

  • Build dSPACE libraries (if dSPACE is installed)

  • Build MEX files for MATLAB/Simulink

  • Generate BUILD_INFO.txt

  • Copy all artifacts to build/ directory

Build System Overview

The Real-Sim FIXS build system uses a modular script-based architecture that automatically detects installed tools and versions. Key features:

  • Automated tool detection: Automatically finds Visual Studio, MATLAB, dSPACE, and CarMaker installations

  • Version management: Central dependencies.yaml file defines all tool versions and configurations

  • Modular scripts: Each subsystem has its own build script for independent development

  • Intelligent configuration: Automatically generates CarMaker BuildConfig files based on detected tool versions

  • Comprehensive logging: Detailed build logs in scripts/dispatch/build.log and scripts/dispatch/build_summary.log

Prerequisites

Required Tools

  1. Visual Studio 2022 (Community, Professional, or Enterprise)

    • Required for building all C++ components

    • Must have C++ desktop development workload installed

    • MSBuild must be in PATH (automatically detected by build scripts)

    • C++ Standard: The project uses mixed C++ standards for compatibility:

      • TrafficLayer: C++17 (uses std::filesystem for runtime library discovery)

      • All other components: C++14 (VirtualEnvironment, DriverModel, SC_DLL, CarMaker projects)

      • C++14 is required for compatibility with CarMaker SDK and dSPACE toolchain

  2. CMake (version 3.10 or higher)

Optional Tools (for specific features)

  1. MATLAB/Simulink (version 2024a or compatible)

    • Required for MEX file compilation and Simulink integration

    • Automatically detected from registry or common installation paths

    • Version can be configured in dependencies.yaml

  2. CarMaker (versions 13.1.3, 11.1.2, or compatible)

    • Required for XIL/HIL vehicle dynamics integration

    • Multiple versions can coexist

    • Automatically detected from common installation paths

  3. dSPACE ConfigurationDesk (version 2024a or compatible)

    • Required for real-time HIL system integration

    • Automatically detected from Program Files

    • Version can be configured in dependencies.yaml

Configuration File

The dependencies.yaml file in the root directory defines all tool versions and configurations:

simulators:
  carmaker:
    version: "13.1.3"
    versions:
      - "13.1.3"
      - "11.1.2"

development_tools:
  visual_studio:
    version: "2022"

  dspace:
    version: "2024a"
    product: "ConfigurationDesk 2024-A"
    release: "24.1"

  matlab:
    version: "2024a"

The build system reads this file to:

  • Determine which CarMaker versions to build

  • Generate version-specific BuildConfig files

  • Locate correct tool installations

  • Create version-specific output artifacts

Release Builds

A release build compiles all components and packages them into the build/ directory for distribution.

Running a Release Build

dispatch.bat

What Gets Built

The release build process executes the following steps:

  1. External Libraries (1_external_libraries.bat)

    • yaml-cpp (YAML configuration parser)

    • libevent (not currently used, but available)

    • Built in both Debug and Release configurations

    • Output: CommonLib/yaml-cpp/build/, CommonLib/libevent/build/

  2. Core Components (2_core_components.bat)

    • TrafficLayer.exe - Main interface executable

    • CoordMerge.exe - Coordinated merge controller

    • VirtualEnvironment.lib - Shared library for virtual environment integration

    • Output: Component directories + copied to build/

  3. VISSIM Components (3_vissim_components.bat)

    • DriverModel_RealSim.dll - VISSIM 2022 driver model

    • DriverModel_RealSim_v2021.dll - VISSIM 2021 driver model

    • Output: ProprietaryFiles/VISSIMserver/ + copied to build/

  4. CarMaker Components (4a_carmaker_components.ps1)

    • Generates BuildConfig Python files for each CarMaker version

    • CarMaker.win64.exe - CarMaker Office executables

    • libcarmaker4sl.mexw64 - CarMaker for Simulink MEX files

    • Built for each version in dependencies.yaml (e.g., CM11, CM13)

    • Output: CarMaker/CM*/ + copied to build/CarMaker/

  5. dSPACE Libraries (4b_carmaker_dspace.ps1) - Optional

    • libRealSimDsLib_2024a_CM*.a - Version-specific dSPACE libraries

    • Only built if dSPACE ConfigurationDesk is detected

    • Built for each CarMaker version

    • Output: CommonLib/ + copied to build/CarMaker/

  6. MEX RealSimSocket (5_mex_realsim_socket.ps1) - Optional

    • RealSimSocket.mexw64 - MATLAB interface for socket communication

    • Only built if MATLAB is detected

    • Output: CommonLib/ + copied to build/

  7. Build Information (6_build_info.ps1)

    • Generates BUILD_INFO.txt with version information

    • Lists all built components and their versions

    • Output: build/BUILD_INFO.txt

Build Output Structure

After a successful release build, the build/ directory contains:

build/
├── BUILD_INFO.txt                    # Build metadata and versions
├── TrafficLayer.exe                  # Core interface
├── CoordMerge.exe                    # Controller
├── DriverModel_RealSim.dll           # VISSIM 2022 interface
├── DriverModel_RealSim_v2021.dll     # VISSIM 2021 interface
├── RealSimSocket.mexw64              # MATLAB MEX file
├── RealSim*.m                        # MATLAB helper scripts
├── CommonLib/                        # Helper libraries and headers
│   ├── *.h                           # Header files
│   └── *.cpp                         # Source files (selective)
└── CarMaker/                         # CarMaker components
    ├── CM11/                         # CarMaker 11.1.2 build
    │   ├── CarMaker.win64.exe
    │   └── libcarmaker4sl.mexw64
    ├── CM13/                         # CarMaker 13.1.3 build
    │   ├── CarMaker.win64.exe
    │   └── libcarmaker4sl.mexw64
    └── libRealSimDsLib_*.a           # dSPACE libraries (if built)

Development Builds

For active development, you can build individual components without running the full dispatch. This is faster and allows focused debugging.

Building Individual Components

Each component has its own build script in scripts/dispatch/:

1. External Libraries Only

scripts\dispatch\1_external_libraries.bat

Builds yaml-cpp and libevent. Only needed once or after clean builds.

2. Core Components Only

scripts\dispatch\2_core_components.bat

Builds TrafficLayer.exe, CoordMerge.exe, VirtualEnvironment.lib. Run this when modifying core C++ code.

3. VISSIM Components Only

scripts\dispatch\3_vissim_components.bat

Builds VISSIM driver model DLLs. Run this when modifying VISSIM interface code.

4. CarMaker Components Only

powershell -ExecutionPolicy Bypass -File scripts\dispatch\4a_carmaker_components.ps1

Builds CarMaker executables. Automatically:

  • Reads CarMaker versions from dependencies.yaml

  • Generates BuildConfig Python files

  • Builds for each detected version

  • Run this when modifying CarMaker integration code

5. dSPACE Libraries Only

powershell -ExecutionPolicy Bypass -File scripts\dispatch\4b_carmaker_dspace.ps1

Builds dSPACE libraries for CarMaker HIL integration. Run this when modifying dSPACE interface code.

6. MEX RealSimSocket Only

powershell -ExecutionPolicy Bypass -File scripts\dispatch\5_mex_realsim_socket.ps1

Builds MATLAB MEX file for socket communication. Run this when modifying MATLAB interface code.

Common Development Workflows

Scenario 1: Modified TrafficLayer C++ code

scripts\dispatch\2_core_components.bat

Scenario 2: Modified VISSIM driver model

scripts\dispatch\3_vissim_components.bat

Scenario 3: Modified CarMaker User.c or integration

powershell -ExecutionPolicy Bypass -File scripts\dispatch\4a_carmaker_components.ps1

Scenario 4: Testing full release package

dispatch.bat

Debug vs Release Configuration

The build system supports both Debug and Release configurations.

Release Configuration (Default)

Release builds are optimized for performance and distribution:

  • Compiler optimizations enabled

  • Debug symbols minimal or stripped

  • Default for dispatch.bat

  • Used for distributable builds in build/ directory

Debug Configuration

Debug builds include full debugging information:

  • No compiler optimizations

  • Full debug symbols

  • Easier to debug with Visual Studio debugger

  • Larger executable sizes

Switching to Debug Configuration

For Full Dispatch:

Edit scripts/dispatch/dispatch.bat line 17:

set "RS_BUILD_CONFIG=Debug"

For Individual Components:

Each component script checks the RS_BUILD_CONFIG environment variable:

set RS_BUILD_CONFIG=Debug
scripts\dispatch\2_core_components.bat

Or pass configuration directly to msbuild:

msbuild TrafficLayer\TrafficLayer.sln /p:Configuration=Debug /p:Platform=x64

External Libraries Debug Build

External libraries (yaml-cpp, libevent) are built in both Debug and Release configurations automatically:

  • Release: yaml-cpp.lib, event.lib

  • Debug: yaml-cppd.lib, eventd.lib

When building components in Debug mode, make sure to link against Debug libraries (yaml-cppd.lib).

Build System Architecture

Script Organization

scripts/dispatch/
├── dispatch.bat                     # Main orchestrator
├── detect_tool_paths.ps1            # Auto-detection of tools
├── yaml_helper.ps1                  # Parse dependencies.yaml
├── 1_external_libraries.bat         # Build yaml-cpp, libevent
├── 2_core_components.bat            # Build TrafficLayer, VirtualEnvironment
├── 3_vissim_components.bat          # Build VISSIM DLLs
├── 4a_carmaker_components.ps1       # Build CarMaker executables
├── 4b_carmaker_dspace.ps1           # Build dSPACE libraries
├── 5_mex_realsim_socket.ps1         # Build MATLAB MEX file
└── 6_build_info.ps1                 # Generate BUILD_INFO.txt

Tool Auto-Detection

The detect_tool_paths.ps1 script automatically locates installed tools:

Visual Studio Detection:

  • Searches for VS 2022 (Community, Professional, Enterprise)

  • Locates MSBuild.exe path

  • Validates C++ workload installation

MATLAB Detection:

  • Checks Windows registry: HKLM:\SOFTWARE\MathWorks\MATLAB

  • Searches common installation paths

  • Validates MEX compiler availability

  • Prioritizes version from dependencies.yaml

dSPACE Detection:

  • Searches Program Files for ConfigurationDesk

  • Locates version matching dependencies.yaml

  • Finds DsBuildLibrary.mk for library compilation

CarMaker Detection:

  • Searches Program Files for IPG installations

  • Identifies available CarMaker versions

  • Matches against versions in dependencies.yaml

BuildConfig Auto-Generation

CarMaker builds require a BuildConfig Python file that specifies compiler settings, include paths, and library dependencies. The build system automatically generates these:

Process:

  1. 4a_carmaker_components.ps1 reads dependencies.yaml

  2. For each CarMaker version (e.g., 11.1.2, 13.1.3):

    • Detects MATLAB version

    • Locates CarMaker installation

    • Generates RS_CM{major}_{minor}_{patch}_BuildConfig_{matlab}.py

  3. BuildConfig files are created in CarMaker/ directory

  4. CarMaker uses these during compilation

Generated BuildConfig Features:

  • Correct MATLAB version paths

  • RealSim-specific defines (RS_DSPACE, RS_DEBUG)

  • Include paths for VirEnv_Wrapper.h

  • Links to libRealSimDsLib_*.a (for dSPACE builds)

  • Architecture-specific settings (dsrtlx, dsrt64)

Manual Modifications (Advanced): If you need custom BuildConfig settings, you can:

  1. Generate BuildConfig using the script

  2. Manually edit the generated Python file

  3. Re-run CarMaker build

Note: Re-running 4a_carmaker_components.ps1 will regenerate and overwrite custom changes.

Troubleshooting

Build Failures

Problem: CMake not found

'cmake' is not recognized as an internal or external command

Solution: Install CMake and add to PATH, or restart command prompt after CMake installation.

Problem: MSBuild not found

'msbuild' is not recognized as an internal or external command

Solution:

  • Ensure Visual Studio 2022 is installed with C++ workload

  • Build scripts should auto-detect MSBuild

  • Manually add to PATH: %ProgramFiles%\Microsoft Visual Studio\2022\<Edition>\MSBuild\Current\Bin

Problem: yaml-cpp.lib not found during TrafficLayer build

LINK : fatal error LNK1181: cannot open input file 'yaml-cpp.lib'

Solution: Build external libraries first:

scripts\dispatch\1_external_libraries.bat

Problem: MATLAB MEX build fails

Error: Could not find MATLAB installation

Solution:

  • Ensure MATLAB is installed

  • Update dependencies.yaml with correct MATLAB version

  • Check MATLAB registry entries exist

  • Try specifying MATLAB path manually in 5_mex_realsim_socket.ps1

Problem: CarMaker build fails with missing include files

fatal error C1083: Cannot open include file: 'VirEnv_Wrapper.h'

Solution:

  • Ensure VirtualEnvironment.lib was built: scripts\dispatch\2_core_components.bat

  • Check that CommonLib/VirEnv_Wrapper.h exists

  • Verify BuildConfig includes correct paths

Problem: dSPACE library build fails

Error: Could not find dSPACE ConfigurationDesk

Solution:

  • This is optional - skip if you don’t need dSPACE HIL

  • Install dSPACE ConfigurationDesk matching version in dependencies.yaml

  • Ensure DsBuildLibrary.mk exists in dSPACE installation

Problem: Debug/Release mismatch errors

LNK2038: mismatch detected for 'RuntimeLibrary'

Solution:

  • Ensure all libraries built in same configuration (Debug or Release)

  • If building Debug, rebuild external libraries in Debug

  • Check that yaml-cppd.lib (Debug) or yaml-cpp.lib (Release) matches your build config

Checking Build Logs

Build logs are located in scripts/dispatch/:

  • build.log: Detailed compilation output from all build steps

  • build_summary.log: High-level summary of each component’s build status

Check these logs for detailed error messages if builds fail.

Verifying Tool Detection

To verify that tools are correctly detected, run:

powershell -ExecutionPolicy Bypass -File scripts\dispatch\detect_tool_paths.ps1

This will print detected paths for Visual Studio, MATLAB, dSPACE, and CarMaker.

Clean Builds

To perform a clean build:

  1. Delete the build/ directory

  2. Delete component-specific output directories:

    • TrafficLayer/x64/

    • VirtualEnvironment/x64/

    • ProprietaryFiles/VISSIMserver/x64/

    • CarMaker/CM*/src*/CarMaker.win64.exe

    • CarMaker/CM*/src*/libcarmaker4sl.mexw64

  3. Optionally delete external library builds:

    • CommonLib/yaml-cpp/build/

    • CommonLib/libevent/build/

  4. Run dispatch.bat

Common Build Order Issues

Components must be built in this order due to dependencies:

  1. External libraries (yaml-cpp) - Required by VirtualEnvironment

  2. VirtualEnvironment.lib - Required by CarMaker

  3. All other components - Can be built in any order

If you get linker errors, ensure you’ve built dependencies first.

Getting Help

If you encounter build issues not covered here:

  1. Check build logs: scripts/dispatch/build.log and build_summary.log

  2. Verify tool versions match dependencies.yaml

  3. Ensure all prerequisites are installed

  4. Try a clean build

  5. Contact: realsimxil@gmail.com