Rune - Clean up strings
[rune.git] / README
1
2                                   RUNE README
3                                  14 April 2016
4                                  Matthew Dillon
5
6     This archive is the Rune language suite and tool chain, written by
7     Matthew Dillon.  It is distributed under the Rune copyright which
8     can be found in the COPYRIGHT file.  This is basically an open-source
9     copyright but with some restrictions to disallow project forking for
10     a period of time, and a few other things.  It will eventually sunset into
11     a 2-clause BSD copyright and I may change the dates to sunset sooner,
12     but for the moment I need to keep relatively tight control over the
13     project.
14
15     Rune is a powerful object-oriented language with built-in high-
16     performance threading, automatic object locking, bounds checking,
17     and many other powerful features.  The current distribution implements
18     the Rune interpreter and the Rune code generator.   The interpreter
19     should be easily ported to linux (its DragonFly/BSD specific at the
20     moment).  The code generator is x86-64 (64 bit intel) only for now.  We
21     will also be soliciting for help writing an ARM generator or making the
22     LLVM backend work (a lot more difficult then it might seem, I immediately
23     hit regressions in LLVM that results in 10-20 minute llvm compilation
24     times for simple programs).
25
26     Rune uses the standard BSD build system.
27
28     This README is meant only as a 'getting started' overview.  More extensive
29     documentation is in docs/ and, frankly, at least until we get people on
30     board to help write documentation, understanding the language mostly
31     means going through the examples in classes/* and tests/*.
32
33         libruntime      - Support library for rune utilities and runtime for
34                           rune binaries.
35
36         librune         - Rune Language parser and resolver.
37
38         libgen          - Rune Language Interpreter and Code Generator.
39
40         ext_x11         - Basic X11 interface (dynamically loaded at
41                           parse-time and run-time), demonstrative of how to
42                           add core APIs to the language.
43
44         rune            - RUNE language front-end utility.
45
46         ras             - RAS  Rune Assembler utility.
47
48         classes         - Rune Language - base classes shipped with the
49                           language (gadgets gfx stdio sys etc)
50
51         tests           - Rune Language - Test programs.
52
53         docs            - Documentation (mostly HTML).
54
55                                    REPOSITORY
56
57     You can obtain the repository with the following GIT command:
58
59         git clone git://git.dragonflybsd.org/rune.git
60
61     If you are a DragonFly committer with permission to commit to the master
62     repo, we recommend these additional steps after creating the initial
63     clone:
64
65         # configure reasonable push defaults and set your username and
66         # email address for pushes.
67         #
68         git config --global push.default simple
69         git config --global --edit
70
71         # Then edit .git/config and change the repository to the master
72         # repo for pushes by changing the url line:
73         #
74         vi .git/config
75
76         (edit the file, change the url line)
77         url = ssh://crater.dragonflybsd.org/repository/git/rune.git
78
79                                     BUILDING
80
81     On a DragonFly system the repo can be built as a user or as root.
82
83         as root -       (recommended) This will install Rune in
84                         /usr/local/rune/ plus two symlinks in /usr/local/bin
85                         for 'ras' and 'rune'.
86
87         as user -       (not recommended) This will install Rune in
88                         ~/.rune/ plus two symlinks in ~/bin/ for 'ras' and
89                         'rune'.  Be sure that you have a ~/bin for your
90                         user and that your $PATH includes it.
91
92     You can also build with or without an independend object hierarchy.  We
93     recommend with (i.e. use make obj).  Make sure the source tree is clean
94     before creating the object hierarchy.  That way the source tree will
95     remain clean.
96
97     The suggested build sequence:
98
99         # WARNING! Be sure not to mix builds without the object hierarchy
100         #          with builds with the object hierarchy.  Your source
101         #          tree should remain clean when building with the object
102         #          hierarchy so make sure there aren't any junk object or
103         #          other files in it.
104         #
105         make clean cleandepend
106         make obj
107         make depend
108         make -j 8
109         make all install
110
111                                     TESTING
112
113     Interpreter.  From the rune repo:
114
115         tests/hello.d
116
117     Compiler (x86 64-bit only for now) examples.  You can generate
118     intermediate Rune assembly by specifying a '.m' suffix, or x86 assembly
119     with a '.s' suffix.  Otherwise rune will do everything needed to create
120     a binary.  Examples:
121
122         rune tests/hello.d -o x
123         ./x
124
125         # Generates intermediate RUNE assembly file only.  This stops
126         # after the rune build stage and does not run 'ras'.
127         #
128         rune tests/hello.d -o x.m
129
130         # Generates machine assembly file only.  This stops after
131         # 'ras' is run and does not run the platform assembler or linker.
132         #
133         rune tests/hello.d -o x.s
134
135         # Generates an actual binary.  This runs all stages, through ras,
136         # and into the platform assembler and linker to generate a binary.
137         # The binary requires the rune infrastructure in ~/.rune or
138         # /usr/local/rune (depending on how you built rune) to operate.
139         #
140         rune tests/hello.d -o x -g
141
142     X11 basic tests w/threads.  This will create a window with 900
143     simple input requestors each with a blinking cursor (which is
144     a thread, so 900+1 Rune threads and typically ~4-8 pthreads).  Under
145     the interpreter:
146
147         tests/gfxinput2.d
148
149     And under the compiler:
150
151         rune tests/gfxinput2.d -o x
152         ./x
153
154                                 Interpretation
155
156     You can interpret a rune script by making the script executable and
157     giving it a script startup as the first line:
158
159         #!/usr/local/bin/rune -x
160
161     See examples, in tests/*.d.  The interpreter can run just about
162     everything but threading is still a bit primitive and it will have
163     problems with the few things in Rune which don't use the event handler
164     and block in real system calls.  Be sure to use the -x option above to
165     tell rune to stop argument processing after the first filename, so
166     additional arguments you supply when you run it get fed into your
167     rune program verbatim.
168
169     The interpreter optimizes itself on the fly and is very fast, probably
170     near the top-end of performance for non-JIT interpreters.  Nominal code
171     will run only 4-8x slower and tight loops only 25x slower in the
172     interpreter.  For example, on a 3.4GHz Haswell the interpreter can
173     execute a tight loop for (i = 0; i < 1000000000L; ++i); with an overhead
174     of around 7ns per loop, which is significantly better than most other
175     interpreted languages.
176
177                                 Code Generation
178
179     Currently the only operational code generator is the 64-bit x86 backend
180     in the rune assembler.  This is the default code generation path which
181     you get when you specify an output file on the rune command line.  The
182     llvm backend is currently non-operational.  I was able to get it to work
183     previously but its a real bitch to interface to and I seem to be hitting
184     degenerate conditions which cause it to twiddle its thumbs for a very
185     long time on simple programs (sometimes upwards of 15 minutes!).  So I've
186     had to set it aside for now.
187
188     Rune generates pseudo-assembly output that it will feed into RAS (the
189     Rune assembler), which then optimizes and converts it to x86.  That is
190     fed into the normal compiler backend ('as', then 'cc' in linker mode).
191     RAS makes use of a number of special ELF features such as section
192     grouping and weak stubs.  My original intend was to develop an entire
193     toolchain but it simply became too much work so Rune generates assembly.
194
195     Currently Rune cannot really generate independent object modules for
196     Rune source files.  It really needs to generate a single output file
197     which gets fed through the assembler, compiler, and linker.  Ultimately
198     the intent is to be able to generate an object module at each library
199     demarc.
200
201     --
202
203     Rune's pseudo-assembly implements a nice orthogonal instruction set along
204     with some meta-instructions for locking and ref-counting to interface
205     with the runtime.  Rune generates the assembly (you can see it if you
206     output to a *.m file).  The assembly implements an infinite register
207     set and RAS is capable of optimizing stack-based memory objects into
208     registers when given appropriate hints, which RUNE generates.
209
210     RAS implements a fairly sophisticated register optimizer.  It certainly
211     can't compete with GCC but it's fast and it works pretty well.  It
212     converts the pseudo-assembly into a basic-block model, adding JMPs as
213     needed (it does not require RUNE to generate basic blocks as output).
214
215     RAS implements graph-based object life calculations for cacheable
216     stack-based memory objects and virtual registers and can do some
217     instruction pruning based on that.  It also implements extra-register
218     spills around calls if it thinks they are needed.
219
220     It implements conditional optimizations and is capable of both reversing
221     AND inverting conditional tests to produce relatively optimal code
222     flow.
223
224     RAS does not implement constant expression collapses, that's actually
225     something the RUNE frontend does during the compilation process so RAS
226     does not have (and does not need) any sort of complex expression handler.
227
228     RAS implements a number of simple instruction optimizations, patricularly
229     when zeroing small blocks with BZERO, using the instruction extension
230     as an alignment hint.
231
232     RUNE and RAS implement 32, 64, and 128-bit floats but do not implement any
233     floating point vectorization, and in-fact I might never implement
234     vectorization as a native feature.  What I may do instead is implement
235     core types for matrices and vectors and basic operations (there aren't
236     actually too many) that do.  That is way in the future though.
237
238     The Rune call model is *NOT* heavily optimized yet.  It uses a memory
239     vector for both call arguments AND return values which is not yet
240     registerized.  Also the mandatory locking is not heavily optimized yet,
241     so there is a lot of overhead associated with object locks and refs.
242
243     Despite that, Rune binaries should run quite fast.
244
245     --
246
247     Rune's run-time threading model is very sophisticated.  Basically it
248     uses sigjmpbuf()s without signal masking which is pretty much the
249     ultimate in terms of switching speed and compactness (roughly spills
250     14 registers and switches without having to make any system calls).
251
252     Rune uses N:M threading so the number of pthreads it creates is
253     relatively limited, making Rune threads EXTREMELY light-weight.  Since
254     Rune is a threading-centric language this winds up being very important.
255     The tests/gfxinput2.d test program demonstrates light-weight threading.
256
257                                 Documentation
258
259     The documentation will improve as the project progresses.  For the moment
260     you will need to learn by example, primariliy by looking at the various
261     tests in tests/*.d and the class hierarchy in classes/*.  The
262     docs/grammer.html and docs/overview.html files are fairly complete.
263
264