doc: expand/clarify "Source Registries" and "Hello World"

The primary motivation was to clarify the search order for registry
entries. Cleaned up and expanded the registry-related parts of Hello World also.

documentation/getting-started-cli/source/hello-world.rst

@@ -16,7 +16,7 @@ how do you write the canonical Hello World app?  This example assumes the
 Ta da!  Now a quick review of the steps with a little bit of explanation.
 
 First you must set ``PATH`` so that the :program:`dylan` and
-:program:`dylan-compiler` commands will be found.  ``./_build/bin`` is where
+:program:`dylan-compiler` executables will be found.  ``./_build/bin`` is where
 :program:`dylan-compiler` puts the executables it builds.
 
 .. note:: Some of these differ on Windows, so please be sure
@@ -25,16 +25,21 @@ First you must set ``PATH`` so that the :program:`dylan` and
 
 ``dylan new application --simple hello-world`` creates a directory named
 "hello-world", and several files. The ``--simple`` flag says to skip generating
-a test suite library.
+a test suite library and instead of a separate ``hello-world`` library and
+``hello-world-app`` executable library to just make one ``hello-world``
+executable library.
 
 1. :file:`hello-world.lid` lists the files in the project.  The order in which
    the files are listed here determines the order in which the code in them is
    loaded. The library definition file should always be first.
 
 2. :file:`library.dylan` contains the library and module definitions.  These
-   can be extended as your project grows in complexity.
+   can be extended as your project grows in complexity. Note that the library
+   and modules are defined in the pre-defined ``dylan-user`` module.
 
-3. :file:`hello-world.dylan` contains the main program code.
+3. :file:`hello-world.dylan` contains the main program code. Note that this
+   code is defined in the ``hello-world`` module of the ``hello-world``
+   library.
 
 4. The :file:`registry` directory is how :program:`dylan-compiler` locates each
    used library. When using the :program:`dylan` tool, this directory is
@@ -43,19 +48,19 @@ a test suite library.
 
 5. :file:`dylan-package.json` describes the new "hello-world" package. This is
    where you can specify dependencies, the package location, etc. See the
-   `dylan-tool documentation
-   <https://docs.opendylan.org/packages/dylan-tool/documentation/source/index.html>`_
-   for more on this. Note that the existence of this file turns the
-   "hello-world" directory into a :program:`dylan` workspace.
+   `dylan tool documentation
+   <https://opendylan.org/package/dylan-tool/index.html>`_ for more on
+   this. Note that the existence of this file turns the "hello-world" directory
+   into a :program:`dylan` workspace.
 
-The first time you build ``hello-world`` all used libraries are built, all the
+The first time you build your project all used libraries are built, all the
 way down to the ``dylan`` library itself. Subsequent builds only need to
 recompile ``hello-world`` itself and are therefore much faster.
 
 .. note:: Don't confuse the ``dylan`` library with the :program:`dylan`
           executable program. The ``dylan`` library contains the core Dylan
           language features that are not implemented inside the compiler. The
-          ``dylan`` program is a tool to help manager Dylan projects and is
+          ``dylan`` program is a tool to help manage Dylan projects and is
           created from a library called ``dylan-tool``.
 
 The compiler places its output in the ``_build`` directory in the current

documentation/getting-started-cli/source/source-registries.rst

@@ -2,66 +2,111 @@ Using Source Registries
 =======================
 
 .. note:: When using the :program:`dylan` tool source registries are created
-          for you via the ``dylan update`` command and you should not have to
-          create them explicitly. You may want to skip this section for now.
+          for you via the `dylan update
+          <https://opendylan.org/package/dylan-tool/index.html#dylan-update>`_
+          command and you should not have to create them explicitly. You may
+          want to skip this section for now.
 
 Passing the name of a ".lid" file to :program:`dylan-compiler` works great when
 you have a single library that only uses other libraries that are part of Open
 Dylan, but what if you want to use a second library that you wrote yourself or
 that you installed from GitHub?  How will :program:`dylan-compiler` find the
-sources for that library?  The answer is registries.  For each Dylan library
-that isn't part of Open Dylan itself, you create a file in the registry that
-points to the ".lid" file for the library.  For example, here's the registry
-file for hello-world, created in the previous section. Note that this assumes
-you are still in the directory created by :command:`dylan new application`::
+sources for that library?  The answer is registries.
 
