Re: [Chicken-users] Understanding modules?

[John Cowan]

Norman Gray scripsit:

> First: what (I think) I understand about compilation units.

Units go back to Chicken 3.  IMAO, you don't need to know anything
about them unless you are writing code to be incorporated into
the main Chicken build, which is unlikely.

>   * import libraries

An import library is an artifact of how Chicken modules are compiled.
When you compile a file containing a module, specifying the -J option
will cause a *.import.scm file to be created.  This file is required in
order to use the module.  Since it is Scheme, you can compile it as well
if you want to, which will speed up the performance of any macros declared
in your module.  You should not create an import library by hand.

>   * load vs use vs import

Load causes a file to be loaded *at run time*.  It is a standard part of
Scheme and has nothing to do with Chicken's module system.  You shouldn't
use it unless you actually need to load code based on decisions made at
run time.

Use (which can also be spelled require-extension) looks for a file foo.so
(compiled) or foo.scm (source) which declares a module foo.  It installs
the file and imports it into the current module.

Import causes the identifiers declared in a module which has already been
installed to be visible in the current environment.

>   * so in order to use functions defined in one module, in another,
> I must _first_ 'require-library' to take care of linking details,
> and _then_ 'import' the module to take care of the scheme bindings

That is necessary only if the file name is not the same as the module
name, or if you are rebinding standard Scheme names in your code.
Otherwise, you can stick to just use and (import scheme chicken).

> (or more typically specify 'require-extension' or 'use').

That is what you should typically use.

> Presumably both the 'chicken' and 'scheme' modules use only scheme
> bindings,

The bindings in those modules are automatically installed, so using them
makes no sense; you just need to import them into a module.  If you are
not in a module, they are already imported.

> which is why we _import_ those, but must _use_ posix (for
> example).  

We must say "use posix" to get the posix unit installed.

> How do I tell the difference between those modules which need 'use'
> and those modules which must use only 'import'?

In general, only scheme (standard R5RS bindings) and chicken (standard
Chicken bindings that aren't R5RS) need to be just imported, because
there are no scheme.scm and chicken.scm files defining those bindings.
Everything else needs to be used.  Note that it is safe to use a file
even if it has already been installed.

> Secondly, in the 'import libraries' section of 'Modules', it would
> be useful to note parenthetically that the 'emit-import-library'
> compiler option has '-s' as its short form -- this would help link
> it to the discussion in the 'Extensions' chapter.  Alternatively,
> use only the longer form in the 'Extensions' chapter.

Not -s but -J.  The purpose of -s is to make a compiled shared library rather
than a compiled application.

> Preconception alert: I'm guessing that it is indeed idiomatic
> Chicken good style to put all code into modules, yes?  If it's not,
> I may be going against the grain here.

Logically speaking, yes.  However, the code does not have to be physically
in the file containing the module declaration.  My style is to have a
file foo.scm which contains the module declaration including imports and
exports, and then (include "foo-impl.scm") which contains pure Scheme
code with no module forms, imports, or uses.  If foo-impl gets too large,
I break it into multiple files with multiple includes in foo.scm.

-- 
John Cowan          http://www.ccil.org/~cowan        address@hidden
How comes city and country to be filled with drones and rogues, our highways
with hackers, and all places with sloth and wickedness?
                --W. Blith, Eng. Improver Improved, 1652