Doc using cargo to manage packages

When you run make install or install rust from a package, you will get a tool called cargo as well.

Cargo is a decentralized system for registering, finding, installing, updating and otherwise "managing" collections of rust source code, libraries, and similar "packages". The definitions here are all somewhat loose since the conventions of use for cargo are still evolving; we encourage new rust users to register any rust code they publish by name with cargo central, our central cargo package list, so that other users can find your work and easily install it.

How it works

Cargo keeps a list of "sources" from which it loads "package lists". Sources are described in a "sources file" kept in $HOME/.cargo/sources.json, a JSON file listing named URLs for package lists. Package lists are, themselves, JSON files called packages.json, loaded from the URLs specified in a sources file.

The $HOME/.cargo/lib, ./.cargo/lib and $INSTALL_DIR/cargo/lib (e.g. /usr/local/lib/cargo/lib on Unix systems) directories are in the default library search path used by rustc, so you should be able to use a library crate directly after successfully installing with cargo locally, globally or to the user's home.

Commands

All Cargo commands are run using cargo <cmd>, where cmd is a specific operation/command you want to use. Not passing any command to Cargo will display a list of commands and general help information.

init

The init command will initialize Cargo in the user's home directory (i.e. $HOME/.cargo). Cargo automatically initializes itself. This command will download the official source manifest from the Rust website and add them to cargo. All previously added custom sources will be lost.

Example

$ cargo init
info: initialized .cargo in /home/phosphorus/.cargo

install <name

list [sources..]

The list command will list all sources and their packages, where packages are listed lexicographically. If you provide a list of source names, it will only list packages from those sources.

Example

$ cargo list
info: syncing source: central...
info: synced source: central
info: central (https://raw.github.com/mozilla/cargo-central/master/packages.json)
   >> bloomfilter, cairo, crypto, csv, elasticsearch, glfw, llvm, mecab, mongrel2, 
   >> mre, mustache, pcre, rparse, rust-hello, rustgl_4_2_core, rustic, rustray, 
   >> rustx, sdl, socket, sqlite, time, tnetstring, uri, uuid, zlib, zmq

search <query | '*'> [tags..]

The search command will search through every source for a specific package with credentials you are looking for.

Example

$ cargo search gl
info: syncing source: central...
info: synced source: central
info: central/glfw (a1848f17-c60e-469d-8b12-8f1b45d2c31f) [opengl, graphics]
   >> glfw bindings for Rust.

info: central/rustgl_4_2_core (72589cd3-f56b-40c3-b944-db257ed8b36c) [opengl, graphics]
   >> Opengl 4.2 bindings for Rust.

info: found 2 packages

sources

List your personal sources.

Example

$ cargo sources
info: central (https://raw.github.com/mozilla/cargo-central/master/packages.json) via curl

sources add <name> <url>

Add a source with name located at url. Cargo will figure out how to fetch the source from the URL.

Example

$ cargo sources add central2 git://github.com/mozilla/cargo-central
info: added source: central2

sources remove <name>

Remove a source by name.

Example

$ cargo sources remove central2
info: removed source: central2

sources rename <name> <new>

Rename a source from name to new.

Example

$ cargo sources rename central2 central3
info: renamed source: central2 to central3

sources set-url <name> <url>

Set a source by name's url to url. It will re-calculate the method to use to fetch the source.

Example

$ cargo sources set-url central git://github.com/mozilla/cargo-central
info: changed source url: 'https://raw.github.com/mozilla/cargo-central/master/packages.json' to 'git://github.com/mozilla/cargo-central'

Registering your own packages

We encourage all users to register their packages with cargo central, the source that is fetched by default, by any new cargo user. This will give the widest visibility to your package and make it easiest for other developers to find and fix packages that might have fallen behind changes to the language, upstream. N.B. Your package entry's name field may only contain alpha-numeric characters, dashes or underscores.

To "register" a package, the easiest approach is the following:

• Push your package to a git repository somewhere. Make sure your package contains a crate file somewhere in its directory structure called <yourpackage>.rc, that contains a suitably detailed #[link ...] attribute describing at least its short name. We will likely make some link attribute fields mandatory for future inclusion in cargo -- possibly the uuid field or vers for version numbers -- so it's good to include those as well. If your package is a library, you will need to add #[crate_type = "lib"]; to the <yourpackage>.rc file.

• fork the cargo-central repository and add a new entry to the packages.json file, for example (including a uuid from the uuidgen tool):

  {
  "name": "crypto",
  "uuid": "38297409-b4c2-4499-8131-a99a7e44dad3",
  "url": "git://github.com/elly/rustcrypto",
  "method": "git",
  "tags": ["crypto"]
  },
  

• submit a pull request and, if you want it expedited, notify someone on IRC or through email who has write access to the cargo-central repository.

Once you've registered your package like this once you no longer have to interact with cargo-central, cargo has been directed to use git to access your repository. So as you push updates to that repository, on your own time, they will immediately become visible to users performing cargo install <yourpackage>.

That's it! We've tried to keep it as simple as possible. The system is structured in a decentralized fashion -- you can add your own sources, you don't have to use cargo-central -- but we encourage you to use cargo-central to help us keep track of all the packages being written, and try to keep name collisions to a minimum.