Index: head/en_US.ISO8859-1/books/porters-handbook/special/chapter.xml =================================================================== --- head/en_US.ISO8859-1/books/porters-handbook/special/chapter.xml +++ head/en_US.ISO8859-1/books/porters-handbook/special/chapter.xml @@ -815,6 +815,345 @@ env.Append and env.Replace. + + + Using <command>cargo</command> + + For ports that use Cargo, + define USES=cargo. + + + Variables the Users Can Define for + <command>cargo</command> Builds + + + + + Variable + Default + Description + + + + + + CARGO_CRATES + + List of crates the port depends on. Each entry + needs to have a format like + cratename-semver for example, + libc-0.2.40. Port maintainers can + generate this list from + Cargo.lock using + make cargo-crates. Manually + bumping crate versions is possible but be mindful of + transitive dependencies. + + + + CARGO_FEATURES + + List of application features to build (space + separated list). + + + + CARGO_CARGOTOML + ${WRKSRC}/Cargo.toml + The path to the Cargo.toml + to use. + + + + CARGO_CARGOLOCK + ${WRKSRC}/Cargo.lock + The path to the Cargo.lock + to use for make cargo-crates. It + is possible to specify more than one lock file when + necessary. + + + + CARGO_ENV + + A list of environment variables to pass to Cargo + similar to MAKE_ENV. + + + + RUSTFLAGS + + Flags to pass to the Rust compiler. + + + + CARGO_CONFIGURE + yes + Use the default + do-configure. + + + + CARGO_UPDATE_ARGS + + Extra arguments to pass to Cargo during the + configure phase. Valid arguments can be looked up + with cargo update --help. + + + + CARGO_BUILDDEP + yes + Add a build dependency on + lang/rust. + + + + CARGO_CARGO_BIN + ${LOCALBASE}/bin/cargo + Location of the cargo + binary. + + + + CARGO_BUILD + yes + Use the default + do-build. + + + + CARGO_BUILD_ARGS + + Extra arguments to pass to Cargo during the + build phase. Valid arguments can be looked up with + cargo build --help. + + + + CARGO_INSTALL + yes + Use the default + do-install. + + + + CARGO_INSTALL_ARGS + + Extra arguments to pass to Cargo during the + install phase. Valid arguments can be looked up with + cargo install --help. + + + + CARGO_TEST + yes + Use the default + do-test. + + + + CARGO_TEST_ARGS + + Extra arguments to pass to Cargo during the test + phase. Valid arguments can be looked up with + cargo test --help. + + + + CARGO_TARGET_DIR + ${WRKDIR}/target + Location of the cargo output directory. + + + + CARGO_DIST_SUBDIR + rust/crates + Directory relative to DISTDIR + where the crate distribution files will be + stored. + + + + CARGO_VENDOR_DIR + ${WRKSRC}/cargo-crates + Location of the vendor directory where + all crates will be extracted to. Try to keep this + under PATCH_WRKSRC, so that + patches can be applied easily. + + + + CARGO_USE_GITHUB + no + Enable fetching of crates locked to specific Git + commits on GitHub via GH_TUPLE. + This will try to patch both + Cargo.lock and + Cargo.toml 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. + + + + CARGO_GH_CARGOTOML + ${CARGO_CARGOTOML} + List of Cargo.toml that + will be patched when using + CARGO_USE_GITHUB. + + + +
+ + + Creating a Port for a Simple Rust Application + + Creating a Cargo based port is a three stage process. + First we need to provide a ports template that fetches the + application distribution file: + + 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> + + Generate an initial + distinfo: + + &prompt.user; make makesum +=> 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 + + Now the distribution file is ready to use and we can go + ahead and extract crate dependencies from the bundled + Cargo.lock: + + &prompt.user; make cargo-crates +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 \ + [...] + + The output of this command needs to be pasted directly + into the Makefile: + + 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> + + distinfo needs to be regenerated to + contain all the crate distribution files: + + &prompt.user; make makesum +=> 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/. +[...] + + The working directory currently only contains the + application sources we extracted as part of the + make cargo-crates step. Before + attempting to build the port the working directory + must be cleaned, so that the crate sources can be + extracted into CARGO_VENDOR_DIR: + + &prompt.user; make clean +===> Cleaning for tokei-7.0.2 + + 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. + + + + Enabling Additional Application Features + + Some applications define additional features in their + Cargo.toml. They can be compiled in + by setting CARGO_FEATURES in the + port. + + Here we enable Tokei's json and + yaml features: + + CARGO_FEATURES= json yaml + + + + Listing Crate Licenses + + Crates have their own licenses. It is important to + know what they are when adding a LICENSE + block to the port (see ). The + helper target + cargo-crates-licenses will try + to list all the licenses of all crates defined in + CARGO_CRATES. + + &prompt.user; make cargo-crates-licenses +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 +[...] + + + The license names + make cargo-crates-licenses 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 + . + + + Index: head/en_US.ISO8859-1/books/porters-handbook/uses/chapter.xml =================================================================== --- head/en_US.ISO8859-1/books/porters-handbook/uses/chapter.xml +++ head/en_US.ISO8859-1/books/porters-handbook/uses/chapter.xml @@ -236,6 +236,17 @@ dependencies. + + <literal>cargo</literal> + + Possible arguments: (none) + + 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 . + + <literal>charsetfix</literal>