     [file version.texi not included]

epsilon
*******

This is the manual documenting epsilon (version VERSION, last updated on UPDATED).

epsilon is an extensible programming language. [FIXME: say something more]

Copyright © 2005, 2013 Luca Saiu

Copyright © 2012 Université Paris 13

Written by Luca Saiu

     Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with the Invariant Sections being ``GNU General Public License'', with no Front-Cover texts and with the Back-Cover text being ``You have freedom to copy and modify this manual, like GNU software.''.

     A copy of the license is included in the section entitled ``GNU Free Documentation License''.

This manual is incomplete
*************************

This manual is very incomplete, actually just a stub.  The project needs actual documentation, and I plan to write it --- but not before the implementation itself is in a stable state.

At the present time I'm using this document mostly to try out ideas, for myself.  You're welcome to look if you're curious, but this is not really ready for users.

As the document gradually converges to a stable state, the presentation style will get richer, and I'll write English in a more careful way.  I'm actually a perfectionist.  But I can't waste time on my literary ambitions when I'm writing braindumps.

Where to look
=============

Ironically, I've already written at length about epsilon.

I've described its formal syntax and semantics, along with its philosophy and rationale, in my PhD thesis.  It's available at http://ageinghacker.net/publications#phd-thesis, and you're very welcome to read it.  Anyway, even if it also describes some source code, a thesis is not software documentation.  The mathematical treatment is not very accessible, and there is barely any mention of the user interface.

Essentially, my thesis provides a formal treatment of epsilon, also deriving some properties from its semantics, by formal proofs.  Such a formal system is inherently fragile, and can't be kept correct unless the language is frozen.  I don't plan any radical change in epsilon0 at the current time, but I might see some change to make in the future.  This is definitely a The Right Thing kind of project, and if it turns out that I have to destroy in order to build a better thing, I'm perfectly willing.  The thesis will stay as it is: it covers my language philosophy and describes very precisely a particular state in the language history.  At the present time, that state is a strict subset of the current state, which makes the description still very relevant.  In the future, this may change and the software may drift away into a different direction.

I plan to use my blog to post updates about epsilon; again, mostly thinking of myself as the public.  Blog posts will show ideas in a less stable state than this document, and will also deal with failed attempts.  The blog address is http://ageinghacker.net/blog

Of course you're welcome to write to the project mailing list (see http://lists.gnu.org/mailman/listinfo/epsilon-devel), or to me personally if you have questions.

Thanks.

--- Luca Saiu

Compilers
*********

Thanks to its architecture, compilers for epsilon are simply sets of ordinary procedures, technically part of its library.  There is no magic external program called a compiler: compilation is simply a functionality available to program, which can decide at some point to dump their state into a native executable file during their execution.

As a consequence of epsilon's architecture, its compilers are whole-program.

At the present time I'm working on the trivial compiler.  A more ambitious compiler, likely using GCC as the middle-end, will come later.

Trivial compiler
================

The trivial compiler is conceived to be very simple and easy to retarget, while still generating code good enough to beat an interpreter in performance.

As a slogan or design goal for the trivial compiler we could say 100,000 times smaller than GCC, only 10 times slower code.  The efficiency goal has not been attained yet.

A frontend translates epsilon0 to an intermediate stack-based language.  Several different backends exist to translate the intermediate code to either machine code, or to code for our custom SVM virtual machine.

Frontend
--------

[FIXME: It works and it doesn't really need much maintaining, but is
currently the ugliest part of the compiler.  I'd like to rewrite
that.]

Intermediate language
---------------------

The intermediate language has a very uniform behavior: parameters and results are passed through a thread-local stack.  Each procedure activation has a stack frame containing slots for input and output, for local variables, and scratch space.  The exact stack layout is specific to each backend.

Primitives may be implemented in portable C or in assembly.  In either case, they operate on the stack, popping parameters off the top of the stack, and pushing back results.  It is reasonable that a new backend starts with all primitives implemented in C, with the user replacing the most used ones with assembly implementations, for better performance.

At all moments the stack height relative to the currently procedure frame is known at compilation time, which enables backends to translate stack accesses into memory read and writes using a frame pointer plus constant offsets, with no need for a stack pointer at run time.

Such frame-pointer-relative operations are more efficient than the naïve alternative, but all the reading, writing and copying of intermediate data through memory (rather than registers) is the main reason the trivial compiler generates inefficient code.

[Some] backends may use a second stack per thread to hold return addresses and some temporaries which are only needed at procedure call time; since everything on the main stack gets to be data, having such a return stack simplifies the garbage collection interface.  As a secondary advantage, the return stack may be used for keeping some temporaries which are only needed at call time, which saves some shuffling on indirect calls.

The intermediate code distinguishes tail and non-tail calls.

[FIXME: add an example]

Backend-dependant runtime
.........................

Backends
--------

The Slow Virtual Machine
........................

[FIXME: The SVM exists, but it was conceived for a previous iteration
of the architecture.  I have to adapt it a little, which will result in
simpler code, and likely in better performance as well.]

MIPS backend
............

[FIXME: This already generates working code, even if the interface is kinda ugly]

x86_64 backend
..............

[FIXME: This will be easy to write.  As soon as the interface for the MIPS backend
gets stable, I'm gonna do this.  The actual assembly part is quite trivial.]

Future backends
...............

[FIXME: I plan to write a backends for PowerPC and x86 as well.  I
don't have access to hardware implementation of other architectures at
the present time, but I know where to ask when the time comes.]

GNU General Public License
**************************

     [file gpl.texi not included]

GNU Free Documentation License
******************************

     [file fdl.texi not included]