From efb3aae55908cb88f5a9c900d6563603ab792d6a Mon Sep 17 00:00:00 2001
From: Bruce Hill <bruce@bruce-hill.com>
Date: Tue, 20 May 2025 15:22:41 -0400
Subject: Add more advanced configuration options to modules.ini and support
 automatically downloading and installing from it.

---
 docs/libraries.md | 32 ++++++++++++++++++++++++++++----
 docs/versions.md  |  4 ++--
 2 files changed, 30 insertions(+), 6 deletions(-)

(limited to 'docs')

diff --git a/docs/libraries.md b/docs/libraries.md
index 37f8ee05..8457b67a 100644
--- a/docs/libraries.md
+++ b/docs/libraries.md
@@ -171,9 +171,9 @@ path where the library is installed, so if the library `foo` has version
 `v1.2`, then it will be installed to
 `~/.local/share/tomo_vX.Y/installed/foo_v1.2/`. When using a library, you must
 explicitly supply either the exact version in the `use` statement like this:
-`use foo_v1.2`, or provide a `modules.ini` file that lists shorthand aliases
-for the libraries you're using alongside the files that use them. The syntax
-is a simple `alias=full_name` format on each line. Here is an example:
+`use foo_v1.2`, or provide a `modules.ini` file that lists version information
+and other details about modules being used. For each module, you should provide
+a `[modulename]` section with a `version=` field.
 
 ```tomo
 # File: foo.tm
@@ -184,10 +184,34 @@ use mylib
 And the accompanying `modules.ini`:
 
 ```ini
-mylib=mylib_v1.2
+[mylib]
+version=v1.2
 ```
 
 The `modules.ini` file must be in the same directory as the source files that
 use its aliases, so if you want to share a `modules.ini` file across multiple
 subdirectories, use a symbolic link.
 
+### Module Downloading
+
+If you want, you can also provide the following options for a module:
+
+- `git`: a Git URL to clone the repository
+- `revision`: if a Git URL is provided, use this revision
+- `url`: a URL to download an archive of the library (`.zip`, `.tar`, `.tar.gz`)
+- `path`: if the library is provided in a subdirectory of the repository or
+  archive, list the subdirectory here.
+
+For example, this is what it would look like to use the `colorful` library that
+is distributed with the Tomo compiler in the `examples/colorful` subdirectory:
+
+```ini
+[colorful]
+version=v1.0
+git=git@github.com:bruce-hill/tomo
+path=examples/colorful
+```
+
+If this extra information is provided, Tomo will prompt the user to ask if they
+want to download and install this module automatically when they run a program
+and don't have the necessary module installed.
diff --git a/docs/versions.md b/docs/versions.md
index db7a1036..c68d1f81 100644
--- a/docs/versions.md
+++ b/docs/versions.md
@@ -70,8 +70,8 @@ version number will be used to determine its installation location and how it's
 used in code. You must either explicitly import the library with its version
 number (e.g. `use foo_v1.2`) or include a `modules.ini` configuration file that
 maps a shorthand alias to a specific version of a library. For example, if the
-`modules.ini` file has `foo=foo_v1.2`, you can put `use foo` to use v1.2 of the
-`foo` library (assuming you have it installed).
+`modules.ini` file has a `[foo]` section with `version=v1.2`, you can put `use
+foo` to use v1.2 of the `foo` library (assuming you have it installed).
 
 # Rationale
 
-- 
cgit v1.2.3