Skip to content

Commit

Permalink
Update instructions for building, testing and publishing with Rust
Browse files Browse the repository at this point in the history
  • Loading branch information
@foursixnine
foursixnine committed Dec 30, 2024
1 parent 9d3f658 commit f3999cd
Showing 1 changed file with 62 additions and 102 deletions.
164 changes: 62 additions & 102 deletions ...ctions/use-cases-and-examples/building-and-testing/building-and-testing-rust.md
View file
Original file line number Diff line number Diff line change
@@ -1,9 +1,7 @@
[---
---
title: Building and testing Rust
intro: You can create a continuous integration (CI) workflow to build and test your Rust project.
versions:
fpt: '*'
ghes: '*'
ghec: '*'
type: tutorial
topics:
Expand Down Expand Up @@ -41,7 +39,6 @@ We recommend that you have a basic understanding of the Rust language. For more
1. On the "Rust - by {% data variables.product.prodname_actions %}" workflow, click **Configure**.

![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)

1. Edit the workflow as required. For example, change the version of Rust.
1. Click **Commit changes**.

Expand All @@ -51,133 +48,96 @@ We recommend that you have a basic understanding of the Rust language. For more

## Specifying a Rust version

~~The easiest way to specify a Rust version is by using the `rustup` action provided by {% data variables.product.prodname_dotcom %}. For more information see, the [`setup-rust` action](https://github.com/actions/setup-rust/).~~

To use a preinstalled version of Rust on a {% data variables.product.prodname_dotcom %}-hosted runner, pass the relevant version to the `rust-version` property of the `setup-rust` action. This action finds a specific version of Rust from the tools cache on each runner, and adds the necessary binaries to `PATH`. These changes will persist for the remainder of the job.

The `setup-rust` action is the recommended way of using rust with {% data variables.product.prodname_actions %}, because it helps ensure consistent behavior across different runners and different versions of Rust. If you are using a self-hosted runner, you must install rust and add it to your self-hosted runner's `PATH`.

### Using multiple versions of rust
### Caching dependencies

You can cache and restore dependencies using the following example below.

```yaml copy
name: Go
- name: ⚡ Cache
uses: actions/cache@v2
with:
path: |
~/.cargo/registry
~/.cargo/git
target
key: ${{ runner.os }}-cargo-${{ hashFiles('**/Cargo.lock') }}
```
If you have a custom requirement or need finer controls for caching, you can use the [`cache` action](https://github.com/marketplace/actions/cache). For more information, see [AUTOTITLE](/actions/using-workflows/caching-dependencies-to-speed-up-workflows).

## Building and testing your code

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:

on: [push]

```yaml copy
jobs:
build:

runs-on: ubuntu-latest
strategy:
matrix:
rust-version: [ '1.8', '1.20', '1.21.x' ]

BUILD_TARGET: [release] # refers to a cargo profile
outputs:
release_built: ${{ steps.set-output.outputs.release_built }}
steps:
- uses: {% data reusables.actions.action-checkout %}
- name: Setup Go {% raw %}${{ matrix.go-version }}{% endraw %}
uses: {% data reusables.actions.action-setup-go %}
with:
go-version: {% raw %}${{ matrix.go-version }}{% endraw %}
# You can test your matrix by printing the current Go version
- name: Display Go version
run: go version
- uses: actions/checkout@v4
- name: Build binaries in "${{ matrix.BUILD_TARGET }}" mode
run: cargo build --profile ${{ matrix.BUILD_TARGET }}
- name: Run tests in "${{ matrix.BUILD_TARGET }}" mode
run: cargo test --profile ${{ matrix.BUILD_TARGET }}
```
Note that the `release` keyword used above, 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.

### Using a specific Go version
You can configure your job to use a specific version of Go, such as `1.20.8`. Alternatively, you can use semantic version syntax to get the latest minor release. This example uses the latest patch release of Go 1.21:
## Upload artifacts

In case publishing artifacts is needed, but not to crates.io, the following example demonstrates how to upload artifacts to the workflow run:
```yaml copy
- name: Setup Go 1.21.x
uses: {% data reusables.actions.action-setup-go %}
- name: Upload Telegram Bot
uses: actions/upload-artifact@v4
with:
# Semantic version range syntax or exact version of Go
go-version: '1.21.x'
```

## Installing dependencies

You can use `go get` to install dependencies:

```yaml copy
steps:
- uses: {% data reusables.actions.action-checkout %}
- name: Setup Go
uses: {% data reusables.actions.action-setup-go %}
with:
go-version: '1.21.x'
- name: Install dependencies
run: |
go get .
go get example.com/octo-examplemodule
go get example.com/[email protected]
```

### Caching dependencies

You can cache and restore dependencies using the [`setup-go` action](https://github.com/actions/setup-go). By default, caching is {% ifversion actions-setup-go-default-cache-enabled %}enabled when using the `setup-go` action.{% else %}disabled, but you can set the `cache` parameter to `true` to enable it.{% endif %}

{% ifversion actions-setup-go-default-cache-enabled %}
The `setup-go` action searches for the dependency file, `go.sum`, in the repository root and uses the hash of the dependency file as a part of the cache key.

You can use the `cache-dependency-path` parameter for cases when multiple dependency files are used, or when they are located in different subdirectories.

```yaml copy
- name: Setup Go
uses: {% data reusables.actions.action-setup-go %}
name: cndk8-telegram-bot
path: target/${{ matrix.BUILD_TARGET }}/telegram
- name: Upload hello app
uses: actions/upload-artifact@v4
with:
go-version: '1.17'
cache-dependency-path: subdir/go.sum
name: cndk8-hello
path: target/${{ matrix.BUILD_TARGET }}/cndk8
```

{% else %}
And to use them on a different job, i.e publishing:

When caching is enabled, the `setup-go` action searches for the dependency file, `go.sum`, in the repository root and uses the hash of the dependency file as a part of the cache key.

```yaml copy
- name: Setup Go
uses: {% data reusables.actions.action-setup-go %}
- name: Download hello app
uses: actions/download-artifact@v4
with:
go-version: '1.21.x'
cache: true
```

Alternatively, you can use the `cache-dependency-path` parameter for cases when multiple dependency files are used, or when they are located in different subdirectories.

```yaml copy
- uses: {% data reusables.actions.action-setup-go %}
with:
go-version: '1.17'
cache: true
cache-dependency-path: subdir/go.sum
name: cndk8-hello
path: ./cndk8-hello
- name: Publish hello app to GitHub Packages
run: |
curl -u "${{ github.actor }}:${{ secrets.GH_TOKEN }}" \
-X POST "https://uploads.github.com/repos/${{ github.repository }}/releases/assets?name=cndk8-hello.tar.gz" \
--header "Content-Type: application/gzip" \
--data-binary @./cndk8-hello/cndk8
```

{% endif %}

If you have a custom requirement or need finer controls for caching, you can use the [`cache` action](https://github.com/marketplace/actions/cache). For more information, see [AUTOTITLE](/actions/using-workflows/caching-dependencies-to-speed-up-workflows).
## Publishing your package or library to crates.io

## Building and testing your code

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:
Once you have setup your workflow to build and test your code, you can alternatively use a secret to login to crates.io and publish your package.

```yaml copy
name: Go
on: [push]
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: {% data reusables.actions.action-checkout %}
- name: Setup Go
uses: {% data reusables.actions.action-setup-rust %}
with:
rust-version: '1.8.x'
- name: Install dependencies
run: go get .
- name: Build
run: go build -v ./...
- name: Test with the Go CLI
run: go test
- uses: actions/checkout@v4
- name: login into crates.io
run: cargo login ${{ secrets.CRATES_IO }}
- name: Build binaries in "release" mode
run: cargo build -r
- name: "Package for crates.io"
run: cargo package # publishes a package as a tarball
- name: "Publish to crates.io"
run: cargo publish # publishes your crate as a library that can be added as a dependency
```
As an example of how packages are published, see the [cndk8 0.1.0](https://crates.io/crates/cndk8/0.1.0). In the case that there are errors with Metadata check
your [manifest](https://doc.rust-lang.org/cargo/reference/manifest.html) Cargo.toml, when its about dirty directory check your Cargo.lock, and read the corresponding documentation.

0 comments on commit f3999cd

Please sign in to comment.