Bug 266571 - Porter's Handbook: Using cargo: Use Makefile.crates instead of Makefile's CARGO_CRATES
Summary: Porter's Handbook: Using cargo: Use Makefile.crates instead of Makefile's CAR...
Status: Closed FIXED
Alias: None
Product: Documentation
Classification: Unclassified
Component: Books & Articles (show other bugs)
Version: Latest
Hardware: Any Any
: --- Affects Many People
Assignee: freebsd-doc (Nobody)
URL:
Keywords:
Depends on:
Blocks:
 
Reported: 2022-09-23 19:44 UTC by Nuno Teixeira
Modified: 2024-04-27 19:14 UTC (History)
2 users (show)

See Also:


Attachments

Note You need to log in before you can comment on or make changes to this bug.
Description Nuno Teixeira freebsd_committer freebsd_triage 2022-09-23 19:44:41 UTC
Hello,

For some time that Mk/Uses/cargo.mk (.sinclude "${MASTERDIR}/Makefile.crates") permits using Makefile.crates instead of Makefile to include list of cargo-crates. This feature has the advantage of having cleaner Makefile and easier updates with `make cargo-crates > Makefile.crates`.

For what I see, only a few maintainers know about this "hiden" ports framework feature.

What I propose is to change methodology of rust/cargo ports to include Makefile.crates.

As an example, we have Makefile PLIST_FILES against pkg-plist and it's very well explained:

"There is only one case when pkg-plist can be omitted from a port. If the port installs just a handful of files, list them in PLIST_FILES, within the port’s Makefile. (...)"

The same could be adapted to Makefile.crates (if/when methodology gets updated):

"There is only one case when Makefile.crates can be omitted from a port. If the port uses just a handful of cargo crates, list them in CARGO_CRATES, within the port’s Makefile. (...)"

Thanks
Comment 1 Daniel Engberg freebsd_committer freebsd_triage 2022-09-25 10:04:42 UTC
First step would be adding instructions to Porters Handbook otherwise we'll just create an endless loop of fixing added ports.

I'd suggest that you use Phabricator (reviews.freebsd.org) and loop in Rust as well as portmgr and docs ppl.
Comment 2 Tobias Kortkamp freebsd_committer freebsd_triage 2022-09-27 12:20:58 UTC
My 2 cents:

- Document Makefile.crates as a possible location but leave it up to
  the maintainer where to put CARGO_CRATES

- It should be documented explicitly that CARGO_CRATES in Makefile is fine
  too. Don't make this a review issue plz.

- Independent of where CARGO_CRATES is stored, updating it can be
  done automatically with cargo-crates-merge if portfmt is installed

I feel like you don't gain anything by declaring that CARGO_CRATES
must be in Makefile.crates instead of Makefile. What's needed is a
technical USES=cargo change along the lines of either

- keep current approach but seed most of CARGO_CRATES from distinfo
  (since we currently have duplication of the same information for
  normal crates). Then most ports won't need to set CARGO_CRATES
  explicitly anywhere.

- properly hook crates to the dependency graph as build inputs (as
  ports that do not create packages to allow reuse of their WRKSRC in
  USES=cargo via something like
  BUILD_DEPENDS=rust-crates.io-libc>0:devel/rust-crates.io-libc:patch).
  Basically adopt a similar approach like GNU Guix cargo-build-system
  with the extra bonus of removing most of the duplicated crate versions
  we currently have (how many libc crate version do we really need???) and
  will allow us to deal with the many vulnerable crates in the tree in a
  comprehensive way just like normal dependencies.
Comment 3 Tobias Kortkamp freebsd_committer freebsd_triage 2022-09-27 14:18:42 UTC
(In reply to Tobias Kortkamp from comment #2)
FWIW, branch with cargo.mk that seeds CARGO_CRATES from distinfo:
https://codeberg.org/tobik/freebsd-ports/commits/branch/no-CARGO_CRATES
Comment 4 Nuno Teixeira freebsd_committer freebsd_triage 2024-04-27 19:14:39 UTC
Hello all,

Just noticed that Makefile.crates was added to Porter's Handbook:
https://docs.freebsd.org/en/books/porters-handbook/book/#using-cargo

Thanks