Cloudsmith + Rust = The World's First Private Cargo Registry Service

What is Rust? What is Cargo? What are Crates?

Rust lang, or Rust, is a systems programming language, designed at Mozilla research, and intended to be a safer alternative to existing systems programming languages like C and C++, but still just as fast. Rust was originally started as a personal side-project by Mozilla engineer Graydon Hoare, but the company quickly and rightfully recognised its promise and began sponsorship of the project in 2009.

Rust quickly became a critical part of Mozilla's efforts to improve the performance and reliability of their browser technology as part of the Servo project. Since then, Rust has only grown in popularity and appeal, year on year, and for the last four years has achieved the coveted top spot for "most loved programming language" on Stack Overflow's Developer Survey (also a great read).

Whilst Rust is maybe best known as a low-level systems language, the same properties that make it appealing for working close to the metal also make it appealing for many other use cases. Rust's memory-safety, ownership semantics, performance, and comprehensive type system (among others) combine to make Rust a very compelling choice in many fields of engineering.

Whether you're writing a device driver for an embedded System-on-Chip (SoC), an operating system, a layout engine for a web browser, a web application, a package management service (heh), or a library for use in the WebAssembly ecosystem, Rust probably has you covered.

Early on, the Rust community realised that for a modern programming language to be successful, it needs modern tooling to accompany it. To this end, various teams in the Rust community have concentrated on tooling, such that Rust is now widely regarded as having best-in-class tools in areas like build and package management; which is something that we (Cloudsmith) recognise, respect and adore.

Rust therefore ships with its own package manager called Cargo. Cargo is an all-in-one frontend for building, packaging and configuring your Rust projects. It can build and run your code (providing a developer-friendly interface to rustc) and manages resolving and fetching any required dependencies (also known as "crates" in the Rust world).

Cargo can install dependencies from a remote registry into your local project for building, using a command like cargo install library. Until April of 2019 the only choice you really had was the official, public registry at crates.io. Crates.io is maintained by the Rust team and is the default public registry for the Rust ecosystem. With the release of Rust 1.34, Cargo now officially supports the use of registries other than crates.io, making it possible to run an alternative registry for the hosting of private or internal crates.

There are several equally fantastic reasons for running/using your own registry:

• To develop Cargo packages internally and share them privately to other teams.
• To distribute and deploy your own Cargo packages in a pipeline at your org.
• To distribute Cargo packages as vendored software (i.e. maybe commercially).
• To make modifications to public Cargo packages, without republishing publicly.
• To mirror public Cargo packages, to isolate from uncontrolled registry events.
• To capture the exact state of your dependencies at a particular version/release.
• To control (whitelist/blacklist) the exact Cargo packages allowed for your org.
• To keep track of the exact versions/releases of Cargo packages you have/use.

As such, if you're interested in the possibilities that hosting your own private or internal crates brings, then this is incredibly good news for you: Cloudsmith are proud to provide the World's first commercially available public and private Cargo registry hosting, with ultra-fast and secure delivery of your Rust packages, alongside all of the usual Enterprise-grade features that we provide.

See also:

• Rust: https://www.rust-lang.org
• The Rust Programming Language: https://doc.rust-lang.org/book/index.html
• the Cargo Book: https://doc.rust-lang.org/cargo/index.html

Setting up a private Cargo registry at Cloudsmith

Getting started with Cloudsmith and Cargo couldn't be simpler. First, you'll need a Cloudsmith account and a repository to which you can upload crates. Secondly, you'll need to ensure you're running at least version 1.34 (or later) of Rust.

If you need to install Rust you can use rustup, the Rust toolchain installer. Rust is available on most commonly used development platforms.

You can check your currently installed Rust and Cargo versions like so:

$ rustc --version
rustc 1.34.1 (fc50f328b 2019-04-24)
$ cargo --version
cargo 1.34.0 (6789d8a0a 2019-04-01)

If you see something like the above, you're ready to go!

Publishing your Cargo crates to Cloudsmith

For the purposes of this demonstration, we'll use the minimal crate created by cargo init. You can initialise your new Cargo crate like so:

$ cargo init my-crate
     Created binary (application) package

If you take a look inside the new crate you'll see a few files:

$ tree my-crate/
my-crate/
├── Cargo.toml
└── src
    └── main.rs

1 directory, 2 files

main.rs contains a simple "Hello World" program, and Cargo.toml contains all configuration and setup data for your crate. For our purposes we can leave both files as-is.

