From: Andrew Kloet <andrew@kloet.net>
Subject: cargo-module: document more behaviour
To: tech@openbsd.org
Date: Sun, 10 May 2026 18:23:24 -0400

Hello tech@

While working on the net/arti port I had a need to modify the
MODCARGO_INSTALL_ARGS variable. I noticed that among this variable,
several others used in other ports are currently undocumented in
cargo-module(5).

The attached diff updates the manual to include these useful variables
and provides clarification on some previously undocumented behavior
within the module.

Feedback and comments welcome.

Andrew

diff --git a/share/man/man5/cargo-module.5 b/share/man/man5/cargo-module.5
index 8b3f973dca4..f1b8420becf 100644
--- a/share/man/man5/cargo-module.5
+++ b/share/man/man5/cargo-module.5
@@ -57,6 +57,17 @@ crates defined in
 are moved to the
 .Ev MODCARGO_VENDOR_DIR
 directory.
+If
+.Ev MODCARGO_CRATES_BUILDDEP
+is enabled,
+the module may modify vendored crates in order to prefer system libraries
+instead of bundled upstream copies.
+This affects several common
+.Dq -sys
+crates such as
+.Dq openssl-sys
+and
+.Dq libsqlite3-sys .
 .Pp
 During
 .Cm post-patch ,
@@ -89,6 +100,15 @@ is added to
 .Pp
 This module defines:
 .Bl -tag -width MODCARGO_INSTALL_TARGET_PATHS
+.It Ev MODCARGO_BUILD
+Whether to define the default
+.Cm do-build
+target.
+Defaults to
+.Sq Yes .
+.It Ev MODCARGO_BUILD_ARGS
+Additional arguments passed to
+.Cm cargo build .
 .It Ev MODCARGO_CARGOTOML
 Path to cargo manifest.
 Defaults to
@@ -103,16 +123,74 @@ Defaults to
 .Pa ${MODCARGO_CARGOTOML:toml=lock} .
 .It Ev MODCARGO_CRATES
 Crates that will be downloaded by the module.
+.It Ev MODCARGO_CRATES_BUILDDEP
+Whether to modify vendored crates in order to prefer system libraries over
+bundled upstream sources.
+Defaults to
+.Sq Yes .
+.It Ev MODCARGO_CRATES_KEEP
+List of crates that should not be modified during
+.Cm post-extract .
+Entries may be specified either as crate names or
+.Dq name-version .
 .It Ev MODCARGO_CRATES_UPDATE
 List of crates to update, overriding the version listed in Cargo.lock.
+.It Ev MODCARGO_DIST_SUBDIR
+Subdirectory used for crate distfiles.
+Defaults to
+.Sq cargo .
+If
+.Ev DIST_SUBDIR
+is defined,
+.Ev MODCARGO_DIST_SUBDIR
+must also be defined.
 .It Ev MODCARGO_FEATURES
 List of features to be used when building.
+.It Ev MODCARGO_INSTALL
+Whether to define the default
+.Cm do-install
+target.
+Defaults to
+.Sq Yes .
+.It Ev MODCARGO_INSTALL_ARGS
+Additional arguments passed to
+.Cm cargo install .
 .It Ev MODCARGO_INSTALL_TARGET_PATHS
 List of paths to pass to
 .Cm cargo install
 instead of
 .Pa \&. .
 Needs to be set for some virtual manifests.
+.It Ev MODCARGO_NO_DEFAULT_FEATURES
+If set to
+.Sq Yes ,
+pass
+.Cm --no-default-features
+to cargo commands.
+.It Ev MODCARGO_RUSTFLAGS
+Flags passed to all
+.Xr rustc 1
+invocations performed by
+.Xr cargo 1 .
+.It Ev MODCARGO_TARGET_DIR
+Location of cargo build artifacts.
+Defaults to
+.Pa ${WRKBUILD}/target .
+.It Ev MODCARGO_TEST
+Whether to define the default
+.Cm do-test
+target.
+Defaults to
+.Sq Yes .
+.It Ev MODCARGO_TEST_ARGS
+Additional arguments passed to
+.Cm cargo test .
+.It Ev MODCARGO_CARGO_BIN
+Path to the
+.Xr cargo 1
+binary.
+Defaults to the version provided by
+.Pa devel/cargo .
 .It Ev MODCARGO_VENDOR_DIR
 Name of the local directory for vendoring crates.
 Defaults to
@@ -126,6 +204,11 @@ It is a copy of
 provided for simplicity.
 .El
 .Pp
+The module creates a local cargo configuration in
+.Pa ${WRKDIR}/.cargo/config.toml
+which configures vendored sources, offline operation,
+Rust toolchain paths, and build profiles.
+.Pp
 This module adds three
 .Xr make 1
 targets: