# wind-river/vxworks7-ros2-build architecture

> Architecture diagram of the GitHub repository wind-river/vxworks7-ros2-build, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/wind-river/vxworks7-ros2-build
- Repository: https://github.com/wind-river/vxworks7-ros2-build

## Overview

##### Project type and purpose
- This is a build‐automation and packaging toolchain for cross‐compiling ROS 2 on the VxWorks 7 RTOS. It provides:
- A GitHub repository with Makefiles, CMake toolchains, patches, and a “pkg” directory of third‐party packages
- Docker images and entrypoints to host the build
- CI/CD workflows (GitHub Actions) to produce prebuilt images and artifacts
- QEMU and Raspberry Pi targets for testing

##### File structure
- Top‐level:
- .github (CI workflows + custom Actions)
- Docker (Ubuntu 18.04 & 22.04 images for vxbuild and vxros2build)
- buildspecs (CMake toolchain definitions for cross‐compile)
- mk (shared Make rules)
- pkg (subdirectories for each dependency: asio, colcon, eigen, ros2, turtlebot3, unixextra, sdk, etc.)
- tests (expect scripts driving QEMU/emulator tests)
- Makefile, README.md
- “pkg” is a plugin‐style directory: each subfolder contains its own Makefile/patches, consumed by the master Makefile.
- Dockerfiles define the build environment (wruser, environment variables, entrypoints).

##### README for additional insights
- The project orchestrates:
- Downloading a VxWorks SDK (local volume mount)
- Building each pkg via Make/CMake inside Docker (/work/pkg → /work/output/build)
- Exporting artifacts (/work/output/export/{root,deploy})
- Optionally assembling a QEMU disk image and launching vxWorks for smoke tests
- CI workflows automate Docker image builds and publish prebuilt artifacts.

