Crates.io | cargo-native-install |
lib.rs | cargo-native-install |
version | 0.3.0 |
source | src |
created_at | 2020-12-09 01:53:28.467643 |
updated_at | 2022-04-01 03:50:25.933978 |
description | Installs cargo targets in a manner similar to make install or cmake --install |
homepage | |
repository | https://github.com/chorman0773/cargo-native-install |
max_upload_size | |
id | 320983 |
size | 119,426 |
Cargo plugin to perform native installation of binary and library packages.
Changes to the described interface below are versioned according to the following policy
Semver Patch (except for 0.x
):
Semver Minor (including patches for 0.x
):
Changes to any behaviours recognized as reserved
run
targets, the list of directory environment variables passed to run
targets and cargo, changes to the directories which are used in subsitutions of installed_path
, whether directory substitutions are applied to install_dir
.Any changes to the exposed Command Line Interface.
Addition of a new key with a default to entries in the install-targets
array.
Semver Major (including 0.x
):
(Note: An up-to-date comprehensive document can be found in the manual page, or by cargo-native-install --help
)
Usage: cargo-native-install [options]...
Options:
--install
is not provided--build
and --build-only
is deprecated in favor of --config
and config.toml
, and using build scripts for configuring build-time installation directories.--build
and --build-only
is deprecated in favor of --config
and config.toml
, and using build scripts for configuring build-time installation directories.config.toml
.Environment:
By default, cargo-native-install
will look for a file name config.toml
in the working directory. The name and path to the file can be configured by specifying the --config
option, but the behaviour remains the same.
If a file exists, it will be parsed (as toml), and install directories will be read from the [dir]
object. Where the directories are present, these will override the default setting for that directory. Note that this will not affect directories specified by environment variables, or command line flags.
This mechanism is intended to replace the --build
and --build-only
flags, which could be used to build the project with the directories specified in the environment. Using config.toml, the package would need to provide a build script that parses the file and sets the appropriate environment variables.
Because the file specifies the default directories, and can be overriden by individual options and environment variables, this can be used to set a "sysroot", where the project is built using a standard prefix, and then installed into a different path, which can then be used with chroot, or to a mount point on a different partition.
All information used by cargo-native-install
is stored in the project's Cargo.toml
.
Each "target" for installation is specified by a key under [package.metadata.install-targets]
.
Each key is the name of a target.
Additionally, each binary and the library target (if any) is automatically an installation target for this program, unless the exclude field of the install-targets
subobject is corresponding to the target is set to true. This is only the case for library targets if the crate-type
field contains cdylib
or staticlib
. For these library targets, if both are present, the staticlib installation target is named <library-name>-staticlib
and the cdylib installation target is <library-name>-cdylib
. Installation candidates are not generated, but may be manually created for rlib
, dylib
, and proc-macro
libraries, by appending -<type>
to the library name.
If a key is specified, then it may have one of several fields, the defaults for each type of binary/library target are provided:
type
: May be one of "bin", "sbin", "library", "libexec", "shared", "include", "data", "doc", "man", "info", "sysconfig", or "run".
rlib
targets, and "shared" for cdylib targets and dylib
targets.privileged
: Do not install when --user-prefix
or --no-privileged
is specified (unless --privileged
is specified). Defaults to false
always.directory
: Create the target as a directory, and copy source files to it. Defaults to false
if not specified.install_dir
: The path to be installed into. Defaults to the installation directory for the type, unless the type is run
(note that no substitutions are performed on install_dir
)
bin
targets use bindir
which defaults to <exec_prefix>/bin
library
targets use libdir
which defaults to <exec_prefix>/lib
sbin
targets use sbindir
which defaults to <exec_prefix>/sbin
libexec
targets use libexecdir
which defaults to <exec_prefix>/lib
data
targets use datadir
which defaults to <datarootdir>
doc
targets use docdir
which defaults to <datarootdir>/doc/<package-name>
man
targets use mandir
which defaults to <datarootdir>/man
info
targets use infodir
which defaults to <datarootdir>/info
sysconfig
targets use sysconfdir
which defaults to <prefix>/etc
(which special cases for /opt/...
and /usr/...
prefixes).<>
, ${}
, or @@
, or any ASCII identifier that ends in dir
(case insensitive) is reserved for future releases.mode
: Sets the mode to install as, in a form acceptable to chmod(1)
(note: only guaranteed to be effective on unix platforms).
installed_path
: The path to the installed file. If it starts with the name of a install directory (like prefix, exec_prefix, or bindir), enclosed in either <>
, @@
or ${}
(as <prefix>
, @exec_prefix@
, or ${bindir}
), it will be replaced with that directory. Otherwise, if it's a relative path, it is resolved by the install_dir
. By default, this is the name of the target file.
dir
enclosed within <>
, @@
, or ${}
which is not substituted as above is reserved.target_file
: The file in the source directory, relative to Cargo.toml
. By default, this is the file built for this target by cargo. Must exist for non-generated targets that do not have directory
set.installed_aliases
: After installing the target, create a symbolic link to it with each of the given names.exclude
: If set, disable this target. If set, all other options are ignored.For run
targets, the target_file
must be an executable program. It is executed with no parameters, and in the install_dir
if explicitly specified (otherwise in the current directory).
An environment variable is set for each of the installation directories to the specified one, as absolute paths.
dir
is reserved for future use. Such variables may be expected by run
targets to be an absolute path name if defined, but such targets may make no further assumptions about the existance or content of such environment variables
Additionally, the verbose flag is passed into the program by setting the _VERBOSE
environment variable to 1
. Note that no requirement is specified that this environment variable be respected, or even meaningful to the program.All environment variables set for run
targets are also set when invoking cargo
for cargo-native-install --build
and --build-only
.
The meaning of exit codes from a run target are as follows:
0
: successful execution, no report, continue installing1
: Error execution, report error, installation fails.2
: Error execution, report error, continue installing (not fatal)10
: target skipped, report, continue installing20
: target skipped, no report, continue installingrun
targets should not return such a code.