8000 Blog post: Cargo: Rust's community crate host · erickt/blog.rust-lang.org@cf942e6 · GitHub
[go: up one dir, main page]
Skip to content

Commit cf942e6

Browse files
alexcrichtonalexcrichton
committed
Blog post: Cargo: Rust's community crate host
1 parent f2fcffa commit cf942e6

File tree

1 file changed

+141
-0
lines changed

1 file changed

+141
-0
lines changed

‎_posts/2014-11-20-Cargo.md

Lines changed: 141 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,141 @@
1+
---
2+
layout: post
3+
title: "Cargo: Rust's community crate host"
4+
author: Alex Crichton
5+
---
6+
7+
Today it is my pleasure to announce that [crates.io](https://crates.io/) is
8+
online and ready for action. The site is a central location to
9+
discover/download Rust crates, and Cargo is ready to start publishing to it
10+
today. For the next few months, we are asking that intrepid early adopters
11+
[help us](http://doc.crates.io/crates-io.html) get the registry battle-tested.
12+
13+
Until Rust itself is stable early next year, registry dependencies will need to
14+
be updated often. Production users may want to continue using git dependencies
15+
until then.
16+
17+
## What is Cargo?
18+
19+
Cargo is a package manager [for Rust](http://www.rust-lang.org/), [in
20+
Rust](https://github.com/rust-lang/cargo). Managing dependencies is a
21+
fundamentally difficult problem, but fortunately over the last decade there's
22+
been a lot of progress in the design of package managers. Designed by Carl
23+
Lerche and Yehuda Katz, Cargo follows the tradition of successes like
24+
[Bundler](http://bundler.io/) and [NPM](https://www.npmjs.org/):
25+
26+
1. Cargo leverages crates.io to foster a thriving community of crates that can
27+
easily interoperate with one another and last for years to come.
28+
29+
2. Cargo releases developers from the worry of managing dependencies and ensures
30+
that all collaborators are building the same code.
31+
32+
3. Cargo lets your dependencies say how they should be built, and manages the
33+
entire build process for you.
34+
35+
## A Community on Cargo
36+
37+
To get a feel for how Cargo achieves its goals, let's take a look at some of
38+
its core mechanics.
39+
40+
### Declaring Dependencies
41+
42+
Cargo makes depending on third-party code as easy as depending on the standard
43+
library. When using Cargo, each crate will have an associated
44+
[manifest](http://doc.crates.io/manifest.html) to describe itself and its
45+
dependencies. Adding a new dependency is now as simple as adding one line to the
46+
manifest, and this ease has allowed Cargo in just a few short months to enable a
47+
large and growing network of Rust projects and libraries which were simply
48+
infeasible before.
49+
50+
Cargo alone, however, is not quite the entire solution. Discovering dependencies
51+
is still difficult, and ensuring that these dependencies are available for years
52+
to come is also not guaranteed.
53+
54+
### crates.io
55+
56+
To pair with Cargo, the central crates.io site serves as a single location for
57+
publishing and discovering libraries. This repository serves as permanent
58+
storage for releases of crates over time to ensure that projects can always
59+
build with the exact same versions years later. Up until now, users of Cargo
60+
have largely just downloaded dependencies directly from the source GitHub
61+
repository, but the primary source will now be shifting to crates.io.
62+
63+
Other programming language communities have been quite successful with this form
64+
of central repository. For example [rubygems.org](http://rubygems.org/) is your
65+
one-stop-shop for [Bundler](http://bundler.io/) dependencies and
66+
[npmjs.org](https://www.npmjs.org/) has had over 600 million downloads in just
67+
this month alone! We intend for crates.io to serve a similar role for Rust as a
68+
critical piece of infrastructure for [Rust's long-term stability story at
69+
1.0][stab].
70+
71+
[stab]: http://blog.rust-lang.org/2014/10/30/Stability.html
72+
73+
## Versioning and Reproducible Builds
74+
75+
Over the past few years, the concept of [Semantic
76+
Versioning](http://semver.org/) has gained traction as a way for library
77+
developers to easily and clearly communicate with users when they make breaking
78+
changes. The core idea of semantic versioning is simple: each new release is
79+
categorized as a minor or major release, and only major releases can introduce
80+
breakage. Cargo allows you to specify version ranges for your dependencies, with
81+
the default meaning of "compatible with".
82+
83+
When specifying a version range, applications often end up requesting
84+
multiple versions of a single crate, and Cargo solves this by selecting the
85+
highest version of each major version ("stable code") requested. This highly
86+
encourages using stable distributions while still allowing duplicates of
87+
unstable code (pre-1.0 and git for example).
88+
89+
Once the set of dependencies and their versions have been calculated, Cargo
90+
generates a [`Cargo.lock`][lock] to encode this information. This "lock file" is
91+
then distributed to collaborators of applications to ensure that the crates
92+
being built remain the same from one build to the next, across times, machines,
93+
and environments.
94+
95+
[lock]: http://doc.crates.io/guide.html#cargo.toml-vs-cargo.lock
96+
97+
## Building Code
98+
99+
Up to this point we've seen how Cargo facilitates discovery and reuse of
100+
community projects while managing what versions to use. Now Cargo just has to
101+
deal with the problem of actually compiling all this code!
102+
103+
With a deep understanding of the Rust code that it is building, Cargo is able to
104+
provide some nice standard features as well as some Rust-specific features:
105+
106+
* By default, Cargo builds as many crates in parallel as possible. This not only
107+
applies to upstream dependencies being built in parallel, but also items for
108+
the local crate such as test suites, binaries, and unit tests.
109+
110+
* Cargo supports unit testing out of the box both for crates themselves and in
111+
the form of integration tests. This even includes example programs to ensure
112+
they don't bitrot.
113+
114+
* Cargo generates documentation for all crates in a dependency graph, and it can
115+
even run [Rust's documentation
116+
tests](http://doc.rust-lang.org/rustdoc.html#testing-the-documentation) to
117+
ensure examples in documentation stay up to date.
118+
119+
* Cargo can run a [build script][build-scripts] before any crate is compiled to
120+
perform tasks such as code generation, compiling native dependencies, or
121+
detecting native dependencies on the local system.
122+
123+
* Cargo supports cross compilation out of the box. Cross compiling is done by
124+
simply specifying a `--target` options and Cargo will manage tasks such as
125+
compiling plugins and other build dependencies for the right platform.
126+
127+
[build-scripts]: http://doc.crates.io/build-script.html
128+
129+
## What else is in store?
130+
131+
The launch of crates.io is a key step in moving the Cargo ecosystem forward,
132+
but the story does not end here. Usage of crates.io is architected assuming a
133+
stable compiler, which should be [coming soon][road-to-1]! There are also a
134+
number of extensions to crates.io such as a hosted documentation service or a CI
135+
build infrastructure hook.
136+
137+
[road-to-1]: http://blog.rust-lang.org/2014/09/15/Rust-1.0.html
138+
139+
This is just the beginning for crates.io, and I'm excited to start finding all
140+
Rust crates from one location. I can't wait to see what the registry looks like
141+
at 1.0, and I can only fathom what it will look like after 1.0!

0 commit comments

Comments
 (0)
0