Re: [Chicken-users] Understanding modules?

[Norman Gray]

John and all, hello.

On 22 May 2016, at 1:59, John Cowan wrote:


It's also worth noting that use (or
require-extension, which is the same thing) depends on the module 
having

the same name as the file.


Thanks: It did look as if that assumption was baked in somewhere; if the 
process _depends_ on the naming, then...




A module may _export_ a subset of the bindings defined in its body, 
making those bindings visible to other code which _imports_ the module, 
at compilation time.  A module must be _loaded_ into a CHICKEN 
interpreter before its bindings can be imported; this loading can happen 
explicitly, or more commonly as a side-effect of some higher level 
expression, as below; this loading happens at run-time.  In CHICKEN, the 
loadable object can be either the Scheme source code in a `.scm` file, 
or a shared object compiled with `csc -shared`.


If, as is usually the case, you compile code which depends on other 
modules, then you must use an _import library_; this is generated by 
`csc` when given the option `-emit-all-import-libraries`.  In the most 
common case, a file foo.scm will contain a single (module foo ...) form, 
and the compilation should be done with `-emit-all-import-libraries`, 
which generates a file `foo.import.scm` named after the module.  If a 
module uses this naming pattern, then the expression `(use foo)` (or 
equivalently `(require-extension foo)`) will automatically handle 
finding and loading the library, and importing its symbols.


The `(module ...)` form is documented below.  See also the discussion of 
`require-extension` and `use` on 
, 
and possibly the discussion of `require` on 





Best wishes,

Norman


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

___
Chicken-users mailing list
Chicken-users@nongnu.org
https://lists.nongnu.org/mailman/listinfo/chicken-users

Re: [Chicken-users] Understanding modules?

[Norman Gray]

Evan and all, hello.

On 22 May 2016, at 3:15, Evan Hanson wrote:

A quick note about units and modules: the two are different things 
used

for different purposes. The former has to do with controlling the
compilation and linking of separate application components, whereas 
the

latter is about namespace management.


I did get that impression, after it was explained on-list.  But the 
prominence of the manual's description of units in 'Basic mode of 
operation' and 'Using the compiler', the existence of a worked example 
in the latter, and the sequencing before modules, gave me the very 
strong impression that '"unit" is how Chicken spells "module"'.  In 
contrast, the first real mention of modules is hidden away inside 
'Supported language', in what looks like a reference section rather than 
anything introductory.  The first paragraph in 'Basic mode of operation' 
does mention modules, but in a way which is easily consistent with the 
'spelling' remark above.



The hunt continues for the best
way to explain either of these features in the manual (particularly
without confusing the two with one another, or with other features 
such

as deployment or the use of dynamic libraries),


I don't have a magic answer to that, but on reflection, I think a brief 
overview at the top of (hmmm...) 'Basic mode of operation' -- or 
possibly 'Using the compiler' -- would provide extremely useful context 
for the reader.  It needn't be an essay, but something terse which says 
'units, modules, deployment and dynamic libraries are orthogonal 
concepts, are used for the following purposes, A, B, C, D, and are 
further documented in W, X, Y and Z.'


I think most schemers will be used to the idea that they have to read 
things multiple times, and anyone who's enjoyed RnRS knows that the 
logical order is not necessarily the same as the friendliest tutorial 
order (and prefers the former), but this depends on clear signposts to 
what's (going to be) explained where.



This looks like a bug to me. Based on the commands you listed, that
application "main/main" should work fine, so I suggest reporting this 
on

bugs.call-cc.org, if you don't mind.


RIghto: I've asked for an account there.


managed by that egg's maintainer, so bug reports about their
documentation will ideally be grouped by extension rather than in one
big ticket so they can be correctly assigned.


Will do.

Best wishes,

Norman


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

___
Chicken-users mailing list
Chicken-users@nongnu.org
https://lists.nongnu.org/mailman/listinfo/chicken-users

Re: [Chicken-users] Understanding modules?

[Evan Hanson]

Hi Norman,

A quick note about units and modules: the two are different things used
for different purposes. The former has to do with controlling the
compilation and linking of separate application components, whereas the
latter is about namespace management. The hunt continues for the best
way to explain either of these features in the manual (particularly
without confusing the two with one another, or with other features such
as deployment or the use of dynamic libraries), but they're almost
entirely orthogonal and equally useful, just for different things.

> Deployment: Either in the 'Modules' page (along with the other examples at
> the end) or in the 'Deployment' page, it would be useful to show how to
> deploy a program using modules.  The obvious things don't appear to work:

This looks like a bug to me. Based on the commands you listed, that
application "main/main" should work fine, so I suggest reporting this on
bugs.call-cc.org, if you don't mind. 

> I've assembled a short list of minor buglets in eggs and egg documentation.
> Is it best if I report them here, or should I ask for an account on
> http://bugs.call-cc.org ?

The best approach is probably to report these individually on
bugs.call-cc.org. The documentation for any given egg is generally
managed by that egg's maintainer, so bug reports about their
documentation will ideally be grouped by extension rather than in one
big ticket so they can be correctly assigned.

