Reloaded Lightweight Rust Build Action

A GitHub Action for building optimized, lightweight Rust binaries and C libraries.

Uses nightly Rust and nightly-only features to minimize binary size and maximize performance:

• Self-Built std: Smaller binaries, better optimizations.
• Abort on Panic: Smaller binaries. (Can be disabled)
• Profile Guided Optimization (PGO): Optimizes based on runtime usage patterns.
• Cross-Compilation: Via cross-rs.
• Tests and Coverage: Optional, via devops-rust-test-and-coverage action.

As a single job/step of a workflow:

build:
  strategy:
    matrix:
      include:
        - os: ubuntu-latest
          target: x86_64-unknown-linux-gnu
          use-pgo: true
          use-cross: false
        - os: windows-latest
          target: x86_64-pc-windows-msvc
          use-pgo: true
          use-cross: false
        - os: macos-latest
          target: aarch64-apple-darwin
          use-pgo: true
          use-cross: false
        - os: ubuntu-latest
          target: aarch64-unknown-linux-gnu
          use-pgo: false # no native runner
          use-cross: true
  runs-on: ${{ matrix.os }}
  steps:
    - name: Checkout Repository
      uses: actions/checkout@v4
    - name: Build Binary
      uses: Reloaded-Project/devops-rust-lightweight-binary@v1
      with:
        target: ${{ matrix.target }}
        crate-name: "my-crate"
        use-pgo: ${{ matrix.use-pgo }}
        use-cross: ${{ matrix.use-cross }}

To use this action in your own repository:

1. Create a new workflow file (e.g., .github/workflows/build-c-library.yml) in your repository.
2. Copy the example usage job from above into the new workflow file.
3. Customize the input parameters as needed for your project.

These parameters are only used when run-tests-and-coverage is enabled and are passed directly to the devops-rust-test-and-coverage action:

Note: The following parameters are used by both this action AND passed through to the test action: target, features, no-default-features, use-cross.

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.

PGO 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:

#[cfg(not(feature = "pgo"))]
{
    // Regular benchmarks, unrealistic for profiling, exclude
    bench_estimate(c);
    bench_decompress(c);
}

#[cfg(feature = "pgo")]
{
    // Realistic usage patterns for PGO
    generate_pgo_data();
}

PGO requires the target platform to match the host. With use-cross: true, cross-compilation may work:

target: aarch64-unknown-linux-gnu  # x64 host to aarch64 simulated guest
use-pgo: true
use-cross: true

If the process fails, your CI will fail, so experiment to find what works.

Set run-tests-and-coverage: true to run tests and generate coverage after the build.

This invokes devops-rust-test-and-coverage with the same configuration (target, features, use-cross, etc.).

• Tests run via cargo or cross (based on use-cross)
• Coverage via Tarpaulin when use-tarpaulin: true (ignored if use-cross: true)

Set build-library: true to build a library instead of a binary (equivalent to crate-type = ["cdylib", "staticlib"]).

Artifacts include static (.a, .lib) and dynamic (.so, .dll, .dylib) libraries depending on target.

Find more examples in the tests.

- name: Build C Library
  uses: Reloaded-Project/devops-rust-lightweight-binary@v1
  with:
    crate-name: my-crate
    target: x86_64-unknown-linux-gnu
    additional-rustflags: -C opt-level=3
    additional-rustc-args: --all-features

- name: Build C Library with Specific Nightly
  uses: Reloaded-Project/devops-rust-lightweight-binary@v1
  with:
    crate-name: my-crate
    target: x86_64-unknown-linux-gnu
    rust-toolchain: nightly-2025-09-18

When building multiple crates within a workspace with the same settings, use a single job. Shared dependencies are compiled once and reused:

- name: Build API Crate
  uses: Reloaded-Project/devops-rust-lightweight-binary@v1
  with:
    rust-project-path: projects/api-crate
    crate-name: api-crate
    target: x86_64-unknown-linux-gnu
    use-cache: true  # first step: restore cache
    install-binstall: true  # default

- name: Build CLI Crate
  uses: Reloaded-Project/devops-rust-lightweight-binary@v1
  with:
    rust-project-path: projects/cli-crate
    crate-name: cli-crate
    target: x86_64-unknown-linux-gnu
    use-cache: false  # subsequent steps: disable to avoid duplicate save
    install-binstall: false  # already installed above

When building crates with different settings, use separate jobs to avoid cache conflicts:

jobs:
  build-standard:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: Reloaded-Project/devops-rust-lightweight-binary@v1
        with:
          crate-name: my-crate
          target: x86_64-unknown-linux-gnu
          features: ""

  build-with-simd:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: Reloaded-Project/devops-rust-lightweight-binary@v1
        with:
          crate-name: my-crate
          target: x86_64-unknown-linux-gnu
          features: "simd,avx2"

Building these in a single job would cause cache conflicts since both use the same target but different features.

After a successful run, the built artifacts will be available as a downloadable artifact in the GitHub Actions run.

Artifact names follow the pattern: {artifact-prefix}-{target}[-features] or {target}[-features] when no prefix is set.

When use-friendly-target-names is enabled (default), the target triple is replaced with a user-friendly platform identifier (e.g., x86_64-unknown-linux-gnu becomes linux-x64, aarch64-apple-darwin becomes macos-arm64). Unmapped targets fall back to the raw target triple.

Use artifact-name-exclude-features to exclude specific features from artifact names while still building them. This is useful when features are already distinguished by artifact-prefix (e.g., C library builds).

The default exclusion is c-exports, which is commonly redundant for C library builds in Reloaded projects; where often the prefix is something like c-library. To include all features in names, set to an empty string "".

When upload-symbols-separately is enabled (default), debug symbols are uploaded as separate artifacts with a .symbols suffix:

• Main artifact: MyApp-linux-x64
• Symbol artifact: MyApp-linux-x64.symbols

To access the artifacts:

1. Navigate to the Actions tab in your repository.
2. Click on the workflow run that built the artifacts.
3. In the "Artifacts" section, you will find the generated artifacts, which you can download.

The crate-name parameter is still used for:

• Cache key: When provided, it helps create unique cache keys for your builds
• Artifact directory: Used in the ARTIFACT_OUT_DIR path construction

However, using crate-name for artifact naming is deprecated. Please use artifact-prefix instead.

For backwards compatibility, if crate-name is set and artifact-prefix is not provided, the legacy naming behaviour is used:

• Binary artifacts: {crate-name}-{target}[-features]
• Library artifacts: C-Library-{crate-name}-{target}[-features]

A deprecation warning will appear in the workflow logs when this legacy behaviour is triggered.

Migration: Replace crate-name: my-crate with artifact-prefix: my-crate for binaries, or artifact-prefix: C-Library-my-crate for libraries to maintain the same artifact names.

Building C libraries from Rust projects can be a complex process, especially when considering different target platforms, compiler flags, and optimizations like PGO.

This action simplifies the process by providing a configurable and reusable workflow that handles the building of C libraries from Rust projects.

Contributions are welcome! If you encounter any issues or have suggestions for improvements, please open an issue or submit a pull request in this repository.

This project is licensed under the MIT License. See the LICENSE file for details.