[Chicken-users] Understanding modules?

[Norman Gray]

Greetings.

...again, on my second day with Chicken.  I can't easily tell from the 
docs what is the idiomatic pattern for usage of Chicken modules.  Can 
anyone point me to a reference?

[ I hope it's useful to ask these somewhat beginner questions.  When I 
become less naive about Chicken I will be no longer able to identify 
new-user gaps.  Hence also the slightly stream-of-consciousness flavour 
of the following. ]

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

The chapter 'Using the Compiler' gives an example of a program in 
multiple source files.  The relationship between the sources is 
indicated by (declare (uses bar)) and (declare (unit bar)).  The 
documentation says 'In this case foo.scm is the main module, because it 
doesn't have a unit declaration' (right, so that's where the main 
program entry point comes from: main() is inserted into the any and all 
source units which don't have (declare (unit xxx)) ), and I can compile 
source units separately with 'csc -c' and 'link' them with 'csc -o main 
*.o'.  So this is suggesting that this is very analogous to the idea of 
modules in C: everything at the top level is visible outside.

The description of unit and uses in the 'Declarations' section again 
suggests that these are 'compilation units' and 'library-units', with 
the language again suggesting that the C analogy is a reasonable one.

OK -- I think I understand that.   Good.

----

But if I want to use modules, it's quite hard to work out what to do.  I 
think the reason for that is that the documentation is missing a 
high-level initial discussion of the distinctions between

  * compilation units
  * extensions
  * import libraries
  * load vs use vs import

The natural place for that, I think, is at the top of the 'Modules' 
chapter, just before the documentation of the 'module' form.  It doesn't 
have to be long, but I think the reader does have to have these concepts 
straight before the rest of this chapter makes sense.

What I think I understand is:

  * 'compilation units' are very like the analogous concept in C (etc): 
you can 'csc -c' all the units, tie them together with (declare (uses 
foo)), and link them with 'csc *.o').  Simple, but all the bindings end 
up global.

  * 'import' makes the bindings of a module visible in other 
compilation units, but has nothing to do with code in libraries (ie, 
ultimately compiled C code)

  * a 'library' (a.k.a. 'import library') is a collection of object 
code generated by -shared, plus some glue information in foo.shared.scm

  * 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 (or more 
typically specify 'require-extension' or 'use').  Presumably both the 
'chicken' and 'scheme' modules use only scheme bindings, which is why we 
_import_ those, but must _use_ posix (for example).  But I can't just 
use 'use' for both: saying (use chicken scheme) doesn't work.  How do I 
tell the difference between those modules which need 'use' and those 
modules which must use only 'import'?

  * an 'extension' is a library which is installed as an egg; however 
'require-extension' is just 'require-library' + 'import', and isn't 
specific to extensions.

Is that approximately correct?

Once one understands these points (if I have!), the rest of the text in 
the 'Modules' chapter is clear and lucid in retrospect (though I still 
don't understand the (use posix) / (import scheme) point above).  But 
without that introduction, it takes a lot of effort to work out what way 
is up.

----

Also: I think that the 'Modules' chapter could use another example at 
the end of 'Examples of using modules', showing how to compile this 
module to a program, and explaining what each step does.  That would 
nicely pair with the above discussion at the top of the chapter.

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.

I hope this screed has been useful in illustrating the naive reader's 
thought processes when working through the manual.

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.

All the best,

Norman


--
Norman Gray  :  https://nxg.me.uk
SUPA School of Physics and Astronomy, University of Glasgow, UK