svn commit: r51721 - in head/en_US.ISO8859-1/books/porters-handbook: special uses
Tobias Kortkamp <[email protected]>
| Newsgroups | gmane.os.freebsd.devel.cvs.doc |
|---|---|
| Message-ID | <[email protected]> |
Author: tobik (ports committer)
Date: Fri May 25 14:38:42 2018
New Revision: 51721
URL: https://svnweb.freebsd.org/changeset/doc/51721
Log:
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
Modified:
head/en_US.ISO8859-1/books/porters-handbook/special/chapter.xml
head/en_US.ISO8859-1/books/porters-handbook/uses/chapter.xml
Modified: head/en_US.ISO8859-1/books/porters-handbook/special/chapter.xml
==============================================================================
--- head/en_US.ISO8859-1/books/porters-handbook/special/chapter.xml Fri May 25 00:02:11 2018 (r51720)
+++ head/en_US.ISO8859-1/books/porters-handbook/special/chapter.xml Fri May 25 14:38:42 2018 (r51721)
@@ -815,6 +815,345 @@ CMAKE_OFF= VAR3</programlisting>
<literal>env.Append</literal> and
<literal>env.Replace</literal>.</para>
</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= [email protected]
+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= [email protected]
+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 xml:id="using-autotools">
Modified: head/en_US.ISO8859-1/books/porters-handbook/uses/chapter.xml
==============================================================================
--- head/en_US.ISO8859-1/books/porters-handbook/uses/chapter.xml Fri May 25 00:02:11 2018 (r51720)
+++ head/en_US.ISO8859-1/books/porters-handbook/uses/chapter.xml Fri May 25 14:38:42 2018 (r51721)
@@ -236,6 +236,17 @@
dependencies.</para>
</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">
<title><literal>charsetfix</literal></title>
_______________________________________________
[email protected] mailing list
https://lists.freebsd.org/mailman/listinfo/svn-doc-all
To unsubscribe, send any mail to "[email protected]"