a. Main components
1. Developer Host
2. Git Repository & CI (GitHub, Actions)
3. Docker Engine
4. Docker Containers
– vxbuild image (installs SDK, host tools)
– vxros2build image (ROS 2 dependencies + colcon + entrypoint)
5. VxWorks SDK Volume
6. Source Code (this repo)
7. Build Orchestrator
– Makefile + mk/*.mk
– CMake toolchain (buildspecs/cmake/toolchain.cmake)
– colcon (for ROS 2 workspace)
8. Package Modules (pkg/*)
9. External Git/Bitbucket (ROS 2, patches, upstream packages)
10. Build Output
– output/build (per‐pkg artifacts)
– output/downloads (third‐party sources)
– output/export/root & deploy (install trees)
11. Test Harness
– QEMU emulator or Raspberry Pi target
– tests/*.exp scripts driving smoke tests

b. Relationships and interactions
– Developer → Git Repo (clone/push)
– GitHub Actions → Docker build (ci pipelines)
– Developer & CI → Docker Engine (build images, run containers)
– Docker Container mounts:
- /wrsdk (VxWorks SDK)
- /work (source tree)
– Inside container:
- Make orchestrates pkg builds (reads mk rules, calls CMake, colcon)
- Downloads upstream sources (git://github.com, bitbucket) into output/downloads
- Applies patches from layer repo into output/build/ros2/patches
– Builds ROS 2 workspace via colcon → output/build/ros2/ros2_ws
– Build Output flows into:
- export/root (headers, dev artifacts)
- export/deploy (binaries, libs, vxscript)
– Test Harness:
- Create IMG via dd + mkfs → mount export/deploy → copy → boot QEMU
- tests/*.exp run through telnet or serial to exercise examples

c. Architectural patterns & design principles
– Layered / plugin architecture: “pkg” modules are loosely coupled, defined by Makefiles
– “Orchestrator” pattern: a top‐level Makefile delegates to sub‐packages
– Containerization: isolate host dependencies via Docker images
– Infrastructure as Code: CI workflows define repeatable pipelines

d. Key technologies & frameworks
– GitHub Actions (CI/CD)
– Docker & Dockerfiles
– Make + mk/*.mk (build orchestrator)
– CMake toolchain (cross‐compile)
– colcon (ROS 2 build tool)
– QEMU / Raspberry Pi (runtime tester)
– Python scripts (Wget/Curl automations, custom GitHub Action)

##### Detail level & separation
- Break the system into:
1. Source & CI layer
2. Containerized build environment layer
3. Orchestrator & pkg module layer
4. Output & packaging layer
5. Test & deployment layer
- Data flows: code → build → artifacts → test.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Source & CI Layer
    subgraph "Source & CI Layer"
        Developer["Developer Host"]:::external
        GitHub["Git Repository"]:::external
        CI["CI/CD (GitHub Actions)"]:::external
    end

    %% Containerized Build Environment Layer
    subgraph "Containerized Build Environment"
        DockerEngine["Docker Engine"]:::orchestrator
        subgraph "Docker Containers"
            VX18_04_VXBUILD["vxbuild (Ubuntu 18.04)"]:::container
            VX18_04_VXROS2["vxros2build (Ubuntu 18.04)"]:::container
            VX22_04_VXBUILD["vxbuild (Ubuntu 22.04)"]:::container
            VX22_04_VXROS2["vxros2build (Ubuntu 22.04)"]:::container
        end
    end

    %% Volumes
    SDKVolume["VxWorks SDK Volume"]:::volume
    SourceCode["Source Code Volume"]:::volume

    %% Orchestrator & pkg module Layer
    subgraph "Orchestrator & pkg Modules"
        MakefileNode["Makefile + mk rules"]:::orchestrator
        CMakeToolchain["CMake Toolchain"]:::orchestrator
        Colcon["colcon (ROS 2 Workspace)"]:::orchestrator
        subgraph "Package Modules (pkg/*)"
            ASIO["pkg/asio"]:::pkg
            COLCON_PKG["pkg/colcon"]:::pkg
            EIGEN["pkg/eigen"]:::pkg
            LIBXML2["pkg/libxml2"]:::pkg
            SDK_PKG["pkg/sdk"]:::pkg
            ROS2_PKG["pkg/ros2"]:::pkg
        end
    end

    %% Output & Packaging Layer
    subgraph "Build Output & Packaging"
        BuildOut["output/build"]:::output
        DownloadOut["output/downloads"]:::output
        ExportRoot["export/root"]:::output
        ExportDeploy["export/deploy"]:::output
    end

    %% Test & Deployment Layer
    subgraph "Test Harness"
        QEMU["QEMU / Raspberry Pi Target"]:::test
        TestScripts["tests/*.exp Scripts"]:::test
    end

    %% Connections - Source & CI to Container
    Developer -->|clone/push| GitHub
    GitHub -->|trigger workflows| CI
    CI -->|build images/run containers| DockerEngine
    Developer -->|docker run| DockerEngine

    %% Volumes mounted into containers
    DockerEngine -->|mount /wrsdk| SDKVolume
    DockerEngine -->|mount /work| SourceCode

    DockerEngine --> VX18_04_VXBUILD
    DockerEngine --> VX18_04_VXROS2
    DockerEngine --> VX22_04_VXBUILD
    DockerEngine --> VX22_04_VXROS2

    %% Inside containers orchestrator flows
    VX18_04_VXROS2 --> MakefileNode
    VX22_04_VXROS2 --> MakefileNode
    MakefileNode --> CMakeToolchain
    MakefileNode --> Colcon
    MakefileNode --> ASIO
    MakefileNode --> COLCON_PKG
    MakefileNode --> EIGEN
    MakefileNode --> LIBXML2
    MakefileNode --> SDK_PKG
    MakefileNode --> ROS2_PKG

    %% Build Output flows
    MakefileNode --> BuildOut
    MakefileNode --> DownloadOut
    BuildOut --> ExportRoot
    BuildOut --> ExportDeploy

    %% Test Harness flows
    ExportDeploy --> QEMU
    QEMU --> TestScripts

    %% Click Events
    click CI "https://github.com/wind-river/vxworks7-ros2-build/blob/master/.github/workflows/docker-build.yaml"
    click CI "https://github.com/wind-river/vxworks7-ros2-build/blob/master/.github/workflows/vxworks-ros2-build.yaml"
    click SDKVolume "https://github.com/wind-river/vxworks7-ros2-build/blob/master/.github/actions/setup-wrsdk/action.yml"
    click VX18_04_VXBUILD "https://github.com/wind-river/vxworks7-ros2-build/tree/master/Docker/18.04/vxbuild/Dockerfile"
    click VX18_04_VXBUILD "https://github.com/wind-river/vxworks7-ros2-build/blob/master/Docker/18.04/vxbuild/docker-entrypoint.sh"
    click VX18_04_VXROS2 "https://github.com/wind-river/vxworks7-ros2-build/tree/master/Docker/18.04/vxros2build/Dockerfile"
    click VX22_04_VXBUILD "https://github.com/wind-river/vxworks7-ros2-build/tree/master/Docker/22.04/vxbuild/Dockerfile"
    click VX22_04_VXBUILD "https://github.com/wind-river/vxworks7-ros2-build/blob/master/Docker/22.04/vxbuild/docker-entrypoint.sh"
    click VX22_04_VXROS2 "https://github.com/wind-river/vxworks7-ros2-build/tree/master/Docker/22.04/vxros2build/Dockerfile"
    click CMakeToolchain "https://github.com/wind-river/vxworks7-ros2-build/blob/master/buildspecs/cmake/toolchain.cmake"
    click CMakeToolchain "https://github.com/wind-river/vxworks7-ros2-build/blob/master/buildspecs/cmake/Platform/VxWorks.cmake"
    click MakefileNode "https://github.com/wind-river/vxworks7-ros2-build/tree/master/Makefile"
    click MakefileNode "https://github.com/wind-river/vxworks7-ros2-build/blob/master/mk/usr/defs.crossbuild.mk"
    click ASIO "https://github.com/wind-river/vxworks7-ros2-build/tree/master/pkg/asio/Makefile"
    click COLCON_PKG "https://github.com/wind-river/vxworks7-ros2-build/tree/master/pkg/colcon/Makefile"
    click EIGEN "https://github.com/wind-river/vxworks7-ros2-build/tree/master/pkg/eigen/Makefile"
    click LIBXML2 "https://github.com/wind-river/vxworks7-ros2-build/tree/master/pkg/libxml2/Makefile"
    click SDK_PKG "https://github.com/wind-river/vxworks7-ros2-build/tree/master/pkg/sdk/Makefile"
    click ROS2_PKG "https://github.com/wind-river/vxworks7-ros2-build/tree/master/pkg/ros2/Makefile"
    click TestScripts "https://github.com/wind-river/vxworks7-ros2-build/blob/master/tests/main_script.exp"

    %% Styles
    classDef external fill:#f9f,stroke:#333,stroke-width:1px
    classDef orchestrator fill:#ccf,stroke:#333,stroke-width:1px
    classDef container fill:#cfc,stroke:#333,stroke-width:1px
    classDef volume fill:#fcf,stroke:#333,stroke-width:1px
    classDef pkg fill:#cff,stroke:#333,stroke-width:1px
    classDef output fill:#ffc,stroke:#333,stroke-width:1px
    classDef test fill:#fdf,stroke:#333,stroke-width:1px
```
