From 59cf3afc11a14728d5bb4a018b212a8610230a8e Mon Sep 17 00:00:00 2001 From: Felix Becker Date: Wed, 21 Jan 2026 09:04:03 +0100 Subject: [PATCH 1/3] Add rules documentation --- bcr-modules/modules/rules_cfg5/README.md | 481 ++++++++++++++++++ .../modules/rules_cfg5/srcs/BUILD.bazel | 1 - bcr-modules/modules/rules_cfg5/srcs/README.md | 3 - bcr-modules/modules/rules_common/README.md | 184 +++++++ .../modules/rules_davinci_developer/README.md | 430 ++++++++++++++++ bcr-modules/modules/rules_dvteam/README.md | 205 ++++++++ bcr-modules/modules/rules_gradle/README.md | 425 ++++++++++++++++ bcr-modules/modules/rules_ocs/README.md | 451 ++++++++++++++++ 8 files changed, 2176 insertions(+), 4 deletions(-) create mode 100644 bcr-modules/modules/rules_cfg5/README.md delete mode 100644 bcr-modules/modules/rules_cfg5/srcs/README.md create mode 100644 bcr-modules/modules/rules_common/README.md create mode 100644 bcr-modules/modules/rules_davinci_developer/README.md create mode 100644 bcr-modules/modules/rules_dvteam/README.md create mode 100644 bcr-modules/modules/rules_gradle/README.md create mode 100644 bcr-modules/modules/rules_ocs/README.md diff --git a/bcr-modules/modules/rules_cfg5/README.md b/bcr-modules/modules/rules_cfg5/README.md new file mode 100644 index 0000000..ece4b3a --- /dev/null +++ b/bcr-modules/modules/rules_cfg5/README.md @@ -0,0 +1,481 @@ +# rules_cfg5 + +## Overview + +**Module Name:** `rules_cfg5` +**Current Version:** 0.0.3 +**Purpose:** Bazel rules for DaVinci Configurator 5 (CFG5) code generation and toolchain management + +### Description + +The `rules_cfg5` module provides Bazel integration for Vector's DaVinci Configurator 5 (CFG5) tool. It enables automated code generation for AUTOSAR projects, including Real-Time (RT) and Virtual Target Time (VTT) configurations. The module creates isolated workspaces for CFG5 execution and provides toolchain definitions for hermetic builds. + +### Key Functionality + +- **Code Generation**: Generate RT and VTT code from CFG5 projects (.dpa files) +- **Toolchain Management**: Define and use CFG5 toolchains in Bazel builds +- **Component Support**: Generate code for specific components with separate output directories +- **Cross-Platform**: Windows and Linux support with platform-specific execution strategies +- **CcInfo Integration**: Generated code exposed as standard Bazel C/C++ dependencies + +--- + +## Module Structure + +``` +rules_cfg5/ + BUILD.bazel + README.md # User documentation (this file) + 0.0.2/ # Version 0.0.2 + └── BUILD.bazel + 0.0.3/ # Version 0.0.3 (current) + └── BUILD.bazel + srcs/ # Source files + ├── BUILD.bazel + ├── MODULE.bazel + ├── defs.bzl # Public API + ├── generate.bzl # Generation entry point + └── private/ + ├── generate.bzl # Core generation logic + ├── rules.bzl # Rule definitions + ├── start.bzl # CFG5 startup rules + ├── toolchains.bzl # Toolchain definitions + ├── common/ + │ └── component_refs.bzl # Component reference utilities + └── templates/ + ├── filter_linux.sh.tpl # Linux file filtering + └── filter_windows.ps1.tpl # Windows file filtering +``` + +--- + +## Installation + +Add to your `MODULE.bazel`: + +```python +bazel_dep(name = "rules_cfg5", version = "0.0.3") +bazel_dep(name = "rules_common", version = "0.2.0") # Required dependency +``` + +--- + +## Rules and Functions + +### cfg5_generate_rt + +Generates Real-Time (RT) code from DaVinci Configurator 5 projects. + +**Signature:** +```python +cfg5_generate_rt( + name, + dpa_file, + config_files, + components = [], + genArgs = [], + excluded_files = [], + additional_source_file_endings = [], + additional_output_files = [], + config_folders = ["Config"] +) +``` + +**Attributes:** + +| Name | Type | Description | Required | Default | +|------|------|-------------|----------|---------| +| `name` | String | Unique name for this target | Yes | - | +| `dpa_file` | Label | DaVinci project file (.dpa) | Yes | - | +| `config_files` | List[Label] | Configuration files (.arxml, .dpa, etc.) | Yes | - | +| `components` | List[String] | Component names for separate targets | No | `[]` | +| `genArgs` | List[String] | Additional arguments for CFG5 CLI | No | `[]` | +| `excluded_files` | List[String] | File patterns to exclude from generation | No | `[]` | +| `additional_source_file_endings` | List[String] | Additional file endings to include as sources | No | `[]` | +| `additional_output_files` | List[String] | Additional files to extract from generator output | No | `[]` | +| `config_folders` | List[String] | Config folder names for workspace structure | No | `["Config"]` | + +**Usage Example:** +```python +load("@rules_cfg5//:defs.bzl", "cfg5_generate_rt") + +cfg5_generate_rt( + name = "my_ecu_config", + dpa_file = "project/MyEcu.dpa", + config_files = glob([ + "Config/**/*.arxml", + ]), + components = ["BswM", "CanIf", "Com"], + genArgs = ["--verbose"], + excluded_files = [ + "*.tmp", + "*_Test.c", + ], +) + +# Use in cc_library +cc_library( + name = "ecu_bsw", + deps = [":my_ecu_config"], +) + +# Use component-specific target +cc_library( + name = "can_stack", + deps = [":my_ecu_config_CanIf"], +) +``` + +--- + +### cfg5_toolchain + +Defines a CFG5 toolchain for use in Bazel builds. + +**Signature:** +```python +cfg5_toolchain( + name, + cfg5cli_path, + cfg5_path = None, + cfg5_files = None +) +``` + +**Attributes:** + +| Name | Type | Description | Required | Default | +|------|------|-------------|----------|---------| +| `name` | Name | Unique name for this target | Yes | - | +| `cfg5cli_path` | Label | Path to the CFG5 CLI executable | Yes | - | +| `cfg5_path` | Label | Path to the CFG5 executable (optional) | No | `None` | +| `cfg5_files` | Label | Optional CFG5 files for hermetic execution | No | `None` | + +**Usage Example:** +```python +load("@rules_cfg5//:defs.bzl", "cfg5_toolchain") + +cfg5_toolchain( + name = "cfg5_linux_toolchain", + cfg5cli_path = "@davinci_cfg5//:bin/DVCfg5Cli", +) + +toolchain( + name = "cfg5_toolchain", + exec_compatible_with = ["@platforms//os:linux"], + target_compatible_with = ["@platforms//os:linux"], + toolchain = ":cfg5_linux_toolchain", + toolchain_type = "@rules_cfg5//:toolchain_type", +) +``` + +--- + +### start_cfg5_windows + +Starts CFG5 GUI on Windows with specified project and arguments. + +**Signature:** +```python +start_cfg5_windows( + name, + dpa, + cfg5_args = "", + config_files = [], + script = None +) +``` + +**Attributes:** + +| Name | Type | Description | Required | Default | +|------|------|-------------|----------|---------| +| `name` | Name | Unique name for this target | Yes | - | +| `dpa` | Label | The .dpa project file to start CFG5 with | Yes | - | +| `cfg5_args` | String | Additional CFG5 command-line arguments | No | `""` | +| `config_files` | List[Label] | Additional configuration files | No | `[]` | +| `script` | Label | Script task/location to add to CFG5 | No | `None` | + +**Usage Example:** +```python +load("@rules_cfg5//:defs.bzl", "start_cfg5_windows") + +start_cfg5_windows( + name = "open_my_project", + dpa = "project/MyEcu.dpa", + config_files = glob(["Config/**/*.arxml"]), + cfg5_args = "--verbose", +) +``` + +--- + +## Usage Guide + +### Setup CFG5 Toolchain + +1. **Add module dependency in MODULE.bazel:** +```python +bazel_dep(name = "rules_cfg5", version = "0.0.3") +bazel_dep(name = "rules_common", version = "0.2.0") +``` + +2. **Define CFG5 toolchain in BUILD.bazel:** +```python +load("@rules_cfg5//:defs.bzl", "cfg5_toolchain") + +cfg5_toolchain( + name = "my_cfg5_toolchain", + cfg5cli_path = "@davinci_tools//:DVCfg5Cli", +) + +toolchain( + name = "cfg5_toolchain", + exec_compatible_with = ["@platforms//os:linux"], + target_compatible_with = ["@platforms//os:linux"], + toolchain = ":my_cfg5_toolchain", + toolchain_type = "@rules_cfg5//:toolchain_type", +) +``` + +3. **Register toolchain in MODULE.bazel:** +```python +register_toolchains("//path/to:cfg5_toolchain") +``` + +### Generate Code from CFG5 Project + +```python +load("@rules_cfg5//:defs.bzl", "cfg5_generate_rt") + +cfg5_generate_rt( + name = "ecu_bsw_gen", + dpa_file = "project/EcuBsw.dpa", + config_files = glob([ + "Config/**/*.arxml", + "Config/**/*.xml", + ]), + components = ["BswM", "CanIf", "CanTp", "Com", "PduR"], + genArgs = [ + "--verbose", + "--logLevel=INFO", + ], + excluded_files = [ + "*_Test.c", + "*_unittest.c", + ], +) + +# Use generated code in C library +cc_library( + name = "bsw", + deps = [":ecu_bsw_gen"], + includes = ["."], +) + +# Use component-specific target +cc_library( + name = "can_stack", + deps = [ + ":ecu_bsw_gen_CanIf", + ":ecu_bsw_gen_CanTp", + ], +) +``` + +--- + +## Dependencies + +### Required Bazel Modules +- `rules_common` (version 0.2.0 or higher) - Provides workspace creation utilities +- `bazel_skylib` (version 1.7.1 or higher) - Common Bazel utilities +- `rules_cc` - C/C++ rules for CcInfo providers + +### External Tools +- **DaVinci Configurator 5**: CFG5 CLI executable must be available + - Linux: Executable with proper permissions + - Windows: .exe executable + +--- + +## Platform Support + +| Platform | Support Level | Notes | +|----------|--------------|-------| +| Linux (x64) | ✅ Full | Requires executable permissions on CFG5 CLI | +| Windows (x64) | ✅ Full | Uses PowerShell for execution | +| macOS | ❌ Not Supported | DaVinci tools not available | + +--- + +## Configuration Requirements + +### DPA File Configuration + +The output directory for GenData in the .dpa file must be set to: + +```xml +../GenData +../GenDataVtt +``` + +--- + +## Limitations + +1. **Single Generation Type**: One rule instance supports either RT or VTT generation, not both simultaneously +2. **Workspace Location**: Generated workspaces created in `bazel-bin` directory +3. **File Filtering**: Uses template-based filtering (platform-specific) +4. **Readonly Handling**: DPA files copied to workaround Bazel readonly restrictions +5. **Component Names**: Must match exactly with CFG5 project component names +6. **Path Restrictions**: Deep nested paths in config files may cause issues with workspace creation +7. **VTT Support**: VTT generation currently commented out (not part of FOSS release) + +--- + +## Advanced Features + +### Component-Specific Code Generation + +When `components` list is provided, the rule creates separate targets for each component: +- Main target: `{name}` - All generated code +- Component targets: `{name}_{ComponentName}` - Component-specific code + +Example: +```python +cfg5_generate_rt( + name = "bsw", + components = ["CanIf", "Com"], + # ... other attributes +) + +# Creates targets: +# - :bsw (all code) +# - :bsw_CanIf (CanIf only) +# - :bsw_Com (Com only) +``` + +### File Filtering + +Control which files are included/excluded from generation: + +```python +cfg5_generate_rt( + name = "config", + excluded_files = [ + "*_Test.c", # Exclude test files + "*_PreCompile.c", # Exclude precompile config + "vLinkGen_Lcfg.c", # Excluded by default for VTT + ], + additional_source_file_endings = [ + "*.asm", # Include assembly files + "*.s", # Include additional source types + ], + # ... +) +``` + +### Custom CFG5 Arguments + +Pass additional arguments directly to CFG5 CLI: + +```python +cfg5_generate_rt( + name = "config", + genArgs = [ + "--verbose", + "--logLevel=DEBUG", + "--reportArgs=CreateXmlFile", + "--genType=REAL", + ], + # ... +) +``` + +--- + +## Troubleshooting + +### Issue: "CFG5 toolchain not found" + +**Solution:** Ensure CFG5 toolchain is properly registered and defined. + +```python +# Check MODULE.bazel +bazel_dep(name = "rules_cfg5", version = "0.0.3") + +# Check toolchain registration +register_toolchains("//toolchains:cfg5_toolchain") +``` + +--- + +### Issue: Generated code not found by compiler + +**Solution:** Verify that `CcInfo` is properly consumed and includes are correct. + +```python +cc_library( + name = "my_lib", + deps = [":cfg5_gen"], # Ensure dependency is correct + includes = ["."], # Add includes if needed +) +``` + +--- + +### Issue: Permission denied on Linux + +**Solution:** Ensure CFG5 CLI has execute permissions. + +```bash +chmod +x path/to/DVCfg5Cli +``` + +--- + +### Issue: Component-specific target not created + +**Solution:** Verify component name exactly matches CFG5 project component name. + +```python +cfg5_generate_rt( + name = "gen", + components = ["CanIf"], # Must match exactly (case-sensitive) + # ... +) +``` + +--- + +### Issue: Deep path errors during workspace creation + +**Solution:** Simplify config file structure or adjust `config_folders` attribute. + +```python +cfg5_generate_rt( + name = "gen", + config_folders = ["Config", "Cfg"], # Adjust folder matching + # ... +) +``` + +--- + +### Issue: "GenData directory not found" + +**Solution:** Verify DPA file has correct GenData path configuration (see Configuration Requirements section above). + +--- + +## Version History + +- **0.0.3** (Current): Enhanced component support and filtering +- **0.0.2**: Initial release with RT generation + +--- + +## License + +Proprietary - Internal use only diff --git a/bcr-modules/modules/rules_cfg5/srcs/BUILD.bazel b/bcr-modules/modules/rules_cfg5/srcs/BUILD.bazel index 23470a2..ee2bac6 100644 --- a/bcr-modules/modules/rules_cfg5/srcs/BUILD.bazel +++ b/bcr-modules/modules/rules_cfg5/srcs/BUILD.bazel @@ -32,7 +32,6 @@ exports_files( "private/templates/filter_windows.ps1.tpl", "generate.bzl", "defs.bzl", - "README.md", "private/toolchains.bzl", "MODULE.bazel", "BUILD.bazel", diff --git a/bcr-modules/modules/rules_cfg5/srcs/README.md b/bcr-modules/modules/rules_cfg5/srcs/README.md deleted file mode 100644 index bc15eda..0000000 --- a/bcr-modules/modules/rules_cfg5/srcs/README.md +++ /dev/null @@ -1,3 +0,0 @@ -# Cfg5 - -- Generation can be used with a distinct workspace created by bazel, sandboxing is possible diff --git a/bcr-modules/modules/rules_common/README.md b/bcr-modules/modules/rules_common/README.md new file mode 100644 index 0000000..62d673d --- /dev/null +++ b/bcr-modules/modules/rules_common/README.md @@ -0,0 +1,184 @@ +# rules_common + +## Overview + +**Module Name:** `rules_common` +**Current Version:** 0.2.0 +**Purpose:** Common utilities and helper functions for DaVinci tool integration with Bazel + +### Description + +The `rules_common` module provides shared functionality used by other DaVinci-related Bazel rule modules. It contains utilities for workspace creation, file operations, package merging, and downloading external resources. This module serves as a foundation for other rule sets like `rules_cfg5`, `rules_dvteam`, and `rules_ocs`. + +### Key Functionality + +- **Workspace Creation**: Helper functions to create isolated workspaces for DaVinci tools +- **File Operations**: Cross-platform file copying and manipulation utilities +- **Package Management**: Download, extract, and merge package functionality +- **Common Abstractions**: Shared code to reduce duplication across rule modules + +--- + +## Module Structure + +``` +rules_common/ +├── BUILD.bazel +├── 0.2.0/ # Version directory +│ └── BUILD.bazel +└── srcs/ # Source files + ├── BUILD.bazel + ├── MODULE.bazel + ├── copy_file.bzl # File copying utilities + ├── create_davinci_tool_workspace.bzl # Workspace creation + ├── download_and_merge.bzl # Package download/merge + ├── extract.bzl # Archive extraction + └── merge_packages.bzl # Package merging utilities +``` + +--- + +## Functions and Utilities + +### create_davinci_tool_workspace + +**Location:** `create_davinci_tool_workspace.bzl` + +Creates a separate workspace in the bazel-bin directory for DaVinci tool execution. This copies all configuration files and optionally provided files (like .dpa projects) into an isolated environment. + +**Signature:** +```python +create_davinci_tool_workspace( + ctx, + workspace_name, + addtional_workspace_files = [], + is_windows = False, + config_files = [], + config_folders = ["Config"] +) +``` + +**Parameters:** + +| Name | Type | Description | Required | Default | +|------|------|-------------|----------|---------| +| `ctx` | Context | Current rule context creating the workspace | Yes | - | +| `workspace_name` | String | Name for the created workspace | Yes | - | +| `addtional_workspace_files` | List[File] | Additional files to add to workspace (e.g., .dpa files) | No | `[]` | +| `is_windows` | Boolean | Whether execution is on Windows platform | No | `False` | +| `config_files` | List[File] | List of configuration files for the workspace | No | `[]` | +| `config_folders` | List[String] | Config folder names to check in file paths for nesting | No | `["Config"]` | + +**Returns:** +`DaVinciToolWorkspaceInfo` struct containing: +- `files`: List of config files in workspace +- `workspace_prefix`: Workspace name +- `addtional_workspace_files`: Copied additional files + +**Usage Example:** +```python +workspace = create_davinci_tool_workspace( + ctx, + workspace_name = "my_tool_workspace", + addtional_workspace_files = [ctx.file.dpa_file], + is_windows = ctx.attr.private_is_windows, + config_files = ctx.files.config_files +) +``` + +--- + +### copy_file + +**Location:** `copy_file.bzl` + +Cross-platform file copying utility that handles differences between Windows and Linux. + +**Signature:** +```python +copy_file(ctx, src, dst, is_windows = False) +``` + +**Parameters:** + +| Name | Type | Description | Required | Default | +|------|------|-------------|----------|---------| +| `ctx` | Context | Current rule context | Yes | - | +| `src` | File | Source file to copy | Yes | - | +| `dst` | File | Destination file path | Yes | - | +| `is_windows` | Boolean | Whether to use Windows copy commands | No | `False` | + +**Implementation Details:** +- Linux: Uses `cp -f` command +- Windows: Generates `.bat` file with `copy /Y` command +- Handles readonly file restrictions in Bazel output directories + +--- + +### download_and_merge + +**Location:** `download_and_merge.bzl` + +Repository rule for downloading and merging multiple packages. + +**Usage in MODULE.bazel:** +```python +download_and_merge = use_repo_rule("@rules_common//:download_and_merge.bzl", "download_and_merge") + +download_and_merge( + name = "merged_packages", + urls = [ + "https://example.com/package1.zip", + "https://example.com/package2.zip", + ], + sha256 = { + "package1.zip": "abc123...", + "package2.zip": "def456...", + }, +) +``` + +--- + +### extract + +**Location:** `extract.bzl` + +Utilities for extracting archives (zip, tar, etc.). + +--- + +### merge_packages + +**Location:** `merge_packages.bzl` + +Functions to merge multiple packages into a single directory structure. + +--- + +## Dependencies + +This module depends on: +- `bazel_skylib` (version 1.7.1) +- `ape` (version 1.0.1) + +**Add in MODULE.bazel:** +```python +bazel_dep(name = "rules_common", version = "0.2.0") +``` + +--- + +## Platform Support + +- **Linux**: Full support +- **Windows**: Full support +- **Cross-platform**: Utilities automatically detect and adapt to platform + +--- + +## Limitations + +- File copying creates copies to workaround Bazel's readonly restrictions on action outputs +- Config folder structure assumes specific naming conventions (default "Config" folder) +- Workspace creation happens in bazel-bin directory diff --git a/bcr-modules/modules/rules_davinci_developer/README.md b/bcr-modules/modules/rules_davinci_developer/README.md new file mode 100644 index 0000000..4fd95da --- /dev/null +++ b/bcr-modules/modules/rules_davinci_developer/README.md @@ -0,0 +1,430 @@ +# rules_davinci_developer + +## Overview + +**Module Name:** `rules_davinci_developer` +**Current Version:** 0.0.1 +**Purpose:** Bazel toolchain definitions for Vector's DaVinci Developer tool suite + +### Description + +The `rules_davinci_developer` module provides Bazel toolchain integration for Vector's DaVinci Developer tools, including DVImEx (Import/Export) and DVSwcGen (SWC Generator). This module enables automated execution of DaVinci Developer operations within Bazel builds, supporting both command-line operations and GUI launching. + +### Key Functionality + +- **Toolchain Management**: Define and register DaVinci Developer toolchains for Bazel builds +- **Multi-Binary Support**: Supports multiple DaVinci Developer binaries (DVImEx, DVSwcGen) +- **Command-Line Execution**: Run DaVinci Developer operations in automated builds +- **GUI Launching**: Start DaVinci Developer GUI with specific projects (Windows) +- **Cross-Platform**: Windows (path-based) and Linux (label-based) support +- **Integration**: Used by other rule modules (rules_dvteam, rules_ocs, rules_cfg5) + +--- + +## Module Structure + +``` +rules_davinci_developer/ +├── BUILD.bazel +├── README.md +├── 0.0.1/ # Version 0.0.1 (current) +│ └── BUILD.bazel +└── srcs/ # Source files + ├── BUILD.bazel + ├── MODULE.bazel + ├── rules.bzl # Rule definitions and implementations + └── toolchains.bzl # Toolchain definitions +``` + +--- + +## Rules and Toolchains + +### davinci_developer_toolchain + +Defines a DaVinci Developer toolchain that provides access to DaVinci Developer binaries. + +**Location:** `toolchains.bzl` + +**Signature:** +```python +davinci_developer_toolchain( + name, + dvimex_label = None, + dvswcgen_label = None, + dvimex_path = "", + dvswcgen_path = "", + davincidev_path = "", + davinci_developer_cmd_label = None +) +``` + +**Attributes:** + +| Name | Type | Description | Required | Default | +|------|------|-------------|----------|---------| +| `name` | Name | Unique name for this target | Yes | - | +| `dvimex_label` | Label | Label pointing to DVImEx binary (Linux) | No | `None` | +| `dvswcgen_label` | Label | Label pointing to DVSwcGen binary (Linux) | No | `None` | +| `dvimex_path` | String | System path to DVImEx binary (Windows) | No | `""` | +| `dvswcgen_path` | String | System path to DVSwcGen binary (Windows) | No | `""` | +| `davincidev_path` | String | Path to DaVinciDEV.exe for GUI launch (Windows) | No | `""` | +| `davinci_developer_cmd_label` | Label | Legacy: Developer CMD label (Linux) | No | `None` | + +**Usage Example - Linux:** +```python +load("@rules_davinci_developer//:toolchains.bzl", "davinci_developer_toolchain") + +davinci_developer_toolchain( + name = "davinci_dev_linux_toolchain", + dvimex_label = "@davinci_tools//:DEVImEx/bin/DVImEx", + dvswcgen_label = "@davinci_tools//:DEVSwcGen/bin/DVSwcGen", + davinci_developer_cmd_label = "@davinci_tools//:DEVImEx/bin/DVImEx", +) + +toolchain( + name = "davinci_developer_toolchain", + exec_compatible_with = [ + "@platforms//os:linux", + ], + target_compatible_with = [ + "@platforms//os:linux", + ], + toolchain = ":davinci_dev_linux_toolchain", + toolchain_type = "@rules_davinci_developer//:toolchain_type", +) +``` + +**Usage Example - Windows:** +```python +load("@rules_davinci_developer//:toolchains.bzl", "davinci_developer_toolchain") + +davinci_developer_toolchain( + name = "davinci_dev_windows_toolchain", + dvimex_path = "C:/Program Files/Vector/DaVinci Developer/DEVImEx/bin/DVImEx.exe", + dvswcgen_path = "C:/Program Files/Vector/DaVinci Developer/DEVSwcGen/bin/DVSwcGen.exe", + davincidev_path = "C:/Program Files/Vector/DaVinci Developer/DaVinciDEV.exe", +) + +toolchain( + name = "davinci_developer_toolchain", + exec_compatible_with = [ + "@platforms//os:windows", + ], + target_compatible_with = [ + "@platforms//os:windows", + ], + toolchain = ":davinci_dev_windows_toolchain", + toolchain_type = "@rules_davinci_developer//:toolchain_type", +) +``` + +--- + +### developer_run + +Executes DaVinci Developer command-line operations (DVImEx or DVSwcGen). + +**Location:** `rules.bzl` + +**Signature:** +```python +developer_run( + name, + dcf_file, + binary_name, + genargs = [], + inputs = [], + export_output = None +) +``` + +**Attributes:** + +| Name | Type | Description | Required | Default | +|------|------|-------------|----------|---------| +| `name` | Name | Unique name for this target | Yes | - | +| `dcf_file` | Label | The .dcf configuration file | Yes | - | +| `binary_name` | String | Which binary to use: "dvimex" or "dvswcgen" | Yes | - | +| `genargs` | List[String] | Additional CLI arguments | No | `[]` | +| `inputs` | List[Label] | Other input files (e.g., model files) | No | `[]` | +| `export_output` | Output | ARXML output file (passed via -ef) | No | `None` | + +**Usage Example:** +```python +load("@rules_davinci_developer//:rules.bzl", "developer_run") + +developer_run( + name = "export_swc_description", + dcf_file = "config/export.dcf", + binary_name = "dvimex", + inputs = [ + "models/Application.arxml", + "models/Platform.arxml", + ], + export_output = "generated/SwcDescription.arxml", + genargs = [ + "-x", + "--verbose", + ], +) + +# Use exported ARXML in another target +filegroup( + name = "swc_configs", + srcs = [":export_swc_description"], +) +``` + +--- + +### start_developer_windows + +Launches DaVinci Developer GUI with a specific project (Windows only). + +**Location:** `rules.bzl` + +**Signature:** +```python +start_developer_windows( + name, + dcf, + model, + developer_args = "" +) +``` + +**Attributes:** + +| Name | Type | Description | Required | Default | +|------|------|-------------|----------|---------| +| `name` | Name | Unique name for this target | Yes | - | +| `dcf` | Label | The .dcf file to open | Yes | - | +| `model` | Label | The .arxml model referenced by the DCF | Yes | - | +| `developer_args` | String | Additional DaVinci Developer arguments | No | `""` | + +**Usage Example:** +```python +load("@rules_davinci_developer//:rules.bzl", "start_developer_windows") + +start_developer_windows( + name = "open_my_project", + dcf = "project/MyApp.dcf", + model = "models/Application.arxml", + developer_args = "--verbose", +) +``` + +**Running:** +```bash +bazel run //:open_my_project +``` + +--- + +## Usage Guide + +### Setup DaVinci Developer Toolchain + +1. **Add module dependency in MODULE.bazel:** +```python +bazel_dep(name = "rules_davinci_developer", version = "0.0.1") +``` + +2. **Define toolchain in BUILD.bazel (Linux):** +```python +load("@rules_davinci_developer//:toolchains.bzl", "davinci_developer_toolchain") + +# Download DaVinci Developer tools +http_archive( + name = "davinci_tools", + url = "https://example.com/davinci_developer_linux.tar.gz", + sha256 = "...", + build_file_content = """ +filegroup( + name = "DEVImEx", + srcs = ["DEVImEx/bin/DVImEx"], + visibility = ["//visibility:public"], +) +filegroup( + name = "DEVSwcGen", + srcs = ["DEVSwcGen/bin/DVSwcGen"], + visibility = ["//visibility:public"], +) +""", +) + +davinci_developer_toolchain( + name = "davinci_dev_toolchain_impl", + dvimex_label = "@davinci_tools//:DEVImEx", + dvswcgen_label = "@davinci_tools//:DEVSwcGen", + davinci_developer_cmd_label = "@davinci_tools//:DEVImEx", +) + +toolchain( + name = "davinci_developer_toolchain", + exec_compatible_with = ["@platforms//os:linux"], + toolchain = ":davinci_dev_toolchain_impl", + toolchain_type = "@rules_davinci_developer//:toolchain_type", +) +``` + +3. **Register toolchain in MODULE.bazel:** +```python +register_toolchains("//path/to:davinci_developer_toolchain") +``` + +### Export ARXML with DVImEx + +```python +load("@rules_davinci_developer//:rules.bzl", "developer_run") + +developer_run( + name = "export_component_description", + dcf_file = "export_config/ComponentExport.dcf", + binary_name = "dvimex", + inputs = [ + "models/ComponentDefinition.arxml", + ], + export_output = "generated/ComponentDescription.arxml", + genargs = ["-x"], # Export mode +) +``` + +### Generate SWC with DVSwcGen + +```python +developer_run( + name = "generate_swc_code", + dcf_file = "swc_config/SwcGen.dcf", + binary_name = "dvswcgen", + inputs = [ + "models/SwcDescription.arxml", + ], + genargs = [ + "--target=C", + "--verbose", + ], +) +``` + +--- + +## Dependencies + +### Required Bazel Modules +- None (standalone module) + +### External Tools +- **DaVinci Developer**: One or more of the following binaries: + - DVImEx: Import/Export operations + - DVSwcGen: Software Component generation + - DaVinciDEV.exe: GUI application (Windows) + +--- + +## Platform Support + +| Platform | Support Level | Notes | +|----------|--------------|-------| +| Linux (x64) | ✅ Full | Uses label-based toolchain (requires downloaded binaries) | +| Windows (x64) | ✅ Full | Uses path-based toolchain (system installation) | +| macOS | ❌ Not Supported | DaVinci tools not available | + +**Platform Differences:** +- **Linux**: Requires binaries as Bazel labels (downloaded via http_archive or similar) +- **Windows**: Uses system paths to installed DaVinci Developer +- GUI launch (`start_developer_windows`) only supported on Windows + +--- + +## Limitations + +1. **Binary Availability**: Requires DaVinci Developer installation or downloaded binaries +2. **Linux Permissions**: Binaries must have execute permissions +3. **Windows Paths**: Windows toolchain requires absolute paths to installed tools +4. **GUI Launch**: Only Windows supports GUI launch rule +5. **Single Binary Per Call**: Each `developer_run` invocation uses one binary (dvimex or dvswcgen) +6. **File Permissions**: May need to handle readonly file attributes (especially on Windows) + +--- + +## Advanced Features + +### Multiple Binary Support + +The toolchain supports multiple DaVinci Developer binaries: + +```python +# Use DVImEx for import/export +developer_run( + name = "export_arxml", + binary_name = "dvimex", + dcf_file = "export.dcf", + export_output = "output.arxml", +) + +# Use DVSwcGen for code generation +developer_run( + name = "generate_code", + binary_name = "dvswcgen", + dcf_file = "codegen.dcf", +) +``` + +### Custom Arguments + +Pass additional arguments to DaVinci Developer: + +```python +developer_run( + name = "export_with_options", + dcf_file = "config.dcf", + binary_name = "dvimex", + genargs = [ + "-x", # Export mode + "--verbose", # Verbose logging + "--force", # Force overwrite + ], +) +``` + +### Integration with Other Rules + +This module is used by other Vector rule modules: + +```python +# Used by rules_dvteam +bazel_dep(name = "rules_dvteam") + +# Used by rules_ocs +bazel_dep(name = "rules_ocs") + +# DVTeam and OCS rules automatically use this toolchain +``` + +--- + +## Troubleshooting + +### Common Issues + +**Issue**: "Developer toolchain is needed for DaVinci Team and needs either..." +- **Solution**: Ensure toolchain is properly defined and registered +- **Check**: At least one of `dvimex_label`/`dvimex_path` or `davinci_developer_cmd_label` must be set + +**Issue**: Permission denied on Linux +- **Solution**: Make binaries executable: `chmod +x DVImEx DVSwcGen` +- **Alternative**: Use http_archive with executable permissions + +**Issue**: "Invalid binary_name" error +- **Solution**: Use only "dvimex" or "dvswcgen" as binary_name +- **Check**: Spelling and case sensitivity + +**Issue**: Windows path not found +- **Solution**: Use absolute paths in Windows toolchain +- **Example**: `C:/Program Files/Vector/DaVinci Developer/DEVImEx/bin/DVImEx.exe` + +**Issue**: Export output not created +- **Solution**: Check .dcf file configuration and input files +- **Debug**: Add `--verbose` to genargs and check log file diff --git a/bcr-modules/modules/rules_dvteam/README.md b/bcr-modules/modules/rules_dvteam/README.md new file mode 100644 index 0000000..c5a5e3b --- /dev/null +++ b/bcr-modules/modules/rules_dvteam/README.md @@ -0,0 +1,205 @@ +# rules_dvteam + +## Overview + +**Module Name:** `rules_dvteam` +**Current Version:** 0.0.1 +**Purpose:** Bazel rules for Vector's DaVinci Team (DVTeam) integration and automation + +### Description + +The `rules_dvteam` module provides Bazel integration for Vector's DaVinci Team tool, which automates the integration of software applications into AUTOSAR Basic Software (BSW) projects. DVTeam uses Gradle as its execution engine and integrates with DaVinci Developer, DaVinci Configurator 5, and VTT (Virtual Target Time) tools. + +### Key Functionality + +- **DVTeam Execution**: Run DaVinci Team integration tasks within Bazel builds +- **App Package Integration**: Integrate application packages into BSW configurations +- **Gradle Integration**: Execute Gradle-based DVTeam workflows +- **Multi-Tool Coordination**: Coordinates DaVinci Developer, CFG5, Gradle, and VTT toolchains +- **Configuration Management**: Handle complex AUTOSAR configuration workflows +- **Cross-Platform**: Windows and Linux support with platform-specific execution + +--- + +## Module Structure + +``` +rules_dvteam/ + BUILD.bazel + README.md + 0.0.1/ # Version 0.0.1 (current) + └── BUILD.bazel + srcs/ # Source files + ├── BUILD.bazel + ├── MODULE.bazel + ├── defs.bzl # Public API + └── private/ + └── rules.bzl # DVTeam rule implementation +``` + +--- + +## Rules and Functions + +### dvteam + +Executes DaVinci Team integration tasks using Gradle and Vector toolchains. + +**Location:** `private/rules.bzl` (exported via `defs.bzl`) + +**Signature:** +```python +dvteam( + name, + dpa_file, + gradle_file, + task, + wfconfig, + results, + sip, + app_package_sources = [], + config_files = [], + config_folders = ["Config"], + dvteam_args = [], + global_instruction_files = [], + custom_scripts = [], + java_keystore_file = None, + java_keystore_password = "changeit" +) +``` + +**Attributes:** + +| Name | Type | Description | Required | Default | +|------|------|-------------|----------|---------| +| `name` | Name | Unique name for this target | Yes | - | +| `dpa_file` | Label | DaVinci project (.dpa) file | Yes | - | +| `gradle_file` | Label | Gradle build file for DVTeam | Yes | - | +| `task` | String | Gradle task to execute | Yes | - | +| `wfconfig` | Label | Workflow configuration JSON file | Yes | - | +| `results` | List[Output] | Expected output files from DVTeam | Yes | - | +| `sip` | Label | SIP (Software Integration Platform) location | Yes | - | +| `app_package_sources` | List[Label] | App packages to integrate | No | `[]` | +| `config_files` | List[Label] | Configuration files (.arxml, .xml, etc.) | No | `[]` | +| `config_folders` | List[String] | Config folder names for workspace structure | No | `["Config"]` | +| `dvteam_args` | List[String] | Additional DVTeam CLI arguments | No | `[]` | +| `global_instruction_files` | List[Label] | Global instruction JSON files | No | `[]` | +| `custom_scripts` | List[Label] | Custom DVGroovy scripts | No | `[]` | +| `java_keystore_file` | Label | Java KeyStore file with certificates | No | `None` | +| `java_keystore_password` | String | Java KeyStore password | No | `"changeit"` | + +**Usage Example:** +```python +load("@rules_dvteam//:defs.bzl", "dvteam") + +dvteam( + name = "integrate_application", + dpa_file = "project/EcuBsw.dpa", + gradle_file = "integration/build.gradle", + task = "IntegrateApplication", + wfconfig = "integration/wfconfig.json", + sip = "@microsar_classic//:bsw_modules", + app_package_sources = [ + "@my_application//:package", + "@my_diagnostics//:package", + ], + config_files = glob([ + "Config/**/*.arxml", + "Config/**/*.xml", + ]), + global_instruction_files = [ + "integration/global_mapping.json", + ], + results = [ + "GenData/EcuBsw_IntegratedConfig.arxml", + "GenData/EcuBsw_DiagnosticConfig.arxml", + ], + dvteam_args = [ + "--debug", + "--info", + ], +) + +# Use integrated configuration in code generation +load("@rules_cfg5//:defs.bzl", "cfg5_generate_rt") + +cfg5_generate_rt( + name = "bsw_gen", + dpa_file = "project/EcuBsw.dpa", + config_files = [":integrate_application"], + # ... other attributes +) +``` + +--- + +## Usage Guide + +### Setup DVTeam Environment + +1. **Add module dependencies in MODULE.bazel:** +```python +bazel_dep(name = "rules_dvteam", version = "0.0.1") +bazel_dep(name = "rules_davinci_developer", version = "0.0.1") +bazel_dep(name = "rules_cfg5", version = "0.0.3") +bazel_dep(name = "rules_gradle", version = "0.0.1") +bazel_dep(name = "rules_common", version = "0.2.0") + +# Required for Linux execution +bazel_dep(name = "rules_dotnet", version = "0.17.5") +dotnet = use_extension("@rules_dotnet//dotnet:extensions.bzl", "dotnet") +dotnet.toolchain(dotnet_version = "8.0.103") +use_repo(dotnet, "dotnet_toolchains") +``` + +2. **Define all required toolchains in BUILD.bazel:** +```python +load("@rules_davinci_developer//:toolchains.bzl", "davinci_developer_toolchain") +load("@rules_cfg5//:defs.bzl", "cfg5_toolchain") +load("@rules_gradle//:defs.bzl", "gradle_toolchain") + +# DaVinci Developer toolchain +davinci_developer_toolchain( + name = "davinci_dev_toolchain_impl", + davinci_developer_cmd_label = "@davinci_tools//:DEVImEx", +) + +toolchain( + name = "davinci_developer_toolchain", + toolchain = ":davinci_dev_toolchain_impl", + toolchain_type = "@rules_davinci_developer//:toolchain_type", +) + +# CFG5 toolchain +cfg5_toolchain( + name = "cfg5_toolchain_impl", + cfg5cli_path = "@davinci_cfg5//:DVCfg5Cli", +) + +toolchain( + name = "cfg5_toolchain", + toolchain = ":cfg5_toolchain_impl", + toolchain_type = "@rules_cfg5//:toolchain_type", +) + +# Gradle toolchain +gradle_toolchain( + name = "gradle_toolchain_impl", + gradle_label = "@gradle_dist//:gradle", +) + +toolchain( + name = "gradle_toolchain", + toolchain = ":gradle_toolchain_impl", + toolchain_type = "@rules_gradle//:toolchain_type", +) +``` + +3. **Register toolchains in MODULE.bazel:** +```python +register_toolchains( + "//toolchains:davinci_developer_toolchain", + "//toolchains:cfg5_toolchain", + "//toolchains:gradle_toolchain", +) +``` diff --git a/bcr-modules/modules/rules_gradle/README.md b/bcr-modules/modules/rules_gradle/README.md new file mode 100644 index 0000000..c327029 --- /dev/null +++ b/bcr-modules/modules/rules_gradle/README.md @@ -0,0 +1,425 @@ +# rules_gradle + +## Overview + +**Module Name:** `rules_gradle` +**Current Version:** 0.0.1 +**Purpose:** Gradle toolchain and authentication utilities for Bazel builds + +### Description + +The `rules_gradle` module provides Bazel integration for Gradle build tool, specifically adapted for Vector's DaVinci tools that rely on Gradle. It includes toolchain definitions for Gradle execution and repository rules for generating Gradle properties files with authentication tokens from .netrc files. + +### Key Functionality + +- **Gradle Toolchain**: Define and use Gradle installations in Bazel builds +- **Authentication Management**: Generate gradle.properties with tokens from .netrc +- **Properties Generation**: Create Gradle properties files dynamically +- **Cross-Platform**: Windows and Linux support (path-based and label-based) +- **Integration**: Used by rules_dvteam and other Gradle-dependent rules + +--- + +## Module Structure + +``` +rules_gradle/ + BUILD.bazel + README.md + 0.0.1/ # Version 0.0.1 (current) + └── BUILD.bazel + srcs/ # Source files + ├── BUILD.bazel + MODULE.bazel + ├── defs.bzl # Public API + └── private/ + ├── rules.bzl # Repository rule for properties generation + └── toolchains.bzl # Gradle toolchain definition +``` + +--- + +## Rules and Functions + +### gradle_toolchain + +Defines a Gradle toolchain for use in Bazel builds. + +**Location:** `private/toolchains.bzl` + +**Signature:** +```python +gradle_toolchain( + name, + gradle_label = None, + gradle_path = "", + gradle_properties = None +) +``` + +**Attributes:** + +| Name | Type | Description | Required | Default | +|------|------|-------------|----------|---------| +| `name` | Name | Unique name for this target | Yes | - | +| `gradle_label` | Label | Label to Gradle executable (when downloaded via Bazel) | No | `None` | +| `gradle_path` | String | System path to Gradle (when installed system-wide) | No | `""` | +| `gradle_properties` | Label | Custom gradle.properties file | No | `None` | + +**Usage Example - Linux (Label-based):** +```python +load("@rules_gradle//:defs.bzl", "gradle_toolchain") + +# Download Gradle distribution +http_archive( + name = "gradle_dist", + url = "https://services.gradle.org/distributions/gradle-8.5-bin.zip", + sha256 = "...", + build_file_content = """ +filegroup( + name = "gradle", + srcs = ["gradle-8.5/bin/gradle"], + visibility = ["//visibility:public"], +) +""", +) + +gradle_toolchain( + name = "gradle_toolchain_impl", + gradle_label = "@gradle_dist//:gradle", + gradle_properties = "@gradle_properties//:gradle.properties", +) + +toolchain( + name = "gradle_toolchain", + exec_compatible_with = ["@platforms//os:linux"], + target_compatible_with = ["@platforms//os:linux"], + toolchain = ":gradle_toolchain_impl", + toolchain_type = "@rules_gradle//:toolchain_type", +) +``` + +**Usage Example - Windows (Path-based):** +```python +load("@rules_gradle//:defs.bzl", "gradle_toolchain") + +gradle_toolchain( + name = "gradle_toolchain_impl", + gradle_path = "C:/Gradle/gradle-8.5/bin/gradle.bat", + gradle_properties = "@gradle_properties//:gradle.properties", +) + +toolchain( + name = "gradle_toolchain", + exec_compatible_with = ["@platforms//os:windows"], + toolchain = ":gradle_toolchain_impl", + toolchain_type = "@rules_gradle//:toolchain_type", +) +``` + +--- + +### generate_gradle_properties + +Repository rule that generates a gradle.properties file with authentication tokens from .netrc. + +**Location:** `private/rules.bzl` + +**Signature:** +```python +generate_gradle_properties( + name, + tokens, + netrc = "", + gradle_properties_content = "" +) +``` + +**Attributes:** + +| Name | Type | Description | Required | Default | +|------|------|-------------|----------|---------| +| `name` | String | Repository name | Yes | - | +| `tokens` | Dict[String, String] | Map of token names to .netrc URLs | Yes | - | +| `netrc` | String | Path to .netrc file (if not using default) | No | `""` | +| `gradle_properties_content` | String | Base content for gradle.properties | No | `""` | + +**Usage in MODULE.bazel:** +```python +generate_gradle_properties = use_repo_rule("@rules_gradle//:defs.bzl", "generate_gradle_properties") + +generate_gradle_properties( + name = "gradle_properties", + tokens = { + "vector.artifactory.user": "artifactory.vector.com", + "vector.artifactory.password": "artifactory.vector.com", + "vector.nexus.token": "nexus.vector.com", + }, + gradle_properties_content = """ +org.gradle.daemon=false +org.gradle.caching=false +""", +) +``` + +**How It Works:** +1. Reads .netrc file (from `netrc` attribute, `$NETRC` env var, or `~/.netrc`) +2. Extracts passwords for specified URLs from .netrc +3. Generates gradle.properties with tokens: `=` +4. Includes base content from `gradle_properties_content` + +**Example .netrc:** +``` +machine artifactory.vector.com + login myuser + password my_secret_token + +machine nexus.vector.com + login api_token + password another_secret_token +``` + +**Generated gradle.properties:** +``` +org.gradle.daemon=false +org.gradle.caching=false +vector.artifactory.user=myuser +vector.artifactory.password=my_secret_token +vector.nexus.token=another_secret_token +``` + +--- + +## Usage Guide + +### Setup Gradle Toolchain + +1. **Add module dependency in MODULE.bazel:** +```python +bazel_dep(name = "rules_gradle", version = "0.0.1") +``` + +2. **Generate gradle.properties with authentication:** +```python +generate_gradle_properties = use_repo_rule("@rules_gradle//:defs.bzl", "generate_gradle_properties") + +generate_gradle_properties( + name = "gradle_properties", + tokens = { + "artifactoryUser": "artifactory.example.com", + "artifactoryPassword": "artifactory.example.com", + }, +) +``` + +3. **Define Gradle toolchain:** +```python +load("@rules_gradle//:defs.bzl", "gradle_toolchain") + +gradle_toolchain( + name = "my_gradle_toolchain", + gradle_label = "@gradle_dist//:gradle", + gradle_properties = "@gradle_properties//:gradle.properties", +) + +toolchain( + name = "gradle_toolchain", + toolchain = ":my_gradle_toolchain", + toolchain_type = "@rules_gradle//:toolchain_type", +) +``` + +4. **Register toolchain:** +```python +register_toolchains("//toolchains:gradle_toolchain") +``` + +### Use in Rules + +Rules can access Gradle toolchain: + +```python +def _my_rule_impl(ctx): + gradle_toolchain = ctx.toolchains["@rules_gradle//:toolchain_type"] + + # Get Gradle executable + gradle_path = ( + gradle_toolchain.gradle_label.path + if gradle_toolchain.gradle_label + else gradle_toolchain.gradle_path + ) + + # Get properties file + gradle_properties = gradle_toolchain.gradle_properties + + # Execute Gradle + ctx.actions.run_shell( + command = "{} --gradle-user-home {} build".format( + gradle_path, + gradle_properties.dirname if gradle_properties else "" + ), + # ... + ) +``` + +--- + +## Dependencies + +### Required Bazel Modules +- None (standalone module) + +### External Tools +- **Gradle**: Version 8.x or compatible +- **Java JDK**: Required by Gradle (provided via Bazel's JDK toolchain) + +--- + +## Platform Support + +| Platform | Support Level | Notes | +|----------|--------------|-------| +| Linux (x64) | ✅ Full | Uses label-based toolchain (Gradle as Bazel label) | +| Windows (x64) | ✅ Full | Uses path-based toolchain (system Gradle installation) | +| macOS | ✅ Supported | Same as Linux, requires Gradle installation | + +**Platform Differences:** +- **Linux/macOS**: Typically use `gradle_label` (downloaded Gradle) +- **Windows**: Typically use `gradle_path` (installed Gradle) +- .netrc reading works on all platforms + +--- + +## Limitations + +1. **Authentication Source**: Only supports .netrc format for credentials +2. **Token Mapping**: Each token requires explicit URL mapping +3. **Password Storage**: Netrc passwords stored in plain text (use file permissions) +4. **Properties Override**: Generated properties take precedence over user's system properties +5. **Local Repository**: Generated properties repository is local=True (not cached) +6. **Security**: gradle.properties contains credentials (keep secure) + +--- + +## Advanced Features + +### Multiple Token Sources + +Map multiple tokens from different netrc machines: + +```python +generate_gradle_properties( + name = "gradle_properties", + tokens = { + "artifactory.user": "artifactory.vector.com", + "artifactory.password": "artifactory.vector.com", + "github.token": "github.com", + "nexus.token": "nexus.internal.com", + }, +) +``` + +### Base Properties Content + +Include standard Gradle configuration: + +```python +generate_gradle_properties( + name = "gradle_properties", + gradle_properties_content = """ +# Performance settings +org.gradle.daemon=false +org.gradle.parallel=true +org.gradle.caching=false +org.gradle.configureondemand=true + +# Memory settings +org.gradle.jvmargs=-Xmx2048m -XX:MaxMetaspaceSize=512m + +# Network settings +systemProp.http.proxyHost=proxy.example.com +systemProp.http.proxyPort=8080 +""", + tokens = { + # ... authentication tokens + }, +) +``` + +### Custom .netrc Location + +Specify non-default .netrc file: + +```python +generate_gradle_properties( + name = "gradle_properties", + netrc = "/path/to/custom/.netrc", + tokens = {...}, +) +``` + +### Environment Variable .netrc + +Use `$NETRC` environment variable: + +```bash +export NETRC=/secure/location/.netrc +bazel build //... +``` + +--- + +## Security Considerations + +1. **Protect .netrc**: Use file permissions (chmod 600) + ```bash + chmod 600 ~/.netrc + ``` + +2. **Protect Generated Properties**: Keep gradle.properties secure + - Not committed to version control + - Generated locally per user + - Contains authentication credentials + +3. **Bazel Output**: Generated repository in bazel-out (not user-writable) + +4. **CI/CD**: Inject .netrc securely in CI environment + ```yaml + # Example GitHub Actions + - name: Setup .netrc + run: | + echo "machine artifactory.example.com" > ~/.netrc + echo " login ${{ secrets.ARTIFACTORY_USER }}" >> ~/.netrc + echo " password ${{ secrets.ARTIFACTORY_TOKEN }}" >> ~/.netrc + chmod 600 ~/.netrc + ``` + +--- + +## Troubleshooting + +### Common Issues + +**Issue**: "Gradle toolchain is needed for DaVinci Team" +- **Solution**: Ensure gradle toolchain is defined and registered +- **Check**: At least one of `gradle_label` or `gradle_path` must be set + +**Issue**: "No authentication token found in .netrc" +- **Solution**: Verify .netrc contains matching machine entry +- **Check**: URL in `tokens` dict matches .netrc machine exactly + +**Issue**: Generated properties file not found +- **Solution**: Ensure repository name is correct: `@//:gradle.properties` +- **Check**: Run `bazel query @gradle_properties//...` to verify + +**Issue**: Gradle execution fails with "permission denied" +- **Solution**: Ensure Gradle executable has execute permissions +- **Linux**: `chmod +x gradle` + +**Issue**: Authentication fails in Gradle build +- **Solution**: Verify generated properties contains correct tokens +- **Debug**: Check `bazel-out/.../external/gradle_properties/gradle.properties` + +**Issue**: .netrc not found +- **Solution**: Create .netrc in home directory or set `$NETRC` variable +- **Location**: `~/.netrc` (Linux/macOS) or `%HOME%/_netrc` (Windows) diff --git a/bcr-modules/modules/rules_ocs/README.md b/bcr-modules/modules/rules_ocs/README.md new file mode 100644 index 0000000..f0d837b --- /dev/null +++ b/bcr-modules/modules/rules_ocs/README.md @@ -0,0 +1,451 @@ +# rules_ocs + +## Overview + +**Module Name:** `rules_ocs` +**Current Version:** 0.0.1 +**Purpose:** Bazel rules for Open Configurator Services (OCS) execution and CFG5 script task automation + +### Description + +The `rules_ocs` module provides Bazel integration for Vector's Open Configurator Services (OCS) framework and CFG5 script task execution. OCS allows custom plugins and automation workflows to be executed within DaVinci Configurator 5 environment. The module also includes utilities for building OCS application packages (uber JARs). + +### Key Functionality + +- **OCS Execution**: Run OCS applications/plugins within CFG5 environment +- **Script Task Execution**: Execute CFG5 script tasks (DVGroovy, JAR) +- **Project Management**: Create or modify DaVinci projects via OCS +- **Input File Updates**: Update project input files via OCS configuration +- **OCS App Building**: Build uber JAR packages for OCS applications +- **Cross-Platform**: Windows and Linux support with platform-specific execution + +--- + +## Module Structure + +``` +rules_ocs/ + BUILD.bazel + README.md + 0.0.1/ # Version 0.0.1 (current) + └── BUILD.bazel + srcs/ # Source files + ├── BUILD.bazel + MODULE.bazel ├ + ├── defs.bzl # Public API + └── private/ + ├── app_building.bzl # OCS app packaging + ├── rules.bzl # OCS and script task rules + └── toolchains.bzl # 7-Zip toolchain (Windows) +``` + +--- + +## Rules and Functions + +### ocs + +Executes OCS (Open Configurator Services) applications within CFG5 environment. + +**Location:** `private/rules.bzl` (exported via `defs.bzl`) + +**Signature:** +```python +ocs( + name, + ocs_app, + result, + dpa_file = None, + input_files = [], + davinci_project_files = [], + ocs_config_files = [], + ocs_args = "" +) +``` + +**Attributes:** + +| Name | Type | Description | Required | Default | +|------|------|-------------|----------|---------| +| `name` | Name | Unique name for this target | Yes | - | +| `ocs_app` | Label | The OCS application JAR file | Yes | - | +| `result` | List[Output] | Expected output files from OCS execution | Yes | - | +| `dpa_file` | Label | DaVinci project file (if modifying existing project) | No | `None` | +| `input_files` | List[Label] | Input files (.arxml, .cdd, .dbc) for input file updates | No | `[]` | +| `davinci_project_files` | List[Label] | Project files (.arxml, .dcf, .xml) if modifying project | No | `[]` | +| `ocs_config_files` | List[Label] | OCS plugin JSON configuration files | No | `[]` | +| `ocs_args` | String | Additional arguments for OCS execution | No | `""` | + +**Usage Example:** +```python +load("@rules_ocs//:defs.bzl", "ocs") + +ocs( + name = "run_custom_plugin", + ocs_app = "plugins/MyCustomPlugin.jar", + ocs_config_files = glob([ + "plugins/CreateProject.json", + "plugins/InputFilesUpdate.json", + "plugins/config/*.json", + ]), + dpa_file = "project/EcuBsw.dpa", + davinci_project_files = glob([ + "project/Config/**/*.arxml", + "project/Config/**/*.xml", + ]), + input_files = [ + "input/System.arxml", + "input/Communication.dbc", + ], + result = [ + "output/ModifiedConfig.arxml", + "output/GeneratedReport.xml", + ], + ocs_args = "--verbose --debug", +) +``` + +--- + +### cfg5_execute_script_task + +Executes a CFG5 script task (DVGroovy or JAR script). + +**Location:** `private/rules.bzl` (exported via `defs.bzl`) + +**Signature:** +```python +cfg5_execute_script_task( + name, + dpa_file, + script, + script_task, + result, + davinci_project_files = [] +) +``` + +**Attributes:** + +| Name | Type | Description | Required | Default | +|------|------|-------------|----------|---------| +| `name` | Name | Unique name for this target | Yes | - | +| `dpa_file` | Label | DaVinci project file | Yes | - | +| `script` | Label | Script file (.jar or .dvgroovy) | Yes | - | +| `script_task` | String | Name of the script task to execute | Yes | - | +| `result` | List[Output] | Expected output files from script execution | Yes | - | +| `davinci_project_files` | List[Label] | Project files if project is modified | No | `[]` | + +**Usage Example:** +```python +load("@rules_ocs//:defs.bzl", "cfg5_execute_script_task") + +cfg5_execute_script_task( + name = "execute_validation_script", + dpa_file = "project/EcuBsw.dpa", + script = "scripts/ValidateConfiguration.dvgroovy", + script_task = "ValidateConfig", + davinci_project_files = glob([ + "project/Config/**/*.arxml", + ]), + result = [ + "output/ValidationReport.xml", + "output/ValidationLog.txt", + ], +) + +# Example with JAR script +cfg5_execute_script_task( + name = "generate_documentation", + dpa_file = "project/EcuBsw.dpa", + script = "scripts/DocGenerator.jar", + script_task = "GenerateDocs", + result = [ + "output/Documentation.pdf", + ], +) +``` + +--- + +### create_ocs_app_deploy_rule + +Creates an OCS application deployment package (uber JAR) by combining and repacking JAR dependencies. + +**Location:** `private/app_building.bzl` (exported via `defs.bzl`) + +**Signature:** +```python +create_ocs_app_deploy_rule( + name, + deploy_src, + jar_file, + additional_libs = [] +) +``` + +**Attributes:** + +| Name | Type | Description | Required | Default | +|------|------|-------------|----------|---------| +| `name` | Name | Unique name for this target | Yes | - | +| `deploy_src` | Label | Source JAR file to deploy | Yes | - | +| `jar_file` | String | Output JAR file name | Yes | - | +| `additional_libs` | List[Label] | Additional library JARs to include | No | `[]` | + +**Usage Example:** +```python +load("@rules_ocs//:defs.bzl", "create_ocs_app_deploy_rule") + +create_ocs_app_deploy_rule( + name = "build_ocs_plugin", + deploy_src = "//src/main:plugin_deploy.jar", + jar_file = "MyOcsPlugin.jar", + additional_libs = [ + "@maven//:com_google_guava_guava", + "@maven//:org_json_json", + ], +) +``` + +--- + +### seven_zip_toolchain + +Defines 7-Zip toolchain for Windows OCS app building. + +**Location:** `private/toolchains.bzl` (exported via `defs.bzl`) + +**Signature:** +```python +seven_zip_toolchain( + name, + sevenzip_dir = "" +) +``` + +**Attributes:** + +| Name | Type | Description | Required | Default | +|------|------|-------------|----------|---------| +| `name` | Name | Unique name for this target | Yes | - | +| `sevenzip_dir` | String | Path to 7-Zip installation directory | No | `""` | + +**Usage Example:** +```python +load("@rules_ocs//:defs.bzl", "seven_zip_toolchain") + +seven_zip_toolchain( + name = "seven_zip_toolchain_impl", + sevenzip_dir = "C:/Program Files/7-Zip", +) + +toolchain( + name = "seven_zip_toolchain", + exec_compatible_with = ["@platforms//os:windows"], + toolchain = ":seven_zip_toolchain_impl", + toolchain_type = "//rules/ocs:toolchain_type", +) +``` + +--- + +## Usage Guide + +### Setup OCS Environment + +1. **Add module dependencies in MODULE.bazel:** +```python +bazel_dep(name = "rules_ocs", version = "0.0.1") +bazel_dep(name = "rules_davinci_developer", version = "0.0.1") +bazel_dep(name = "rules_cfg5", version = "0.0.3") +bazel_dep(name = "rules_common", version = "0.2.0") + +# Required for Linux execution +bazel_dep(name = "rules_dotnet", version = "0.17.5") +dotnet = use_extension("@rules_dotnet//dotnet:extensions.bzl", "dotnet") +dotnet.toolchain(dotnet_version = "8.0.103") +use_repo(dotnet, "dotnet_toolchains") +``` + +2. **Define required toolchains in BUILD.bazel:** +```python +load("@rules_davinci_developer//:toolchains.bzl", "davinci_developer_toolchain") +load("@rules_cfg5//:defs.bzl", "cfg5_toolchain") + +# DaVinci Developer toolchain +davinci_developer_toolchain( + name = "davinci_dev_toolchain_impl", + davinci_developer_cmd_label = "@davinci_tools//:DEVImEx", +) + +toolchain( + name = "davinci_developer_toolchain", + toolchain = ":davinci_dev_toolchain_impl", + toolchain_type = "@rules_davinci_developer//:toolchain_type", +) + +# CFG5 toolchain +cfg5_toolchain( + name = "cfg5_toolchain_impl", + cfg5cli_path = "@davinci_cfg5//:DVCfg5Cli", +) + +toolchain( + name = "cfg5_toolchain", + toolchain = ":cfg5_toolchain_impl", + toolchain_type = "@rules_cfg5//:toolchain_type", +) +``` + +3. **Register toolchains in MODULE.bazel:** +```python +register_toolchains( + "//toolchains:davinci_developer_toolchain", + "//toolchains:cfg5_toolchain", +) +``` + +### Execute OCS Application + +```python +load("@rules_ocs//:defs.bzl", "ocs") + +ocs( + name = "run_ocs_plugin", + ocs_app = "plugins/MyPlugin.jar", + ocs_config_files = glob(["plugins/config/*.json"]), + dpa_file = "project/MyProject.dpa", + davinci_project_files = glob(["project/Config/**/*"]), + result = ["output/result.arxml"], +) +``` + +### Execute CFG5 Script Task + +```python +load("@rules_ocs//:defs.bzl", "cfg5_execute_script_task") + +cfg5_execute_script_task( + name = "run_script", + dpa_file = "project/MyProject.dpa", + script = "scripts/MyScript.dvgroovy", + script_task = "MyTask", + result = ["output/result.txt"], +) +``` + +### OCS Configuration Files + +OCS supports special configuration JSON files: + +**CreateProject.json** - Creates new DaVinci project: +```json +{ + "generalSettings": { + "projectFolder": "path/to/project" + }, + "developerWorkspace": { + "developerExecutable": "path/to/DaVinciDEV.exe" + } +} +``` + +**InputFilesUpdate.json** - Updates input files in project: +```json +{ + "inputFiles": [ + { + "path": "path/to/input.arxml", + "type": "AUTOSAR" + } + ] +} +``` + +The rule automatically modifies these files with correct paths. + +--- + +## Dependencies + +### Required Bazel Modules +- `rules_davinci_developer` - DaVinci Developer toolchain +- `rules_cfg5` - DaVinci Configurator 5 toolchain +- `rules_common` - Common utilities +- `rules_dotnet` (Linux only) - .NET runtime + +### External Tools +- **DaVinci Configurator 5**: CFG5 CLI executable +- **DaVinci Developer**: For OCS project operations +- **7-Zip** (Windows only): For OCS app building +- **.NET Runtime** (Linux): For CFG5 execution + +--- + +## Platform Support + +| Platform | Support Level | Notes | +|----------|--------------|-------| +| Linux (x64) | ✅ Full | Requires .NET runtime via rules_dotnet | +| Windows (x64) | ✅ Full | Requires 7-Zip for app building | +| macOS | ❌ Not Supported | DaVinci tools not available | + +--- + +## Limitations + +1. **Single OCS Task**: Each rule invocation runs one OCS task/script +2. **Output Prediction**: Must pre-declare all expected output files +3. **Project Modification**: Project files copied to handle readonly restrictions +4. **JSON Configuration**: Auto-modification limited to specific JSON formats +5. **7-Zip Dependency**: Windows app building requires 7-Zip +6. **Script Format**: Supports .jar and .dvgroovy scripts only + +--- + +## Advanced Features + +### Automatic Path Resolution + +The rule automatically resolves paths in OCS configuration files: + +- **CreateProject.json**: Updates `projectFolder` and `developerExecutable` +- **InputFilesUpdate.json**: Updates input file paths to Bazel paths + +### Project File Management + +Automatically handles: +- Copying DPA and config files to workspace +- Removing write protection (Windows and Linux) +- Maintaining project structure + +--- + +## Troubleshooting + +### Common Issues + +**Issue**: "Developer toolchain is needed for OCS" +- **Solution**: Ensure `rules_davinci_developer` toolchain is registered +- **Check**: `davinci_developer_cmd_label` (Linux) or `davinci_developer_path` (Windows) + +**Issue**: "Cfg5 toolchain is needed for OCS" +- **Solution**: Ensure `rules_cfg5` toolchain is registered +- **Check**: `cfg5cli_path` must be set + +**Issue**: "7z is needed under Windows" +- **Solution**: Define `seven_zip_toolchain` and register it +- **Install**: Download 7-Zip from https://www.7-zip.org/ + +**Issue**: OCS config files not found +- **Solution**: Verify `ocs_config_files` glob pattern matches files +- **Check**: Files must be in subdirectory with `/plugins/` in path + +**Issue**: CreateProject.json path not updated +- **Solution**: Ensure JSON file named exactly "CreateProject.json" +- **Format**: Verify JSON structure matches expected format + +**Issue**: Script task execution fails +- **Solution**: Verify `script_task` name matches task in script +- **Check**: Ensure script file is valid .jar or .dvgroovy From 607f5078884a8ac72f2d8018dafa335482394683 Mon Sep 17 00:00:00 2001 From: Felix Becker Date: Wed, 21 Jan 2026 09:20:20 +0100 Subject: [PATCH 2/3] Add link to module specific documentation --- README.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/README.md b/README.md index 5967e3f..9fad1f9 100644 --- a/README.md +++ b/README.md @@ -68,3 +68,20 @@ This repository is structured around three main development areas: ├── docs/ # Documentation and guides └── .github/ # CI/CD configuration ``` + +## Rule Documentation + +Comprehensive documentation for each Bazel module is available in its respective directory: + +**User Documentation**: `bcr-modules/modules//README.md` + +### Available Modules + +- **rules_cfg5** - DaVinci Configurator 5 code generation +- **rules_common** - Common utilities for DaVinci tool integration +- **rules_davinci_developer** - DaVinci Developer toolchain +- **rules_dvteam** - DaVinci Team integration automation +- **rules_gradle** - Gradle toolchain and authentication +- **rules_ocs** - OCS execution and CFG5 script tasks + +Each module's README.md contains installation instructions, usage examples, API reference and troubleshooting information. From f91986232b366e5ef00502e3d69ddb5d82a74c09 Mon Sep 17 00:00:00 2001 From: Felix Becker Date: Wed, 21 Jan 2026 10:20:40 +0100 Subject: [PATCH 3/3] Minor fixes --- README.md | 3 ++- bcr-modules/modules/rules_cfg5/README.md | 1 + bcr-modules/modules/rules_davinci_developer/README.md | 3 ++- 3 files changed, 5 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 9fad1f9..a85eada 100644 --- a/README.md +++ b/README.md @@ -8,10 +8,11 @@ To consume the rules defined in this repository, you need to register the custom **Configuration Steps:** -1. **Update `.bazelrc`**: Add the following flag to your project's `.bazelrc` file to point Bazel to the raw content of the registry directory. +1. **Update `.bazelrc`**: Add the following flag to your project's `.bazelrc` file to point Bazel to the registry directory and the Bazel Central Registry. ```properties common --registry=https://raw.githubusercontent.com/vectorgrp/bazel-rules/main/vector-bazel-central-registry + common --registry=https://bcr.bazel.build ``` 2. **Add Dependencies**: In your `MODULE.bazel` file, declare the dependencies you need using `bazel_dep`. diff --git a/bcr-modules/modules/rules_cfg5/README.md b/bcr-modules/modules/rules_cfg5/README.md index ece4b3a..09e23c8 100644 --- a/bcr-modules/modules/rules_cfg5/README.md +++ b/bcr-modules/modules/rules_cfg5/README.md @@ -291,6 +291,7 @@ cc_library( - `rules_common` (version 0.2.0 or higher) - Provides workspace creation utilities - `bazel_skylib` (version 1.7.1 or higher) - Common Bazel utilities - `rules_cc` - C/C++ rules for CcInfo providers +- `ape` - (version 1.0.1 or higher) - Used for file filtering ### External Tools - **DaVinci Configurator 5**: CFG5 CLI executable must be available diff --git a/bcr-modules/modules/rules_davinci_developer/README.md b/bcr-modules/modules/rules_davinci_developer/README.md index 4fd95da..b4771b6 100644 --- a/bcr-modules/modules/rules_davinci_developer/README.md +++ b/bcr-modules/modules/rules_davinci_developer/README.md @@ -313,7 +313,8 @@ developer_run( ## Dependencies ### Required Bazel Modules -- None (standalone module) +- `rules_common` (version 0.2.0 or higher) - Provides workspace creation utilities +- `bazel_skylib` (version 1.7.1 or higher) - Common Bazel utilities ### External Tools - **DaVinci Developer**: One or more of the following binaries: