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,223 @@ 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_BUILD + Use the default do-build target. Default: yes + + + + CARGO_INSTALL + Use the default do-install target. Default: yes + + + + CARGO_TEST + Use the default do-test target. Default: yes + + + +
+ + + 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 make cargo-crates 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 clean makesum +===> Cleaning for tokei-7.0.2 +=> 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 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>