{"id":19293507,"url":"https://github.com/reloaded-project/devops-rust-lightweight-binary","last_synced_at":"2026-03-19T09:08:08.834Z","repository":{"id":244726644,"uuid":"816048950","full_name":"Reloaded-Project/devops-rust-lightweight-binary","owner":"Reloaded-Project","description":"Composite Action for Building \u0026 Cross Compiling Lightweight no_std Rust Binaries with PGO","archived":false,"fork":false,"pushed_at":"2025-12-15T09:36:13.000Z","size":311,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"v1-master","last_synced_at":"2025-12-17T07:32:51.804Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Reloaded-Project.png","metadata":{"files":{"readme":"README.MD","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-06-16T23:16:49.000Z","updated_at":"2025-12-15T09:35:12.000Z","dependencies_parsed_at":"2024-12-25T12:22:01.417Z","dependency_job_id":"54c7de05-6979-40cd-8a29-e48f4db46277","html_url":"https://github.com/Reloaded-Project/devops-rust-lightweight-binary","commit_stats":null,"previous_names":["reloaded-project/devops-rust-lightweight-binary"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/Reloaded-Project/devops-rust-lightweight-binary","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Reloaded-Project%2Fdevops-rust-lightweight-binary","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Reloaded-Project%2Fdevops-rust-lightweight-binary/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Reloaded-Project%2Fdevops-rust-lightweight-binary/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Reloaded-Project%2Fdevops-rust-lightweight-binary/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Reloaded-Project","download_url":"https://codeload.github.com/Reloaded-Project/devops-rust-lightweight-binary/tar.gz/refs/heads/v1-master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Reloaded-Project%2Fdevops-rust-lightweight-binary/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29998513,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-02T09:59:02.300Z","status":"ssl_error","status_checked_at":"2026-03-02T09:59:02.001Z","response_time":60,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-09T22:35:14.586Z","updated_at":"2026-03-19T09:08:08.827Z","avatar_url":"https://github.com/Reloaded-Project.png","language":"Shell","readme":"\u003cdiv align=\"center\"\u003e\n  \u003ca href=\"https://github.com/Reloaded-Project/rust-lightweight-binary\" target=\"_blank\"\u003e\n    \u003cimg src=\"assets/reloaded-logo.png\" alt=\"reloaded Logo\" width=\"100\"/\u003e\n  \u003c/a\u003e\n\n  \u003ch1 align=\"center\"\u003eReloaded Lightweight Rust Build Action\u003c/h1\u003e\n\n  \u003cp\u003e\n    \u003ca href=\"LICENSE\"\u003e\n      \u003cimg src=\"https://img.shields.io/badge/License-MIT-blue.svg\" alt=\"License\"\u003e\n    \u003c/a\u003e\n  \u003c/p\u003e\n\u003c/div\u003e\n\nA GitHub Action for building optimized, lightweight Rust binaries and C libraries.\n\nUses nightly Rust and nightly-only features to minimize binary size and maximize performance:\n\n- **Self-Built std**: Smaller binaries, better optimizations.\n- **Abort on Panic**: Smaller binaries. (Can be disabled)\n- **Profile Guided Optimization (PGO)**: Optimizes based on runtime usage patterns.\n- **Cross-Compilation**: Via `cross-rs`.\n- **Tests and Coverage**: Optional, via `devops-rust-test-and-coverage` action.\n\n## Example Usage\n\nAs a single job/step of a workflow:\n\n```yaml\nbuild:\n  strategy:\n    matrix:\n      include:\n        - os: ubuntu-latest\n          target: x86_64-unknown-linux-gnu\n          use-pgo: true\n          use-cross: false\n        - os: windows-latest\n          target: x86_64-pc-windows-msvc\n          use-pgo: true\n          use-cross: false\n        - os: macos-latest\n          target: aarch64-apple-darwin\n          use-pgo: true\n          use-cross: false\n        - os: ubuntu-latest\n          target: aarch64-unknown-linux-gnu\n          use-pgo: false # no native runner\n          use-cross: true\n  runs-on: ${{ matrix.os }}\n  steps:\n    - name: Checkout Repository\n      uses: actions/checkout@v4\n    - name: Build Binary\n      uses: Reloaded-Project/devops-rust-lightweight-binary@v1\n      with:\n        target: ${{ matrix.target }}\n        crate-name: \"my-crate\"\n        use-pgo: ${{ matrix.use-pgo }}\n        use-cross: ${{ matrix.use-cross }}\n```\n\n\u003e [!TIP]\n\u003e Adjust `rust-project-path` and `workspace-path` (if using cargo workspaces) if your project is not in the root folder `.`.\n\n## Setup\n\nTo use this action in your own repository:\n\n1. Create a new workflow file (e.g., `.github/workflows/build-c-library.yml`) in your repository.\n2. Copy the example usage job from above into the new workflow file.\n3. Customize the input parameters as needed for your project.\n\n## Configuration\n\n### Inputs\n\n#### Commonly Used\n\n| Input                    | Required | Default | Description                                                                                                                                    |\n| ------------------------ | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |\n| `rust-project-path`      | No       | `.`     | Path to the Rust project                                                                                                                       |\n| `workspace-path`         | No       | `.`     | Workspace folder where `target` directory is. Uses `rust-project-path` if not set.                                                             |\n| `build-library`          | No       | `false` | Build a library instead of a binary.                                                                                                           |\n| `target`                 | Yes      |         | The target platform for the Rust compiler                                                                                                      |\n| `features`               | No       | `''`    | Comma-separated list of features to include in the build                                                                                       |\n| `artifact-prefix`        | No       | `''`    | Prefix for artifact names. Combined with target/features to form final name (e.g., `MyApp` -\u003e `MyApp-linux-x64`). If empty, no prefix is used. |\n| `run-tests-and-coverage` | No       | `false` | Run tests and coverage using the `devops-rust-test-and-coverage` action.                                                                       |\n| `use-cache`              | No       | `true`  | Enable or disable the build cache using `Swatinem/rust-cache`.                                                                                 |\n\n#### Build Configuration\n\n| Input                 | Required | Default   | Description                                                                                         |\n| --------------------- | -------- | --------- | --------------------------------------------------------------------------------------------------- |\n| `no-default-features` | No       | `false`   | Do not include default features in the build                                                        |\n| `rust-toolchain`      | No       | `nightly` | The Rust toolchain to use. Can be nightly or a specific nightly version (e.g., nightly-2025-09-18). |\n| `use-cross`           | No       | `false`   | Use cross-rs for building. If false, use cargo.                                                     |\n\n#### Optimization Options\n\n| Input                | Required | Default          | Description                                                                            |\n| -------------------- | -------- | ---------------- | -------------------------------------------------------------------------------------- |\n| `use-pgo`            | No       | `false`          | Use Profile-Guided Optimization [PGO] to build the library.                            |\n| `pgo-project-path`   | No       | `.`              | Path to the Rust project used for gathering PGO data. Can be same or separate project. |\n| `pgo-benchmark-name` | No       | `'my_benchmark'` | Benchmark name to use with PGO.                                                        |\n| `abort-on-panic`     | No       | `true`           | Abort immediately on panic. If false, the default panic handler is used.               |\n| `size-optimized-std` | No       | `false`          | Builds `std` with size optimizations, such as reduced `core::fmt` footprint.           |\n\n#### Artifact \u0026 Output Settings\n\n| Input                            | Required | Default                   | Description                                                                                                                                                       |\n| -------------------------------- | -------- | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `upload-artifacts`               | No       | `true`                    | Upload the built artifacts as a GitHub Actions artifact                                                                                                           |\n| `upload-symbols-separately`      | No       | `true`                    | Upload debug symbol files (.pdb, .dwp, .dSYM) as separate artifacts instead of bundling with main artifacts                                                       |\n| `use-friendly-target-names`      | No       | `true`                    | Transform target triples to user-friendly names (e.g., `x86_64-unknown-linux-gnu` -\u003e `linux-x64`) in artifact names.                                              |\n| `artifact-name-exclude-features` | No       | `c-exports,bench,nightly` | Comma-separated list of features to exclude from artifact names. Features are still built but not included in artifact names. Set to empty string to include all. |\n\n#### Advanced / Low-Level\n\n| Input                     | Required | Default | Description                                       |\n| ------------------------- | -------- | ------- | ------------------------------------------------- |\n| `additional-rustflags`    | No       | `''`    | Additional RUSTFLAGS to pass to the Rust compiler |\n| `additional-rustc-args`   | No       | `''`    | Additional arguments to pass directly to `rustc`  |\n| `additional-std-features` | No       | ``      | Specify extra `build-std` features.               |\n\n#### Parameters Passed Through to `devops-rust-test-and-coverage`\n\nThese parameters are only used when `run-tests-and-coverage` is enabled and are passed directly to the [devops-rust-test-and-coverage][devops-test-coverage] action:\n\n| Input                        | Required | Default              | Description                                                                                           |\n| ---------------------------- | -------- | -------------------- | ----------------------------------------------------------------------------------------------------- |\n| `upload-coverage-to-codecov` | No       | `true`               | Whether to upload coverage to Codecov                                                                 |\n| `codecov-token`              | No       |                      | Codecov token for uploading coverage                                                                  |\n| `use-tarpaulin`              | No       | `true`               | Whether to use Tarpaulin for code coverage. If false, only runs tests.                                |\n| `use-binstall`               | No       | `true`               | Whether to use cargo-binstall for installing components like tarpaulin. If false, uses cargo install. |\n| `install-binstall`           | No       | `true`               | Whether to install cargo-binstall. If false, assumes it is already available in the environment.      |\n| `additional-test-args`       | No       | `''`                 | Additional arguments passed directly to the cargo test command.                                       |\n| `additional-tarpaulin-args`  | No       | `''`                 | Additional arguments passed directly to the cargo tarpaulin command.                                  |\n| `codecov-flags`              | No       | `'unittests'`        | Flags to pass to Codecov for organizing coverage reports.                                             |\n| `codecov-name`               | No       | `'codecov-umbrella'` | Custom defined name for the coverage upload.                                                          |\n| `packages`                   | No       | `''`                 | Multi-line list of package names to test (one per line). If empty, tests all packages in workspace.   |\n\n**Note:** The `packages` parameter is passed through to the test action and does not affect which binary is built.\n\n**Note:** The following parameters are used by both this action AND passed through to the test action: `target`, `features`, `no-default-features`, `use-cross`.\n\n\u003e **Note:** Stable and beta toolchains are not supported due to required nightly features. Only nightly and specific nightly versions (e.g., `nightly-2025-09-18`) are supported.\n\n### Setting up Profile-Guided Optimization (PGO)\n\nPGO compiles and runs a benchmark (configured via `pgo-benchmark-name` and `pgo-project-path`) to collect runtime data, then uses that profile to optimize the final build. Keep the benchmark close to real usage patterns:\n\n```rust\n#[cfg(not(feature = \"pgo\"))]\n{\n    // Regular benchmarks, unrealistic for profiling, exclude\n    bench_estimate(c);\n    bench_decompress(c);\n}\n\n#[cfg(feature = \"pgo\")]\n{\n    // Realistic usage patterns for PGO\n    generate_pgo_data();\n}\n```\n\nPGO requires the target platform to match the host. With `use-cross: true`, cross-compilation may work:\n\n```yaml\ntarget: aarch64-unknown-linux-gnu  # x64 host to aarch64 simulated guest\nuse-pgo: true\nuse-cross: true\n```\n\nIf the process fails, your CI will fail, so experiment to find what works.\n\n## Running Tests and Coverage\n\nSet `run-tests-and-coverage: true` to run tests and generate coverage after the build.\n\nThis invokes [devops-rust-test-and-coverage][devops-test-coverage] with the same configuration (`target`, `features`, `use-cross`, etc.).\n\n- Tests run via `cargo` or `cross` (based on `use-cross`)\n- Coverage via Tarpaulin when `use-tarpaulin: true` (ignored if `use-cross: true`)\n\n## Building Libraries\n\nSet `build-library: true` to build a library instead of a binary (equivalent to `crate-type = [\"cdylib\", \"staticlib\"]`).\n\nArtifacts include static (`.a`, `.lib`) and dynamic (`.so`, `.dll`, `.dylib`) libraries depending on target.\n\n## Examples\n\nFind more examples in [the tests](./.github/workflows/test-rust-build-c-library-workflow.yml).\n\n### Custom `rustc` Arguments and RUSTFLAGS\n\n```yaml\n- name: Build C Library\n  uses: Reloaded-Project/devops-rust-lightweight-binary@v1\n  with:\n    crate-name: my-crate\n    target: x86_64-unknown-linux-gnu\n    additional-rustflags: -C opt-level=3\n    additional-rustc-args: --all-features\n```\n\n### Pin to Specific Nightly Version\n\n```yaml\n- name: Build C Library with Specific Nightly\n  uses: Reloaded-Project/devops-rust-lightweight-binary@v1\n  with:\n    crate-name: my-crate\n    target: x86_64-unknown-linux-gnu\n    rust-toolchain: nightly-2025-09-18\n```\n\n### Building Multiple Projects\n\n\u003e [!TIP]\n\u003e The best approach depends on whether your builds share the same settings.\n\n#### Same Settings\n\nWhen building multiple crates within a workspace with the same settings, use a single job.\nShared dependencies are compiled once and reused:\n\n```yaml\n- name: Build API Crate\n  uses: Reloaded-Project/devops-rust-lightweight-binary@v1\n  with:\n    rust-project-path: projects/api-crate\n    crate-name: api-crate\n    target: x86_64-unknown-linux-gnu\n    use-cache: true  # first step: restore cache\n    install-binstall: true  # default\n\n- name: Build CLI Crate\n  uses: Reloaded-Project/devops-rust-lightweight-binary@v1\n  with:\n    rust-project-path: projects/cli-crate\n    crate-name: cli-crate\n    target: x86_64-unknown-linux-gnu\n    use-cache: false  # subsequent steps: disable to avoid duplicate save\n    install-binstall: false  # already installed above\n```\n\n\u003e [!NOTE]\n\u003e Only enable `use-cache` on the first step. The cache is restored at the start and saved after the job completes.\n\u003e Same applies to `install-binstall` - only install once per job.\n\n#### Different Settings\n\nWhen building crates with different settings, use separate jobs to avoid cache conflicts:\n\n```yaml\njobs:\n  build-standard:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v4\n      - uses: Reloaded-Project/devops-rust-lightweight-binary@v1\n        with:\n          crate-name: my-crate\n          target: x86_64-unknown-linux-gnu\n          features: \"\"\n\n  build-with-simd:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v4\n      - uses: Reloaded-Project/devops-rust-lightweight-binary@v1\n        with:\n          crate-name: my-crate\n          target: x86_64-unknown-linux-gnu\n          features: \"simd,avx2\"\n```\n\nBuilding these in a single job would cause cache conflicts since both use the same target but different features.\n\n## Accessing the Built Artifacts\n\nAfter a successful run, the built artifacts will be available as a downloadable\nartifact in the GitHub Actions run.\n\n### Artifact Naming\n\nArtifact names follow the pattern: `{artifact-prefix}-{target}[-features]` or `{target}[-features]` when no prefix is set.\n\n| Scenario                  | Example Name                             |\n| ------------------------- | ---------------------------------------- |\n| No prefix, friendly names | `linux-x64`, `windows-arm64`             |\n| With prefix `MyApp`       | `MyApp-linux-x64`, `MyApp-windows-arm64` |\n| With features `simd,avx2` | `linux-x64-simd,avx2`                    |\n| With prefix and features  | `MyApp-linux-x64-simd,avx2`              |\n\nWhen `use-friendly-target-names` is enabled (default), the target triple is replaced with a\nuser-friendly platform identifier (e.g., `x86_64-unknown-linux-gnu` becomes `linux-x64`,\n`aarch64-apple-darwin` becomes `macos-arm64`). Unmapped targets fall back to the raw target triple.\n\n#### Excluding Features from Artifact Names\n\nUse `artifact-name-exclude-features` to exclude specific features from artifact names while still building them.\nThis is useful when features are already distinguished by `artifact-prefix` (e.g., C library builds).\n\n| Features         | Exclude List | Resulting Suffix |\n| ---------------- | ------------ | ---------------- |\n| `c-exports`      | `c-exports`  | (none)           |\n| `c-exports,simd` | `c-exports`  | `-simd`          |\n| `foo,bar`        | `foo,bar`    | (none)           |\n| `bar,foo`        | `foo,bar`    | (none)           |\n\nThe default exclusion is `c-exports`, which is commonly redundant for C library builds in Reloaded projects;\nwhere often the prefix is something like `c-library`. To include all features in names, set to an empty string `\"\"`.\n\nWhen `upload-symbols-separately` is enabled (default), debug symbols are uploaded as separate artifacts\nwith a `.symbols` suffix:\n\n- Main artifact: `MyApp-linux-x64`\n- Symbol artifact: `MyApp-linux-x64.symbols`\n\n### Downloading Artifacts\n\nTo access the artifacts:\n\n1. Navigate to the Actions tab in your repository.\n2. Click on the workflow run that built the artifacts.\n3. In the \"Artifacts\" section, you will find the generated artifacts, which you can download.\n\n## Deprecated Options\n\n### `crate-name` Parameter\n\n| Input        | Required | Default | Description                                                                |\n| ------------ | -------- | ------- | -------------------------------------------------------------------------- |\n| `crate-name` | No       | `''`    | Name of the Rust crate/package. Used for cache key and artifact directory. |\n\nThe `crate-name` parameter is still used for:\n- **Cache key**: When provided, it helps create unique cache keys for your builds\n- **Artifact directory**: Used in the `ARTIFACT_OUT_DIR` path construction\n\nHowever, using `crate-name` for **artifact naming** is deprecated. Please use `artifact-prefix` instead.\n\n#### Legacy Artifact Naming Behaviour\n\nFor backwards compatibility, if `crate-name` is set and `artifact-prefix` is not provided, the legacy\nnaming behaviour is used:\n\n- Binary artifacts: `{crate-name}-{target}[-features]`\n- Library artifacts: `C-Library-{crate-name}-{target}[-features]`\n\nA deprecation warning will appear in the workflow logs when this legacy behaviour is triggered.\n\n**Migration**: Replace `crate-name: my-crate` with `artifact-prefix: my-crate` for binaries, or\n`artifact-prefix: C-Library-my-crate` for libraries to maintain the same artifact names.\n\n## Why this Exists?\n\nBuilding C libraries from Rust projects can be a complex process, especially when\nconsidering different target platforms, compiler flags, and optimizations like PGO.\n\nThis action simplifies the process by providing a configurable and reusable workflow\nthat handles the building of C libraries from Rust projects.\n\n## Contributing\n\nContributions are welcome! If you encounter any issues or have suggestions for improvements,\nplease open an issue or submit a pull request in this repository.\n\n## License\n\nThis project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.\n\n[devops-test-coverage]: https://github.com/Reloaded-Project/devops-rust-test-and-coverage","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Freloaded-project%2Fdevops-rust-lightweight-binary","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Freloaded-project%2Fdevops-rust-lightweight-binary","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Freloaded-project%2Fdevops-rust-lightweight-binary/lists"}