diff --git a/README.md b/README.md index 308c979ded5..24643df8390 100644 --- a/README.md +++ b/README.md @@ -1,178 +1,319 @@ -# Score Reference Integration +# Eclipse S-CORE Reference Integration -This workspace integrates multiple Eclipse Score modules (baselibs, communication, persistency, orchestrator, etc.) to validate cross-repository builds and detect integration issues early in the development cycle. +This workspace integrates multiple Eclipse S-CORE modules (baselibs, communication, persistency, orchestrator, etc.) to validate cross-repository builds and detect integration issues early in the development cycle. ## Overview -The reference integration workspace serves as a single Bazel build environment to: +The reference integration workspace serves as a unified Bazel build environment for: -- Validate cross-module dependency graphs -- Detect label and repository boundary issues -- Test toolchain and platform support (Linux, QNX, LLVM/GCC) -- Prepare for release validation workflows +- Validating cross-module dependency graphs and boundary issues +- Testing toolchain and platform support (Linux x86_64, QNX x86_64, Elektrobit corbos Linux aarch64, Red Hat AutoSD) +- Running Feature Integration Tests (FIT) and Integration Test Framework (ITF) tests +- Preparing for release validation and integration workflows -## Get started +For additional documentation covering repository workflows and platform-specific details, see the `docs/` directory. -Simply run `./score_starter` and select which integration You want to run. Once running, You will be guided by our welcome cli to run selected examples. +## Prerequisites -## Structure of repo +Install required system packages before building or running anything in this repository: -Intention for each folder is described below +```bash +sudo apt-get update +sudo apt-get install -y protobuf-compiler libclang-dev lcov qemu-system-x86 +``` -### bazel_common +For Docker, follow the [official Docker Engine install guide](https://docs.docker.com/engine/install/ubuntu/). -Used to keep a common bazel functionalities for `images` like: +## Quick Start -- toolchain setups -- common tooling deps -- common S-CORE modules deps -- common `.bzl` extensions needed to streamline images +Simply run: -### showcases +```bash +./score_starter +``` -Used to keep `S-CORE` wide **showcases** implementation to showcase S-CORE in certain deployments (images). Contains: +You will be guided interactively through available integrations, build options, and examples to run. -- proxy target bundling all `standalone` examples from all `S-CORE` repos to deploy then as single bazel target into image -- implementation of certain **showcases** that shall be deployed into images +## Run showcases -#### cli +Use the interactive helper or Bazel to run showcase binaries. Examples: -Contains a CLI tool to be used on runner that is showcasing the S-CORE functionality. It will provide superior user experience and will guide user to run examples. -How to use it in Your image, look [here] (./showcases/cli/README.md) +```bash +# Interactive helper +./score_starter -### images +# Run a CLI showcase (example target, may vary by workspace state) +bazel run //showcases/cli:cli -- --help +``` -Used to keep concrete `images` for given target platform as bazel modules. Each platform shall have it's own folder with name `{platform}_{arch}` ie. `qnx_aarch64`. +See [showcases/cli/README.md](showcases/cli/README.md) for CLI configuration and examples. -This `images` shall: +## Build and deploy showcases on Raspberry Pi (QNX aarch64) -- deploy all `showcases` into image so they can be run inside -- other specific code for given `image` +The `images/qnx_aarch64` image packages all S-CORE showcases into a bootable QNX 8.0 IFS (Image File System) for AArch64 targets. It can be run in QEMU for local development and testing, or deployed to a Raspberry Pi 4/5 for real hardware validation. -### runners +### Prerequisites -Used to keep thin logic ro reuse `runners` between images, like docker runner etc. +- **QNX SDP 8.0.0** — a licensed copy of the QNX Software Development Platform is required for cross-compilation. See the [QNX SDP product page](https://blackberry.qnx.com/en/products/foundation-software/qnx-software-development-platform). +- For RPi hardware: a **Raspberry Pi** (4 or later), microSD card, and the [QNX Raspberry Pi BSP](https://www.qnx.com/developers/docs/8.0/) — consult the BSP documentation for model-specific support and requirements. -## Docs +### Build the QNX aarch64 image -To generate a full documentation of all integrated modules, run: +Cross-compile all showcases and assemble the IFS image: ```bash -bazel run //:docs_combo_experimental +bazel build --config=qnx-aarch64 //images/qnx_aarch64:image ``` -## Operating system integrations +The built IFS image is written to: -> [!NOTE] -> Please refer to the README documents in the respective sub-directories for details about the specific integration. +``` +bazel-bin/images/qnx_aarch64/build/init +``` -- [QNX](./images/qnx_x86_64//README.md) -- [Red Hat AutoSD](./images/autosd_x86_64/build/README.md) -- [Elektrobit corbos Linux for Safety Applications](./images/ebclfsa_aarch64/README.md) -- Linux x86_64 +### Run in QEMU (development and testing) -## Workspace support +Before deploying to hardware, validate the image in QEMU: -You can obtain a complete S-CORE workspace, i.e. a git checkout of all modules from `known_good.json`, on the specific branches / commits, integrated into one Bazel build. -This helps with cross-module development, debugging, and generally "trying out things". +```bash +bazel run --config=qnx-aarch64 //images/qnx_aarch64:run +``` + +SSH into the running QEMU instance (no password required): + +```bash +ssh -p 2222 root@localhost +``` + +The showcases CLI starts automatically on boot. You can also launch it manually: + +```bash +/showcases/bin/cli +``` + +### Flash QNX on Raspberry Pi > [!NOTE] -> The startup of the [S-CORE devcontainer](https://github.com/eclipse-score/devcontainer) [integrated in this repository](.devcontainer/) already installs supported workspace managers and generates the required metadata. -> You can do this manually as well, of course (e.g. if you do not use the devcontainer). -> Take a look at `.devcontainer/prepare_workspace.sh`, which contains the setup script. +> The default `images/qnx_aarch64` image uses `startup-virt`, which is suitable for QEMU. Deploying to real RPi hardware requires replacing this with the board-specific startup binary from the QNX Raspberry Pi BSP. See the `TODO` comment in [`images/qnx_aarch64/build/init.build`](images/qnx_aarch64/build/init.build). + +General steps to create a bootable QNX SD card for Raspberry Pi: -### Initialization of the workspace +1. **Obtain the QNX Raspberry Pi BSP** from [BlackBerry QNX](https://blackberry.qnx.com/en/sdp8) and follow its *Getting Started* guide to install it under your QNX SDP. -1. Switch to local path overrides, using the VSCode Task (`Terminal`->`Run Task...`) "Switch Bazel modules to `local_path_overrides`". - Note that you can switch back to `git_overrides` (the default) using the task "Switch Bazel modules to `git_overrides`" +2. **Replace the startup binary** in `images/qnx_aarch64/build/init.build`: substitute `startup-virt` with the RPi-specific startup binary provided by the BSP (consult the BSP documentation for the correct binary name for your RPi model). - **Command line:** +3. **Rebuild the image** (see [Build the QNX aarch64 image](#build-the-qnx-aarch64-image) above). + +4. **Prepare the SD card** following the QNX BSP instructions. This typically involves creating a boot partition and copying the QNX IFS image to it: ```bash - python3 scripts/known_good/update_module_from_known_good.py --override-type local_path + # Copy the IFS image to the SD card boot partition (exact path depends on your BSP layout) + cp bazel-bin/images/qnx_aarch64/build/init /media/$USER/boot/qnx-image.ifs + sync && umount /media/$USER/boot ``` -2. Update workspace metadata from known good, using the VSCode Task "Update workspace metadata from known good". - This will generate the `.gita-workspace.csv` file based on `known_good.json`. +5. **Insert the SD card** into the RPi and power it on. QNX boots and starts all services defined in [`images/qnx_aarch64/configs/startup.sh`](images/qnx_aarch64/configs/startup.sh). + +### Deploy and run showcases on Raspberry Pi - **Command line:** +Once QNX is running on the RPi: + +1. **Find the RPi IP address** — the system acquires an address via DHCP on the `vtnet0` interface at startup (configured in [`configs/network_setup_dhcp.sh`](images/qnx_aarch64/configs/network_setup_dhcp.sh)). Check your router's DHCP table or connect a serial console to read the address from the boot log. + +2. **SSH into the RPi** (root, no password — see [`configs/sshd_config`](images/qnx_aarch64/configs/sshd_config)): ```bash - python3 scripts/known_good/known_good_to_workspace_metadata.py + ssh root@ ``` -3. Run VSCode Task "<Name>: Generate workspace", e.g. "Gita: Generate workspace". - This will clone all modules using the chosen workspace manager. - The modules will be in sub-directories starting with `score_`. - Note that the usage of different workspace managers is mutually exclusive. +3. **Showcases are pre-loaded** in `/showcases/bin/`. The interactive CLI is started automatically on boot (see [`configs/startup.sh`](images/qnx_aarch64/configs/startup.sh)). Re-launch it at any time: - **Command line:** + ```bash + /showcases/bin/cli + ``` + +4. **Run a specific showcase** by following the CLI prompts, or invoke a binary directly. For example, to run the lifecycle management example (from [`showcases/simple_lifecycle`](showcases/simple_lifecycle)): ```bash - gita clone --preserve-path --from-file .gita-workspace.csv + /showcases/bin/launch_manager ``` -When you now run Bazel, it will use the local working copies of all modules and not download them from git remotes. -You can make local changes to each module, which will be directly reflected in the next Bazel run. +5. **View system logs**: -## Known Issues ⚠️ + ```bash + slog2info + ``` -### Communication +## Run tests -**Module:** `score/mw/com/requirements` +Run Feature Integration Tests (FIT) and Integration Test Framework (ITF) with Bazel. Common examples: -**Issues when building from external repository:** +```bash +# Run all FIT tests (Rust + C++) +bazel test --config=linux-x86_64 //feature_integration_tests/test_cases:fit --test_output=streamed -1. **Label inconsistency:** Some `BUILD` files use `@//third_party` instead of `//third_party` (repository-qualified vs. local label). Should standardize on local labels within the module. -2. **Outdated path reference:** `runtime_test.cpp:get_path` checks for `safe_posix_platform` (likely obsolete module name) instead of `external/score_communication+/`. +# Run only Rust scenarios listing +bazel run //feature_integration_tests/test_scenarios/rust:rust_test_scenarios -- --list-scenarios -### Coverage +# Run ITF tests on Docker (Linux) +bazel test --config=linux-x86_64 //feature_integration_tests/itf --test_output=streamed -Running coverage has to be executed on Ubuntu 22.04, newer versions are not supported and might have issues. +# Run ITF tests on QNX (uses the itf-qnx-x86_64 test config) +bazel test --config=itf-qnx-x86_64 //feature_integration_tests/itf --test_output=streamed +``` -## System Dependencies +Notes: +- Use `--config=` to select the correct toolchain/platform (supported configs for tests: `linux-x86_64`, `qnx-x86_64`). See `.bazelrc` for all available configs. +- For streaming test output and real-time logs, use `--test_output=streamed` or `--test_output=all`. -Install the following system packages: +## Repository Structure -```bash -sudo apt-get update -sudo apt-get install -y protobuf-compiler libclang-dev lcov -``` +Intention for each folder is described below. + +### `bazel_common/` + +Common Bazel configurations and macros used across the workspace: +- Toolchain setups (GCC, Rust, QNX) +- S-CORE module dependency versions +- Bazel extensions and bundling macros + +### `feature_integration_tests/` -## Proxy & External Dependencies 🌐 +Feature Integration Tests and test scenarios: +- **`test_cases/`**: Python test orchestration and fixtures +- **`test_scenarios/`**: Rust and C++ scenario implementations +- **`itf/`**: Integration Test Framework (QEMU/Docker-based platform tests) +- **`configs/`**: DLT, QEMU, and target-specific configurations -### Current Issue +### `showcases/` -The `starpls.bzl` file ([source](https://github.com/eclipse-score/tooling/blob/main/starpls/starpls.bzl)) uses `curl` directly for downloading dependencies, which: +Eclipse S-CORE demonstration applications and examples: +- **`cli/`**: Interactive CLI tool for running examples on deployed systems +- **`standalone/`**: Standalone example binaries (communication, persistence, etc.) +- **`orchestration_persistency/`**: Multi-module orchestration examples +- **`simple_lifecycle/`**: Basic lifecycle management examples -- Bypasses Bazel's managed fetch lifecycle and dependency tracking -- Breaks reproducibility and remote caching expectations -- May fail in corporate proxy-restricted environments +Configuration for CLI autodiscovery is in `name.score.json` files; see [showcases/cli/README.md](showcases/cli/README.md) for details. -### Workaround +### `images/` -Use a `local_path_override` and configure proxy environment variables before building: +Platform-specific target images bundling S-CORE artifacts and showcases: +- **`linux_x86_64/`**: Linux x86_64 Docker image +- **`qnx_x86_64/`**: QNX x86_64 QEMU image +- **`qnx_aarch64/`**: QNX 8.0 aarch64 image — QEMU or Raspberry Pi 4/5 (see [Build and deploy showcases on Raspberry Pi](#build-and-deploy-showcases-on-raspberry-pi-qnx-aarch64)) +- **`ebclfsa_aarch64/`**: Elektrobit corbos Linux for Safety Applications (aarch64) (see [images/ebclfsa_aarch64/README.md](images/ebclfsa_aarch64/README.md)) +- **`autosd/`**: Red Hat AutoSD x86_64 + +### `runners/` + +Thin abstraction layers for Docker and QEMU execution: +- Centralized logic for spawning and interacting with target environments +- Reusable across multiple image definitions + +## Documentation + +For documentation covering repository workflows, testing frameworks, and platform-specific details, see the `docs/` directory and these entry points: + +- **[Feature Integration Tests](feature_integration_tests/README.md)** — FIT and ITF test framework usage +- **[CLI Documentation](showcases/cli/README.md)** — CLI tool configuration and usage +- **Platform-Specific Guides:** + - [Elektrobit corbos Linux (aarch64)](images/ebclfsa_aarch64/README.md) + - [QNX aarch64 / Raspberry Pi](#build-and-deploy-showcases-on-raspberry-pi-qnx-aarch64) + +To generate HTML documentation for all integrated modules: ```bash -export http_proxy=http://127.0.0.1:3128 -export https_proxy=http://127.0.0.1:3128 -export HTTP_PROXY=http://127.0.0.1:3128 -export HTTPS_PROXY=http://127.0.0.1:3128 +bazel run //:docs_combo_experimental ``` -Add this to your `MODULE.bazel`: +## Supported Platforms -```python -local_path_override(module_name = "score_tooling", path = "../tooling") -``` +Integration and deployment platforms for S-CORE: + +- **QNX x86_64** — QNX RTOS integration (QEMU-based testing) +- **QNX aarch64 (RPi)** — QNX 8.0 on Raspberry Pi 4/5 or QEMU aarch64; see [Build and deploy showcases on Raspberry Pi](#build-and-deploy-showcases-on-raspberry-pi-qnx-aarch64) +- **[Elektrobit corbos Linux for Safety Applications (aarch64)](images/ebclfsa_aarch64/README.md)** — Safety-critical automotive Linux +- **Red Hat AutoSD (x86_64)** — Automotive system development +- **Linux x86_64** — Standard Linux development and testing (Docker-based) + +## Multi-Module Development Workspace + +For cross-module development, you can obtain a complete S-CORE workspace—a local git checkout of all modules pinned in `known_good.json` on specific branches/commits—integrated into a single Bazel build. + +This enables: +- Cross-module development and debugging +- Testing changes across multiple modules simultaneously +- Reproducible builds with pinned versions + +> [!NOTE] +> The [S-CORE devcontainer](https://github.com/eclipse-score/devcontainer) [integrated in this repository](.devcontainer/) pre-installs workspace managers and generates required metadata. +> Manual setup is also possible; see `.devcontainer/prepare_workspace.sh` for the setup script. + +### Initialization Steps + +1. **Switch to local path overrides:** + + Use the VS Code Task (`Terminal` → `Run Task...`): **"Switch Bazel modules to `local_path_overrides`"** + + Command line: + ```bash + python3 scripts/known_good/update_module_from_known_good.py --override-type local_path + ``` + + To revert to git overrides: + ```bash + python3 scripts/known_good/update_module_from_known_good.py --override-type git + ``` + +2. **Update workspace metadata from known good:** + + Use the VS Code Task: **"Update workspace metadata from known good"** + + Command line: + ```bash + python3 scripts/known_good/known_good_to_workspace_metadata.py + ``` + +3. **Clone all modules:** + + Use the VS Code Task: **"Gita: Generate workspace"** + + Command line (using gita): + ```bash + gita clone --preserve-path --from-file .gita-workspace.csv + ``` + +Modules are cloned into subdirectories prefixed with `score_` (e.g., `score_persistency/`, `score_communication/`). + +When running Bazel, it will use these local working copies, and your changes will be immediately reflected in the next build. + +## Known Issues ⚠️ -## IDE support +For a comprehensive list of known issues, limitations, and troubleshooting guidance, see the `docs/` directory. + +### Communication Module + +**Module:** `score/mw/com/requirements` + +**Integration issues when building from external repository:** + +1. **Label inconsistency**: Some `BUILD` files use `@//third_party` instead of `//third_party` (repository-qualified vs. local labels). Should standardize on local labels. +2. **Outdated path reference**: `runtime_test.cpp:get_path` checks for obsolete `safe_posix_platform` instead of the current module path structure. + +## IDE Support ### Rust -Use `scripts/generate_rust_analyzer_support.sh` to generate rust_analyzer settings that will let VS Code work. +To enable VS Code Rust analyzer support: + +```bash +scripts/generate_rust_analyzer_support.sh +``` + +This generates the necessary Rust analyzer configuration for the workspace. + +## Internal Tooling -## Internal tooling +Internal tooling scripts are currently under development to provide a unified interface for repository operations. -Internal tooling scripts are currently under development to provide user single point of interaction with all -created goods. More detailed readme can be found in scripts: [Tooling README](scripts/tooling/README.md) +For detailed documentation, see [scripts/tooling/README.md](scripts/tooling/README.md). diff --git a/feature_integration_tests/README.md b/feature_integration_tests/README.md index a68a1f9c492..6f9ced5daf9 100644 --- a/feature_integration_tests/README.md +++ b/feature_integration_tests/README.md @@ -36,6 +36,18 @@ bazel test //feature_integration_tests/test_cases:fit_rust bazel test --config=linux-x86_64 //feature_integration_tests/test_cases:fit_cpp ``` +## Quick try + +Run a quick smoke of the FIT harness (lists scenarios or runs a small subset): + +```bash +# List available Rust scenarios +bazel run //feature_integration_tests/test_scenarios/rust:rust_test_scenarios -- --list-scenarios + +# Run all FIT tests (streaming output) +bazel test --config=linux-x86_64 //feature_integration_tests/test_cases:fit --test_output=streamed +``` + ### ITF Tests (QEMU-based) ITF tests run on a QEMU target and require the `itf-qnx-x86_64` config: diff --git a/showcases/cli/README.md b/showcases/cli/README.md index 65d5d4e5955..69b0ea4b535 100644 --- a/showcases/cli/README.md +++ b/showcases/cli/README.md @@ -63,4 +63,16 @@ Alternatively, the configuration file can contain a top-level array of configs, ] ``` -You can customize where to look for examples using env `SCORE_CLI_INIT_DIR`. \ No newline at end of file +You can customize where to look for examples using env `SCORE_CLI_INIT_DIR`. + +## Quick run + +Build and run the CLI example with Bazel: + +```bash +# Show CLI help +bazel run //showcases/cli:cli -- --help + +# Run CLI using the dev helper +./score_starter +``` \ No newline at end of file