rust-musl-builder/README.md

226 lines
9.6 KiB
Markdown
Raw Normal View History

# `rust-musl-builder`: Docker container for easily building static Rust binaries
[![Docker Image](https://img.shields.io/docker/pulls/ekidd/rust-musl-builder.svg?maxAge=2592000)](https://hub.docker.com/r/ekidd/rust-musl-builder/)
**OPENSSL SECURITY NOTE:** Previously, `stable` included OpenSSL 1.0.2, and `stable-openssl11` included OpenSSL 1.1.1. However, OpenSSL 1.0.2 is **no longer receiving security fixes,** so the new tagging system will be:
- `stable`: OpenSSL 1.1.1 and the latest stable Rust.
- **DEPRECATED** `stable-openssl11`: OpenSSL 1.1 and Rust 1.42.0. This will no longer be updated. Use `stable` instead.
- **DEPRECATED** `1.42.0-openssl10` and `nightly-2020-03-12-openssl10`: OpenSSL 1.0.2. These will not be updated to newer Rust. You will still be able to build newer OpenSSL 1.0.2 images manually.
I hate to break compatibility with projects that require OpenSSL 1.0.2, but since it will receive no future security updates, I no longer feel comfortable supplying pre-built images.
## What is this?
2019-04-28 17:37:21 +00:00
Do you want to compile a completely static Rust binary with no external dependencies? If so, try:
```sh
alias rust-musl-builder='docker run --rm -it -v "$(pwd)":/home/rust/src ekidd/rust-musl-builder'
2016-04-17 11:46:15 +00:00
rust-musl-builder cargo build --release
2018-03-25 14:39:23 +00:00
```
2018-03-26 10:01:57 +00:00
This command assumes that `$(pwd)` is readable and writable by uid 1000, gid 1000. At the moment, it doesn't attempt to cache libraries between builds, so this is best reserved for making final release builds.
2019-04-28 17:37:21 +00:00
For a more realistic example, see the `Dockerfile` for [examples/using-diesel](./examples/using-diesel).
## Deploying your Rust application
2017-10-13 11:13:10 +00:00
With a bit of luck, you should be able to just copy your application binary from `target/x86_64-unknown-linux-musl/release`, and install it directly on any reasonably modern x86_64 Linux machine. In particular, you should be able make static release binaries using TravisCI and GitHub, or you can copy your Rust application into an [Alpine Linux container][]. See below for details!
## Available tags
In general, we provide the following tagged Docker images:
- `latest`, `stable`: Current stable Rust, now with OpenSSL 1.1. We
try to update this fairly rapidly after every new stable release, and
after most point releases.
2019-04-28 17:37:21 +00:00
- `X.Y.Z`: Specific versions of stable Rust.
- `beta`: This usually gets updated every six weeks alongside the stable
release. It will usually not be updated for beta bugfix releases.
- `nightly-YYYY-MM-DD`: Specific nightly releases. These should almost
always support `clippy`, `rls` and `rustfmt`, as verified using
[rustup components history][comp]. If you need a specific date for
compatibility with `tokio` or another popular library using unstable
Rust, please file an issue.
At a minimum, each of these images should be able to
compile [examples/using-diesel](./examples/using-diesel).
[comp]: https://rust-lang.github.io/rustup-components-history/index.html
2018-07-09 13:08:59 +00:00
## Caching builds
You may be able to speed up build performance by adding the following `-v` commands to the `rust-musl-builder` alias:
```txt
2019-04-18 13:43:03 +00:00
-v cargo-git:/home/rust/.cargo/git
-v cargo-registry:/home/rust/.cargo/registry
-v target:/home/rust/src/target
2018-07-09 13:08:59 +00:00
```
You will also need to fix the permissions on the mounted volumes:
```sh
2019-04-18 13:43:03 +00:00
rust-musl-builder sudo chown -R rust:rust \
/home/rust/.cargo/git /home/rust/.cargo/registry /home/rust/src/target
2018-07-09 13:08:59 +00:00
```
## How it works
`rust-musl-builder` uses [musl-libc][], [musl-gcc][], and the new [rustup][] `target` support. It includes static versions of several libraries:
- The standard `musl-libc` libraries.
- OpenSSL, which is needed by many Rust applications.
2019-04-28 17:55:14 +00:00
- `libpq`, which is needed for applications that use `diesel` with PostgreSQL.
2017-09-26 13:26:46 +00:00
- `libz`, which is needed by `libpq`.
- SQLite3. See [examples/using-diesel](./examples/using-diesel/).
2017-09-26 13:26:46 +00:00
This library also sets up the environment variables needed to compile popular Rust crates using these libraries.
## Extras
This image also supports the following extra goodies:
- Basic compilation for `armv7` using `musl-libc`. Not all libraries are supported at the moment, however.
- [`mdbook`][mdbook] and `mdbook-graphviz` for building searchable HTML documentation from Markdown files. Build manuals to use alongside your `cargo doc` output!
2018-07-25 11:08:58 +00:00
- [`cargo audit`][audit] to check your Rust project for known security issues.
## Making OpenSSL work
If your application uses OpenSSL, you will also need to take a few extra steps to make sure that it can find OpenSSL's list of trusted certificates, which is stored in different locations on different Linux distributions. You can do this using [`openssl-probe`](https://crates.io/crates/openssl-probe) as follows:
2017-07-26 04:57:29 +00:00
```rust
extern crate openssl_probe;
fn main() {
openssl_probe::init_ssl_cert_env_vars();
//... your code
}
```
## Making Diesel work
In addition to setting up OpenSSL, you'll need to add the following lines to your `Cargo.toml`:
```toml
[dependencies]
diesel = { version = "1", features = ["postgres", "sqlite"] }
# Needed for sqlite.
libsqlite3-sys = { version = "*", features = ["bundled"] }
# Needed for Postgres.
openssl = "*"
```
2019-04-18 13:43:03 +00:00
For PostgreSQL, you'll also need to include `diesel` and `openssl` in your `main.rs` in the following order (in order to avoid linker errors):
2018-07-09 12:20:11 +00:00
```toml
extern crate openssl;
2019-04-18 13:43:03 +00:00
#[macro_use]
extern crate diesel;
2018-07-09 12:20:11 +00:00
```
2019-04-18 13:43:03 +00:00
If this doesn't work, you _might_ be able to fix it by reversing the order. See [this PR](https://github.com/emk/rust-musl-builder/issues/69) for a discussion of the latest issues involved in linking to `diesel`, `pq-sys` and `openssl-sys`.
## Making static releases with Travis CI and GitHub
These instructions are inspired by [rust-cross][].
First, read the [Travis CI: GitHub Releases Uploading][uploading] page, and run `travis setup releases` as instructed. Then add the following lines to your existing `.travis.yml` file, replacing `myapp` with the name of your package:
```yaml
language: rust
sudo: required
os:
- linux
- osx
rust:
- stable
services:
- docker
before_deploy: "./build-release myapp ${TRAVIS_TAG}-${TRAVIS_OS_NAME}"
deploy:
provider: releases
api_key:
secure: "..."
file_glob: true
file: "myapp-${TRAVIS_TAG}-${TRAVIS_OS_NAME}.*"
skip_cleanup: true
on:
rust: stable
tags: true
```
Next, copy [`build-release`](./examples/build-release) into your project and run `chmod +x build-release`.
Finally, add a `Dockerfile` to perform the actual build:
```rust
FROM ekidd/rust-musl-builder
# We need to add the source code to the image because `rust-musl-builder`
# assumes a UID of 1000, but TravisCI has switched to 2000.
2019-11-13 10:14:16 +00:00
ADD --chown=rust:rust . ./
CMD cargo build --release
```
When you push a new tag to your project, `build-release` will automatically build new Linux binaries using `rust-musl-builder`, and new Mac binaries with Cargo, and it will upload both to the GitHub releases page for your repository.
2017-09-26 13:26:46 +00:00
For a working example, see [faradayio/cage][cage].
[rust-cross]: https://github.com/japaric/rust-cross
[uploading]: https://docs.travis-ci.com/user/deployment/releases
2017-09-26 13:26:46 +00:00
[cage]: https://github.com/faradayio/cage
2017-10-13 11:13:10 +00:00
## Making tiny Docker images with Alpine Linux and Rust binaries
Docker now supports [multistage builds][multistage], which make it easy to build your Rust application with `rust-musl-builder` and deploy it using [Alpine Linux][]. For a working example, see [`examples/using-diesel/Dockerfile`](./examples/using-diesel/Dockerfile).
2017-10-13 11:13:10 +00:00
[multistage]: https://docs.docker.com/engine/userguide/eng-image/multistage-build/
[Alpine Linux]: https://alpinelinux.org/
## Adding more C libraries
If you're using Docker crates which require specific C libraries to be installed, you can create a `Dockerfile` based on this one, and use `musl-gcc` to compile the libraries you need. For an example, see [`examples/adding-a-library/Dockerfile`](./examples/adding-a-library/Dockerfile). This usually involves a bit of experimentation for each new library, but it seems to work well for most simple, standalone libraries.
2017-10-13 11:13:10 +00:00
If you need an especially common library, please feel free to submit a pull request adding it to the main `Dockerfile`! We'd like to support popular Rust crates out of the box.
2017-10-13 11:13:10 +00:00
2019-04-28 17:37:21 +00:00
## ARM support (experimental)
To target ARM hard float (Raspberry Pi):
```sh
rust-musl-builder cargo build --target=armv7-unknown-linux-musleabihf --release
```
Binaries will be written to `target/$TARGET_ARCHITECTURE/release`. By default it targets `x86_64-unknown-linux-musl` unless specified with `--target`.
This is missing many of the libraries used by the `x86_64` build, and it should probably be split out of the base image and given its own tags.
## Development notes
After modifying the image, run `./test-image` to make sure that everything works.xs
2017-10-19 20:23:47 +00:00
## Other ways to build portable Rust binaries
If for some reason this image doesn't meet your needs, there's a variety of other people working on similar projects:
2017-10-19 20:23:47 +00:00
- [messense/rust-musl-cross](https://github.com/messense/rust-musl-cross) shows how to build binaries for many different architectures.
- [japaric/rust-cross](https://github.com/japaric/rust-cross) has extensive instructions on how to cross-compile Rust applications.
- [clux/muslrust](https://github.com/clux/muslrust) also supports libcurl.
- [golddranks/rust_musl_docker](https://github.com/golddranks/rust_musl_docker). Another Docker image.
2017-10-19 20:23:47 +00:00
2016-04-17 11:45:08 +00:00
## License
Either the [Apache 2.0 license](./LICENSE-APACHE.txt), or the
[MIT license](./LICENSE-MIT.txt).
[Alpine Linux container]: https://hub.docker.com/_/alpine/
2018-07-25 11:08:58 +00:00
[audit]: https://github.com/RustSec/cargo-audit
[mdbook]: https://github.com/rust-lang-nursery/mdBook
[musl-libc]: http://www.musl-libc.org/
[musl-gcc]: http://www.musl-libc.org/how.html
[rustup]: https://www.rustup.rs/