Date: Fri, 25 May 2018 14:38:43 +0000 (UTC) From: Tobias Kortkamp <tobik@FreeBSD.org> To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r51721 - in head/en_US.ISO8859-1/books/porters-handbook: special uses Message-ID: <201805251438.w4PEchUU038076@repo.freebsd.org>
next in thread | raw e-mail | index | archive | help
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= 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 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>
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201805251438.w4PEchUU038076>