cargo-native-install

Cargo 插件，用于执行二进制和库包的原生安装。

版本策略

以下描述的接口更改根据以下策略进行版本控制

Semver 补丁（除了 0.x）

• 错误修复、安全更新

Semver 小版本（包括 0.x 的补丁）

• 对任何已识别为保留的行为的更改
  • 这包括：未提及的 run 目标的返回码的行为，传递给 run 目标和 cargo 的目录环境变量列表，用于 installed_path 替换的目录的更改，目录替换是否应用于 install_dir。
• 任何对暴露的命令行界面的更改。
• 向 install-targets 数组添加一个新键，并设置默认值。

Semver 主版本（包括 0.x）

• 在“格式”部分下定义的任何指定行为的更改，除非指定为保留。

命令行界面

（注意：最新的完整文档可以在手册页中找到，或者通过 cargo-native-install --help 查找）

用法：cargo-native-install [选项]...

• 将当前 cargo 项目安装到本地系统目录中（类似于 GNU make install 或 cmake --install）

选项

• --help: 打印此信息，并退出
• --version: 打印版本信息，并退出
• --dry-run: 显示每个安装操作的输出结果，但不执行任何操作
• --user-prefix: 默认前缀为 ~/.local，而不是系统目录
• --prefix=: 设置安装操作的前缀
• --bindir=dir: 将 dir 作为安装二进制程序的目录。可以是绝对路径，也可以是相对于前缀的路径。（默认为 bin）
• --libdir=dir: 将 dir 作为安装库的目录。可以是绝对路径，也可以是相对于前缀的路径（默认为 lib）
• --sbindir=dir：使用dir作为安装系统管理员程序的目录。可以是绝对路径，也可以是相对于prefix的路径（默认为sbin）
• --libexecdir=dir：使用dir作为安装不是直接从shell使用的程序的目录。可以是绝对路径，也可以是相对于prefix的路径（默认为libexec）
• --includedir=dir：使用dir作为安装头文件的目录。可以是绝对路径，也可以是相对于prefix的路径（默认为include）
• --datarootdir=dir：使用dir作为平台无关数据的、文档和手册的前缀。可以是绝对路径，也可以是相对于prefix的路径（默认为share）
• --datadir=dir：使用dir作为安装平台无关数据的目录。可以是绝对路径，也可以是相对于数据根的路径（默认与数据根相同）
• --mandir=dir：使用dir作为安装手册页的目录。可以是绝对路径，也可以是相对于数据根的路径（默认为man）
• --infodir=dir：使用dir作为安装info页的目录。可以是绝对路径，也可以是相对于数据根的路径（默认为info）
• --docdir=dir：使用dir作为安装项目文档的目录。可以是绝对路径，也可以是相对于数据根的路径（默认为doc）
• --localedir=dir：使用dir作为安装特定地区信息的目录。可以是绝对路径，也可以是相对于数据根的路径（默认为locale）
• --sysconfdir=dir：使用dir作为系统配置文件的目录。可以是绝对路径，也可以是相对于prefix的路径（默认为etc）
• --localstatedir=dir：使用dir作为本地系统状态的目录。可以是绝对路径，也可以是相对于prefix的路径（默认为var）
• --sharedstatedir=dir：使用dir作为共享系统状态的目录。可以是绝对路径，也可以是相对于prefix的路径（默认为com）
• --manifiest-dir=dir：指示cargo清单的目录。
• --no-strip：即使找到strip也不对程序进行strip
• --without-strip：与--no-strip相同
• --strip=：使用strip，而不是默认值（strip）
• --install=：使用install安装程序，而不是默认值（install）
• --internal-install：不调用任何程序进行安装。而是直接复制文件。如果未找到install，并且没有提供--install，则为默认值
• --mode=：强制安装的文件使用chmod *mode的形式（如果文件是二进制目标或目录，则X是可执行位）
• --no-create：不创建安装目录。也不会创建任何前缀目录
• --verbose：打印每个操作的提示信息
• --force：安装所有文件，即使这会替换较新的文件
• --no-privileged：不安装特权二进制文件（安装到sbin的文件）
• --privileged：将特权二进制文件安装到sbindir，即使使用了用户特定的前缀
• --target=target：只安装此目标
• --no-libexec：将libexec目标安装到bin而不是libexec
• --no-sbin：将sbin目标安装到bin而不是sbin（注意，这不会启用特权二进制文件）
• --arch-prefix[=target]：将bin、lib、include、libexec、sbin目标安装到特定架构的前缀。
• --build：在安装之前构建软件包。在构建过程中设置对应每个目录的环境变量。使用--build和--build-only已弃用，建议使用--config和config.toml，以及使用构建脚本配置构建时安装目录。
• –build-only：仅构建包而不安装。类似于–build，环境变量将设置所有目录。使用--build和--build-only已被弃用，转而使用--config和config.toml，以及使用构建脚本配置构建时安装目录。
• –shared=lib：默认将cdylib目标视为库目标并安装到libdir。这在类Unix目标上是默认的
• –shared=bin：默认将cdylib目标视为二进制目标并安装到bindir。在Windows上是默认的
• –out-dir=dir：将cargo目标存储在dir而不是manifest-dir/target
• –release：将cargo目标视为已以发布模式构建（默认）
• –debug：将cargo目标视为已以调试模式构建
• –config=file：如果file存在，则从该路径读取默认安装目录，而不是config.toml。

