From owner-svn-doc-head@freebsd.org Fri May 25 14:38:44 2018 Return-Path: Delivered-To: svn-doc-head@mailman.ysv.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mailman.ysv.freebsd.org (Postfix) with ESMTP id 33AE2EE3A84; Fri, 25 May 2018 14:38:44 +0000 (UTC) (envelope-from tobik@FreeBSD.org) Received: from mxrelay.nyi.freebsd.org (mxrelay.nyi.freebsd.org [IPv6:2610:1c1:1:606c::19:3]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (Client CN "mxrelay.nyi.freebsd.org", Issuer "Let's Encrypt Authority X3" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id CB51C8406C; Fri, 25 May 2018 14:38:43 +0000 (UTC) (envelope-from tobik@FreeBSD.org) Received: from repo.freebsd.org (repo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:0]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (Client did not present a certificate) by mxrelay.nyi.freebsd.org (Postfix) with ESMTPS id A842A22119; Fri, 25 May 2018 14:38:43 +0000 (UTC) (envelope-from tobik@FreeBSD.org) Received: from repo.freebsd.org ([127.0.1.37]) by repo.freebsd.org (8.15.2/8.15.2) with ESMTP id w4PEchM6038078; Fri, 25 May 2018 14:38:43 GMT (envelope-from tobik@FreeBSD.org) Received: (from tobik@localhost) by repo.freebsd.org (8.15.2/8.15.2/Submit) id w4PEchUU038076; Fri, 25 May 2018 14:38:43 GMT (envelope-from tobik@FreeBSD.org) Message-Id: <201805251438.w4PEchUU038076@repo.freebsd.org> X-Authentication-Warning: repo.freebsd.org: tobik set sender to tobik@FreeBSD.org using -f From: Tobias Kortkamp Date: Fri, 25 May 2018 14:38:43 +0000 (UTC) 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 X-SVN-Group: doc-head X-SVN-Commit-Author: tobik X-SVN-Commit-Paths: in head/en_US.ISO8859-1/books/porters-handbook: special uses X-SVN-Commit-Revision: 51721 X-SVN-Commit-Repository: doc MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-BeenThere: svn-doc-head@freebsd.org X-Mailman-Version: 2.1.26 Precedence: list List-Id: SVN commit messages for the doc tree for head List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Fri, 25 May 2018 14:38:44 -0000 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 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 + . + + + 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. + + <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>