README.md 5.04 KB
Newer Older
Jorge Aparicio's avatar
Jorge Aparicio committed
1
2
# `trust`

Jorge Aparicio's avatar
Jorge Aparicio committed
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
> Travis CI and AppVeyor template to test your Rust crate on 5 architectures
> and publish [binary releases] of it for Linux, macOS and Windows

[binary releases]: https://github.com/japaric/trust/releases

### Features

- CI test your crate (library or binary) on Linux, macOS and Windows and on more
  than just the x86 architecture.

- Cargo artifacts are cached and reused between CI builds.

- "Deploys": Publish binary releases of your application by just pushing a new
  (Git) tag.

## Requirements

- Your crate must be hosted on GitHub (free).

- A [Travis CI](https://travis-ci.org/) account (free).

- An [AppVeyor](https://www.appveyor.com/) account (free).

## How-to

### Use this template

Copy the `ci` directory, and the `.travis.yml` and `appveyor.yml` files into the
repository where you host your Rust crate.

You'll have to adjust those files to meet your needs. Just look inside those
files for comments that start with the word `TODO`; they'll tell you want needs
to be changed.

This is an overview of what must / can be changed:

- The GitHub token used for deploys.

- The list of test targets. Trim it down to reduce test times.

- The Rust channel used for testing / deploys.

- The "test phase". Tweak how your crate is tested.

- the "package phase". Tweak what goes into the release tarball / zipfile.

### Generate binary releases

You only need to push an **annotated** tag to kick off the build process.

```
# Optional: Publish a new version of your crate to crates.io
$ cargo publish

$ git tag -a $TAG

$ git push origin $TAG
```

### Use the binary releases on Travis CI

There's
an [`install.sh`](https://github.com/japaric/trust/blob/gh-pages/install.sh)
script that you can use to quickly install a binary release produced using this
CI template.

```
$ curl -LSfs https://japaric.github.io/trust/install.sh | \
    sh -s -- --git japaric/cross
```

For more details about this installation script see `install.sh -h`

Jorge Aparicio's avatar
Jorge Aparicio committed
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
### How to disable deploys?

If you don't want to generate binary releases at all, perhaps because your Cargo
project is a library or you only want to test your project, then you can simply
change `deploy.on.condition`, in `.travis.yml`, and `deploy.on`, in
`appveyor.yml`, to always be false. For example:

``` yml
# .travis.yml
deploy:
  on:
    condition: $DEPLOY = never
```

### How to upgrade your CI configuration?

First, figure out which version of the trust template you are using. The version
is written in the header of the `.travis.yml` and `appveyor.yml` files. If
there's no header, that means you are using version `v0.1.0`.

Next, look at the [change log](CHANGELOG.md) to check if there's a new release
and to learn, at a high level, how the template has changed: what has been
fixed, what has been added, etc.

If it makes sense for you to upgrade, you can see the required "code" changes by
looking at the "diff" between the version you are using and the version you are
going to upgrade to. For example:

https://github.com/japaric/trust/compare/v0.1.0...v0.1.1

As for the upgrade itself, GitHub can generate a patch from the above diff that
then you can apply to your repository with `git am` or similar:

https://github.com/japaric/trust/compare/v0.1.0...v0.1.1.patch

Jorge Aparicio's avatar
Jorge Aparicio committed
111
## Supported targets
Jorge Aparicio's avatar
Jorge Aparicio committed
112

Jorge Aparicio's avatar
Jorge Aparicio committed
113
114
### Linux

115
116
117
118
119
120
121
Courtesy of [`cross`](https://github.com/japaric/cross).

If you run into any problem with any of these targets, report them
to [`cross`'s issue tracker](https://github.com/japaric/cross/issues) but first
check if using a newer release (see `ci/install.sh`)
would
[fix your problem](https://github.com/japaric/cross/blob/master/CHANGELOG.md).
Jorge Aparicio's avatar
Jorge Aparicio committed
122

Bryant Mairs's avatar
Bryant Mairs committed
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
### Android

- aarch64-linux-android

- arm-linux-androideabi

- armv7-linux-androideabi

- i686-linux-android

- x86_64-linux-android

### iOS

- aarch64-apple-ios

- armv7-apple-ios

- armv7s-apple-ios

- i386-apple-ios

- x86_64-apple-ios

### Linux

Jorge Aparicio's avatar
Jorge Aparicio committed
149
150
151
152
153
154
155
- `i686-unknown-linux-gnu`

- `i686-unknown-linux-musl`

- `x86_64-unknown-linux-gnu`

- `x86_64-unknown-linux-musl`
Jorge Aparicio's avatar
Jorge Aparicio committed
156
157

- `aarch64-unknown-linux-gnu`
Jorge Aparicio's avatar
Jorge Aparicio committed
158

Bryant Mairs's avatar
Bryant Mairs committed
159
160
- `arm-unknown-linux-gnueabi`

Jorge Aparicio's avatar
Jorge Aparicio committed
161
- `armv7-unknown-linux-gnueabihf`
Jorge Aparicio's avatar
Jorge Aparicio committed
162

Jorge Aparicio's avatar
Jorge Aparicio committed
163
- `mips-unknown-linux-gnu`
Jorge Aparicio's avatar
Jorge Aparicio committed
164

Jorge Aparicio's avatar
Jorge Aparicio committed
165
- `mips64-unknown-linux-gnuabi64`
Jorge Aparicio's avatar
Jorge Aparicio committed
166

Jorge Aparicio's avatar
Jorge Aparicio committed
167
- `mips64el-unknown-linux-gnuabi64`
Jorge Aparicio's avatar
Jorge Aparicio committed
168

Jorge Aparicio's avatar
Jorge Aparicio committed
169
- `mipsel-unknown-linux-gnu`
Jorge Aparicio's avatar
Jorge Aparicio committed
170

Jorge Aparicio's avatar
Jorge Aparicio committed
171
- `powerpc-unknown-linux-gnu`
Jorge Aparicio's avatar
Jorge Aparicio committed
172

Jorge Aparicio's avatar
Jorge Aparicio committed
173
- `powerpc64-unknown-linux-gnu`
Jorge Aparicio's avatar
Jorge Aparicio committed
174

Jorge Aparicio's avatar
Jorge Aparicio committed
175
- `powerpc64le-unknown-linux-gnu`
Jorge Aparicio's avatar
Jorge Aparicio committed
176

Jorge Aparicio's avatar
Jorge Aparicio committed
177
- `s390x-unknown-linux-gnu`
Jorge Aparicio's avatar
Jorge Aparicio committed
178

Jorge Aparicio's avatar
Jorge Aparicio committed
179
180
181
### macOS

- `i686-apple-darwin`
Jorge Aparicio's avatar
Jorge Aparicio committed
182

Jorge Aparicio's avatar
Jorge Aparicio committed
183
184
- `x86_64-apple-darwin`

Jorge Aparicio's avatar
Jorge Aparicio committed
185
186
187
188
189
190
191
192
### *BSD

- `i686-unknown-freebsd`

- `x86_64-unknown-freebsd`

- `x86_64-unknown-netbsd`

Jorge Aparicio's avatar
Jorge Aparicio committed
193
### Windows (MinGW)
Jorge Aparicio's avatar
Jorge Aparicio committed
194
195
196

- `i686-pc-windows-gnu`

Jorge Aparicio's avatar
Jorge Aparicio committed
197
- `x86_64-pc-windows-gnu`
Jorge Aparicio's avatar
Jorge Aparicio committed
198

Jorge Aparicio's avatar
Jorge Aparicio committed
199
### Windows (MSVC)
Jorge Aparicio's avatar
Jorge Aparicio committed
200

Jorge Aparicio's avatar
Jorge Aparicio committed
201
- `i686-pc-windows-msvc`
Jorge Aparicio's avatar
Jorge Aparicio committed
202

Jorge Aparicio's avatar
Jorge Aparicio committed
203
- `x86_64-pc-windows-msvc`
Jorge Aparicio's avatar
Jorge Aparicio committed
204

Jorge Aparicio's avatar
Jorge Aparicio committed
205
206
207
208
209
## License

Licensed under either of

- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or
TemTem's avatar
TemTem committed
210
211
  https://www.apache.org/licenses/LICENSE-2.0)
- MIT license ([LICENSE-MIT](LICENSE-MIT) or https://opensource.org/licenses/MIT)
Jorge Aparicio's avatar
Jorge Aparicio committed
212
213
214
215
216

at your option.

### Contribution

Jorge Aparicio's avatar
Jorge Aparicio committed
217
218
219
Unless you explicitly state otherwise, any contribution intentionally submitted
for inclusion in the work by you, as defined in the Apache-2.0 license, shall be
dual licensed as above, without any additional terms or conditions.