Building Real-Sim FIXS

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

Quick Start
Build System Overview
Prerequisites
Release Builds
Development Builds
Debug vs Release Configuration
Build System Architecture
Troubleshooting

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

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
CMake (version 3.10 or higher)
- Required for building external libraries (yaml-cpp, libevent)
- Must be in PATH
- Download from: https://cmake.org/download/

Optional Tools (for specific features)

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
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
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:

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/
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/
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/
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/
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/
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/
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:

4a_carmaker_components.ps1 reads dependencies.yaml
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
BuildConfig files are created in CarMaker/ directory
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:

Generate BuildConfig using the script
Manually edit the generated Python file
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:

Delete the build/ directory
Delete component-specific output directories:
- TrafficLayer/x64/
- VirtualEnvironment/x64/
- ProprietaryFiles/VISSIMserver/x64/
- CarMaker/CM*/src*/CarMaker.win64.exe
- CarMaker/CM*/src*/libcarmaker4sl.mexw64
Optionally delete external library builds:
- CommonLib/yaml-cpp/build/
- CommonLib/libevent/build/
Run dispatch.bat

Common Build Order Issues

Components must be built in this order due to dependencies:

External libraries (yaml-cpp) - Required by VirtualEnvironment
VirtualEnvironment.lib - Required by CarMaker
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:

Check build logs: scripts/dispatch/build.log and build_summary.log
Verify tool versions match dependencies.yaml
Ensure all prerequisites are installed
Try a clean build
Contact: realsimxil@gmail.com

FilesExpand file tree

BUILD.md

Latest commit

History

BUILD.md

File metadata and controls

Building Real-Sim FIXS

Table of Contents

Quick Start

Build System Overview

Prerequisites

Required Tools

Optional Tools (for specific features)

Configuration File

Release Builds

Running a Release Build

What Gets Built

Build Output Structure

Development Builds

Building Individual Components

1. External Libraries Only

2. Core Components Only

3. VISSIM Components Only

4. CarMaker Components Only

5. dSPACE Libraries Only

6. MEX RealSimSocket Only

Common Development Workflows

Debug vs Release Configuration

Release Configuration (Default)

Debug Configuration

Switching to Debug Configuration

For Full Dispatch:

For Individual Components:

External Libraries Debug Build

Build System Architecture

Script Organization

Tool Auto-Detection

BuildConfig Auto-Generation

Troubleshooting

Build Failures

Checking Build Logs

Verifying Tool Detection

Clean Builds

Common Build Order Issues

Getting Help