closes #44 This doesn't cover all functionality, but it covers a bunch of common use cases I had to figure out to use this crate for another project.

Question, if I use the conf_file_param I find that options set in that config file overwrite options set in environment variables. Is that intentional?

set out_dir like pb builder's style：Builder::out_dir.

fn path_in_out_dir<P: AsRef<Path>>(file_name: P) -> Result<PathBuf, Error> {
    //TODO  pass the out_dir config
    let mut out: PathBuf = std::env::var_os("OUT_DIR").ok_or(ErrorData::MissingOutDir)?.into();
    out.push(file_name);

    Ok(out)
}

Consider changing sequence to map in specification Toml input. That means:

[[param]]
name = "foo"
type = "String"

would become:

[param.foo]
type = "String"

Alternative that makes Toml input map more directly to Rust code, catching duplicates much more early:

[field.foo]
cli = "param" # other possibilities: switch, disabled
type = "String"

So far I think I prefer the less verbose option, duplicate detection can be written differently.

@dr-orlovsky @romanz would appreciate your thoughts.

How is it possible to use per-binary configuration and code generation (when there are multiple bins in src/bin section and each one needs a separate config)?

It'd be great to add an option to enable skipping default config files. It'd resolve https://github.com/romanz/electrs/issues/217 as well as provide some robustness for other interesting cases. Programs that don't have such options are sometimes painful to work with (pkg-config comes to mind).

Proposed solution: make it possible to add skip_default_configs to a boolean flag. After processing arguments, this is checked and configs are not loaded if it's set to true.

Pros:

• Looks very easy to implement
• Implicitly prevents people from making two different options of the same name (because of the field name in the struct).
• Makes it possible to access this value - e.g. for logging purposes
• No need to write a separate documentation generating code

Cons:

• One might accidentally make more than one such option - this would work, but it'd be weird - maybe issue a warning?
• It leaks the value, cementing the implementation detail immediately, removing the ability to change it in the future
• It forces everyone to document this option, while it might be entirely fine to provide doc string automatically. Maybe we could set it as the default, but I'm not sure if it'd be easy enough.

Alternatives:

• Silently ignore bunch of other errors (e.g. EPERM) - lot of hair pulling in cases where the user forgot didn't want this behavior.
• Print warning if a file is skipped because of any other reason - annoying warning clutter for projects that'd need this feature
• Make this option always present in configure_me - would remove configuration handling, but be inflexible. There's a precedent with --help, but that is extremely widespread - basically every program understands -h and --help. This isn't true for skipping default config.

• [x] Wait for merging of description section
• [x] Wait for release of man with description section
• [x] Implement description
• [x] Verify that the resulting man page conforms to standards
• [x] Add option to override binary name
• [x] Add ability to write to custom destination as well as default one

One of the challenges of configure_me is its usage being less common. Good error messages, among other things, can make development easier and may help people understand configure_me better.

This makes several significant improvements of error messages:

• Uses codespan-reporting to report the exact places of root causes of errors - the messages look very similar to those of rustc!
• Doesn't stop after first validation error - if multiple errors can be detected and reported they are.
• Moves identifier validation out of deserialization to allow detecting other errors and print very detailed messages with hints.
• Treats --help/-h as reserved and reports it as such.
• Adds detection of duplicate short options - this was previously missing.
• Spanned messages don't just report the locations but also explain possibly less-obvious details - such as setting default = true in switch makes it inverted.
• Improves wording of some messages.

New API and new style of build script

Error has new methods report and report_and_exit that report the error with colors to stderr. The latter one is intended for use in build script inside unwrap_or_else:

fn main() {
    configure_me_codegen::build_script_auto()
        .unwrap_or_else(|error| error.report_and_exit());
}

The addition of unwrap_or_else is offset by removal of -> Result<...>. Note that the existing build scripts still work, they are just colorless.

Merging of conf files is illogical, error-prone, confusing and possibly buggy. Tests need to be written and merge_in modified to override &mut self.

It'd be neat if template files and scripts could be generated from the configuration.

When file list is implemented in build script, then it could auto-generate the config file too. That'd help a lot.

It might be nice to be able to convert parameter type to a different type. This would be useful for scenarios when newtype is used to implement ParseArg.

