rs-cargo/README.md

133 lines
4.4 KiB
Markdown
Raw Normal View History

2019-09-12 23:48:44 +03:00
# Rust `cargo` Action
2020-03-25 07:40:28 +02:00
[![Sponsoring](https://img.shields.io/badge/Support%20it-Say%20%22Thank%20you!%22-blue)](https://actions-rs.github.io/#sponsoring)
2019-09-15 11:45:45 +03:00
![MIT licensed](https://img.shields.io/badge/license-MIT-blue.svg)
2019-09-14 20:42:21 +03:00
[![Gitter](https://badges.gitter.im/actions-rs/community.svg)](https://gitter.im/actions-rs/community)
2020-03-25 07:40:28 +02:00
![Continuous integration](https://github.com/actions-rs/cargo/workflows/Continuous%20integration/badge.svg)
![Dependabot enabled](https://api.dependabot.com/badges/status?host=github&repo=actions-rs/toolchain)
2019-09-14 20:42:21 +03:00
2019-09-12 23:48:44 +03:00
This GitHub Action runs specified [`cargo`](https://github.com/rust-lang/cargo)
command on a Rust language project.
2020-03-25 07:40:28 +02:00
**Table of Contents**
* [Example workflow](#example-workflow)
* [Use cases](#use-cases)
2020-03-25 07:40:28 +02:00
* [Inputs](#inputs)
* [Toolchain](#toolchain)
2020-03-25 07:40:28 +02:00
* [Cross-compilation](#cross-compilation)
* [License](#license)
* [Contribute and support](#contribute-and-support)
2019-09-12 23:48:44 +03:00
## Example workflow
```yaml
on: [push]
name: CI
jobs:
build_and_test:
name: Rust project
runs-on: ubuntu-latest
steps:
2020-03-25 07:40:28 +02:00
- uses: actions/checkout@v2
- uses: actions-rs/toolchain@v1
with:
toolchain: stable
2019-09-12 23:48:44 +03:00
- uses: actions-rs/cargo@v1
with:
command: build
2019-09-18 12:55:16 +03:00
args: --release --all-features
2019-09-12 23:48:44 +03:00
```
2019-09-16 10:37:57 +03:00
See [additional recipes here](https://github.com/actions-rs/meta).
## Use cases
Note that this Action is not required usually
and you can just use [`run`](https://help.github.com/en/actions/reference/workflow-syntax-for-github-actions#jobsjob_idstepsrun)
step instead as in example below:
```yaml
jobs:
build_and_test:
name: Rust project
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- uses: actions-rs/toolchain@v1
with:
toolchain: stable
- run: cargo build --release --all-features
```
Why would you want to use this Action instead:
1. Transparent `cross` installation and execution with `use-cross: true` input enabled
2. Warnings and errors issued by `cargo` will be displayed in GitHub UI
2019-09-12 23:48:44 +03:00
## Inputs
2019-09-29 00:34:53 +03:00
| Name | Required | Description | Type | Default |
| ------------| :------: | -------------------------------------------------------------------------| ------ | --------|
2019-09-29 00:34:53 +03:00
| `command` | ✓ | Cargo command to run, ex. `check` or `build` | string | |
| `toolchain` | | Rust toolchain name to use | string | |
| `args` | | Arguments for the cargo command | string | |
| `use-cross` | | Use [`cross`](https://github.com/rust-embedded/cross) instead of `cargo` | bool | false |
2019-09-13 00:21:16 +03:00
2020-03-25 07:40:28 +02:00
## Toolchain
2019-09-15 11:45:45 +03:00
2020-03-25 07:40:28 +02:00
By default this Action will call whatever `cargo` binary is available
in the current [virtual environment](https://help.github.com/en/articles/software-in-virtual-environments-for-github-actions).
2019-09-15 11:45:45 +03:00
You can use [`actions-rs/toolchain`](https://github.com/actions-rs/toolchain)
2020-03-25 07:40:28 +02:00
to install specific Rust toolchain with `cargo` included.
2019-09-15 11:45:45 +03:00
2020-03-25 07:40:28 +02:00
## Cross-compilation
2019-09-13 00:21:16 +03:00
2020-03-25 07:40:28 +02:00
In order to make cross-compile an easy process,
2019-09-15 11:45:45 +03:00
this Action can install [cross](https://github.com/rust-embedded/cross)
tool on demand if `use-cross` input is enabled; `cross` executable will be invoked
then instead of `cargo` automatically.
2020-03-25 07:40:28 +02:00
All consequent calls of this Action in the same job
with `use-cross: true` input enabled will use the same `cross` installed.
2019-09-15 11:45:45 +03:00
```yaml
on: [push]
2019-09-13 00:21:16 +03:00
2019-09-15 11:45:45 +03:00
name: ARMv7 build
2019-09-13 00:21:16 +03:00
2019-09-15 11:45:45 +03:00
jobs:
linux_arm7:
name: Linux ARMv7
runs-on: ubuntu-latest
steps:
2020-03-25 07:40:28 +02:00
- uses: actions/checkout@v2
2019-09-15 11:45:45 +03:00
- uses: actions-rs/toolchain@v1
with:
toolchain: stable
target: armv7-unknown-linux-gnueabihf
override: true
- uses: actions-rs/cargo@v1
with:
use-cross: true
command: build
args: --target armv7-unknown-linux-gnueabihf
```
2020-03-25 07:40:28 +02:00
## License
This Action is distributed under the terms of the MIT license, see [LICENSE](https://github.com/actions-rs/toolchain/blob/master/LICENSE) for details.
## Contribute and support
Any contributions are welcomed!
If you want to report a bug or have a feature request,
check the [Contributing guide](https://github.com/actions-rs/.github/blob/master/CONTRIBUTING.md).
You can also support author by funding the ongoing project work,
see [Sponsoring](https://actions-rs.github.io/#sponsoring).