Page MenuHomeFreeBSD
Files F151106670

D15471.id42796.diff
No OneTemporary
Actions

D15471.id42796.diff
View Options

Index: en_US.ISO8859-1/books/porters-handbook/special/chapter.xml
===================================================================
--- en_US.ISO8859-1/books/porters-handbook/special/chapter.xml
+++ en_US.ISO8859-1/books/porters-handbook/special/chapter.xml
@@ -815,6 +815,323 @@
<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>Means</entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry><varname>CARGO_CRATES</varname></entry>
+ <entry>List of crates the port depends on. Each entry
+ should have a format like <literal>cratename-semver</literal> e.g.
+ <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>List of application features to build (space separated list).</entry>
+ </row>
+
+ <row>
+ <entry><varname>CARGO_CARGOTOML</varname></entry>
+ <entry>The path to the <filename>Cargo.toml</filename> to use.
+ Default: <literal>${WRKSRC}/Cargo.toml</literal></entry>
+ </row>
+
+ <row>
+ <entry><varname>CARGO_CARGOLOCK</varname></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.
+ Default: <literal>${WRKSRC}/Cargo.lock</literal></entry>
+ </row>
+ <row>
+ <entry><varname>CARGO_ENV</varname></entry>
+ <entry>A list of environment variables to pass to Cargo similar
+ to MAKE_ENV.</entry>
+ </row>
+ <row>
+ <entry><varname>RUSTFLAGS</varname></entry>
+ <entry>Flags to pass to the Rust compiler.</entry>
+ </row>
+
+ <row>
+ <entry><varname>CARGO_CONFIGURE</varname></entry>
+ <entry>Use the default do-configure target. Default: yes</entry>
+ </row>
+
+ <row>
+ <entry><varname>CARGO_UPDATE_ARGS</varname></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>Add a build dependency on <literal>lang/rust</literal>.
+ Default: yes</entry>
+ </row>
+
+ <row>
+ <entry><varname>CARGO_CARGO_BIN</varname></entry>
+ <entry>Location of the <command>cargo</command> binary.
+ Default: <literal>${LOCALBASE}/bin/cargo</literal></entry>
+ </row>
+
+ <row>
+ <entry><varname>CARGO_BUILD</varname></entry>
+ <entry>Use the default do-build target. Default: yes</entry>
+ </row>
+
+ <row>
+ <entry><varname>CARGO_BUILD_ARGS</varname></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>Use the default do-install target. Default: yes</entry>
+ </row>
+
+ <row>
+ <entry><varname>CARGO_INSTALL_ARGS</varname></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>Use the default do-test target. Default: yes</entry>
+ </row>
+
+ <row>
+ <entry><varname>CARGO_TEST_ARGS</varname></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>Location of the cargo output directory. Default:
+ <literal>${WRKDIR}/target</literal></entry>
+ </row>
+
+ <row>
+ <entry><varname>CARGO_DIST_SUBDIR</varname></entry>
+ <entry>Directory relative to <varname>DISTDIR</varname> where
+ the crate distfiles will be stored. Default:
+ <filename>rust/crates</filename></entry>
+ </row>
+
+ <row>
+ <entry><varname>CARGO_VENDOR_DIR</varname></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. Default: <literal>${WRKSRC}/cargo-crates</literal></entry>
+ </row>
+
+ <row>
+ <entry><varname>CARGO_USE_GITHUB</varname></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.
+ It should be used with caution as transitive Git dependencies
+ are not resolved and patched correctly. Default:
+ <literal>no</literal></entry>
+ </row>
+
+ <row>
+ <entry><varname>CARGO_GH_CARGOTOML</varname></entry>
+ <entry>List of <filename>Cargo.toml</filename> that should be
+ patched when using <varname>CARGO_USE_GITHUB</varname>.
+ Default: <literal>${CARGO_CARGOTOML}</literal></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 distfile:
+ </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 &lt;bsd.port.mk&gt;</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 distfile is ready to use and we can go ahead and extract
+ crate dependencies from the bundled <filename>Cargo.lock</filename>
+ file:</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 &lt;bsd.port.mk&gt;</programlisting>
+
+ <para><filename>distinfo</filename> needs to be regenerated to
+ contain all the crate distfiles:</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>Tokei defines the following features in its
+ <filename>Cargo.toml</filename>:</para>
+
+ <programlisting>[features]
+all = ["json", "cbor", "toml-io", "yaml"]
+cbor = ["io", "hex", "serde_cbor"]
+default = []
+io = ["serde_derive", "serde"]
+json = ["io", "serde_json"]
+toml-io = ["io", "toml"]
+yaml = ["io", "serde_yaml"]</programlisting>
+
+ <para>To enable the <literal>json</literal> and <literal>yaml</literal>
+ features we can add this to our port:</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
+ <literal>cargo-crates-licenses</literal> 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">
Index: en_US.ISO8859-1/books/porters-handbook/uses/chapter.xml
===================================================================
--- en_US.ISO8859-1/books/porters-handbook/uses/chapter.xml
+++ en_US.ISO8859-1/books/porters-handbook/uses/chapter.xml
@@ -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>

File Metadata

Mime Type
text/plain
Expires
Tue, Apr 7, 2:57 AM (11 h, 26 m)
Storage Engine
blob
Storage Format
Raw Data
Storage Handle
31007478
Default Alt Text
D15471.id42796.diff (12 KB)

Event Timeline