Configure me

一个易于处理应用配置的 Rust 库

关于

这个 crate 旨在帮助从文件、环境变量和命令行参数中读取应用程序配置，将其合并并验证。它根据规范文件自动生成大部分解析和反序列化代码。它为您创建一个结构体，您可以使用它来读取配置。它将包含所有解析和验证的字段，因此您可以快速、轻松、直观地访问信息。

生成的代码格式化得易于阅读和理解。

等等，为什么这个 crate 不使用 derive？

我很想使用 derive。遗憾的是，它与手册页生成和其他工具的兼容性不好。

更详细的内容，请参阅 docs/why_not_derive.md

示例

假设，您的应用程序需要以下参数来运行

• 端口 - 这是必需的
• 要绑定的 IP 地址 - 默认为 0.0.0.0
• TLS 证书的路径 - 可选，如果没有提供，则服务器将不安全

首先创建 config_spec.toml 配置文件，指定所有参数

[[param]]
name = "port"
type = "u16"
optional = false
# This text will be used in the documentation (help etc)
# It's not mandatory, but your progam will be ugly without it.
doc = "Port to listen on."

[[param]]
name = "bind_addr"
type = "::std::net::Ipv4Addr" # Yes, this works and  you can use your own types implementing Deserialize and ParseArg as well!
default = "::std::net::Ipv4Addr::new(0, 0, 0, 0)" # Rust expression that creates the value
doc = "IP address to bind to."

[[param]]
name = "tls_cert"
type = "String"
doc = "Path to the TLS certificate. The connections will be unsecure if it isn't provided."
# optional = true is the default, no need to add it here

然后，创建一个简单的 build.rs 脚本，如下所示

extern crate configure_me_codegen;

fn main() -> Result<(), configure_me_codegen::Error> {
    configure_me_codegen::build_script_auto()
}

提示：使用 cfg_me 为您的程序生成手册页。

将依赖项添加到 Cargo.toml

[package]
# ...
build = "build.rs"

# This tells auto build script and other tools where to look for your specificcation
[package.metadata.configure_me]
spec = "config_spec.toml"

[dependencies]
configure_me = "0.4.0"

[build-dependencies]
configure_me_codegen = "0.4.0"

最后，将适当的初始化语句添加到 src/main.rs

#[macro_use]
extern crate configure_me;

include_config!();

fn main() {
    // Don't worry, unwrap_or_exit() prints a nice message instead of ugly panic
    let (server_config, _remaining_args) = Config::including_optional_config_files(&["/etc/my_awesome_server/server.conf"]).unwrap_or_exit();

    // Your code here
    // E.g.:
    let listener = std::net::TcpListener::bind((server_config.bind_addr, server_config.port)).expect("Failed to bind socket");
}

如果您需要为多个二进制文件生成不同的文件，请为每个二进制文件创建一个单独的文件，然后在 Cargo.toml 中分别定义它们

# config for binary foo
[package.metadata.configure_me.bin]
foo = "foo_config_spec.toml"

# config for binary bar
[package.metadata.configure_me.bin]
bar = "bar_config_spec.toml"

然后在 foo 中包含该文件，如下所示

include_config!("foo");

这需要具体指定，因为没有方法可以检测二进制文件名。

手册页生成

该 crate 导出了一个用于生成手册页的接口，但我建议您不必担心这一点。有一个 工具 可以从您的规范文件生成额外的文件（目前仅限手册页）。您可以使用 cargo 安装它。

安装后，您可以输入cfg_me man来查看生成的man页面。运行cfg_me -o program_name.1 man将其保存到文件。

Debconf生成

这个crate还包含在debconf特性后面的实验性debconf支持。它为您生成templates、configure和postinst文件。如果您打算打包您的应用程序，可以使用它。请注意，这尚未与cargo-deb集成。

为了使用此功能，您必须在Cargo.toml中启用标志

configure_me_codegen = { version = "0.4.0", features = ["debconf"] }

然后添加debconf选项到您的配置规范

[debconf]
# Sets the name of the package
# Enables debconf support
package_name = "my-awesome-app"

[[param]]
name = "port"
type = "u16"
optional = false
# Documentation IS mandatory for debconf!
doc = "Port to listen on."
# Priority used for debconf questions
# "high" is recommended for non-default, mandatory questions
# In case of missing priority, the option is skipped!
debconf_priority = "high"

[[param]]
name = "bind_addr"
type = "::std::net::Ipv4Addr"
default = "::std::net::Ipv4Addr::new(0, 0, 0, 0)" # Rust expression that creates the value
doc = "IP address to bind to."
debconf_priority = "low"
# The default set by debconf. While it might seem redundant, this way the user sees the
# default value when editing.
debconf_default = "0.0.0.0"

[[param]]
name = "tls_cert"
type = "String"
doc = "Path to the TLS certificate. The connections will be unsecure if it isn't provided."
debconf_priority = "medium"

最后，将DEBCONF_OUT环境变量设置为您希望在其中生成文件的现有目录，然后构建您的应用程序。

计划中的功能

这个crate还未完成，还有一些我肯定想实现的功能

• 支持非常详细地记录您的配置 - 完成
• 支持环境变量 - 完成
• 生成bash自动完成
• 一些高级功能

与clap的比较

clap是一个工作良好的优秀crate，但它不支持从配置文件中读取。它还有一个字符串类型的API，这增加了样板代码和（尽管很小，但非零）运行时开销。

另一方面，它更加成熟，支持一些这个crate没有的功能（bash自动完成和原生子命令）。

clap可能更适合那些应该易于通过命令行操作的程序，而configure_me可能更适合具有许多配置选项的长运行进程。

许可证

MITNFA