We can use cargo to build our crate and prepare it for upload to Cloudsmith:

$ cd my-crate/
$ cargo package --allow-dirty
warning: manifest has no description, license, license-file, documentation, homepage or repository.
See <http://doc.crates.io/manifest.html#package-metadata> for more info.
   Packaging my-crate v0.1.0 (/Users/cloudsmith/my-crate)
   Verifying my-crate v0.1.0 (/Users/cloudsmith/my-crate)
   Compiling my-crate v0.1.0 (/Users/cloudsmith/my-crate/target/package/my-crate-0.1.0)
    Finished dev [unoptimized + debuginfo] target(s) in 1.45s

NOTE: We use --allow-dirty in the cargo package command as we haven't committed the new crate to git. Under normal circumstances you'll just call cargo package without the extra flag.

Cargo, by default, spits out your packaged crate under the target/package/ directory.

$ ls -l target/package/
total 4
drwxr-xr-x 6 cloudsmith cloudsmith 192 Apr 30 16:09 my-crate-0.1.0
-rw-r--r-- 1 cloudsmith cloudsmith 673 Apr 30 16:09 my-crate-0.1.0.crate

Once built you can push the crate to Cloudsmith using the Cloudsmith CLI. We don't yet support pushing crates with cargo publish, but we'll be adding support in a future release (if you want it, please let us know). For now, use the CLI.

First, ensure you've installed the Cloudsmith CLI and configured authentication:

$ pip install cloudsmith-cli
$ export CLOUDSMITH_API_KEY=xxxxx

Then, use the CLI to push the crate, which operates like cargo publish but is specific to Cloudsmith:

$ cloudsmith push cargo my-org/my-repo target/package/my-crate-0.1.0.crate

Checking cargo package upload parameters ... OK
Checking my-crate-0.1.0.crate file upload parameters ... OK
Requesting file upload for my-crate-0.1.0.crate ... OK
Creating a new cargo package ... OK
Created: my-org/my-repo/my-crate-010crate (ffb4n20QxSYM)

Synchronising my-crate-010crate:  [####################################]  100%  Sync Completed / Fully Synchronised
Package synchronised successfully!

Your repository should now contain the uploaded crates. An example of which is our official Cloudsmith examples repository (this is where we upload our examples from), as shown below:

Once pushed, your crate is ready for installation with Cargo.

Installing your Cargo crates from Cloudsmith

First, we need to tell Cargo how to access the registry. To do so you need to add the following entry in your .cargo/configfile (replace TOKEN with an entitlement token, which is a type of read-only authentication token that we support):

[registries]
cloudsmith = { index = "https://dl.cloudsmith.io/TOKEN/my-org/my-repo/cargo/index.git" }

And then install the crate:

$ cargo install my-crate --registry cloudsmith
    Updating `https://dl.cloudsmith.io/TOKEN/my-org/my-repo/cargo/index.git` index
  Downloaded my-crate v0.1.0 (registry `https://dl.cloudsmith.io/TOKEN/my-org/my-repo/cargo/index.git`)
  Downloaded 1 crates (673 B) in 0.54s
  Installing my-crate v0.1.0 (registry `https://dl.cloudsmith.io/TOKEN/my-org/my-repo/cargo/index.git`)
   Compiling my-crate v0.1.0 (registry `https://dl.cloudsmith.io/TOKEN/my-org/my-repo/cargo/index.git`)
    Finished release [optimized] target(s) in 2.60s
  Installing /Users/cloudsmith/.cargo/bin/my-crate

Assuming ~/.cargo/bin/my-crate is on your $PATH then you should be able to run the installed program:

$ my-crate
Hello, world!

It really is that simple, and now you've sourced a crate privately from your very own private Cargo registry on Cloudsmith. Well done!

Conclusion

Rust is an exciting new programming language, with many interesting properties that make it perfect for use in a wide range of scenarios. Cargo provides a robust suite of tools for installing, configuring and managing dependencies for your Rust projects.

Cloudsmith provides fully featured Cargo registries on all plans, flexible enough for use whether you’re hosting public crates for a public or open source project, or private crates for your company’s internal needs. We're extremely proud to be able to support the Rust ecosystem with this first (non-official) implementation of public and private Cargo registries.

You can find further, context-specific information, including detailed setup and integration instructions inside each Cloudsmith repository. You can see an example of this documentation in our public examples repository.

Why wait? Get your public and private Cargo registry hosting at Cloudsmith now.