Repository files navigation

• Source on GitHub
• Changelog

UPDATED: This repository is effectively dead at this point, given the increasing rarity of crates which require OpenSSL.

However,rustls now works well with most of the Rust ecosystem, includingreqwest,tokio,tokio-postgres,sqlx and many others. The only major project which still requireslibpq and OpenSSL isDiesel. If you don't needdiesel orlibpq:

• See if you can switch away from OpenSSL, typically by usingfeatures inCargo.toml to ask your dependencies to userustls instead.
• If you don't need OpenSSL, trycross build --target=x86_64-unknown-linux-musl --release to cross-compile your binaries forlibmusl. This supports many more platforms, with less hassle!

This image allows you to build static Rust binaries usingdiesel,sqlx oropenssl. These images can be distributed as single executable files with no dependencies, and they should work on any modern Linux system.

To try it, run:

alias rust-musl-builder='docker run --rm -it -v "$(pwd)":/home/rust/src ekidd/rust-musl-builder'rust-musl-builder cargo build --release

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.

For a more realistic example, see theDockerfiles forexamples/using-diesel andexamples/using-sqlx.

With a bit of luck, you should be able to just copy your application binary fromtarget/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 anAlpine Linux container. See below for details!

In general, we provide the following tagged Docker images:

• latest,stable: Current stable Rust, now with OpenSSL 1.1. Wetry to update this fairly rapidly after every new stable release, andafter most point releases.
• X.Y.Z: Specific versions of stable Rust.
• beta: This usually gets updated every six weeks alongside the stablerelease. It will usually not be updated for beta bugfix releases.
• nightly-YYYY-MM-DD: Specific nightly releases. These should almostalways supportclippy,rls andrustfmt, as verified usingrustup components history. If you need a specific date forcompatibility withtokio or another popular library using unstableRust, please file an issue.

At a minimum, each of these images should be able tocompileexamples/using-diesel andexamples/using-sqlx.

You may be able to speed up build performance by adding the following-v commands to therust-musl-builder alias:

-v cargo-git:/home/rust/.cargo/git-v cargo-registry:/home/rust/.cargo/registry-v target:/home/rust/src/target

You will also need to fix the permissions on the mounted volumes:

rust-musl-builder sudo chown -R rust:rust \  /home/rust/.cargo/git /home/rust/.cargo/registry /home/rust/src/target

rust-musl-builder usesmusl-libc,musl-gcc, and the newrustuptarget support. It includes static versions of several libraries:

• The standardmusl-libc libraries.
• OpenSSL, which is needed by many Rust applications.
• libpq, which is needed for applications that usediesel with PostgreSQL.
• libz, which is needed bylibpq.
• SQLite3. Seeexamples/using-diesel.

This library also sets up the environment variables needed to compile popular Rust crates using these libraries.

This image also supports the following extra goodies:

• Basic compilation forarmv7 usingmusl-libc. Not all libraries are supported at the moment, however.
• mdbook andmdbook-graphviz for building searchable HTML documentation from Markdown files. Build manuals to use alongside yourcargo doc output!
• cargo about to collect licenses for your dependencies.
• cargo deb to build Debian packages
• cargo deny to check your Rust project for known security issues.

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 usingopenssl-probe as follows:

fnmain(){    openssl_probe::init_ssl_cert_env_vars();//... your code}

In addition to setting up OpenSSL, you'll need to add the following lines to yourCargo.toml:

[dependencies]diesel = {version ="1",features = ["postgres","sqlite"] }# Needed for sqlite.libsqlite3-sys = {version ="*",features = ["bundled"] }# Needed for Postgres.openssl ="*"

For PostgreSQL, you'll also need to includediesel andopenssl in yourmain.rs in the following order (in order to avoid linker errors):

externcrate openssl;#[macro_use]externcrate diesel;

If this doesn't work, youmight be able to fix it by reversing the order. Seethis PR for a discussion of the latest issues involved in linking todiesel,pq-sys andopenssl-sys.

These instructions are inspired byrust-cross.

First, read theTravis CI: GitHub Releases Uploading page, and runtravis setup releases as instructed. Then add the following lines to your existing.travis.yml file, replacingmyapp with the name of your package:

language:rustsudo:requiredos:-linux-osxrust:-stableservices:-dockerbefore_deploy:"./build-release myapp ${TRAVIS_TAG}-${TRAVIS_OS_NAME}"deploy:provider:releasesapi_key:secure:"..."file_glob:truefile:"myapp-${TRAVIS_TAG}-${TRAVIS_OS_NAME}.*"skip_cleanup:trueon:rust:stabletags:true

Next, copybuild-release into your project and runchmod +x build-release.

Finally, add aDockerfile to perform the actual build:

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.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 usingrust-musl-builder, and new Mac binaries with Cargo, and it will upload both to the GitHub releases page for your repository.

For a working example, seefaradayio/cage.

Docker now supportsmultistage builds, which make it easy to build your Rust application withrust-musl-builder and deploy it usingAlpine Linux. For a working example, seeexamples/using-diesel/Dockerfile.

If you're using Docker crates which require specific C libraries to be installed, you can create aDockerfile based on this one, and usemusl-gcc to compile the libraries you need. For an example, seeexamples/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.

If you need an especially common library, please feel free to submit a pull request adding it to the mainDockerfile! We'd like to support popular Rust crates out of the box.

After modifying the image, run./test-image to make sure that everything works.

If for some reason this image doesn't meet your needs, there's a variety of other people working on similar projects:

• messense/rust-musl-cross shows how to build binaries for many different architectures.
• japaric/rust-cross has extensive instructions on how to cross-compile Rust applications.
• clux/muslrust also supports libcurl.
• golddranks/rust_musl_docker. Another Docker image.

Either theApache 2.0 license, or theMIT license.