I noticed that the Nimscript manual https://nim-lang.org/docs/nims.html and the Nim compiler manual https://nim-lang.org/docs/nimc.html#compiler-usage-configuration-files both talk about Configuration Files. But Nimscipt doc mostly refer to config.nims and $project.nims while Nim compiler doc calls them nim.cfg and $project.nim.cfg. Other than this difference in file names the language in both docs is identical.
Are both naming conventions valid? If yes, then what is the processing order if I have nim.cfg and config.nims in the same directory? Similarly, if I have both foo.nims and foo.nim.cfg where foo is the project name?
Even after googling I was unable to find any systematic description of the format used in nim.cfg files, bummer.
Is there anything in nim.cfg that cannot be achieved with Nimscript config.nims files? In other words, as a new Nim user, can I safely ignore nim.cfg in favor of Nimscript based configuration files?
My understanding of it is that nim.cfg is just a list of flag passed to the compiler. The list of existing flags exists in the compiler documentation https://nim-lang.org/docs/nimc.html
On the other hand config.nims is a nimscript that is automatically executed upon compilation It can be used to add / define flags to the compilation, but since it is a scrip it can do much more things (define task, have conditoinnal etc.). You can find more about on the NimScript pages : https://nim-lang.org/docs/nims.html
My recommandation would be to prefer config.nims over nim.cfg because projects builds tends to increase in complexity over time and config.nims is more equipped to handle that complexity than nim.cfg.
The nim.cfg language is slightly less spartan than what @Clonk says. It has (@if, @else, @elif, @end) conditionals and strings, comments, and environment variable expansion ($home), and maybe a little bit more. config/nim.cfg in the Nim distro (or /usr/lib/nim/config/nim.cfg or similar in an "installed Nim") is a large example. It is still very spartan compared to NimScript.
Not mentioned anywhere I saw in the linked to manual, but often useful, you can use either foo.nims or foo.nim.cfg to adjust compile flags for compiling just foo. lib/pure/asyncdispatch.nim.cfg is one example in the stdlib.
A simple experiment shows that presently foo.nim.cfg is processed first, if it exists and then foo.nims if it also exists.
The config.nims recommendation is probably right. The stdlib seems to use the .nim.cfg style exclusively. Maybe there is some reason that someone else could explain beyond nim.cfg worked first.
I didn't know you could do that in nim.cfg. I stand corrected.
I assumed nim.cfg is the ancestor of config.nims and has been kept for background compatibility and to avoid breaking a lot of package.
@cblake wrote:
Not mentioned anywhere I saw in the linked to manual, but often useful, you can use either foo.nims or foo.nim.cfg to adjust compile flags for compiling just foo.
Actually the Nimscript doc states this exactly:
A project can also have a project specific configuration file named $project.nims that resides in the same directory as $project.nim. This file can be skipped with the same --skipProjCfg command line option.
Where the "project file" is defined in the Nim compiler manual https://nim-lang.org/docs/nimc.html
Note: The project file name is the name of the .nim file that is passed as a command line argument to the compiler.
and also talks about $project.nim.cfg file.
Thanks to the power of Nim's templates one can use cmdline options syntax in Nimscript files like
--threads:on # expands to switch("threads", "on")
Yeah well, everything that it has been said is correct. :-)
I'm looking forward to the day where we only have .nims files left but with a different internal implementation that isn't a pita to work with... Tried to do that and failed so far.
IIRC like so:
switch("arm.linux.gcc.exe", "valueHere")