Skip to content

Commit f07c33d

Browse files
foursixninemattr-felicitymayjanbrasna
authoredFeb 3, 2025··
Add instructions for building and testing with Rust (#35725)
Co-authored-by: Matt Rogers <[email protected]> Co-authored-by: Felicity Chapman <[email protected]> Co-authored-by: Jan Brasna <[email protected]>
1 parent 10e1811 commit f07c33d

File tree

3 files changed

+174
-0
lines changed

3 files changed

+174
-0
lines changed
 

‎assets/images/help/actions/starter-workflow-rust.png

188 KB
Loading

‎content/actions/use-cases-and-examples/building-and-testing/building-and-testing-rust.md

+173
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,173 @@
1+
---
2+
title: Building and testing Rust
3+
intro: You can create a continuous integration (CI) workflow to build and test your Rust project.
4+
versions:
5+
fpt: '*'
6+
ghec: '*'
7+
ghes: '*'
8+
type: tutorial
9+
topics:
10+
- CI
11+
shortTitle: Build & test Rust
12+
---
13+
14+
{% data reusables.actions.enterprise-github-hosted-runners %}
15+
16+
## Introduction
17+
18+
This guide shows you how to build, test, and publish a Rust package.
19+
20+
{% data variables.product.prodname_dotcom %}-hosted runners have a tools cache with preinstalled software, which includes the dependencies for Rust. For a full list of up-to-date software and the preinstalled versions of Rust, see [AUTOTITLE](/actions/using-github-hosted-runners/using-github-hosted-runners/about-github-hosted-runners#preinstalled-software).
21+
22+
## Prerequisites
23+
24+
You should already be familiar with YAML syntax and how it's used with {% data variables.product.prodname_actions %}. For more information, see [AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions).
25+
26+
We recommend that you have a basic understanding of the Rust language. For more information, see [Getting started with Rust](https://www.rust-lang.org/learn).
27+
28+
## Using a Rust workflow template
29+
30+
{% data reusables.actions.workflow-templates-get-started %}
31+
32+
{% data variables.product.prodname_dotcom %} provides a Rust workflow template that should work for most basic Rust projects. The subsequent sections of this guide give examples of how you can customize this workflow template.
33+
34+
{% data reusables.repositories.navigate-to-repo %}
35+
{% data reusables.repositories.actions-tab %}
36+
{% data reusables.actions.new-starter-workflow %}
37+
1. The "Choose a workflow" page shows a selection of recommended workflow templates. Search for "Rust".
38+
1. Filter the selection of workflows by clicking **Continuous integration**.
39+
1. On the "Rust - by {% data variables.product.prodname_actions %}" workflow, click **Configure**.
40+
41+
![Screenshot of the "Choose a workflow" page. The "Configure" button on the "Rust" workflow is highlighted with an orange outline.](/assets/images/help/actions/starter-workflow-rust.png)
42+
43+
{%- ifversion ghes %}
44+
If you don't find the "Rust - by {% data variables.product.prodname_actions %}" workflow template, copy the following workflow code to a new file called `rust.yml` in the `.github/workflows` directory of your repository.
45+
46+
```yaml copy
47+
name: Rust
48+
49+
on:
50+
push:
51+
branches: [ "main" ]
52+
pull_request:
53+
branches: [ "main" ]
54+
55+
env:
56+
CARGO_TERM_COLOR: never
57+
58+
jobs:
59+
build:
60+
61+
runs-on: ubuntu-latest
62+
63+
steps:
64+
- uses: {% data reusables.actions.action-checkout %}
65+
- name: Build
66+
run: cargo build --verbose
67+
- name: Run tests
68+
run: cargo test --verbose
69+
```
70+
71+
{%- endif %}
72+
73+
1. Edit the workflow as required. For example, change the version of Rust.
74+
1. Click **Commit changes**.
75+
76+
{% ifversion fpt or ghec %}
77+
The `rust.yml` workflow file is added to the `.github/workflows` directory of your repository.
78+
{% endif %}
79+
80+
## Specifying a Rust version
81+
82+
{% data variables.product.prodname_dotcom %}-hosted runners include a recent version of the Rust toolchain. You can use rustup to report on the version installed on a runner, override the version, and to install different toolchains. For more information, see [The rustup book](https://rust-lang.github.io/rustup/).
83+
84+
This example shows steps you could use to setup your runner environment to use the nightly build of rust and to report the version.
85+
86+
```yaml copy
87+
- name: Temporarily modify the rust toolchain version
88+
run: rustup override set nightly
89+
- name: Output rust version for educational purposes
90+
run: rustup --version
91+
```
92+
93+
### Caching dependencies
94+
95+
You can cache and restore dependencies using the Cache action. This example assumes that your repository contains a `Cargo.lock` file.
96+
97+
```yaml copy
98+
- name: Cache
99+
- uses: {% data reusables.actions.action-cache %}
100+
with:
101+
path: |
102+
~/.cargo/registry
103+
~/.cargo/git
104+
target
105+
key: {% raw %}${{ runner.os }}-cargo-${{ hashFiles('**/Cargo.lock') }}{% endraw %}
106+
```
107+
108+
If you have custom requirements or need finer controls for caching, you should explore other configuration options for the [`cache` action](https://github.com/marketplace/actions/cache). For more information, see [AUTOTITLE](/actions/using-workflows/caching-dependencies-to-speed-up-workflows).
109+
110+
## Building and testing your code
111+
112+
You can use the same commands that you use locally to build and test your code. This example workflow demonstrates how to use `cargo build` and `cargo test` in a job:
113+
114+
```yaml copy
115+
jobs:
116+
build:
117+
runs-on: ubuntu-latest
118+
strategy:
119+
matrix:
120+
BUILD_TARGET: [release] # refers to a cargo profile
121+
outputs:
122+
release_built: {% raw %}${{ steps.set-output.outputs.release_built }}{% endraw %}
123+
steps:
124+
- uses: {% data reusables.actions.action-checkout %}
125+
- name: Build binaries in "{% raw %}${{ matrix.BUILD_TARGET }}{% endraw %}" mode
126+
run: cargo build --profile ${% raw %}{{ matrix.BUILD_TARGET }}{% endraw %}
127+
- name: Run tests in "${% raw %}{{ matrix.BUILD_TARGET }}{% endraw %}" mode
128+
run: cargo test --profile ${% raw %}{{ matrix.BUILD_TARGET }}{% endraw %}
129+
```
130+
131+
The `release` keyword used in this example corresponds to a cargo profile. You can use any [profile](https://doc.rust-lang.org/cargo/reference/profiles.html) you have defined in your `Cargo.toml` file.
132+
133+
## Publishing your package or library to crates.io
134+
135+
Once you have setup your workflow to build and test your code, you can use a secret to login to [crates.io](https://crates.io/) and publish your package.
136+
137+
```yaml copy
138+
- name: Login into crates.io
139+
run: cargo login {% raw %}${{ secrets.CRATES_IO }}{% endraw %}
140+
- name: Build binaries in "release" mode
141+
run: cargo build -r
142+
- name: "Package for crates.io"
143+
run: cargo package # publishes a package as a tarball
144+
- name: "Publish to crates.io"
145+
run: cargo publish # publishes your crate as a library that can be added as a dependency
146+
```
147+
148+
If there are any errors building and packaging the crate, check the metadata in your manifest, `Cargo.toml` file, see [The Manifest Format](https://doc.rust-lang.org/cargo/reference/manifest.html). You should also check your `Cargo.lock` file, see [Cargo.toml vs Cargo.lock](https://doc.rust-lang.org/cargo/guide/cargo-toml-vs-cargo-lock.html).
149+
150+
## Packaging workflow data as artifacts
151+
152+
After a workflow completes, you can upload the resulting artifacts for analysis or to use in another workflow. You could add these example steps to the workflow to upload an application for use by another workflow.
153+
154+
```yaml copy
155+
- name: Upload release artifact
156+
uses: {% data reusables.actions.action-upload-artifact %}
157+
with:
158+
name: {% raw %}<my-app>{% endraw %}
159+
path: {% raw %}target/${{ matrix.BUILD_TARGET }}/<my-app>{% endraw %}
160+
```
161+
162+
To use the uploaded artifact in a different job, ensure your workflows have the right permissions for the repository, see [AUTOTITLE](/actions/security-for-github-actions/security-guides/automatic-token-authentication). You could use these example steps to download the app created in the previous workflow and publish it on {% data variables.product.github %}.
163+
164+
```yaml copy
165+
- uses: {% data reusables.actions.action-checkout %}
166+
- name: Download release artifact
167+
uses: {% data reusables.actions.action-download-artifact %}
168+
with:
169+
name: {% raw %}<my-app>{% endraw %}
170+
path: ./{% raw %}<my-app>{% endraw %}
171+
- name: Publish built binary to {% data variables.product.github %} releases
172+
- run: |
173+
gh release create --generate-notes ./{% raw %}<my-app>/<my-project>#<my-app>{% endraw %}

‎content/actions/use-cases-and-examples/building-and-testing/index.md

+1
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,7 @@ children:
2727
- /building-and-testing-powershell
2828
- /building-and-testing-python
2929
- /building-and-testing-ruby
30+
- /building-and-testing-rust
3031
- /building-and-testing-swift
3132
- /building-and-testing-xamarin-applications
3233
---

0 commit comments

Comments
 (0)
Please sign in to comment.