{"id":13438826,"url":"https://github.com/Kixunil/configure_me","last_synced_at":"2025-03-20T06:31:31.789Z","repository":{"id":48643391,"uuid":"131201118","full_name":"Kixunil/configure_me","owner":"Kixunil","description":"A Rust library for processing application configuration easily","archived":false,"fork":false,"pushed_at":"2024-09-12T12:20:10.000Z","size":308,"stargazers_count":67,"open_issues_count":23,"forks_count":14,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-03-13T01:36:39.833Z","etag":null,"topics":["command-line","parsing","rust-crate"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Kixunil.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-04-26T19:25:14.000Z","updated_at":"2025-03-01T04:29:23.000Z","dependencies_parsed_at":"2024-10-25T18:43:26.315Z","dependency_job_id":"7f004955-071a-4ae8-a99b-bcc3baf67112","html_url":"https://github.com/Kixunil/configure_me","commit_stats":{"total_commits":106,"total_committers":5,"mean_commits":21.2,"dds":"0.047169811320754707","last_synced_commit":"329944f169d30fe3803bc94c0c8c673f18eda434"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kixunil%2Fconfigure_me","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kixunil%2Fconfigure_me/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kixunil%2Fconfigure_me/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kixunil%2Fconfigure_me/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Kixunil","download_url":"https://codeload.github.com/Kixunil/configure_me/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244565514,"owners_count":20473283,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["command-line","parsing","rust-crate"],"created_at":"2024-07-31T03:01:08.764Z","updated_at":"2025-03-20T06:31:26.781Z","avatar_url":"https://github.com/Kixunil.png","language":"Rust","funding_links":[],"categories":["Libraries","库 Libraries","库"],"sub_categories":["Configuration","配置 Configuration","配置"],"readme":"Configure me\n============\n\nA Rust library for processing application configuration easily\n\nAbout\n-----\n\nThis crate aims to help with reading configuration of application from files, environment variables and command line arguments, merging it together and validating.\nIt auto-generates most of the parsing and deserializing code for you based on specification file.\nIt creates a struct for you, which you can use to read configuration into.\nIt will contain all the parsed and validated fields, so you can access the information quickly easily and idiomatically.\n\nThe generated code is formatted to be easy to read and understand.\n\nWait a second, why this crate doesn't use derive?\n-------------------------------------------------\n\nI'd love to use derive. Unfortunately it doesn't compose well with man page generation and other tooling.\n\nFor a longer version, see [docs/why\\_not\\_derive.md](docs/why_not_derive.md)\n\nExample\n-------\n\nLet's say, your application needs these parametrs to run:\n\n* Port - this is mandatory\n* IP address to bind to - defaults to 0.0.0.0\n* Path to TLS certificate - optional, the server will be unsecure if not given\n\nFirst create `config_spec.toml` configuration file specifying all the parameters:\n\n```toml\n[[param]]\nname = \"port\"\ntype = \"u16\"\noptional = false\n# This text will be used in the documentation (help etc.)\n# It's not mandatory, but your progam will be ugly without it.\ndoc = \"Port to listen on.\"\n\n[[param]]\nname = \"bind_addr\"\ntype = \"::std::net::Ipv4Addr\" # Yes, this works and you can use your own types as well! (impl. Deserialize and ParseArg)\ndefault = \"::std::net::Ipv4Addr::new(0, 0, 0, 0)\" # Rust expression that creates the value.\ndoc = \"IP address to bind to.\"\n\n[[param]]\nname = \"tls_cert\"\ntype = \"String\"\ndoc = \"Path to the TLS certificate. The connections will be unsecure if it isn't provided.\"\n# optional = true is the default, no need to add it here.\n```\n\nThen, create a simple `build.rs` script, or use `unstable-metabuild` on nightly (see below).\n\n```rust\nextern crate configure_me_codegen;\n\nfn main() -\u003e Result\u003c(), configure_me_codegen::Error\u003e {\n    configure_me_codegen::build_script_auto()\n}\n```\n\n*Tip: use [`cfg_me`](https://github.com/Kixunil/cfg_me) to generate a man page for your program.*\n\nAdd dependencies to `Cargo.toml`:\n\n```toml\n[package]\n# ...\nbuild = \"build.rs\"\n\n# This tells auto build script and other tools where to look for your specification.\n[package.metadata.configure_me]\nspec = \"config_spec.toml\"\n\n[dependencies]\nconfigure_me = \"0.4.0\"\n\n[build-dependencies]\nconfigure_me_codegen = \"0.4.0\"\n```\n\nAnd finally add appropriate incantations into `src/main.rs`:\n\n```rust\n#[macro_use]\nextern crate configure_me;\n\ninclude_config!();\n\nfn main() {\n    // Don't worry, unwrap_or_exit() prints a nice message instead of ugly panic.\n    let (server_config, _remaining_args) = Config::including_optional_config_files(\u0026[\"/etc/my_awesome_server/server.conf\"]).unwrap_or_exit();\n\n    // Your code here, for example:\n    let listener = std::net::TcpListener::bind((server_config.bind_addr, server_config.port)).expect(\"Failed to bind socket\");\n}\n```\n\nIf you need to generate different files for multiple binaries, create a separate file for each binary and then define them separately in `Cargo.toml`:\n\n```toml\n# config for binary foo\n[package.metadata.configure_me.bin]\nfoo = \"foo_config_spec.toml\"\n\n# config for binary bar\n[package.metadata.configure_me.bin]\nbar = \"bar_config_spec.toml\"\n```\n\nAnd include the file in `foo` like this:\n\n```rust\ninclude_config!(\"foo\");\n```\n\nThis needs to be specific because there's no way to detect binary name.\n\nMetabuild feature\n-----------------\n\nIf you use nightly you can avoid writing the build script by using metabuild instead.\nFirst inform yourself about metabuild status in the [tracking issue](https://github.com/rust-lang/rust/issues/49803).\nIf you decided to try it out:\n\n0. Remove (or rename) `build.rs`.\n1. Add `cargo-features = [\"metabuild\"]` at the top of your `Cargo.toml` (above `[package]` section).\n2. Add `metabuild = [\"configure_me_codegen\"]` to `[package]` section of your `Cargo.toml`.\n3. Add `features = [\"unstable-metabuild\"]` to `configure_me_codegen` build dependency.\n4. Try building your project - it should work\n\n**Important: due to the nature of nightly features there are NO stability guarantees!**\nAny changes to the feature will ignore semver.\nIf you want to get this stable soon test it in your project and report your experience in the tracking issue.\nPerhaps help with the Cargo code as well if needed.\n\nManual page generation\n----------------------\n\nThe crate exports an interface for generating manual pages, but I recommend you to not worry about it.\nThere's a [tool](https://github.com/Kixunil/cfg_me) for generating extra files (currently only man page) from your specification. You can install it using `cargo`.\n\nAfter installing it, you can type `cfg_me man` to see the generated man page. Run `cfg_me -o program_name.1 man` to save it to a file.\n\nDebconf generation\n------------------\n\nThis crate also contains experimental debconf support behind `debconf` feature. It generates `templates`, `configure` and `postinst` files for you. If you plan to package your application, you can use it. Note that this isn't integrated with `cargo-deb` yet.\n\nIn order to use this feature, you must enable the flag in `Cargo.toml`:\n\n```toml\nconfigure_me_codegen = { version = \"0.4.0\", features = [\"debconf\"] }\n```\n\nThen add debconf options to your configuration specification:\n\n```toml\n[debconf]\n# Sets the name of the package.\n# Enables debconf support.\npackage_name = \"my-awesome-app\"\n\n[[param]]\nname = \"port\"\ntype = \"u16\"\noptional = false\n# Documentation IS mandatory for debconf!\ndoc = \"Port to listen on.\"\n# Priority used for debconf questions \"high\" is recommended for non-default,\n# mandatory questions. In case of missing priority, the option is skipped!\ndebconf_priority = \"high\"\n\n[[param]]\nname = \"bind_addr\"\ntype = \"::std::net::Ipv4Addr\"\n# Rust expression that creates the default value.\ndefault = \"::std::net::Ipv4Addr::new(0, 0, 0, 0)\"\ndoc = \"IP address to bind to.\"\ndebconf_priority = \"low\"\n# The default set by debconf.While it might seem redundant, this way the user\n# sees the default value when editing.\ndebconf_default = \"0.0.0.0\"\n\n[[param]]\nname = \"tls_cert\"\ntype = \"String\"\ndoc = \"Path to the TLS certificate. The connections will be unsecure if it isn't provided.\"\ndebconf_priority = \"medium\"\n```\n\nFinally build your application with `DEBCONF_OUT` environment variable set to existing directory\nwhere `configure_me` should generate the files.\n\nPlanned features\n----------------\n\nThis crate is unfinished and there are features I definitelly want:\n\n* Support for documenting your configuration very well - done\n* Support environment variables - done\n* Generate bash completion\n* Some advanced features\n\nComparison with clap\n--------------------\n\n`clap` is a great crate that works well. Unfortunately, it doesn't support reading from config files. It also has stringly-typed API, which adds boilerplate and (arguably small, but non-zero) runtime overhead.\n\nOn the other hand, it's much more mature and supports some features this crate doesn't (bash completion and native subcommands).\n\n`clap` may be more suitable for programs that should be easy to work with from command line, `configure_me` may be better for long-running processes with a lot of configuration options.\n\nLicense\n-------\n\nMITNFA\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FKixunil%2Fconfigure_me","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FKixunil%2Fconfigure_me","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FKixunil%2Fconfigure_me/lists"}