环境

• prefix：安装目录可以指定为环境变量，也可以使用选项。如果环境变量和CLI选项都存在，则选项具有优先权
• exec_prefix：类似于prefix。
• bindir：类似于prefix。
• libdir：类似于prefix。
• sbindir：类似于prefix。
• libexecdir：类似于prefix。
• includedir：类似于prefix。
• datarootdir：类似于prefix。
• datadir：类似于prefix。
• docdir：类似于prefix。
• mandir：类似于prefix。
• infodir：类似于prefix。
• localedir：类似于prefix。
• localstatedir：类似于prefix。
• sharedstatedir：类似于prefix。
• sysconfdir：类似于prefix。
• runstatedir：如果指定，则将变量传播到运行目标，以及cargo。对程序没有进一步的影响
• PATH：在这些路径中搜索安装和strip

config.toml

默认情况下，cargo-native-install将在工作目录中查找名为config.toml的文件。可以指定--config选项来配置文件的名称和路径，但行为保持不变。如果文件存在，它将被解析（作为toml），并且安装目录将从[dir]对象中读取。在这些目录中存在的目录将覆盖该目录的默认设置。请注意，这不会影响由环境变量或命令行标志指定的目录。

此机制旨在替代--build和--build-only标志，这些标志可用于使用环境中的目录构建项目。使用config.toml，包需要提供一个解析该文件并设置适当环境变量的构建脚本。因为文件指定了默认目录，并且可以由单个选项和环境变量覆盖，所以可以使用此功能设置“sysroot”，在标准prefix下构建项目，然后安装到不同的路径，然后可以使用chroot或安装到不同分区的挂载点。

格式

cargo-native-install使用的所有信息都存储在项目的Cargo.toml中。

每个安装“目标”由[package.metadata.install-targets]下的一个键指定。

每个键都是目标的名称。

此外，每个二进制文件以及库目标（如果有）都是该程序的安装目标，除非 install-targets 子对象的 exclude 字段对应的目标设置为 true。这种情况仅适用于库目标，如果 crate-type 字段包含 cdylib 或 staticlib。对于这些库目标，如果两者都存在，则 staticlib 安装目标名为 <library-name>-staticlib，而 cdylib 安装目标为 <library-name>-cdylib。不会生成安装候选，但对于 rlib、dylib 和 proc-macro 库，可以通过将 -<type> 添加到库名称来手动创建。

如果指定了密钥，则它可能具有几个字段，为每种类型的二进制文件/库目标提供了默认值

• type：可以是 "bin"、"sbin"、"library"、"libexec"、"shared"、"include"、"data"、"doc"、"man"、"info"、"sysconfig" 或 "run"。
  • 对于没有设置权限的二进制目标，默认为 "bin"，对于设置权限的目标默认为 "sbin"。
  • 对于 staticlib 目标以及 rlib 目标，默认为 "library"，而对于 cdylib 目标和 dylib 目标，默认为 "shared"。
• privileged：当指定了 --user-prefix 或 --no-privileged 时，不安装（除非指定了 --privileged）。始终默认为 false。
• directory：将目标创建为目录，并将源文件复制到其中。如果未指定，默认为 false。
• install_dir：要安装到的路径。除非类型是 run（注意在 install_dir 上不执行替换），否则默认为该类型的安装目录。
  • bin 目标使用 bindir，默认为 <exec_prefix>/bin。
  • library 目标使用 libdir，默认为 <exec_prefix>/lib。
  • sbin 目标使用 sbindir，默认为 <exec_prefix>/sbin。
  • libexec 目标使用 libexecdir，默认为 <exec_prefix>/lib。
  • data 目标使用 datadir，默认为 <datarootdir>。
  • doc 目标使用 docdir，默认为 <datarootdir>/doc/<package-name>。
  • man 目标使用 mandir，默认为 <datarootdir>/man。
  • info 目标使用 infodir，默认为 <datarootdir>/info。
  • sysconfig 目标使用 sysconfdir，其默认值为 <prefix>/etc（对于 /opt/... 和 /usr/... 前缀有特殊处理）。
  • 指定以安装目录名称开头且用 <>、${} 或 @@ 包围的目录，或任何以 dir 结尾的 ASCII 标识符（不区分大小写）都保留用于未来的版本。
• mode：设置安装模式，采用 chmod(1) 可接受的格式（注意：仅保证在 Unix 平台上有效）。
  • 对于二进制目标，默认为 “=rwx”。
  • 对于所有库目标，默认为 “=rw”。
• installed_path：已安装文件的路径。如果它以安装目录的名称开头（如 prefix、exec_prefix 或 bindir），并用 <>、@@ 或 ${} 包围（如 <prefix>、@exec_prefix@ 或 ${bindir}），则会被替换为该目录。否则，如果它是相对路径，则通过 install_dir 解析。默认情况下，这是目标文件的名称。
  • 以 <>、@@ 或 ${} 包围的、不以 dir 结尾的任何 ASCII 标识符开头的路径保留。
• target_file：源目录中的文件，相对于 Cargo.toml。默认情况下，这是 cargo 为此目标构建的文件。对于未设置 directory 的非生成目标，必须存在。
• installed_aliases：在安装目标后，为给定的每个名称创建指向它的符号链接。
• exclude：如果设置，禁用此目标。如果设置，则忽略所有其他选项。