Document USES=cargo in the Porter's Handbook
PR: 227585 Submitted by: tobik Reported by: 0mp Reviewed by: mat, 0mp Approved by: mat Differential Revision: https://reviews.freebsd.org/D15471
This commit is contained in:
Tobias Kortkamp
parent
6e3972e5df
commit
ba059a8d54
Notes:
svn2git
2020-12-08 03:00:23 +00:00
svn path=/head/; revision=51721
2 changed files with 350 additions and 0 deletions
|
|
@ -815,6 +815,345 @@ CMAKE_OFF= VAR3</programlisting>
|
||||||
<literal>env.Append</literal> and
|
<literal>env.Append</literal> and
|
||||||
<literal>env.Replace</literal>.</para>
|
<literal>env.Replace</literal>.</para>
|
||||||
</sect2>
|
</sect2>
|
||||||
|
|
||||||
|
<sect2 xml:id="using-cargo">
|
||||||
|
<title>Using <command>cargo</command></title>
|
||||||
|
|
||||||
|
<para>For ports that use <application>Cargo</application>,
|
||||||
|
define <literal>USES=cargo</literal>.</para>
|
||||||
|
|
||||||
|
<table frame="none" xml:id="using-cargo-user-variables">
|
||||||
|
<title>Variables the Users Can Define for
|
||||||
|
<command>cargo</command> Builds</title>
|
||||||
|
|
||||||
|
<tgroup cols="2">
|
||||||
|
<thead>
|
||||||
|
<row>
|
||||||
|
<entry>Variable</entry>
|
||||||
|
<entry>Default</entry>
|
||||||
|
<entry>Description</entry>
|
||||||
|
</row>
|
||||||
|
</thead>
|
||||||
|
|
||||||
|
<tbody>
|
||||||
|
<row>
|
||||||
|
<entry><varname>CARGO_CRATES</varname></entry>
|
||||||
|
<entry></entry>
|
||||||
|
<entry>List of crates the port depends on. Each entry
|
||||||
|
needs to have a format like
|
||||||
|
<literal>cratename-semver</literal> for example,
|
||||||
|
<literal>libc-0.2.40</literal>. Port maintainers can
|
||||||
|
generate this list from
|
||||||
|
<filename>Cargo.lock</filename> using
|
||||||
|
<command>make cargo-crates</command>. Manually
|
||||||
|
bumping crate versions is possible but be mindful of
|
||||||
|
transitive dependencies.</entry>
|
||||||
|
</row>
|
||||||
|
|
||||||
|
<row>
|
||||||
|
<entry><varname>CARGO_FEATURES</varname></entry>
|
||||||
|
<entry></entry>
|
||||||
|
<entry>List of application features to build (space
|
||||||
|
separated list).</entry>
|
||||||
|
</row>
|
||||||
|
|
||||||
|
<row>
|
||||||
|
<entry><varname>CARGO_CARGOTOML</varname></entry>
|
||||||
|
<entry><literal>${WRKSRC}/Cargo.toml</literal></entry>
|
||||||
|
<entry>The path to the <filename>Cargo.toml</filename>
|
||||||
|
to use.</entry>
|
||||||
|
</row>
|
||||||
|
|
||||||
|
<row>
|
||||||
|
<entry><varname>CARGO_CARGOLOCK</varname></entry>
|
||||||
|
<entry><literal>${WRKSRC}/Cargo.lock</literal></entry>
|
||||||
|
<entry>The path to the <filename>Cargo.lock</filename>
|
||||||
|
to use for <command>make cargo-crates</command>. It
|
||||||
|
is possible to specify more than one lock file when
|
||||||
|
necessary.</entry>
|
||||||
|
</row>
|
||||||
|
|
||||||
|
<row>
|
||||||
|
<entry><varname>CARGO_ENV</varname></entry>
|
||||||
|
<entry></entry>
|
||||||
|
<entry>A list of environment variables to pass to Cargo
|
||||||
|
similar to <varname>MAKE_ENV</varname>.</entry>
|
||||||
|
</row>
|
||||||
|
|
||||||
|
<row>
|
||||||
|
<entry><varname>RUSTFLAGS</varname></entry>
|
||||||
|
<entry></entry>
|
||||||
|
<entry>Flags to pass to the Rust compiler.</entry>
|
||||||
|
</row>
|
||||||
|
|
||||||
|
<row>
|
||||||
|
<entry><varname>CARGO_CONFIGURE</varname></entry>
|
||||||
|
<entry><literal>yes</literal></entry>
|
||||||
|
<entry>Use the default
|
||||||
|
<buildtarget>do-configure</buildtarget>.</entry>
|
||||||
|
</row>
|
||||||
|
|
||||||
|
<row>
|
||||||
|
<entry><varname>CARGO_UPDATE_ARGS</varname></entry>
|
||||||
|
<entry></entry>
|
||||||
|
<entry>Extra arguments to pass to Cargo during the
|
||||||
|
configure phase. Valid arguments can be looked up
|
||||||
|
with <command>cargo update --help</command>.</entry>
|
||||||
|
</row>
|
||||||
|
|
||||||
|
<row>
|
||||||
|
<entry><varname>CARGO_BUILDDEP</varname></entry>
|
||||||
|
<entry><literal>yes</literal></entry>
|
||||||
|
<entry>Add a build dependency on
|
||||||
|
<package role="port">lang/rust</package>.</entry>
|
||||||
|
</row>
|
||||||
|
|
||||||
|
<row>
|
||||||
|
<entry><varname>CARGO_CARGO_BIN</varname></entry>
|
||||||
|
<entry><literal>${LOCALBASE}/bin/cargo</literal></entry>
|
||||||
|
<entry>Location of the <command>cargo</command>
|
||||||
|
binary.</entry>
|
||||||
|
</row>
|
||||||
|
|
||||||
|
<row>
|
||||||
|
<entry><varname>CARGO_BUILD</varname></entry>
|
||||||
|
<entry><literal>yes</literal></entry>
|
||||||
|
<entry>Use the default
|
||||||
|
<buildtarget>do-build</buildtarget>.</entry>
|
||||||
|
</row>
|
||||||
|
|
||||||
|
<row>
|
||||||
|
<entry><varname>CARGO_BUILD_ARGS</varname></entry>
|
||||||
|
<entry></entry>
|
||||||
|
<entry>Extra arguments to pass to Cargo during the
|
||||||
|
build phase. Valid arguments can be looked up with
|
||||||
|
<command>cargo build --help</command>.</entry>
|
||||||
|
</row>
|
||||||
|
|
||||||
|
<row>
|
||||||
|
<entry><varname>CARGO_INSTALL</varname></entry>
|
||||||
|
<entry><literal>yes</literal></entry>
|
||||||
|
<entry>Use the default
|
||||||
|
<buildtarget>do-install</buildtarget>.</entry>
|
||||||
|
</row>
|
||||||
|
|
||||||
|
<row>
|
||||||
|
<entry><varname>CARGO_INSTALL_ARGS</varname></entry>
|
||||||
|
<entry></entry>
|
||||||
|
<entry>Extra arguments to pass to Cargo during the
|
||||||
|
install phase. Valid arguments can be looked up with
|
||||||
|
<command>cargo install --help</command>.</entry>
|
||||||
|
</row>
|
||||||
|
|
||||||
|
<row>
|
||||||
|
<entry><varname>CARGO_TEST</varname></entry>
|
||||||
|
<entry><literal>yes</literal></entry>
|
||||||
|
<entry>Use the default
|
||||||
|
<buildtarget>do-test</buildtarget>.</entry>
|
||||||
|
</row>
|
||||||
|
|
||||||
|
<row>
|
||||||
|
<entry><varname>CARGO_TEST_ARGS</varname></entry>
|
||||||
|
<entry></entry>
|
||||||
|
<entry>Extra arguments to pass to Cargo during the test
|
||||||
|
phase. Valid arguments can be looked up with
|
||||||
|
<command>cargo test --help</command>.</entry>
|
||||||
|
</row>
|
||||||
|
|
||||||
|
<row>
|
||||||
|
<entry><varname>CARGO_TARGET_DIR</varname></entry>
|
||||||
|
<entry><literal>${WRKDIR}/target</literal></entry>
|
||||||
|
<entry>Location of the cargo output directory.</entry>
|
||||||
|
</row>
|
||||||
|
|
||||||
|
<row>
|
||||||
|
<entry><varname>CARGO_DIST_SUBDIR</varname></entry>
|
||||||
|
<entry><filename>rust/crates</filename></entry>
|
||||||
|
<entry>Directory relative to <varname>DISTDIR</varname>
|
||||||
|
where the crate distribution files will be
|
||||||
|
stored.</entry>
|
||||||
|
</row>
|
||||||
|
|
||||||
|
<row>
|
||||||
|
<entry><varname>CARGO_VENDOR_DIR</varname></entry>
|
||||||
|
<entry><literal>${WRKSRC}/cargo-crates</literal></entry>
|
||||||
|
<entry>Location of the vendor directory where
|
||||||
|
all crates will be extracted to. Try to keep this
|
||||||
|
under <varname>PATCH_WRKSRC</varname>, so that
|
||||||
|
patches can be applied easily.</entry>
|
||||||
|
</row>
|
||||||
|
|
||||||
|
<row>
|
||||||
|
<entry><varname>CARGO_USE_GITHUB</varname></entry>
|
||||||
|
<entry><literal>no</literal></entry>
|
||||||
|
<entry>Enable fetching of crates locked to specific Git
|
||||||
|
commits on GitHub via <varname>GH_TUPLE</varname>.
|
||||||
|
This will try to patch both
|
||||||
|
<filename>Cargo.lock</filename> and
|
||||||
|
<filename>Cargo.toml</filename> to point to the
|
||||||
|
offline sources instead of fetching them from a
|
||||||
|
Git repository during the build. Use with caution
|
||||||
|
as transitive Git dependencies are not resolved and
|
||||||
|
patched correctly.</entry>
|
||||||
|
</row>
|
||||||
|
|
||||||
|
<row>
|
||||||
|
<entry><varname>CARGO_GH_CARGOTOML</varname></entry>
|
||||||
|
<entry><literal>${CARGO_CARGOTOML}</literal></entry>
|
||||||
|
<entry>List of <filename>Cargo.toml</filename> that
|
||||||
|
will be patched when using
|
||||||
|
<varname>CARGO_USE_GITHUB</varname>.</entry>
|
||||||
|
</row>
|
||||||
|
</tbody>
|
||||||
|
</tgroup>
|
||||||
|
</table>
|
||||||
|
|
||||||
|
<example xml:id="cargo-ex1">
|
||||||
|
<title>Creating a Port for a Simple Rust Application</title>
|
||||||
|
|
||||||
|
<para>Creating a Cargo based port is a three stage process.
|
||||||
|
First we need to provide a ports template that fetches the
|
||||||
|
application distribution file:</para>
|
||||||
|
|
||||||
|
<programlisting>PORTNAME= tokei
|
||||||
|
DISTVERSIONPREFIX= v
|
||||||
|
DISTVERSION= 7.0.2
|
||||||
|
CATEGORIES= devel
|
||||||
|
|
||||||
|
MAINTAINER= tobik@FreeBSD.org
|
||||||
|
COMMENT= Display statistics about your code
|
||||||
|
|
||||||
|
USES= cargo
|
||||||
|
USE_GITHUB= yes
|
||||||
|
GH_ACCOUNT= Aaronepower
|
||||||
|
|
||||||
|
.include <bsd.port.mk></programlisting>
|
||||||
|
|
||||||
|
<para>Generate an initial
|
||||||
|
<filename>distinfo</filename>:</para>
|
||||||
|
|
||||||
|
<screen>&prompt.user; <userinput>make makesum</userinput>
|
||||||
|
=> Aaronepower-tokei-v7.0.2_GH0.tar.gz doesn't seem to exist in /usr/ports/distfiles/.
|
||||||
|
=> Attempting to fetch https://codeload.github.com/Aaronepower/tokei/tar.gz/v7.0.2?dummy=/Aaronepower-tokei-v7.0.2_GH0.tar.gz
|
||||||
|
fetch: https://codeload.github.com/Aaronepower/tokei/tar.gz/v7.0.2?dummy=/Aaronepower-tokei-v7.0.2_GH0.tar.gz: size of remote file is not known
|
||||||
|
Aaronepower-tokei-v7.0.2_GH0.tar.gz 45 kB 239 kBps 00m00s</screen>
|
||||||
|
|
||||||
|
<para>Now the distribution file is ready to use and we can go
|
||||||
|
ahead and extract crate dependencies from the bundled
|
||||||
|
<filename>Cargo.lock</filename>:</para>
|
||||||
|
|
||||||
|
<screen>&prompt.user; <userinput>make cargo-crates</userinput>
|
||||||
|
CARGO_CRATES= aho-corasick-0.6.4 \
|
||||||
|
ansi_term-0.11.0 \
|
||||||
|
arrayvec-0.4.7 \
|
||||||
|
atty-0.2.9 \
|
||||||
|
bitflags-1.0.1 \
|
||||||
|
byteorder-1.2.2 \
|
||||||
|
[...]</screen>
|
||||||
|
|
||||||
|
<para>The output of this command needs to be pasted directly
|
||||||
|
into the Makefile:</para>
|
||||||
|
|
||||||
|
<programlisting>PORTNAME= tokei
|
||||||
|
DISTVERSIONPREFIX= v
|
||||||
|
DISTVERSION= 7.0.2
|
||||||
|
CATEGORIES= devel
|
||||||
|
|
||||||
|
MAINTAINER= tobik@FreeBSD.org
|
||||||
|
COMMENT= Display statistics about your code
|
||||||
|
|
||||||
|
USES= cargo
|
||||||
|
USE_GITHUB= yes
|
||||||
|
GH_ACCOUNT= Aaronepower
|
||||||
|
|
||||||
|
CARGO_CRATES= aho-corasick-0.6.4 \
|
||||||
|
ansi_term-0.11.0 \
|
||||||
|
arrayvec-0.4.7 \
|
||||||
|
atty-0.2.9 \
|
||||||
|
bitflags-1.0.1 \
|
||||||
|
byteorder-1.2.2 \
|
||||||
|
[...]
|
||||||
|
|
||||||
|
.include <bsd.port.mk></programlisting>
|
||||||
|
|
||||||
|
<para><filename>distinfo</filename> needs to be regenerated to
|
||||||
|
contain all the crate distribution files:</para>
|
||||||
|
|
||||||
|
<screen>&prompt.user; <userinput>make makesum</userinput>
|
||||||
|
=> rust/crates/aho-corasick-0.6.4.tar.gz doesn't seem to exist in /usr/ports/distfiles/.
|
||||||
|
=> Attempting to fetch https://crates.io/api/v1/crates/aho-corasick/0.6.4/download?dummy=/rust/crates/aho-corasick-0.6.4.tar.gz
|
||||||
|
rust/crates/aho-corasick-0.6.4.tar.gz 100% of 24 kB 6139 kBps 00m00s
|
||||||
|
=> rust/crates/ansi_term-0.11.0.tar.gz doesn't seem to exist in /usr/ports/distfiles/.
|
||||||
|
=> Attempting to fetch https://crates.io/api/v1/crates/ansi_term/0.11.0/download?dummy=/rust/crates/ansi_term-0.11.0.tar.gz
|
||||||
|
rust/crates/ansi_term-0.11.0.tar.gz 100% of 16 kB 21 MBps 00m00s
|
||||||
|
=> rust/crates/arrayvec-0.4.7.tar.gz doesn't seem to exist in /usr/ports/distfiles/.
|
||||||
|
=> Attempting to fetch https://crates.io/api/v1/crates/arrayvec/0.4.7/download?dummy=/rust/crates/arrayvec-0.4.7.tar.gz
|
||||||
|
rust/crates/arrayvec-0.4.7.tar.gz 100% of 22 kB 3237 kBps 00m00s
|
||||||
|
=> rust/crates/atty-0.2.9.tar.gz doesn't seem to exist in /usr/ports/distfiles/.
|
||||||
|
=> Attempting to fetch https://crates.io/api/v1/crates/atty/0.2.9/download?dummy=/rust/crates/atty-0.2.9.tar.gz
|
||||||
|
rust/crates/atty-0.2.9.tar.gz 100% of 5898 B 81 MBps 00m00s
|
||||||
|
=> rust/crates/bitflags-1.0.1.tar.gz doesn't seem to exist in /usr/ports/distfiles/.
|
||||||
|
[...]</screen>
|
||||||
|
|
||||||
|
<para>The working directory currently only contains the
|
||||||
|
application sources we extracted as part of the
|
||||||
|
<command>make cargo-crates</command> step. Before
|
||||||
|
attempting to build the port the working directory
|
||||||
|
must be cleaned, so that the crate sources can be
|
||||||
|
extracted into <varname>CARGO_VENDOR_DIR</varname>:</para>
|
||||||
|
|
||||||
|
<screen>&prompt.user; <userinput>make clean</userinput>
|
||||||
|
===> Cleaning for tokei-7.0.2</screen>
|
||||||
|
|
||||||
|
<para>The port is now ready for a test build and further
|
||||||
|
adjustments like creating a plist, writing a description,
|
||||||
|
adding license information, options, etc. as normal.</para>
|
||||||
|
</example>
|
||||||
|
|
||||||
|
<example xml:id="cargo-ex2">
|
||||||
|
<title>Enabling Additional Application Features</title>
|
||||||
|
|
||||||
|
<para>Some applications define additional features in their
|
||||||
|
<filename>Cargo.toml</filename>. They can be compiled in
|
||||||
|
by setting <varname>CARGO_FEATURES</varname> in the
|
||||||
|
port.</para>
|
||||||
|
|
||||||
|
<para>Here we enable Tokei's <literal>json</literal> and
|
||||||
|
<literal>yaml</literal> features:</para>
|
||||||
|
|
||||||
|
<programlisting>CARGO_FEATURES= json yaml</programlisting>
|
||||||
|
</example>
|
||||||
|
|
||||||
|
<example xml:id="cargo-ex3">
|
||||||
|
<title>Listing Crate Licenses</title>
|
||||||
|
|
||||||
|
<para>Crates have their own licenses. It is important to
|
||||||
|
know what they are when adding a <varname>LICENSE</varname>
|
||||||
|
block to the port (see <xref linkend="licenses" />). The
|
||||||
|
helper target
|
||||||
|
<buildtarget>cargo-crates-licenses</buildtarget> will try
|
||||||
|
to list all the licenses of all crates defined in
|
||||||
|
<varname>CARGO_CRATES</varname>.</para>
|
||||||
|
|
||||||
|
<screen>&prompt.user; <userinput>make cargo-crates-licenses</userinput>
|
||||||
|
aho-corasick-0.6.4 Unlicense/MIT
|
||||||
|
ansi_term-0.11.0 MIT
|
||||||
|
arrayvec-0.4.7 MIT/Apache-2.0
|
||||||
|
atty-0.2.9 MIT
|
||||||
|
bitflags-1.0.1 MIT/Apache-2.0
|
||||||
|
byteorder-1.2.2 Unlicense/MIT
|
||||||
|
[...]</screen>
|
||||||
|
|
||||||
|
<note>
|
||||||
|
<para>The license names
|
||||||
|
<command>make cargo-crates-licenses</command> outputs are
|
||||||
|
SPDX 2.1 licenses expression which do not match the
|
||||||
|
license names defined in the ports framework. They need
|
||||||
|
to be translated to the names from
|
||||||
|
<xref linkend="licenses-license-list" />.</para>
|
||||||
|
</note>
|
||||||
|
</example>
|
||||||
|
</sect2>
|
||||||
</sect1>
|
</sect1>
|
||||||
|
|
||||||
<sect1 xml:id="using-autotools">
|
<sect1 xml:id="using-autotools">
|
||||||
|
|
|
||||||
|
|
@ -236,6 +236,17 @@
|
||||||
dependencies.</para>
|
dependencies.</para>
|
||||||
</sect1>
|
</sect1>
|
||||||
|
|
||||||
|
<sect1 xml:id="uses-cargo">
|
||||||
|
<title><literal>cargo</literal></title>
|
||||||
|
|
||||||
|
<para>Possible arguments: (none)</para>
|
||||||
|
|
||||||
|
<para>Uses Cargo for configuring, building, and testing.
|
||||||
|
It can be used to port Rust applications that use the Cargo
|
||||||
|
build system. For more information see <xref
|
||||||
|
linkend="using-cargo" />.</para>
|
||||||
|
</sect1>
|
||||||
|
|
||||||
<sect1 xml:id="uses-charsetfix">
|
<sect1 xml:id="uses-charsetfix">
|
||||||
<title><literal>charsetfix</literal></title>
|
<title><literal>charsetfix</literal></title>
|
||||||
|
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue