Andrew Kloet <andrew@kloet.net> writes:

> 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.

Thanks for your contribution. It looks fine.

MODCARGO_CRATES_BUILDDEP is documented twice, but I will deal with it.

I should be able to commit it soon.

> 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:
-- 
Sebastien Marie