Clarify bundled modules in numbat dist package?

[Hrxn]

First time trying numbat (on Windows)!

Download from the releases pages looks like this:

PS C:\Apps\Temp\numbat-v1.7.0-x86_64-pc-windows-msvc> ls

    Directory: C:\Apps\Temp\numbat-v1.7.0-x86_64-pc-windows-msvc

Mode                 LastWriteTime         Length Name
----                 -------------         ------ ----
d----          2023-11-03    21:27                modules
-a---          2023-11-03    21:27          11558 LICENSE-APACHE
-a---          2023-11-03    21:27           1123 LICENSE-MIT
-a---          2023-11-03    21:27        3842560 numbat.exe
-a---          2023-11-03    21:27           6645 README.md

PS C:\Apps\Temp\numbat-v1.7.0-x86_64-pc-windows-msvc>

I've been reading the docs, module usage/paths are explained here: https://numbat.dev/doc/cli-customization.html#module-paths

There's a link to https://numbat.dev/doc/cli-installation.html#guidelines-for-package-maintainers

And this has me now a bit confused, specifically

Numbat has a standard library that is written in Numbat itself. The sources for this so called “prelude” are available in the numbat/modules folder. We also include this modules folder in the pre-built GitHub releases. Installing this folder as part of the package installation is not necessary for Numbat to work, as the prelude is also stored inside the numbat binary. But ideally, this folder should be made available for users. There are three reasons for this: [..]

Okay, so the modules directory belongs to the (platform-specific) config path, but this description implies (at least to me) that numbat.exe is a self-contained static binary that already includes the "prelude", i.e. all standard modules?

Or do I get this wrong?

[sharkdp]

First time trying numbat (on Windows)!

Cool — did it work? :-)

And this has me now a bit confused

That should not be the case, ideally. It means our documentation did not serve its purpose. Please let us know if/how we can improve the documentation after we have clarified things here.

Okay, so the modules directory belongs to the (platform-specific) config path

Yes. If Numbat finds a module folder in the config path, it will prefer to load the modules from there. It will only fall back to the built-into-the-binary modules if a module is requested that is not present in one of the module folders.

this description implies (at least to me) that numbat.exe is a self-contained static binary that already includes the "prelude", i.e. all standard modules?

Yes. It is. There is a literal copy of all of these files inside the binary. In 95% of the cases, this is completely enough. There are two drawbacks though:

• Error messages (such as the one that you get when trying let m = 2) will not refer to a file, but rather to File <builtin>/modules/units/si.nbt:10:6. And there is no way for the user to inspect this source code.
• You can not modify the standard library.

That's it. If you don't care about this, you can just use numbat as a standalone binary.

[Hrxn]

Yes, it does work just fine.
Although I haven't done much yet. A couple unit conversions, basic arithmetic plus exponentiation, as well as assigning and using variables - although they are apparently always called constants, even if I can reassign them? 🤔

That should not be the case, ideally. It means our documentation did not serve its purpose. Please let us know if/how we can improve the documentation after we have clarified things here.

The documentation is correct. So, it's not a big deal. It could, maybe, made are bit more explicit, that the /modules directory that is shipped as part of the distribution package of the pre-built binaries is basically optional. Not needed to run numbat at all.
Which, to be fair, is mentioned, but it is mentioned under the heading of Guidelines for package maintainers, which means that the average end-user might have a non-zero probability to overlook this part.

There are two drawbacks though:

• Error messages (such as the one that you get when trying let m = 2) will not refer to a file, but rather to File <builtin>/modules/units/si.nbt:10:6. And there is no way for the user to inspect this source code.
• You can not modify the standard library.

Does not seem like a big deal for me.
First, there's always https://github.com/sharkdp/numbat/blob/master/numbat/modules/units/si.nbt, and second, I don't think I will end up in a situation where I'd need to make any changes to the standard library in the near future 😄

[sharkdp]

Which, to be fair, is mentioned, but it is mentioned under the heading of Guidelines for package maintainers, which means that the average end-user might have a non-zero probability to overlook this part.

👍

[sharkdp]

@Hrxn I added a new section here: https://numbat.dev/doc/cli-installation.html#from-pre-built-binaries

[Hrxn]

@sharkdp That's about perfect, thanks 👍