source: general/prog/cargo.xml@ 8e848de9

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
  <!ENTITY % general-entities SYSTEM "../../general.ent">
  %general-entities;

  <!ENTITY cargo-download-http "https://github.com/rust-lang/cargo/archive/&cargo-version;.tar.gz">
  <!ENTITY cargo-download-ftp  " ">
  <!ENTITY cargo-md5sum        "c0bdbfdeead6a7cdfd7fbfe2183bfc61">
  <!ENTITY cargo-size          "624 KB">
  <!ENTITY cargo-buildsize     "129 MB plus extra 115 MB in ~/.cargo and 2.2GB for the testsuite">
  <!ENTITY cargo-time          "1.8 SBU plus 2.4 SBU for the testsuite on a machine with 4 cores">

  <!-- RUSTIDATE is deined in packages.ent -->
  <!-- temporarily at higgs so people can download it -->
  <!ENTITY rusti-download-http "&sources-anduin-http;/rust/rust-installer-&RUSTIDATE;.tar.xz">
  <!ENTITY rusti-md5sum        "8fb6c87f12d735b0a8bc1304d7640c69">
  <!ENTITY rusti-size          "18 KB">

  <!-- similarly, CARGOPREV is defined in packages.ent -->
  <!ENTITY cargoprev64-download-http "https://static.rust-lang.org/dist/cargo-&CARGOPREV;-x86_64-unknown-linux-gnu.tar.gz">
  <!ENTITY cargoprev64-md5sum  "ad2b513d591f35271f1041e2e04f484c">
  <!ENTITY cargoprev64-size    "4.4 MB">
  <!ENTITY cargoprev32-download-http "https://static.rust-lang.org/dist/cargo-&CARGOPREV;-i686-unknown-linux-gnu.tar.gz">
  <!ENTITY cargoprev32-md5sum  "24d4eda62991bfbaecb3a6d1e09df143">
  <!ENTITY cargoprev32-size    "4.3 MB">
]>

<sect1 id="cargo" xreflabel="cargo-&cargo-version;">
  <?dbhtml filename="cargo.html"?>

  <sect1info>
    <othername>$LastChangedBy$</othername>
    <date>$Date$</date>
  </sect1info>

  <title>Cargo-&cargo-version;</title>

  <indexterm zone="cargo">
    <primary sortas="a-cargo">Cargo</primary>
  </indexterm>

  <sect2 role="package">
    <title>Introduction to cargo</title>

    <para>
      <application>Cargo</application> is the Package Manager for
      <application>Rust</application>. Like that, during the build it uses
      <command>curl</command> to download <filename>cargo</filename> files
      which are actually <filename>.tar.gz</filename> source archives.
    </para>

    <para>
      This package requires internet access to build and at runtime (when
      <command>rust</command> is compiling another package). It will use all
      available cores. It also needs the current or previous version to compile
      itself, so here a binary of the previous version is used to bootstrap.
    </para>

    &lfs80_checked;

    <note><para><application>Firefox</application> will download a correctly
    named tarball, or you can download it via wget as:</para>

<screen><userinput>wget https://github.com/rust-lang/cargo/archive/&cargo-version;.tar.gz \
     -O cargo-&cargo-version;.tar.gz</userinput></screen>
    </note>

    <bridgehead renderas="sect3">Package Information</bridgehead>
    <itemizedlist spacing="compact">
      <listitem>
        <para>
          Download (HTTP): <ulink url="&cargo-download-http;"/>
        </para>
      </listitem>
      <listitem>
        <para>
          Download (FTP): <ulink url="&cargo-download-ftp;"/>
        </para>
      </listitem>
      <listitem>
        <para>
          Download MD5 sum: &cargo-md5sum;
        </para>
      </listitem>
      <listitem>
        <para>
          Download size: &cargo-size;
        </para>
      </listitem>
      <listitem>
        <para>
          Estimated disk space required: &cargo-buildsize;
        </para>
      </listitem>
      <listitem>
        <para>
          Estimated build time: &cargo-time;
        </para>
      </listitem>
    </itemizedlist>

    <bridgehead renderas="sect3">Additional Downloads</bridgehead>
    <itemizedlist spacing="compact">
      <listitem>
        <para>Rust Installer:
        <ulink url="&rusti-download-http;"/></para>
      </listitem>
      <listitem>
        <para>Installer MD5 sum: &rusti-md5sum;</para>
      </listitem>
      <listitem>
        <para>Installer size: &rusti-size;</para>
      </listitem>
    </itemizedlist>
    <itemizedlist spacing="compact">
      <listitem>
        <para>Binary download (x86_64):
        <ulink url="&cargoprev64-download-http;"/></para>
      </listitem>
      <listitem>
        <para>Binary x86_64 MD5 sum: &cargoprev64-md5sum;</para>
      </listitem>
      <listitem>
        <para>Binary x86_64 download size: &cargoprev64-size;</para>
      </listitem>
    </itemizedlist>
    <itemizedlist spacing="compact">
      <listitem>
        <para>Binary download (i686):
        <ulink url="&cargoprev32-download-http;"/></para>
      </listitem>
      <listitem>
        <para>Binary i686 MD5 sum: &cargoprev32-md5sum;</para>
      </listitem>
      <listitem>
        <para>Binary i686 download size: &cargoprev32-size;</para>
      </listitem>
    </itemizedlist>

    <bridgehead renderas="sect3">Cargo Dependencies</bridgehead>

    <bridgehead renderas="sect4">Required</bridgehead>
    <para role="required">
      <xref linkend="cmake"/>,
      <xref linkend="rust"/>
    </para>

    <bridgehead renderas="sect4">Optional</bridgehead>
    <para role="optional">
      <xref linkend="git"/>,
      <xref linkend="openssl"/>
    </para>

    <para condition="html" role="usernotes">
      User Notes: <ulink url="&blfs-wiki;/cargo"/>
    </para>
  </sect2>

  <sect2 role="installation">
    <title>Installation of cargo</title>

    <para>
      Install <application>cargo</application> by running the following
      commands:
    </para>

