<!DOCTYPE HTML>
<html lang="en" class="sidebar-visible no-js">
<head>
<!-- Book generated using mdBook -->
<meta charset="UTF-8">
<title>Registries - The Cargo Book</title>
<meta content="text/html; charset=utf-8" http-equiv="Content-Type">
<meta name="description" content="">
<meta name="viewport" content="width=device-width, initial-scale=1">
<meta name="theme-color" content="#ffffff" />
<base href="../">
<link rel="stylesheet" href="book.css">
<link href="https://fonts.googleapis.com/css?family=Open+Sans:300italic,400italic,600italic,700italic,800italic,400,300,600,700,800" rel="stylesheet" type="text/css">
<link href="https://fonts.googleapis.com/css?family=Source+Code+Pro:500" rel="stylesheet" type="text/css">
<link rel="shortcut icon" href="favicon.png">
<!-- Font Awesome -->
<link rel="stylesheet" href="_FontAwesome/css/font-awesome.css">
<link rel="stylesheet" href="highlight.css">
<link rel="stylesheet" href="tomorrow-night.css">
<link rel="stylesheet" href="ayu-highlight.css">
<!-- Custom theme stylesheets -->
</head>
<body class="light">
<!-- Work around some values being stored in localStorage wrapped in quotes -->
<script type="text/javascript">
try {
var theme = localStorage.getItem('mdbook-theme');
var sidebar = localStorage.getItem('mdbook-sidebar');
if (theme.startsWith('"') && theme.endsWith('"')) {
localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1));
}
if (sidebar.startsWith('"') && sidebar.endsWith('"')) {
localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1));
}
} catch (e) { }
</script>
<!-- Set the theme before any content is loaded, prevents flash -->
<script type="text/javascript">
var theme;
try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
if (theme === null || theme === undefined) { theme = 'light'; }
document.body.className = theme;
document.querySelector('html').className = theme + ' js';
</script>
<!-- Hide / unhide sidebar before it is displayed -->
<script type="text/javascript">
var html = document.querySelector('html');
var sidebar = 'hidden';
if (document.body.clientWidth >= 1080) {
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
sidebar = sidebar || 'visible';
}
html.classList.remove('sidebar-visible');
html.classList.add("sidebar-" + sidebar);
</script>
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
<ol class="chapter"><li class="affix"><a href="index.html">Introduction</a></li><li><a href="getting-started/index.html"><strong aria-hidden="true">1.</strong> Getting Started</a></li><li><ol class="section"><li><a href="getting-started/installation.html"><strong aria-hidden="true">1.1.</strong> Installation</a></li><li><a href="getting-started/first-steps.html"><strong aria-hidden="true">1.2.</strong> First Steps with Cargo</a></li></ol></li><li><a href="guide/index.html"><strong aria-hidden="true">2.</strong> Cargo Guide</a></li><li><ol class="section"><li><a href="guide/why-cargo-exists.html"><strong aria-hidden="true">2.1.</strong> Why Cargo Exists</a></li><li><a href="guide/creating-a-new-project.html"><strong aria-hidden="true">2.2.</strong> Creating a New Package</a></li><li><a href="guide/working-on-an-existing-project.html"><strong aria-hidden="true">2.3.</strong> Working on an Existing Package</a></li><li><a href="guide/dependencies.html"><strong aria-hidden="true">2.4.</strong> Dependencies</a></li><li><a href="guide/project-layout.html"><strong aria-hidden="true">2.5.</strong> Package Layout</a></li><li><a href="guide/cargo-toml-vs-cargo-lock.html"><strong aria-hidden="true">2.6.</strong> Cargo.toml vs Cargo.lock</a></li><li><a href="guide/tests.html"><strong aria-hidden="true">2.7.</strong> Tests</a></li><li><a href="guide/continuous-integration.html"><strong aria-hidden="true">2.8.</strong> Continuous Integration</a></li><li><a href="guide/build-cache.html"><strong aria-hidden="true">2.9.</strong> Build Cache</a></li></ol></li><li><a href="reference/index.html"><strong aria-hidden="true">3.</strong> Cargo Reference</a></li><li><ol class="section"><li><a href="reference/specifying-dependencies.html"><strong aria-hidden="true">3.1.</strong> Specifying Dependencies</a></li><li><a href="reference/manifest.html"><strong aria-hidden="true">3.2.</strong> The Manifest Format</a></li><li><a href="reference/config.html"><strong aria-hidden="true">3.3.</strong> Configuration</a></li><li><a href="reference/environment-variables.html"><strong aria-hidden="true">3.4.</strong> Environment Variables</a></li><li><a href="reference/build-scripts.html"><strong aria-hidden="true">3.5.</strong> Build Scripts</a></li><li><a href="reference/publishing.html"><strong aria-hidden="true">3.6.</strong> Publishing on crates.io</a></li><li><a href="reference/pkgid-spec.html"><strong aria-hidden="true">3.7.</strong> Package ID Specifications</a></li><li><a href="reference/source-replacement.html"><strong aria-hidden="true">3.8.</strong> Source Replacement</a></li><li><a href="reference/external-tools.html"><strong aria-hidden="true">3.9.</strong> External Tools</a></li><li><a href="reference/registries.html" class="active"><strong aria-hidden="true">3.10.</strong> Registries</a></li><li><a href="reference/unstable.html"><strong aria-hidden="true">3.11.</strong> Unstable Features</a></li></ol></li><li><a href="commands/index.html"><strong aria-hidden="true">4.</strong> Cargo Commands</a></li><li><ol class="section"><li><a href="commands/build-commands.html"><strong aria-hidden="true">4.1.</strong> Build Commands</a></li><li><ol class="section"><li><a href="commands/cargo-bench.html"><strong aria-hidden="true">4.1.1.</strong> bench</a></li><li><a href="commands/cargo-build.html"><strong aria-hidden="true">4.1.2.</strong> build</a></li><li><a href="commands/cargo-check.html"><strong aria-hidden="true">4.1.3.</strong> check</a></li><li><a href="commands/cargo-clean.html"><strong aria-hidden="true">4.1.4.</strong> clean</a></li><li><a href="commands/cargo-doc.html"><strong aria-hidden="true">4.1.5.</strong> doc</a></li><li><a href="commands/cargo-fetch.html"><strong aria-hidden="true">4.1.6.</strong> fetch</a></li><li><a href="commands/cargo-fix.html"><strong aria-hidden="true">4.1.7.</strong> fix</a></li><li><a href="commands/cargo-run.html"><strong aria-hidden="true">4.1.8.</strong> run</a></li><li><a href="commands/cargo-rustc.html"><strong aria-hidden="true">4.1.9.</strong> rustc</a></li><li><a href="commands/cargo-rustdoc.html"><strong aria-hidden="true">4.1.10.</strong> rustdoc</a></li><li><a href="commands/cargo-test.html"><strong aria-hidden="true">4.1.11.</strong> test</a></li></ol></li><li><a href="commands/manifest-commands.html"><strong aria-hidden="true">4.2.</strong> Manifest Commands</a></li><li><ol class="section"><li><a href="commands/cargo-generate-lockfile.html"><strong aria-hidden="true">4.2.1.</strong> generate-lockfile</a></li><li><a href="commands/cargo-locate-project.html"><strong aria-hidden="true">4.2.2.</strong> locate-project</a></li><li><a href="commands/cargo-metadata.html"><strong aria-hidden="true">4.2.3.</strong> metadata</a></li><li><a href="commands/cargo-pkgid.html"><strong aria-hidden="true">4.2.4.</strong> pkgid</a></li><li><a href="commands/cargo-update.html"><strong aria-hidden="true">4.2.5.</strong> update</a></li><li><a href="commands/cargo-verify-project.html"><strong aria-hidden="true">4.2.6.</strong> verify-project</a></li></ol></li><li><a href="commands/package-commands.html"><strong aria-hidden="true">4.3.</strong> Package Commands</a></li><li><ol class="section"><li><a href="commands/cargo-init.html"><strong aria-hidden="true">4.3.1.</strong> init</a></li><li><a href="commands/cargo-install.html"><strong aria-hidden="true">4.3.2.</strong> install</a></li><li><a href="commands/cargo-new.html"><strong aria-hidden="true">4.3.3.</strong> new</a></li><li><a href="commands/cargo-search.html"><strong aria-hidden="true">4.3.4.</strong> search</a></li><li><a href="commands/cargo-uninstall.html"><strong aria-hidden="true">4.3.5.</strong> uninstall</a></li></ol></li><li><a href="commands/publishing-commands.html"><strong aria-hidden="true">4.4.</strong> Publishing Commands</a></li><li><ol class="section"><li><a href="commands/cargo-login.html"><strong aria-hidden="true">4.4.1.</strong> login</a></li><li><a href="commands/cargo-owner.html"><strong aria-hidden="true">4.4.2.</strong> owner</a></li><li><a href="commands/cargo-package.html"><strong aria-hidden="true">4.4.3.</strong> package</a></li><li><a href="commands/cargo-publish.html"><strong aria-hidden="true">4.4.4.</strong> publish</a></li><li><a href="commands/cargo-yank.html"><strong aria-hidden="true">4.4.5.</strong> yank</a></li></ol></li><li><a href="commands/general-commands.html"><strong aria-hidden="true">4.5.</strong> General Commands</a></li><li><ol class="section"><li><a href="commands/cargo-help.html"><strong aria-hidden="true">4.5.1.</strong> help</a></li><li><a href="commands/cargo-version.html"><strong aria-hidden="true">4.5.2.</strong> version</a></li></ol></li></ol></li><li><a href="faq.html"><strong aria-hidden="true">5.</strong> FAQ</a></li><li><a href="appendix/glossary.html"><strong aria-hidden="true">6.</strong> Appendix: Glossary</a></li></ol>
</nav>
<div id="page-wrapper" class="page-wrapper">
<div class="page">
<div id="menu-bar" class="menu-bar">
<div id="menu-bar-sticky-container">
<div class="left-buttons">
<button id="sidebar-toggle" class="icon-button" type="button" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
<i class="fa fa-bars"></i>
</button>
<button id="theme-toggle" class="icon-button" type="button" title="Change theme" aria-label="Change theme" aria-haspopup="true" aria-expanded="false" aria-controls="theme-list">
<i class="fa fa-paint-brush"></i>
</button>
<ul id="theme-list" class="theme-popup" aria-label="Themes" role="menu">
<li role="none"><button role="menuitem" class="theme" id="light">Light <span class="default">(default)</span></button></li>
<li role="none"><button role="menuitem" class="theme" id="rust">Rust</button></li>
<li role="none"><button role="menuitem" class="theme" id="coal">Coal</button></li>
<li role="none"><button role="menuitem" class="theme" id="navy">Navy</button></li>
<li role="none"><button role="menuitem" class="theme" id="ayu">Ayu</button></li>
</ul>
<button id="search-toggle" class="icon-button" type="button" title="Search. (Shortkey: s)" aria-label="Toggle Searchbar" aria-expanded="false" aria-keyshortcuts="S" aria-controls="searchbar">
<i class="fa fa-search"></i>
</button>
</div>
<h1 class="menu-title">The Cargo Book</h1>
<div class="right-buttons">
<a href="print.html" title="Print this book" aria-label="Print this book">
<i id="print-button" class="fa fa-print"></i>
</a>
</div>
</div>
</div>
<div id="search-wrapper" class="hidden">
<form id="searchbar-outer" class="searchbar-outer">
<input type="search" name="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
</form>
<div id="searchresults-outer" class="searchresults-outer hidden">
<div id="searchresults-header" class="searchresults-header"></div>
<ul id="searchresults">
</ul>
</div>
</div>
<!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM -->
<script type="text/javascript">
document.getElementById('sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible');
document.getElementById('sidebar').setAttribute('aria-hidden', sidebar !== 'visible');
Array.from(document.querySelectorAll('#sidebar a')).forEach(function(link) {
link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1);
});
</script>
<div id="content" class="content">
<main>
<a class="header" href="reference/registries.html#registries" id="registries"><h2>Registries</h2></a>
<p>Cargo installs crates and fetches dependencies from a "registry". The default
registry is <a href="https://crates.io/">crates.io</a>. A registry contains an "index" which contains a
searchable list of available crates. A registry may also provide a web API to
support publishing new crates directly from Cargo.</p>
<blockquote>
<p>Note: If you are interested in mirroring or vendoring an existing registry,
take a look at <a href="reference/source-replacement.html">Source Replacement</a>.</p>
</blockquote>
<a class="header" href="reference/registries.html#using-an-alternate-registry" id="using-an-alternate-registry"><h3>Using an Alternate Registry</h3></a>
<p>To use a registry other than <a href="https://crates.io/">crates.io</a>, the name and index URL of the
registry must be added to a <a href="reference/config.html"><code>.cargo/config</code> file</a>. The <code>registries</code>
table has a key for each registry, for example:</p>
<pre><code class="language-toml">[registries]
my-registry = { index = "https://my-intranet:8080/git/index" }
</code></pre>
<p>The <code>index</code> key should be a URL to a git repository with the registry's index.
A crate can then depend on a crate from another registry by specifying the
<code>registry</code> key and a value of the registry's name in that dependency's entry
in <code>Cargo.toml</code>:</p>
<pre><code class="language-toml"># Sample Cargo.toml
[package]
name = "my-project"
version = "0.1.0"
[dependencies]
other-crate = { version = "1.0", registry = "my-registry" }
</code></pre>
<p>As with most config values, the index may be specified with an environment
variable instead of a config file. For example, setting the following
environment variable will accomplish the same thing as defining a config file:</p>
<pre><code>CARGO_REGISTRIES_MY_REGISTRY_INDEX=https://my-intranet:8080/git/index
</code></pre>
<blockquote>
<p>Note: <a href="https://crates.io/">crates.io</a> does not accept packages that depend on crates from other
registries.</p>
</blockquote>
<a class="header" href="reference/registries.html#publishing-to-an-alternate-registry" id="publishing-to-an-alternate-registry"><h3>Publishing to an Alternate Registry</h3></a>
<p>If the registry supports web API access, then packages can be published
directly to the registry from Cargo. Several of Cargo's commands such as
<a href="commands/cargo-publish.html"><code>cargo publish</code></a> take a <code>--registry</code> command-line flag to indicate which
registry to use. For example, to publish the package in the current directory:</p>
<ol>
<li>
<p><code>cargo login --registry=my-registry</code></p>
<p>This only needs to be done once. You must enter the secret API token
retrieved from the registry's website. Alternatively the token may be
passed directly to the <code>publish</code> command with the <code>--token</code> command-line
flag or an environment variable with the name of the registry such as
<code>CARGO_REGISTRIES_MY_REGISTRY_TOKEN</code>.</p>
</li>
<li>
<p><code>cargo publish --registry=my-registry</code></p>
</li>
</ol>
<p>Instead of always passing the <code>--registry</code> command-line option, the default
registry may be set in <a href="reference/config.html"><code>.cargo/config</code></a> with the <code>registry.default</code>
key.</p>
<p>Setting the <code>package.publish</code> key in the <code>Cargo.toml</code> manifest restricts which
registries the package is allowed to be published to. This is useful to
prevent accidentally publishing a closed-source package to <a href="https://crates.io/">crates.io</a>. The
value may be a list of registry names, for example:</p>
<pre><code class="language-toml">[package]
# ...
publish = ["my-registry"]
</code></pre>
<p>The <code>publish</code> value may also be <code>false</code> to restrict all publishing, which is
the same as an empty list.</p>
<p>The authentication information saved by <a href="commands/cargo-login.html"><code>cargo login</code></a> is stored in the
<code>credentials</code> file in the Cargo home directory (default <code>$HOME/.cargo</code>). It
has a separate table for each registry, for example:</p>
<pre><code class="language-toml">[registries.my-registry]
token = "854DvwSlUwEHtIo3kWy6x7UCPKHfzCmy"
</code></pre>
<a class="header" href="reference/registries.html#running-a-registry" id="running-a-registry"><h3>Running a Registry</h3></a>
<p>A minimal registry can be implemented by having a git repository that contains
an index, and a server that contains the compressed <code>.crate</code> files created by
<a href="commands/cargo-package.html"><code>cargo package</code></a>. Users won't be able to use Cargo to publish to it, but this
may be sufficient for closed environments.</p>
<p>A full-featured registry that supports publishing will additionally need to
have a web API service that conforms to the API used by Cargo. The web API is
documented below.</p>
<p>At this time, there is no widely used software for running a custom registry.
There is interest in documenting projects that implement registry support, or
existing package caches that add support for Cargo.</p>
<a class="header" href="reference/registries.html#index-format" id="index-format"><h3>Index Format</h3></a>
<p>The following defines the format of the index. New features are occasionally
added, which are only understood starting with the version of Cargo that
introduced them. Older versions of Cargo may not be able to use packages that
make use of new features. However, the format for older packages should not
change, so older versions of Cargo should be able to use them.</p>
<p>The index is stored in a git repository so that Cargo can efficiently fetch
incremental updates to the index. In the root of the repository is a file
named <code>config.json</code> which contains JSON information used by Cargo for
accessing the registry. This is an example of what the <a href="https://crates.io/">crates.io</a> config file
looks like:</p>
<pre><code class="language-javascript">{
"dl": "https://crates.io/api/v1/crates",
"api": "https://crates.io"
}
</code></pre>
<p>The keys are:</p>
<ul>
<li><code>dl</code>: This is the URL for downloading crates listed in the index. The value
may have the markers <code>{crate}</code> and <code>{version}</code> which are replaced with the
name and version of the crate to download. If the markers are not present,
then the value <code>/{crate}/{version}/download</code> is appended to the end.</li>
<li><code>api</code>: This is the base URL for the web API. This key is optional, and if it
is not specified, commands such as <a href="commands/cargo-publish.html"><code>cargo publish</code></a> will not work. The web
API is described below.</li>
</ul>
<p>The download endpoint should send the <code>.crate</code> file for the requested package.
Cargo supports https, http, and file URLs, HTTP redirects, HTTP1 and HTTP2.
The exact specifics of TLS support depend on the platform that Cargo is
running on, the version of Cargo, and how it was compiled.</p>
<p>The rest of the index repository contains one file for each package, where the
filename is the name of the package in lowercase. Each version of the package
has a separate line in the file. The files are organized in a tier of
directories:</p>
<ul>
<li>Packages with 1 character names are placed in a directory named <code>1</code>.</li>
<li>Packages with 2 character names are placed in a directory named <code>2</code>.</li>
<li>Packages with 3 character names are placed in the directory
<code>3/{first-character}</code> where <code>{first-character}</code> is the first character of
the package name.</li>
<li>All other packages are stored in directories named
<code>{first-two}/{second-two}</code> where the top directory is the first two
characters of the package name, and the next subdirectory is the third and
fourth characters of the package name. For example, <code>cargo</code> would be stored
in a file named <code>ca/rg/cargo</code>.</li>
</ul>
<blockquote>
<p>Note: Although the index filenames are in lowercase, the fields that contain
package names in <code>Cargo.toml</code> and the index JSON data are case-sensitive and
may contain upper and lower case characters.</p>
</blockquote>
<p>Registries may want to consider enforcing limitations on package names added
to their index. Cargo itself allows names with any <a href="https://doc.rust-lang.org/std/primitive.char.html#method.is_alphanumeric">alphanumeric</a>, <code>-</code>, or <code>_</code>
character. For example, <a href="https://crates.io/">crates.io</a> imposes relatively strict limitations,
such as requiring it to be a valid Rust identifier, only allowing ASCII
characters, under a specific length, and rejects reserved names such as
Windows special filenames like "nul".</p>
<p>Each line in a package file contains a JSON object that describes a published
version of the package. The following is a pretty-printed example with comments
explaining the format of the entry.</p>
<pre><code class="language-javascript">{
// The name of the package.
// This must only contain alphanumeric, `-`, or `_` characters.
"name": "foo",
// The version of the package this row is describing.
// This must be a valid version number according to the Semantic
// Versioning 2.0.0 spec at https://semver.org/.
"vers": "0.1.0",
// Array of direct dependencies of the package.
"deps": [
{
// Name of the dependency.
// If the dependency is renamed from the original package name,
// this is the new name. The original package name is stored in
// the `package` field.
"name": "rand",
// The semver requirement for this dependency.
// This must be a valid version requirement defined at
// https://github.com/steveklabnik/semver#requirements.
"req": "^0.6",
// Array of features (as strings) enabled for this dependency.
"features": ["i128_support"],
// Boolean of whether or not this is an optional dependency.
"optional": false,
// Boolean of whether or not default features are enabled.
"default_features": true,
// The target platform for the dependency.
// null if not a target dependency.
// Otherwise, a string such as "cfg(windows)".
"target": null,
// The dependency kind.
// "dev", "build", or "normal".
// Note: this is a required field, but a small number of entries
// exist in the crates.io index with either a missing or null
// `kind` field due to implementation bugs.
"kind": "normal",
// The URL of the index of the registry where this dependency is
// from as a string. If not specified or null, it is assumed the
// dependency is in the current registry.
"registry": null,
// If the dependency is renamed, this is a string of the actual
// package name. If not specified or null, this dependency is not
// renamed.
"package": null,
}
],
// A SHA256 checksum of the `.crate` file.
"cksum": "d867001db0e2b6e0496f9fac96930e2d42233ecd3ca0413e0753d4c7695d289c",
// Set of features defined for the package.
// Each feature maps to an array of features or dependencies it enables.
"features": {
"extras": ["rand/simd_support"]
},
// Boolean of whether or not this version has been yanked.
"yanked": false,
// The `links` string value from the package's manifest, or null if not
// specified. This field is optional and defaults to null.
"links": null
}
</code></pre>
<p>The JSON objects should not be modified after they are added except for the
<code>yanked</code> field whose value may change at any time.</p>
<a class="header" href="reference/registries.html#web-api" id="web-api"><h3>Web API</h3></a>
<p>A registry may host a web API at the location defined in <code>config.json</code> to
support any of the actions listed below.</p>
<p>Cargo includes the <code>Authorization</code> header for requests that require
authentication. The header value is the API token. The server should respond
with a 403 response code if the token is not valid. Users are expected to
visit the registry's website to obtain a token, and Cargo can store the token
using the <a href="commands/cargo-login.html"><code>cargo login</code></a> command, or by passing the token on the
command-line.</p>
<p>Responses use a 200 response code for both success and errors. Cargo looks at
the JSON response to determine if there was success or failure. Failure
responses have a JSON object with the following structure:</p>
<pre><code class="language-javascript">{
// Array of errors to display to the user.
"errors": [
{
// The error message as a string.
"detail": "error message text"
}
]
}
</code></pre>
<p>Servers may also respond with a 404 response code to indicate the requested
resource is not found (for example, an unknown crate name). However, using a
200 response with an <code>errors</code> object allows a registry to provide a more
detailed error message if desired.</p>
<p>For backwards compatibility, servers should ignore any unexpected query
parameters or JSON fields. If a JSON field is missing, it should be assumed to
be null. The endpoints are versioned with the <code>v1</code> component of the path, and
Cargo is responsible for handling backwards compatibility fallbacks should any
be required in the future.</p>
<p>Cargo sets the following headers for all requests:</p>
<ul>
<li><code>Content-Type</code>: <code>application/json</code></li>
<li><code>Accept</code>: <code>application/json</code></li>
<li><code>User-Agent</code>: The Cargo version such as <code>cargo 1.32.0 (8610973aa 2019-01-02)</code>. This may be modified by the user in a configuration value.
Added in 1.29.</li>
</ul>
<a class="header" href="reference/registries.html#publish" id="publish"><h4>Publish</h4></a>
<ul>
<li>Endpoint: <code>/api/v1/crates/new</code></li>
<li>Method: PUT</li>
<li>Authorization: Included</li>
</ul>
<p>The publish endpoint is used to publish a new version of a crate. The server
should validate the crate, make it available for download, and add it to the
index.</p>
<p>The body of the data sent by Cargo is:</p>
<ul>
<li>32-bit unsigned little-endian integer of the length of JSON data.</li>
<li>Metadata of the package as a JSON object.</li>
<li>32-bit unsigned little-endian integer of the length of the <code>.crate</code> file.</li>
<li>The <code>.crate</code> file.</li>
</ul>
<p>The following is a commented example of the JSON object. Some notes of some
restrictions imposed by <a href="https://crates.io/">crates.io</a> are included only to illustrate some
suggestions on types of validation that may be done, and should not be
considered as an exhaustive list of restrictions <a href="https://crates.io/">crates.io</a> imposes.</p>
<pre><code class="language-javascript">{
// The name of the package.
"name": "foo",
// The version of the package being published.
"vers": "0.1.0",
// Array of direct dependencies of the package.
"deps": [
{
// Name of the dependency.
// If the dependency is renamed from the original package name,
// this is the original name. The new package name is stored in
// the `explicit_name_in_toml` field.
"name": "rand",
// The semver requirement for this dependency.
"version_req": "^0.6",
// Array of features (as strings) enabled for this dependency.
"features": ["i128_support"],
// Boolean of whether or not this is an optional dependency.
"optional": false,
// Boolean of whether or not default features are enabled.
"default_features": true,
// The target platform for the dependency.
// null if not a target dependency.
// Otherwise, a string such as "cfg(windows)".
"target": null,
// The dependency kind.
// "dev", "build", or "normal".
"kind": "normal",
// The URL of the index of the registry where this dependency is
// from as a string. If not specified or null, it is assumed the
// dependency is in the current registry.
"registry": null,
// If the dependency is renamed, this is a string of the new
// package name. If not specified or null, this dependency is not
// renamed.
"explicit_name_in_toml": null,
}
],
// Set of features defined for the package.
// Each feature maps to an array of features or dependencies it enables.
// Cargo does not impose limitations on feature names, but crates.io
// requires alphanumeric ASCII, `_` or `-` characters.
"features": {
"extras": ["rand/simd_support"]
},
// List of strings of the authors.
// May be empty. crates.io requires at least one entry.
"authors": ["Alice <a@example.com>"],
// Description field from the manifest.
// May be null. crates.io requires at least some content.
"description": null,
// String of the URL to the website for this package's documentation.
// May be null.
"documentation": null,
// String of the URL to the website for this package's home page.
// May be null.
"homepage": null,
// String of the content of the README file.
// May be null.
"readme": null,
// String of a relative path to a README file in the crate.
// May be null.
"readme_file": null,
// Array of strings of keywords for the package.
"keywords": [],
// Array of strings of categories for the package.
"categories": [],
// String of the license for the package.
// May be null. crates.io requires either `license` or `license_file` to be set.
"license": null,
// String of a relative path to a license file in the crate.
// May be null.
"license_file": null,
// String of the URL to the website for the source repository of this package.
// May be null.
"repository": null,
// Optional object of "status" badges. Each value is an object of
// arbitrary string to string mappings.
// crates.io has special interpretation of the format of the badges.
"badges": {
"travis-ci": {
"branch": "master",
"repository": "rust-lang/cargo"
}
},
// The `links` string value from the package's manifest, or null if not
// specified. This field is optional and defaults to null.
"links": null,
}
</code></pre>
<p>A successful response includes the JSON object:</p>
<pre><code class="language-javascript">{
// Optional object of warnings to display to the user.
"warnings": {
// Array of strings of categories that are invalid and ignored.
"invalid_categories": [],
// Array of strings of badge names that are invalid and ignored.
"invalid_badges": [],
// Array of strings of arbitrary warnings to display to the user.
"other": []
}
}
</code></pre>
<a class="header" href="reference/registries.html#yank" id="yank"><h4>Yank</h4></a>
<ul>
<li>Endpoint: <code>/api/v1/crates/{crate_name}/{version}/yank</code></li>
<li>Method: DELETE</li>
<li>Authorization: Included</li>
</ul>
<p>The yank endpoint will set the <code>yank</code> field of the given version of a crate to
<code>true</code> in the index.</p>
<p>A successful response includes the JSON object:</p>
<pre><code class="language-javascript">{
// Indicates the delete succeeded, always true.
"ok": true,
}
</code></pre>
<a class="header" href="reference/registries.html#unyank" id="unyank"><h4>Unyank</h4></a>
<ul>
<li>Endpoint: <code>/api/v1/crates/{crate_name}/{version}/unyank</code></li>
<li>Method: PUT</li>
<li>Authorization: Included</li>
</ul>
<p>The unyank endpoint will set the <code>yank</code> field of the given version of a crate
to <code>false</code> in the index.</p>
<p>A successful response includes the JSON object:</p>
<pre><code class="language-javascript">{
// Indicates the delete succeeded, always true.
"ok": true,
}
</code></pre>
<a class="header" href="reference/registries.html#owners" id="owners"><h4>Owners</h4></a>
<p>Cargo does not have an inherent notion of users and owners, but it does
provide the <code>owner</code> command to assist managing who has authorization to
control a crate. It is up to the registry to decide exactly how users and
owners are handled. See the <a href="reference/publishing.html#cargo-owner">publishing documentation</a> for a description of
how <a href="https://crates.io/">crates.io</a> handles owners via GitHub users and teams.</p>
<a class="header" href="reference/registries.html#owners-list" id="owners-list"><h5>Owners: List</h5></a>
<ul>
<li>Endpoint: <code>/api/v1/crates/{crate_name}/owners</code></li>
<li>Method: GET</li>
<li>Authorization: Included</li>
</ul>
<p>The owners endpoint returns a list of owners of the crate.</p>
<p>A successful response includes the JSON object:</p>
<pre><code class="language-javascript">{
// Array of owners of the crate.
"users": [
{
// Unique unsigned 32-bit integer of the owner.
"id": 70,
// The unique username of the owner.
"login": "github:rust-lang:core",
// Name of the owner.
// This is optional and may be null.
"name": "Core",
}
]
}
</code></pre>
<a class="header" href="reference/registries.html#owners-add" id="owners-add"><h5>Owners: Add</h5></a>
<ul>
<li>Endpoint: <code>/api/v1/crates/{crate_name}/owners</code></li>
<li>Method: PUT</li>
<li>Authorization: Included</li>
</ul>
<p>A PUT request will send a request to the registry to add a new owner to a
crate. It is up to the registry how to handle the request. For example,
<a href="https://crates.io/">crates.io</a> sends an invite to the user that they must accept before being
added.</p>
<p>The request should include the following JSON object:</p>
<pre><code class="language-javascript">{
// Array of `login` strings of owners to add.
"users": ["login_name"]
}
</code></pre>
<p>A successful response includes the JSON object:</p>
<pre><code class="language-javascript">{
// Indicates the add succeeded, always true.
"ok": true,
// A string to be displayed to the user.
"msg": "user ehuss has been invited to be an owner of crate cargo"
}
</code></pre>
<a class="header" href="reference/registries.html#owners-remove" id="owners-remove"><h5>Owners: Remove</h5></a>
<ul>
<li>Endpoint: <code>/api/v1/crates/{crate_name}/owners</code></li>
<li>Method: DELETE</li>
<li>Authorization: Included</li>
</ul>
<p>A DELETE request will remove an owner from a crate. The request should include
the following JSON object:</p>
<pre><code class="language-javascript">{
// Array of `login` strings of owners to remove.
"users": ["login_name"]
}
</code></pre>
<p>A successful response includes the JSON object:</p>
<pre><code class="language-javascript">{
// Indicates the remove succeeded, always true.
"ok": true
}
</code></pre>
<a class="header" href="reference/registries.html#search" id="search"><h4>Search</h4></a>
<ul>
<li>Endpoint: <code>/api/v1/crates</code></li>
<li>Method: GET</li>
<li>Query Parameters:
<ul>
<li><code>q</code>: The search query string.</li>
<li><code>per_page</code>: Number of results, default 10, max 100.</li>
</ul>
</li>
</ul>
<p>The search request will perform a search for crates, using criteria defined on
the server.</p>
<p>A successful response includes the JSON object:</p>
<pre><code class="language-javascript">{
// Array of results.
"crates": [
{
// Name of the crate.
"name": "rand",
// The highest version available.
"max_version": "0.6.1",
// Textual description of the crate.
"description": "Random number generators and other randomness functionality.\n",
}
],
"meta": {
// Total number of results available on the server.
"total": 119
}
}
</code></pre>
<a class="header" href="reference/registries.html#login" id="login"><h4>Login</h4></a>
<ul>
<li>Endpoint: <code>/me</code></li>
</ul>
<p>The "login" endpoint is not an actual API request. It exists solely for the
<a href="commands/cargo-login.html"><code>cargo login</code></a> command to display a URL to instruct a user to visit in a web
browser to log in and retrieve an API token.</p>
</main>
<nav class="nav-wrapper" aria-label="Page navigation">
<!-- Mobile navigation buttons -->
<a rel="prev" href="reference/external-tools.html" class="mobile-nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
<i class="fa fa-angle-left"></i>
</a>
<a rel="next" href="reference/unstable.html" class="mobile-nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
<i class="fa fa-angle-right"></i>
</a>
<div style="clear: both"></div>
</nav>
</div>
</div>
<nav class="nav-wide-wrapper" aria-label="Page navigation">
<a href="reference/external-tools.html" class="nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
<i class="fa fa-angle-left"></i>
</a>
<a href="reference/unstable.html" class="nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
<i class="fa fa-angle-right"></i>
</a>
</nav>
</div>
<script src="searchindex.js" type="text/javascript" charset="utf-8"></script>
<script src="elasticlunr.min.js" type="text/javascript" charset="utf-8"></script>
<script src="mark.min.js" type="text/javascript" charset="utf-8"></script>
<script src="searcher.js" type="text/javascript" charset="utf-8"></script>
<script src="clipboard.min.js" type="text/javascript" charset="utf-8"></script>
<script src="highlight.js" type="text/javascript" charset="utf-8"></script>
<script src="book.js" type="text/javascript" charset="utf-8"></script>
<!-- Custom JS scripts -->
</body>
</html>
distrib
>
Mageia
>
7
>
armv7hl
>
media
>
core-release
>
by-pkgid
>
0c2243f8a1696816431e7210e991fa52
>
files
>
1124
