console: configuration file

[hawkw]

What problem are you trying to solve?

Currently, the tokio-console CLI honors a number of command-line arguments and environment variables to configure its behavior. These include view options, such as colors and UTF-8 support:

console/tokio-console/src/config.rs

Lines 71 to 107 in 3c55912

	pub struct ViewOptions {
	/// Disable ANSI colors entirely.
	#[clap(name = "no-colors", long = "no-colors")]
	no_colors: bool,
	/// Overrides the terminal's default language.
	#[clap(long = "lang", env = "LANG", default_value = "en_us.UTF-8")]
	lang: String,
	/// Explicitly use only ASCII characters.
	#[clap(long = "ascii-only")]
	ascii_only: bool,
	/// Overrides the value of the `COLORTERM` environment variable.
	///
	/// If this is set to `24bit` or `truecolor`, 24-bit RGB color support will be enabled.
	#[clap(
	long = "colorterm",
	name = "truecolor",
	env = "COLORTERM",
	parse(from_str = parse_true_color),
	possible_values = &["24bit", "truecolor"],
	)]
	truecolor: Option<bool>,
	/// Explicitly set which color palette to use.
	#[clap(
	long,
	possible_values = &["8", "16", "256", "all", "off"],
	group = "colors",
	conflicts_with_all = &["no-colors", "truecolor"]
	)]
	palette: Option<Palette>,
	#[clap(flatten)]
	toggles: ColorToggles,
	}

In general, these kinds of configurations are typically not the sort of thing that users would want to pass a bunch of CLI flags for. Instead, users might want to set these configurations globally for their system.

How should the problem be solved?

We should support a configuration file for configuring the tokio-console CLI.

Currently, the main things we would set in a config file are view options like colors and Unicode support, but as we add more features, there may be additional configuration surface area. In particular, #148 proposes the ability to control what warnings are enabled/disabled; we would almost certainly want to be able to configure this from a config file.

Any alternatives you've considered?

We could just not do this.

How would users interact with this feature?

TOML is probably a good configuration language for our purposes: as it's widely used for Rust tools and most Rust developers are probably already familiar with it; and we don't need to represent particularly complex configurations.

On Unix systems, we should probably use the XDG_CONFIG_HOME environment variable to determine where to look for the config file. This way, if the user's systems stores configs in a non-standard location, we'll be able to find the config file.

We may also want to support overriding parts of the configuration with a config file in the current working directory. That way, users could have per-project configs for different projects, and (potentially) check them into source control. This could allow different projects to do things like enable or disable different sets of warnings. We would probably want to combine local configs with global ones in a way where the local configs override the global config in the case of conflicts. This could be a separate issue once basic config file support is implemented.

Would you like to work on this feature?

no

[hawkw]

This would probably be a good first issue for anyone interested in helping contribute to the console.

[nrskt]

i’d like to take it.

[hawkw]

@nrskt That would be great! Please let me know if you have any questions!

[nrskt]

@hawkw

[Q1] Do you want to use the view options from the config file only? (Can I disable the options no_colors, ascii_only and etc?)

I think both options are realized is ideal. But it's complex for me because I don't know how to use the default value from the config file using clap derive-style.

First implementation:

• Disable arguments as follows.
  • no_colors
  • lang
  • ascii_only
  • truecolor
  • palette
  • color_durations
  • color_terminated
• Can read config file on $XDG_CONFIG_HOME/tokio-console/console.toml if it exists.
• Can read config file on current directry if it exists.
• If config files does not exits, use default value

How about it?

[Q2] $XDG_CONFIG_HOME environment variable is set on Linux. I don't know if the variable exists when using the Mac or WIndows.

Can I use $XDG_CONFIG_HOME env?