From e8b3f0cb806669177a06ba58d256ed0379773bc5 Mon Sep 17 00:00:00 2001 From: Ryan Steel Date: Wed, 15 Jul 2026 14:43:24 +0000 Subject: [PATCH 1/3] docs: update readme --- README.md | 244 +++++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 175 insertions(+), 69 deletions(-) diff --git a/README.md b/README.md index 1e8af750..cf3b8fd5 100644 --- a/README.md +++ b/README.md @@ -1,114 +1,220 @@ +# Time -# C++ & Rust Bazel Template Repository +Unified time service library and distributed time synchronization infrastructure for automotive ECU software. -This repository serves as a **template** for setting up **C++ and Rust projects** using **Bazel**. -It provides a **standardized project structure**, ensuring best practices for: +[![Documentation](https://img.shields.io/badge/docs-time-blue)](https://eclipse-score.github.io/time) -- **Build configuration** with Bazel. -- **Testing** (unit and integration tests). -- **Documentation** setup. -- **CI/CD workflows**. -- **Development environment** configuration. +## Overview + +Portable and high-performance implementation of time services for the S-CORE project. + +This repository contains source code for time clocks, time distribution infrastructure, and PTP synchronization. The Time module is implemented in C++ and provides working examples demonstrating usage patterns. + +High-level functionality provided by the Time module: + +- **Clock Domains**: Four time sources accessed through unified `Clock` API + - **SystemTime**: Wall-clock time (Unix epoch) for timestamps and user-visible time displays + - **SteadyTime**: Monotonic time for duration measurements and timeouts + - **HighResSteadyTime**: High-precision monotonic time for precise timing applications + - **VehicleTime**: PTP-synchronized time for distributed automotive applications requiring initialization +- **Unified API**: Type-safe `Clock::GetInstance().Now()` returns `ClockSnapshot` with atomic time + metadata reads +- **Event Subscription**: `Subscribe()` / `Unsubscribe()` for status changes and PTP protocol data +- **Time Infrastructure** + - **TimeDaemon**: Plugin-based time distribution daemon with IPC message broker + - **TimeSlave**: PTP protocol implementation with offset calculation and rate adjustment +- **Test Utilities**: Mock backends and `ScopedClockOverride` for comprehensive testing + +All clock domains support nanosecond precision and compile-time domain selection preventing cross-domain timing errors. + +--- + +## 📋 Public API + +### Clock Domains + +#### SystemTime + +| Target | Purpose | +|--------|---------| +| `//score/time/system_time` | Wall-clock time (Unix epoch) for timestamps | +| `//score/time/system_time:system_time_mock` | Mock backend for SystemTime testing | +| `//score/time/system_time:interface` | Header-only interface (no backend) | + +#### SteadyTime + +| Target | Purpose | +|--------|---------| +| `//score/time/steady_time` | Monotonic time for duration measurement | +| `//score/time/steady_time:steady_time_mock` | Mock backend for SteadyTime testing | +| `//score/time/steady_time:interface` | Header-only interface (no backend) | + +#### HighResSteadyTime + +| Target | Purpose | +|--------|---------| +| `//score/time/high_res_steady_time` | High-precision monotonic time | +| `//score/time/high_res_steady_time:high_res_steady_time_mock` | Mock backend for HighResSteadyTime testing | +| `//score/time/high_res_steady_time:interface` | Header-only interface (no backend) | + +#### VehicleTime + +| Target | Purpose | +|--------|---------| +| `//score/time/vehicle_time` | PTP-synchronized vehicle time | +| `//score/time/vehicle_time:vehicle_time_mock` | Mock backend for VehicleTime testing | +| `//score/time/vehicle_time:interface` | Header-only interface (no backend) | + +### Time Infrastructure + +| Target | Purpose | +|--------|---------| +| `//score/time_daemon:time_daemon` | TimeDaemon binary for time distribution | +| `//score/time_slave:time_slave` | TimeSlave binary for PTP synchronization | + +### Test Utilities + +| Target | Purpose | +|--------|---------| +| `//score/time/clock:clock_test_utils` | ScopedClockOverride and ClockTestFactory utilities | + +--- + +## ⚙️ Using as Dependency + +Add to your `MODULE.bazel`: + +```python +bazel_dep(name = "score_time", version = "x.x.x") +``` + +Check available versions in the [S-CORE Bazel Registry](https://github.com/eclipse-score/bazel_registry/tree/main/modules/score_time). + +### Using Unreleased Versions + +To depend on an unreleased version (for development or testing), use a git override in your `MODULE.bazel`: + +```python +git_override( + module_name = "score_time", + commit = "abc123...", + remote = "https://github.com/eclipse-score/time.git", +) +``` + +Replace the `commit` value with the specific git hash you want to use. --- -## 📂 Project Structure - -| File/Folder | Description | -| ----------------------------------- | ------------------------------------------------- | -| `README.md` | Short description & build instructions | -| `src/` | Source files for the module | -| `tests/` | Unit tests (UT) and integration tests (IT) | -| `examples/` | Example files used for guidance | -| `docs/` | Documentation (Doxygen for C++ / mdBook for Rust) | -| `.github/workflows/` | CI/CD pipelines | -| `.vscode/` | Recommended VS Code settings | -| `.bazelrc`, `MODULE.bazel`, `BUILD` | Bazel configuration & settings | -| `project_config.bzl` | Project-specific metadata for Bazel macros | -| `LICENSE.md` | Licensing information | -| `CONTRIBUTION.md` | Contribution guidelines | +## 📖 Documentation + +- **[Time Feature Documentation](https://eclipse-score.github.io/score/main/features/time/index.html)**: High-level feature overview and S-CORE platform integration +- **[Time Module Documentation](https://eclipse-score.github.io/time)**: Detailed API documentation, architecture, and requirements + +Generate module documentation locally: + +```bash +bazel run //:docs +``` --- ## 🚀 Getting Started +This section contains information on how to build and use the Time module. + ### 1️⃣ Clone the Repository -```sh -git clone https://github.com/eclipse-score/YOUR_PROJECT.git -cd YOUR_PROJECT +```bash +git clone https://github.com/eclipse-score/time.git +cd time ``` -### 2️⃣ Build the Examples of module +### 2️⃣ Prerequisites -> DISCLAIMER: Depending what module implements, it's possible that different -> configuration flags needs to be set on command line. +- **C++ Compiler**: gcc/clang with C++17 support +- **Build System**: Bazel 8+ (managed via Bazelisk) +- **Operating System**: Linux (Ubuntu 24.04+) +- **Dependencies**: S-CORE Baselibs, Google Test +- **For QNX targets**: QNX 8.0 SDP -To build all targets of the module the following command can be used: +### 3️⃣ Development Environment -```sh -bazel build //src/... -``` +Follow the [S-CORE Development Environment Guide](https://eclipse-score.github.io/score/main/contribute/development/development_environment.html) for Linux host setup requirements. -This command will instruct Bazel to build all targets that are under Bazel -package `src/`. The ideal solution is to provide single target that builds -artifacts, for example: +### 4️⃣ Building the Project -```sh -bazel build //src/:release_artifacts +Build all components for **Linux x86_64** by running: + +```bash +bazel build //... ``` -where `:release_artifacts` is filegroup target that collects all release -artifacts of the module. +Run all tests: -> NOTE: This is just proposal, the final decision is on module maintainer how -> the module code needs to be built. +```bash +bazel test //... +``` -### 3️⃣ Run Tests +#### Other Platforms -```sh -bazel test //tests/... +**Linux AArch64**: +```bash +bazel build --config=time-arm64-linux //... +bazel test --config=time-arm64-linux //... ``` ---- +**QNX x86_64**: +```bash +bazel build --config=time-x86_64-qnx //... +bazel test --config=time-x86_64-qnx //... +``` -## 🛠 Tools & Linters +**QNX AArch64**: +```bash +bazel build --config=time-aarch64-qnx //... +bazel test --config=time-aarch64-qnx //... +``` + +#### Testing with Sanitizers -The template integrates **tools and linters** from **centralized repositories** to ensure consistency across projects. +To test with AddressSanitizer, UBSan, and LeakSanitizer enabled: -- **C++:** `clang-tidy`, `cppcheck`, `Google Test` -- **Rust:** `clippy`, `rustfmt`, `Rust Unit Tests` -- **CI/CD:** GitHub Actions for automated builds and tests +```bash +bazel test --config=time-x86_64-linux --config=asan_ubsan_lsan --build_tests_only //... +``` --- -## 📖 Documentation +## 💡 Examples -- A **centralized docs structure** is planned. +Working examples demonstrating clock usage patterns, testing approaches, and integration techniques. See [examples/](examples/) for complete usage examples. --- -## ⚙️ `project_config.bzl` +## 📂 Repository Structure -This file defines project-specific metadata used by Bazel macros, such as `dash_license_checker`. +``` +├── score/ +│ ├── time/ # Clock domains (SystemTime, SteadyTime, etc.) +│ ├── time_daemon/ # Time distribution daemon +│ ├── time_slave/ # PTP synchronization implementation +│ └── ts_client/ # Time status utilities (internal) +├── examples/ # Usage examples and patterns +├── docs/ # Module documentation +└── tools/ # Build and development utilities +``` -### 📌 Purpose +--- -It provides structured configuration that helps determine behavior such as: +## 🤝 Contributing -- Source language type (used to determine license check file format) -- Safety level or other compliance info (e.g. ASIL level) +See our [Contributing Guide](CONTRIBUTION.md) for contribution guidelines and development workflow. -### 📄 Example Content +--- -```python -PROJECT_CONFIG = { - "asil_level": "QM", # or "ASIL-A", "ASIL-B", etc. - "source_code": ["cpp", "rust"] # Languages used in the module -} -``` +## 🔗 Support -### 🔧 Use Case +### Community -When used with macros like `dash_license_checker`, it allows dynamic selection of file types - (e.g., `cargo`, `requirements`) based on the languages declared in `source_code`. +- **Issues**: Report bugs and request features via [GitHub Issues](https://github.com/eclipse-score/time/issues) +- **Discussions**: Join time [Slack Channel](https://sdvworkinggroup.slack.com/archives/C0ADTA4SKUH) From 6fb12b96e7ed91b12de43d55a219aae4474ee3a3 Mon Sep 17 00:00:00 2001 From: Ryan Steel Date: Wed, 15 Jul 2026 15:53:32 +0100 Subject: [PATCH 2/3] retrigger CI From ca1e0976bdce441cf1c25984f9637ff41d3d3dcd Mon Sep 17 00:00:00 2001 From: Ryan Steel Date: Thu, 16 Jul 2026 09:53:54 +0000 Subject: [PATCH 3/3] chore: update bazel registry link --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index cf3b8fd5..3315abab 100644 --- a/README.md +++ b/README.md @@ -87,7 +87,7 @@ Add to your `MODULE.bazel`: bazel_dep(name = "score_time", version = "x.x.x") ``` -Check available versions in the [S-CORE Bazel Registry](https://github.com/eclipse-score/bazel_registry/tree/main/modules/score_time). +Check available versions in the [S-CORE Bazel Registry](https://eclipse-score.github.io/bazel_registry_ui/modules/score_time). ### Using Unreleased Versions