Standardised static package-level configuration for out-of-code tooling

[lpil]

As the Gleam ecosystem grows more tools will be created for various tasks, such as linting, dependency auditing, code generation, etc.

Configuration for dependencies in Gleam is typically passed in as arguments, but there are situations in which writing a wrapper module for the tool isn't possible, such as:

• The tool uses a specific target, so packages using the other target will not be able to run it.
• The tool is written in a non-Gleam language, such as C or Go.
• The tool needs to be runnable even if the codebase does not currently successfully compile.

It would be good to have a recommendation for how to configure these out-of-code tools!

In some other ecosystems these result in a number of config files in different formats (JSON, YAML, TOML, XML, INI, JavaScript, etc) in the root of the project directory.

In Python it is recommended for each tool to parse the pyproject.toml config file (analogous to our gleam.toml) and read config from [tool.$TOOL_NAME], resulting in less file system clutter, and consistency with the configuration language used.

Are there other options we could consider?

[TanklesXL]

I'm glad this is getting brought up, I've thought about this a bit over the course of building gladvent and I am of mixed opinions

1. gleam.toml is the easiest because when working in a gleam project it's guaranteed to exist, and users are already familiar with its contents. Though that also means that a tool can potentially accesses fields that aren't relevant.

2. I kinda like the idea of having a dedicated config file for the tool if necessary at the top level sitting beside gleam.toml where the file name matches the module name/path (eg. gladvent -> gladvent.toml, lustre/dev -> lustre_dev.toml) or in a tools or config directory because that makes it clear that a given config file is for a specific tool. I am personally a fan of using a dedicated dir for these things since I hate bloating the top level of a repo with config files but like having dedicated files so that my tool config doesn't absolutely take over something like gleam.toml

As for format: regardless of where it lives, let's push for toml pls

[lpil]

If it's not part of gleam.toml how would we encourage developers to use toml and to put it in this config directory?

[TanklesXL]

Hmmm 🤔 that's a good point, I was thinking that documentation/convention could go quite far but you're right that it technically doesn't give us a way to mandate a specific format

[sporto]

This is a great initiative. My preferences would be

• Storing config files for each tool separately. I have worked with several tools in the npm ecosystem that want to put their config in package.json. I didn't find this good, the configuration for the tool is harder to find and the package.json is left with stray config when the tool has been replaced for something else. Having a separate file makes it obvious.
• Having files in config dir or similar.
• TOML is good as it is already used by gleam.toml, and way better than plain json or yaml. And most languages can use toml. My ideal would be https://github.com/tweag/nickel (static typing, validations, functions) but is not a popular format yet.

[Norlock]

+1 for putting it in a config directory, I really dislike looking at a git repo online where 80% of the files in the root are cluttered config files for whatever tool.

[lpil]

If it's not part of gleam.toml how would we encourage developers to use toml and to put it in this config directory?

[Norlock]

After thinking about it a bit longer I think the main gleam.toml is a good place, I don't know if there will be tools that require lots of configuration flags, but I guess that will be very rare. The python example looks pretty clean

[isaacharrisholt]

I think one of the main concerns with having it in one file is to do with length, but big modules are a normal Gleam thing, and the problem is mostly solved by folding in editors anyway.

[TanklesXL]

Embrace the fold

[ankddev]

Just my $0.02. Personally I will like to add tools' settings in gleam.toml, since:

1. This allows me to maintain all (or almost all) configuration in single file. So, when I want to edit some settings, I just open that file and make edits.
2. When locating configs in root dir it will result in cluttering it with many files.
3. Adding all configs to dedicated directory like config still adds one more folder to root of project with large amount of files.
4. When locating configs in dedicated files it will be logical that each tool will select favourite file format which will result in context switching when I want to edit multiple configs. E.g. I change project structure and then need to recall how to do some thing in particular file format.
5. Many files may result in large effort to synchronise changes between configs (since some settings overlap).

[isaacharrisholt]

Also for sticking stuff in gleam.toml under a tool key. To follow the format we seem to be going with:

1. Config sprawl is horrible in larger JavaScript projects - I don't want to end up with that in Gleam, too.

2. Most config is gonna be pretty short. Lots of the longer config files in the wild are for formatters, linters and bundlers, none of which we need to worry about, so config for a Gleam CLI tool is likely to be closer to 5-10 LOC per tool on average.

3. If everything is in one place (and therefore forced to be in the same file format), it's easy to standardise on a way to read that config. Could be a gleam_community package or something.

The one downside I can think of is that it makes it harder for tools to have an init command or similar that scaffolds out a default config, as we'd probably want to discourage tools from editing the gleam.toml. Again, though, most config is likely to be short (2), so I'm not sure how necessary this would be, and we could include a well-tested way of initialising as part of a community package (3).

[lpil]

Good point. Having a library for editing toml files is likely needed.

[idea-list]

I am generally in favor of keeping tool configs in gleam.toml under [tool.<toolname>], especially by default. However ability to have separate config files is also nice sometimes, and in that case I prefer a separate config dir, e.g. ./.config/<toolname>.toml. For example, ruff kind of does this letting you configure it in pyproject.toml or in separate ruff.toml.

Maybe having those two places as the only officially blessed config locations would be enough for devs to stick to gleam.toml (or at least to a TOML config in a designated subdir). If you think more coercion is needed then gleam.toml could have a reserved subsection that requires developers to explicitly mark tools that have external configs. Though I think that's probably excessive and wouldn't really work unless all tools are forced to consume own config values through some kind of DI from gleam tooling instead of just reading own configs.