Commits on Feb 14, 2021

1. add some extra detail to docs

   

   Shamazo committed Feb 14, 2021
   Configuration menu

   • View commit details
   • Copy full SHA for 0850314
   • Browse repository at this point

   Copy the full SHA

   0850314 View commit details

   Browse the repository at this point in the history

2. add readme changes generated with # configure_me …

   This crate aims to help with reading configuration of application from files,
   environment variables and command line arguments, merging it together and
   validating. It auto-generates most of the code for you based on configuration (heh)
   file. It creates a struct for you, which contains all the parsed and validated
   fields, so you can access the information quickly easily and idiomatically.
   
   This is currently only a facade for the dependencies, the core of the crate is in
   `configure_me_codegen` crate.
   
   **Important:** In order to use this crate, you need to create a build script using
   `configure_me_codegen` to generate the code that will use this crate! See the example.
   
   Wait a second, why this crate doesn't use derive?
   -------------------------------------------------
   
   I'd love to use derive. Unfortunately it doesn't compose well with man page generation and other tooling.
   
   For a longer version, see [docs/why\_not\_derive.md](docs/why_not_derive.md)
   
   Example
   -------
   
   Let's say, your application needs these parametrs to run:
   
   * Port - this is mandatory
   * IP address to bind to - defaults to 0.0.0.0
   * Path to TLS certificate - optional, the server will be unsecure if not given
   * RunFast - switch, if present the server will run in fast mode
   
   First create `config_spec.toml` configuration file specifying all the parameters:
   
   ```toml
   [[param]]
   # short param, e.g -p
   abbr = "p"
   # long arg, e.g --port
   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"
   # merge from env var. e.g BIND_ADDR
   env_var = true
   # Yes, this works and  you can use your own T: Deserialize + ParseArg as well!
   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."
   
   [[param]]
   name = "tls_cert"
   type = "::std::path::PathBuf"
   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
   # If the type is optional, it will be represented as Option<T>
   # e.g. Option<::std::path::PathBuf> in this case.
   
   [[switch]]
   # switches are parsed as bools, true if present false otherwise
   name = "run_fast"
   doc = "Will make the server run in fast mode"
   ```
   
   Then, create a simple build script:
   
   ```rust
   extern crate configure_me;
   
   fn main() {
       configure_me::build_script_auto().unwrap_or_exit();
   }
   ```
   
   Add dependencies to `Cargo.toml`:
   
   ```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.3.3"
   
   [build-dependencies]
   configure_me_codegen = "0.3.3"
   ```
   
   And finally add appropriate incantations into `src/main.rs`:
   
   ```rust
   #[macro_use]
   extern crate configure_me;
   
   include_config!();
   
   fn main() {
       // This will read configuration from "/etc/my_awesome_server/server.conf" file, environment variables and
       // the command-line arguments.
       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");
   }
   ```
   Configuration
   -------------
   Configuration of the code generation is set in the same toml file as the specification
   ```toml
   [general]
   # Prefix for all env vars - enables all env vars by default if present
   build = "build.rs"
   
   # The name of the parameter which, if specified causes parameter parsing to
   # immediately load a config file, parse it, and override all configuration
   # provided so far with that file.
   conf_file_param = "/path/to/conf/file.toml"
   ```
   If you need to generate different files for multiple binaries, create a separate file for each binary and then define them separately in `Cargo.toml`:
   
   ```toml
   [package.metadata.configure_me.bin]
   # config for binary foo
   foo = "foo_config_spec.toml"
   # config for binary bar
   bar = "bar_config_spec.toml"
   ```
   
   And include the file in `foo` like this:
   
   ```rust
   include_config!("foo");
   ```
   
   This needs to be specific because there's no way to detect binary name.
   
   License: MITNFA

   

   Shamazo committed Feb 14, 2021
   Configuration menu

   • View commit details
   • Copy full SHA for 8775752
   • Browse repository at this point

   Copy the full SHA

   8775752 View commit details

   Browse the repository at this point in the history