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 @@ 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 + Means + + + + + + CARGO_CRATES + List of crates the port depends on. Each entry + should have a format like cratename-semver e.g. + 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 + The path to the Cargo.toml to use. + Default: ${WRKSRC}/Cargo.toml + + + + CARGO_CARGOLOCK + The path to the Cargo.lock to use for + make cargo-crates. It is possible to specify + more than one lock file when necessary. + Default: ${WRKSRC}/Cargo.lock + + + 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 + Use the default do-configure target. Default: yes + + + + 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 + Add a build dependency on lang/rust. + Default: yes + + + + CARGO_CARGO_BIN + Location of the cargo binary. + Default: ${LOCALBASE}/bin/cargo + + + + CARGO_BUILD + Use the default do-build target. Default: yes + + + + 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 + Use the default do-install target. Default: yes + + + + 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 + Use the default do-test target. Default: yes + + + + 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 + Location of the cargo output directory. Default: + ${WRKDIR}/target + + + + CARGO_DIST_SUBDIR + Directory relative to DISTDIR where + the crate distfiles will be stored. Default: + rust/crates + + + + CARGO_VENDOR_DIR + 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. Default: ${WRKSRC}/cargo-crates + + + + CARGO_USE_GITHUB + 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. + It should be used with caution as transitive Git dependencies + are not resolved and patched correctly. Default: + no + + + + CARGO_GH_CARGOTOML + List of Cargo.toml that should be + patched when using CARGO_USE_GITHUB. + Default: ${CARGO_CARGOTOML} + + + +
+ + + 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 distfile: + + + 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 distfile is ready to use and we can go ahead and extract + crate dependencies from the bundled Cargo.lock + file: + + &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 distfiles: + + &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. + + + Tokei defines the following features in its + Cargo.toml: + + [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"] + + To enable the json and yaml + features we can add this to our port: + + 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: 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. + + <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>