<screen><userinput>tar -xf ../../../rust-installer-&RUSTIDATE;.tar.xz \
    --strip-components=1 --directory src/rust-installer &amp;&amp;

case $(uname -m) in
    x86_64) tar -xf ../cargo-&CARGOPREV;-x86_64-unknown-linux-gnu.tar.gz
    ;;
    i686) tar -xf ../cargo-&CARGOPREV;-i686-unknown-linux-gnu.tar.gz
    ;;
esac                                                 &amp;&amp;

./configure --prefix=/usr                        \
            --sysconfdir=/etc                    \
            --docdir=/usr/share/doc/cargo-&cargo-version; \
            --cargo=./cargo-nightly*/cargo/bin/cargo &amp;&amp;
make</userinput></screen>

    <para>
      To test the results, issue: <command>CFG_DISABLE_CROSS_TESTS=1
      ./target/*-unknown-linux-gnu/release/cargo test</command>.
    </para>

    <para>
      Now, as the <systemitem class="username">root</systemitem> user:
    </para>

<screen role="root"><userinput>make install                                                  &amp;&amp;
mv -v /usr/etc/bash_completion.d/cargo /etc/bash_completion.d</userinput></screen>
  </sect2>

  <sect2 role="commands">
    <title>Command Explanations</title>

    <para>
      <command>tar -xf ../../../rust-installer-&RUSTIDATE;.tar.xz ...</command>:
      The rust-installer is needed, but not shipped with
      <application>cargo</application>, so BLFS provides a repackaged git
      snapshot.
    </para>

    <para>
      <parameter>--cargo=</parameter>: This points to the binary of the previous
      version, so that the package can be bootstrapped. When upgrading, or if
      rebuilding, it is possible to use the current installed version without
      this switch, but that takes longer and uses more space.
    </para>

    <para>
      <command>CFG_DISABLE_CROSS_TESTS=1 ...</command>: By default the tests
      will try to cover cross-builds for other architectures, but BLFS only
      installs <command>rust</command> for the host architecture. This switch
      also points to where cargo has been created, using a wildcard to match the
      one target-triple directory which has been created.
    </para>

    <para>
      <command>mv -v /usr/etc/bash_completion.d/cargo ...</command>: Cargo
      accepts the sysconfdir switch but does not respect it. This fixes up the
      misplaced file.
    </para>
  </sect2>

  <sect2 role="content">
    <title>Contents</title>

    <segmentedlist>
      <segtitle>Installed Program(s)</segtitle>
      <segtitle>Installed Librar(y,ies)</segtitle>
      <segtitle>Installed Director(y,ies)</segtitle>

      <seglistitem>
        <seg>
          cargo
        </seg>
        <seg>
          None
        </seg>
        <seg>
          /usr/share/doc/cargo-&cargo-version; and
          /usr/share/zsh/site-functions.
        </seg>
      </seglistitem>
    </segmentedlist>

    <variablelist>
      <bridgehead renderas="sect3">Short Descriptions</bridgehead>
      <?dbfo list-presentation="list"?>
      <?dbhtml list-presentation="table"?>

      <varlistentry id="cargo-prog">
        <term><command>cargo</command></term>
        <listitem>
          <para>
            is the Package Manager for Rust.
          </para>
          <indexterm zone="cargo cargo-prog">
            <primary sortas="b-cargo">cargo</primary>
          </indexterm>
        </listitem>
      </varlistentry>

    </variablelist>
  </sect2>
</sect1>