<h1 id="rust-crates-to-debian-packages">Rust crates to Debian
packages</h1>
<p><code>debcargo</code> is the official tool for packaging Rust crates
to be part of the <a href="https://www.debian.org/">Debian</a>
system.</p>
<p>It creates a Debian source package (<code>*.dsc</code>) from a Rust
crate that follows Debian’s <a
href="https://www.debian.org/doc/debian-policy/">general packaging
policy</a> as well as the Debian Rust team’s <a
href="https://wiki.debian.org/Teams/RustPackaging/Policy">crate
packaging policy</a>.</p>
<h2 id="features">Features</h2>
<ul>
<li>Easy to customize, using config files and overlay directories. This
includes patching or otherwise fixing Rust crates to adhere to Debian
policy.</li>
<li>Guess copyright information from crate metadata and source code,
used to suggest appropriate values for
<code>debian/copyright</code>.</li>
<li>Put <code>FIXME (hint)</code> strings where it can’t detect full
information, so user can provide an override/overlay or manually fix
it.</li>
<li>Resulting packages automatically support general functionality
available to all policy-conforming Debian packages, such as:
<ul>
<li>binaries for <a href="https://www.debian.org/ports/">10+
architectures</a> are made available directly to users, via
<code>apt-get</code></li>
<li>debugging symbols are placed in a separate binary package,
integrating with the standard Debian <a
href="https://wiki.debian.org/HowToGetABacktrace">distribution system
for debugging symbols</a></li>
<li>full system integration with non-Rust software, including
cross-language dependency resolution</li>
<li>cross-compilation support, including automatic resolution and
installation of non-Rust cross-dependencies, via Debian build tools such
as <code>sbuild</code>.</li>
</ul></li>
<li>Determine a crate’s full dependency tree (i.e. build order), from
both Debian packaging and QA perspectives.</li>
</ul>
<h2 id="installation">Installation</h2>
<p>On Debian systems, <code>debcargo</code> can be installed the usual
way:</p>
<pre class="shell"><code>$ apt-get install debcargo</code></pre>
<p>To build locally for development:</p>
<pre class="shell"><code>$ apt-get build-dep debcargo
$ cargo build debcargo</code></pre>
<p>On non-Debian systems, you can try simply:</p>
<pre class="shell"><code>$ cargo build debcargo</code></pre>
<p>and fix any build errors that come up, e.g. by installing missing
libraries. Probably, this will include OpenSSL as a dependency of
cargo.</p>
<h2 id="examples">Examples</h2>
<p>To download and unpack the latest <code>clap</code> crate and prepare
the source package:</p>
<pre class="shell"><code>$ debcargo package clap</code></pre>
<p>To download and unpack version <code>2.25.0</code> of
<code>clap</code> crate and prepare the source package:</p>
<pre class="shell"><code>$ debcargo package clap =2.25.0</code></pre>
<p>To provide additional packaging-specific config for downloading and
packaging latest <code>clap</code> crate from crates.io:</p>
<pre class="shell"><code>$ debcargo package --config clap-2/debian/debcargo.toml clap</code></pre>
<p>See <code>debcargo.toml.example</code> for a sample TOML file.</p>
<h2 id="long-term-package-maintenance">Long-term package
maintenance</h2>
<p>The Debian Rust team uses this tool together with the configs and
overlays in https://salsa.debian.org/rust-team/debcargo-conf/. If you
are interested in contributing, please see that repository for further
information and instructions on how to collaborate with us.</p>
<h2 id="building-unofficial-debian-packages">Building unofficial Debian
packages</h2>
<p>Debian packaging policy is quite detailed. If you just want to create
Debian binary packages (<code>*.deb</code>) without worrying about these
policies, you may want to use other tools instead that ignore and bypass
these policies. For example, <code>cargo-deb</code>.</p>
<p>The trade-off is that the resulting packages integrate less well with
a Debian system, and do not integrate at all with the Debian build
system, which means you lose the features described earlier.
Furthermore, you will be responsible for hosting and distributing those
packages yourself, outside of the official Debian distribution
infrastructure.</p>
<h2 id="license">License</h2>
<p>Debcargo is licensed under <code>MIT/Apache-2.0</code>. It is written
by <code>Josh Triplett</code> and <code>Ximin Luo</code>, and improved
by members of <strong>Debian Rust Maintainers team</strong></p>