<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="generator" content="rustdoc">
<title>External tools</title>
<link rel="stylesheet" type="text/css" href="stylesheets/normalize.css">
<link rel="stylesheet" type="text/css" href="stylesheets/all.css">
<link rel="stylesheet" type="text/css" href="stylesheets/prism.css">
<script src="https://code.jquery.com/jquery-2.1.1.min.js"></script>
<link rel="icon" type="image/x-icon" href="favicon.ico">
</head>
<body class="rustdoc">
<!--[if lte IE 8]>
<div class="warning">
This old browser is unsupported and will most likely display funky
things.
</div>
<![endif]-->
<a href='https://github.com/rust-lang/cargo' class='fork-me'>
<img src='images/forkme.png'/>
</a>
<div id="header">
<a href='https://crates.io' class='logo'>
<img id="logo" height=100 width=100 src='images/Cargo-Logo-Small.png'/>
</a>
<a href="index.html">
<h1>CARGO</h1>
</a>
<div class="search">
<form action="https://crates.io/search"
method="GET">
<input name="q" class="search" placeholder="Search crates" type="text"/>
</form>
</div>
<div class="nav">
<a href='https://crates.io/crates'>Browse All Crates</a>
<span class='sep'>|</span>
<div class="dropdown-container">
<button class="dropdown">
Docs
<span class="arrow"></span>
</button>
<!-- Sync this list with
https://github.com/rust-lang/crates.io/blob/master/app/templates/application.hbs
and with Makefile.in in this repository -->
<ul id="current-user-links" class="dropdown" data-bindattr-503="503">
<li><a href='index.html'>Getting Started</a></li>
<li><a href='guide.html'>Guide</a></li>
<li><a href='specifying-dependencies.html'>Specifying Dependencies</a></li>
<li><a href='crates-io.html'>Publishing on crates.io</a></li>
<li><a href='faq.html'>FAQ</a></li>
<li><a href='manifest.html'>Cargo.toml Format</a></li>
<li><a href='build-script.html'>Build Scripts</a></li>
<li><a href='config.html'>Configuration</a></li>
<li><a href='pkgid-spec.html'>Package ID specs</a></li>
<li><a href='environment-variables.html'>Environment Variables</a></li>
<li><a href='source-replacement.html'>Source Replacement</a></li>
<li><a href='external-tools.html'>External Tools</a></li>
<li><a href='policies.html'>Policies</a></li>
</ul>
</div>
</div>
</div>
<main>
<h1 class="title">External tools</h1>
<p>One of the goals of Cargo is simple integration with third-party tools, like
IDEs and other build systems. To make integration easier, Cargo has several
facilities:</p>
<ul>
<li><p><code>cargo metadata</code> command, which outputs project structure and dependencies
information in JSON,</p></li>
<li><p><code>--message-format</code> flag, which outputs information about a particular build,</p></li>
<li><p>support for custom subcommands.</p></li>
</ul>
<h1 id='information-about-project-structure' class='section-header'><a href='#information-about-project-structure'>Information about project structure</a></h1>
<p>You can use <code>cargo metadata</code> command to get information about project structure
and dependencies. The output of the command looks like this:</p>
<pre><code class="language-text">{
// Integer version number of the format.
"version": integer,
// List of packages for this workspace, including dependencies.
"packages": [
{
// Opaque package identifier.
"id": PackageId,
"name": string,
"version": string,
"source": SourceId,
// A list of declared dependencies, see `resolve` field for actual dependencies.
"dependencies": [ Dependency ],
"targets: [ Target ],
// Path to Cargo.toml
"manifest_path": string,
}
],
"workspace_members": [ PackageId ],
// Dependencies graph.
"resolve": {
"nodes": [
{
"id": PackageId,
"dependencies": [ PackageId ]
}
]
}
}
</code></pre>
<p>The format is stable and versioned. When calling <code>cargo metadata</code>, you should
pass <code>--format-version</code> flag explicitly to avoid forward incompatibility
hazard.</p>
<p>If you are using Rust, there is <a href="https://crates.io/crates/cargo_metadata">cargo_metadata</a> crate.</p>
<h1 id='information-about-build' class='section-header'><a href='#information-about-build'>Information about build</a></h1>
<p>When passing <code>--message-format=json</code>, Cargo will output the following
information during the build:</p>
<ul>
<li><p>compiler errors and warnings,</p></li>
<li><p>produced artifacts,</p></li>
<li><p>results of the build scripts (for example, native dependencies).</p></li>
</ul>
<p>The output goes to stdout in the JSON object per line format. The <code>reason</code> field
distinguishes different kinds of messages.</p>
<p>Information about dependencies in the Makefile-compatible format is stored in
the <code>.d</code> files alongside the artifacts.</p>
<h1 id='custom-subcommands' class='section-header'><a href='#custom-subcommands'>Custom subcommands.</a></h1>
<p>Cargo is designed to be extensible with new subcommands without having to modify
Cargo itself. This is achieved by translating a cargo invocation of the form
cargo <code>(?<command>[^ ]+)</code> into an invocation of an external tool
<code>cargo-${command}</code> that then needs to be present in one of the user's <code>$PATH</code>
directories.</p>
<p>Custom subcommand may use <code>CARGO</code> environment variable to call back to
Cargo. Alternatively, it can link to <code>cargo</code> crate as a library, but this
approach has drawbacks:</p>
<ul>
<li><p>Cargo as a library is unstable, API changes without deprecation,</p></li>
<li><p>versions of Cargo library and Cargo binary may be different.</p></li>
</ul>
</main>
<footer>
<a href='index.html'>Install</a>
<span class='sep'>|</span>
<a href='index.html'>Getting Started</a>
<span class='sep'>|</span>
<a href='guide.html'>Guide</a>
</footer>
<script type='text/javascript' src='javascripts/prism.js'></script>
<script type='text/javascript' src='javascripts/all.js'></script>
</body>
</html>