Thanks very much for the detailed write-up -- feedback like this is
quite valuable.

Cheers,

Evan

___
Chicken-users mailing list
Chicken-users@nongnu.org
https://lists.nongnu.org/mailman/listinfo/chicken-users

Re: [Chicken-users] Understanding modules?

[John Cowan]

Norman Gray scripsit:

> A puzzle: in his message John mentioned that 'Use [...] installs the
> file and imports it into the current module.'  I'm puzzled at this
> use of 'install'.  

It should have been "loads".  It's also worth noting that use (or
require-extension, which is the same thing) depends on the module having
the same name as the file.

-- 
 John Cowan  http://www.ccil.org/~cowanco...@ccil.org
   Si hoc legere scis, nimium eruditionis habes.

___
Chicken-users mailing list
Chicken-users@nongnu.org
https://lists.nongnu.org/mailman/listinfo/chicken-users

Re: [Chicken-users] Understanding modules?

[Norman Gray]

Greetings.

On 16 Mar 2016, at 17:01, Norman Gray wrote:

Thank you Oleg and John, for these explanations.  I won't be back in 
Chicken-land for a couple of days, but as soon as I can I'll aim to 
understand this point well enough to offer a draft of additional text 
for the manual.


A little while ago, I was asking some new-user questions about modules, 
and received very useful clarifications from John Cowan and Oleg Kolosov 
-- for which, many thanks.  Finally, I have a chance to rework these 
into some suggested changes for the corresponding parts of the Chicken 
manual.  The text below includes some additional text, and mentions some 
remaining puzzles.


The page  
says that 'The most portable way of creating separately linkable 
entities is supported by so-called units', and describes the (declare 
(uses UNITNAME)) expression.  The next page, 
, includes a 
section 'An example with multiple files', which illustrates a process 
for combining multiple bodies of code into a single executable, using 
units -- (declare (uses bar)).  This gives the strong impression that 
using units is the preferred, or idiomatic, way of combining separate 
bodies of code.


However John remarked, regarding units, that '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.'  In the same thread 
Oleg said that the use of unit files 'is generally frowned upon.'  In 
that case, is it desirable to have them appear so early and so 
prominently in the Chicken manual?  I appreciate it may be the logical 
place from an implementation point of view.


I get the impression from the list that it is instead modules that are 
the preferred way of combining bodies of code; if so, then it might be 
useful to remove the discussion of units in the 'Using the compiler' 
page, or at least note that this is a low-level feature which should be 
used in practice only via modules, and pointing to 
.


The 'Modules' page could I think be a little clearer about the 
distinctions between importing, loading and using modules.  If these 
distinctions aren't clear in the reader's head (well, _this_ reader's 
head, at least), then the rest of the text is rather harder work than it 
need be.  Can I suggest something like the following text, which is 
heavily based on John's and Oleg's replies in this thread?  This would 
be located just before the documentation of the 'module' form in this 
page.




A module may _export_ a subset of the bindings defined in its body, 
making those bindings visible to other code which _imports_ the module, 
at compilation time.  A module must be _loaded_ into a CHICKEN 
interpreter before its bindings can be imported; this loading can happen 
explicitly, or more commonly as a side-effect of some higher level 
expression, as below; this loading happens at run-time.  In CHICKEN, the 
loadable object can be either the Scheme source code in a `.scm` file, 
or a shared object compiled with `csc -shared`.


If, as is usually the case, you compile code which depends on other 
modules, then you must use an _import library_; this is generated by 
`csc` when given the option `-emit-import-library`.  In the most common 
case where a file foo.scm contains a single (module foo ...) form, the 
compilation should be done with `-emit-all-import-libraries`, which 
generates a file `foo.import.scm` named after the module.  In that case, 
the expression `(use foo)` (or equivalently `(require-extension foo)`) 
will automatially handle finding and loading the library, and importing 
its symbols.


The `(module ...)` form is documented below.  See also the discussion of 
`require-extension` and `use` on 
, 
and possibly the discussion of `require` on 





The 'Modules' page suggests that we 'follow the general rule of (import 
chicken scheme) (use anything-else)'.  But this is the only mention of 
`(use ...)` on this page.  Perhaps the link above would resolve this.


Can I suggest avoiding the module name 'test' in 'Examples of using 
modules' -- there is already an egg called 'test', and thus a file 
test.import.so in the egg tree, so there is a certain amount of scope 
for path confusion (ahem).


It would be reassuring, at the end of the subsection 'Examples of using 
modules', to include an example of using the `hello.scm` module in 
compiled code.  With `hello.scm` changed so that the module is named 
`hello` rather than `test`:


% csc -emit-all-import-libraries -shared hello.scm
% ls hello*
hello.import.scmhello.scmhello.so
% cat main.scm
(use hello)
(hello)
% csc -o main main.scm
% ./main

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/~cowanco...@ccil.org
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

___
Chicken-users mailing list
Chicken-users@nongnu.org
https://lists.nongnu.org/mailman/listinfo/chicken-users

[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

___
Chicken-users mailing list
Chicken-users@nongnu.org
https://lists.nongnu.org/mailman/listinfo/chicken-users