-  $ cat ./registry/{platform}/hello-world   # substitute your platform
-  abstract://dylan/hello-world.lid
+For each Dylan library that isn't part of Open Dylan itself, you create a file
+in the registry which is named the same as the library and contains a pointer
+to the ".lid" file for the library.  For example, here's the registry file for
+hello-world, created in the previous section. Note that this assumes you are
+still in the directory created by `dylan new application
+<https://opendylan.org/package/dylan-tool/index.html#dylan-new-application>`_.
+
+::
+
+  $ ls registry/*/hello-world
+  registry/x86_64-darwin/hello-world
 
 What's going on here?  First of all, the registry mechanism makes it possible
-to have platform-specific libraries.  Anything platform-independent goes in the
-:file:`registry/generic` directory. Other supported platform names are
-``x86_64-freebsd``, ``x86_64-linux``, ``x86-win32``, etc. For a full list see
-`the Open Dylan registry
-<https://github.com/dylan-lang/opendylan/tree/master/sources/registry>`_.
+to have platform-specific libraries.  The `dylan
+<https://opendylan.org/package/dylan-tool/index.html>`_ tool currently always
+writes registry entries to a platform-specific directory, in this case
+``x86_64-darwin``, but anything platform-independent can actually go in the
+:file:`registry/generic` subdirectory.
 
 Platform-specific registry directories are searched before
 :file:`registry/generic`, so if you have a library that includes an extra file
-for Windows-only definitions, you can use two registry entries: one in the
-"x86-win32" directory and one in the "generic" directory.
+for Windows-only definitions, you can use two registry entries: one in
+:file:`registry/x86-win32/hello-world` pointing to the Windows-specific LID
+file and one in :file:`registry/generic/hello-world` pointing to the LID file
+that works on other platforms.
 
 Now let's look at the actual content of our hello-world registry file::
 
+  $ cat registry/x86_64-darwin/hello-world
   abstract://dylan/hello-world.lid
 
 What this is doing is locating a file *relative to the directory containing the
 registry directory itself*.  If the :file:`registry` directory is
-``/home/you/xyz/registry`` then ``abstract://dylan/hello-world.lid`` says the
-hello-world ".lid" file is in ``/home/you/xyz/hello-world.lid``.
+``/tmp/hello-world/registry`` then ``abstract://dylan/hello-world.lid`` says
+the hello-world LID file is in ``/tmp/hello-world/hello-world.lid``.
 "abstract://dylan/" is just boilerplate.
 
-When you invoke :program:`dylan-compiler` in the directory containing the
+When you invoke :program:`dylan-compiler` in the directory containing a
 "registry" directory it automatically uses that registry, in addition to (and
 taking precedence over) the registry in the Open Dylan installation directory.
 
-If you prefer to invoke the compiler from elsewhere, you can set the
-:envvar:`OPEN_DYLAN_USER_REGISTRIES` environment variable to point your
-registry directory. For example::
 
-  $ export OPEN_DYLAN_USER_REGISTRIES=/home/you/xyz/registry
+OPEN_DYLAN_USER_REGISTRIES
+--------------------------
 
-Once you've set :envvar:`OPEN_DYLAN_USER_REGISTRIES` to your new registry,
-:program:`dylan-compiler` can find the hello-world library source no matter
-what directory you're currently working in. You only need to specify the
-library name::
+If you prefer to invoke the compiler from outside your workspace or if you want
+to include multiple workspace registries when searching for libraries, you can
+set the :envvar:`OPEN_DYLAN_USER_REGISTRIES` environment variable. For
+example::
+
+  $ export OPEN_DYLAN_USER_REGISTRIES=/tmp/workspace1/registry
+
+Once you've set :envvar:`OPEN_DYLAN_USER_REGISTRIES`, :program:`dylan-compiler`
+can find library source code no matter what directory you're currently working
+in. You only need to specify the library name::
 
   $ cd /tmp
   $ dylan-compiler -build hello-world
 
 You can add more than one registry to :envvar:`OPEN_DYLAN_USER_REGISTRIES` by
 separating them with colons (Unix) or semicolons (Windows)::
 
-  $ export OPEN_DYLAN_USER_REGISTRIES=/my/registry:/their/registry
+  $ export OPEN_DYLAN_USER_REGISTRIES=/tmp/workspace1/registry:/tmp/workspace2/registry
+
+
+Registry Search Order
+---------------------
+
+For each step in the following list, the directory named for the current
+platform is searched **before** the "generic" directory.
+
+1. If :envvar:`OPEN_DYLAN_USER_REGISTRIES` is set then its list of registries
+   is searched in order.
+
+2. If a directory named :file:`registry` exists in the current working
+   directory where the Dylan compiler is started, it is searched.
+
+3. The internal Open Dylan registry in the :file:`sources/registry` directory
+   in your Open Dylan installation is searched last.
+
+To see the list of registries in the order they will be searched, use the
+``show registries`` command in the interactive compiler.  Example::
 
-.. note:: If :envvar:`OPEN_DYLAN_USER_REGISTRIES` is set, the "registry"
-          directory in the current working directory is ignored.
+  $ echo $OPEN_DYLAN_USER_REGISTRIES
+  OPEN_DYLAN_USER_REGISTRIES=/tmp/a:/tmp/b
+  $ cd /tmp/x
+  $ mkdir registry
+  $ dylan-compiler
+  > show registries
+    {personal registry in /tmp/a/x86_64-linux/}
+    {personal registry in /tmp/b/x86_64-linux/}
+    {personal registry in /tmp/x/registry/x86_64-linux/}
+    {personal registry in /opt/opendylan-2024.2/sources/registry/x86_64-linux/}
+    {personal registry in /tmp/a/generic/}
+    {personal registry in /tmp/b/generic/}
+    {personal registry in /tmp/x/registry/generic/}
+    {personal registry in /opt/opendylan-2024.2/sources/registry/generic/}