Re: plan for merging guile-vm docs into guile manual

[Ludovic Courtès]

Hello!

Andy Wingo <address@hidden> writes:

> The biggest regression that I know of is that the traps interface
> won't work with compiled code.

<broken record>
  The reader interface is unusable as well.
</broken record>

Seriously, I consider it an annoyance, but I don't know how many people
are concerned about this.  Only 3 files in Guile core refer to
`read-(enable|disable|options)', so it surely isn't much of a problem
for Guile itself.

I suppose it'd be easy to hack something in the Scheme translator,
perhaps making it optional.  Maybe I could look into it myself and
report back.

> The general plan that I've come up with is that we should interleave
> notes about compilation through the manual in all places that we talk
> about evaluation or memoization, and then at the end of the manual, we
> should add a separate toplevel section: "History and Implemention
> Details".
>
> We would fold in the "Data representation" into this section, and use it
> to talk about where Guile has come from (something I've always thought
> is lacking, in our public narrative), how it is implemented today, and
> where it's going (generally speaking).
>
> So we can talk about the memoizer/evaluator and its strengths, its
> principles of a highly dynamic development environment, its origins in
> "low-latency programming", in which we reduce to the minimum the delay
> between writing code and having it active.

Sounds like a good idea!

> At that point we can talk about the data representation used in Guile,
> as coming from SCM and being one of the fastest hand-coded interpreters
> out there.

Fastest?!  All "major" Scheme implementations come with an interpreter,
and it should be easy to pick one of them and show that it's faster than
Guile (I know I noticed that with Bigloo's interpreter, even though that
interpreter has the reputation of being quite slow).  Granted, they may
not all have the same feature set, in particular pthread support, but
still.

To summarize, I think it's a good idea to describe that philosophy and
genesis, but let's use consensual wording.  ;-)

> At that point we talk about the VM and its model: its registers, its
> memory model, its execution model, the representation of programs in
> memory, the representation of compiled code on disk, heap, stack, and
> toplevel variables, etc.
>
> Then we can describe the interface of the compiler: `compile' and
> `compile-file', `guile-tools compile', and the disassembler. Perhaps
> this section could actually go in the main reference, along with
> documentation for `load', `eval', et al.
>
> Then we can talk about the implementation of the compiler, its
> multilingual translation system, GHIL, GLIL, and all the rest. (It would
> be good to add GHIL and GLIL language definitions, so you can type them
> in directly at the REPL.) Also what optimizations the compiler
> implements, notes on performance, and some suggestions for future
> directions (JIT, etc). We can also devote a section to the VM
> instruction set around here, including a section on how to add new
> instructions, issues of compiled code compatibility, and when it is
> appropriate to add a new instruction.

Part of that already exists in `guile-vm.texi'.  Are you planning to
somehow start from there or rewrite something?

Thanks for doing this!

Ludo'.