It may be useful to be able to debug which config files were loaded. An example where this might've been useful: https://github.com/rootzoll/raspiblitz/issues/3447 I've seen some services doing such logging (Tor, I think) and it was handy.

The proposed API is to have a Metadata struct returned together with the configuration. It will also contain program path and spans. And potentially more things in the future. We can simply use Vec<PathBuf>. It will slow down startup a bit but hopefully not much. If this ever becomes a problem we may offer a feature/cfg option to not fill it (empty is zero cost).

xtask pattern could improve compilation times for libraries. However it's not entirely suited for this kind of optimization. So instead we can put codegen into cfg_me and if it's installed just run it, if it's not run xtask which will do the same thing.

And make sure cfg_me is versioned similarly to cargo +version ... (but maybe scan the project file for version instead?) so that we can make sure codegen matches.

It'd be nice to be able to condition switches/params on features being enabled or based on platform etc.

Suggested design:

• When enabled, everything works like now.
• When disabled, the parameters are still parsed but generate a nice error.
• Help page does not mention the parameter but it could mention that the app was built with specific features.

Support subcommands like e.g. commit is a subcommand of git.

Example input:

[general]
# global options

# This is a global param - given to program in the form of cmd --foo subcmd
# We could later support cmd subcmd --foo
[[param]]
name = "foo"
type = "String"
# ...

# same as above an be done with switch

# We use subcmd instead of subcommand to keep it reasonably short because it will be repeated
[subcmd.subcmdname.general]
# Only support these two for now, other things available above are mostly non-sensical here
summary = "This command does something"
doc = "Long explanation of what this command is all about..."
# LATER we could also support include = "file-relative-to-current"
# included files should probably only support params and switches

# works exactly the same as in top-level
[[subcmd.subcmdname.param]]
name = "bar"
type = "String"

# switch is supported here as well
# nested subcommand is also supported

The generated code will look something like this:

enum Subcommand {
    Subcmdname(subcmdname::Config),
}

// recursively generates almost the same thing as top-level
mod subcmdname {
    struct Config {
        // no _program_name here, it's pointless
        bar: String,
    }

    // also has raw module like the top-level
    mod raw {
    }
}

Specification parsing code will get subcmd: HashMap<Ident, Subcommand> field.

struct Subcommand {
    global: SubcommandGlobal,
    param: Vec<Param>,
    switch: Vec<Switch>,
}

Difficult stuff:

• How to parse and process config files for subcommands? Suggestion: don't support in initial impl
• How to process env vars for config files? Suggestion: don't support in initial impl
• Should subcommand be inside Config, or outside? The advantage of being outside is it can get global config without self-reference but maybe that's not useful as immutable references will most likely be used?
• Should we support more straightforward design as clap does? If there are multiple nested subcommands and mid-commmands don't have any options, then avoiding the struct would lead to easier-to-write code, although harder-to-refactor. Maybe instead have Subcmdname { config: subcmdname::Config, subcmd: subcmdname::Subcommand }, then matching code can just ignore empty struct. This obviously implies "outside" for the question about.

I am trying to use configure_me for a crate with two executables each with their own config files. This section in the documentation seems wrong:

# 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"

I believe it should be

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

I can open a PR for this later.

Just would like to check that I am using this lib efficiently with cases we have in different LNP/BP nodes (LNP Node, BP Node, RGB Node).

Each node is represented by

• a set of microservices, each of which can be loaded either in form of separate process (daemon) or as a thread withing a single process, depending on the configuration and environment (mobile app or server + docker).
• a main service (it can also be just a thread withing mobile app) which launches and manages the rest.

The main service should be configured with either:

• config file + command-line args matching config file + env variables (in case it is a process), or
• with rust structure passed to it's entry point (in case it is started as a thread).

The rest of services are never intended to be launched by human from command-line (they are started as threads or processes by the main service, or automatically by something like Kubernetes), but they also should be configured with

• some service-specific command line options/env vars, which should not map to the configuration file (their value is unique per service instance) +
• read parts of the shared config from the main service - or get it's configuration structure for multi-threaded case.

What I plan is:

• to have a single configure_me-based configuration for the main service, generating command-line args for it + support for env variables and man pages
• to re-use that config file by the rest of services, but using direct TOML reads, not configure_me-based routines
• to add other per-service command-line configuration options (which do not map to the config file and do not need man page) using Clap