Submodules
==========

Use cases / advantages of submodules:
* Organizing large modules
* A basic form of encapsulation within a module
* Possibility of incremental compilation
* Possibility of faster compilation through parallelization
* Prevents refactorings from having unintentional cross-submodule effects
* Bundling/vendoring code

Also, the step between a submodule and a real module is farily small
--> Submodules can fairly easilly be broken out and become standalone modules
    (as long as they don't depend on symbols from other submodules)

Perhaps something like this:

    main.slul

        \slul 0.0.0
        \name somelib
        \type library
        \depends xyz 1.0
        ...
        \submodule a
        \submodule b
        \source api_funcs.slul

        func work(arena) -> int

    api_funcs.slul

        func work(arena) -> bool
        {
            return do_stuff_a(arena) and
                   do_stuff_b(arena)
        }

    # It's not very nice to have several files called "main.slul"
    # (it makes it harder to search for them, and harder to identify
    # tabs in editors etc.). So the "main" file of a submodule could
    # perhaps be called <name>.slul instead.
    # - Note: the main file may not include itself with \source!
    a/a.slul

        \slul 0.0.0
        \name a
        \type submodule
        ...
        \source stuff.slul

        func do_stuff(arena) -> bool

    a/stuff.slul

        func do_stuff(arena) -> bool
        {
            # ...
            return true
        }

Problems
--------

* Should it be possible to compile a submodule from the submodule directory?
  If so, there has to be a way to locate the "top module".
* Should it be possible to have single-file modules, in addition to having
  one directory per module?
* How to specifiy \depends on other submodules?
* Should it be possible to specify common dependencies in the "top module"?
  Or version numbers only?
  Or not at all?

Alternative solutions
---------------------

* Rely on bundling instead (see namespaces.txt).
  i.e. have a directory called "subpkgs/" that contains the submodules
  and that is configured as a bundled package repository.