Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

docs

  • Loading branch information...
commit 6e4c0d98018fdaa4207c51e733bb12c344971ca1 1 parent 70045cf
@txus authored
Showing with 95 additions and 29 deletions.
  1. +95 −29 README.md
View
124 README.md
@@ -1,45 +1,57 @@
# TerrorVM
-![TerrorVM](https://github.com/txus/terrorvm/raw/master/assets/tvm_large.png)
+A lightweight Virtual Machine for dynamic, object-oriented languages. It aims to
+be fast, as simple as possible, easily optimizable, with LLVM support, and
+easily targetable for language designers and implementors. That's why its
+interface (instruction set) is extensively documented and an example compiler is
+provided under the `compiler` folder.
-A lightweight Virtual Machine for dynamic, object-oriented languages.
+Before anything, I want to give special thanks to my awesome mentors [Jeremy
+Tregguna][jtregunna], [Brian Ford][brixen], [Dirkjan Bussink][dbussink] and
+[Evan Phoenix][evanphx]. Without their teachings and patience I would never have
+started this in the first place.
-TODO: Write a project description
+### Disclaimer
-## Building the VM
+I'd love to discuss literally **anything** about my choices regarding the design
+and the implementation of TerrorVM. Feel free to ping me [on twitter][twitter],
+drop me [an email][email], or if you are in Berlin, just grab some beers
+together :) After all,
- $ git clone git://github.com/txus/terrorvm.git
- $ cd terrorvm
- $ make
+![I have no idea what I'm
+doing](http://static2.fjcdn.com/comments/I+have+no+idea+what+I+m+doing+thread+_06af9676f192d84f17cf5a5816dc7523.jpg)
-To run the tests:
+## Object model
- $ make dev
+In TerrorVM, everything is an object, and every object may have a prototype. The
+basic value types that the VM provides are:
-And to clean the mess:
+* `Integer`: Simple integers.
+* `String`: Immutable strings.
+* `Vector`: Dynamically sized vectors that may contain any type.
+* `Map`: Hashmaps (for now only strings are supported as keys).
+* `Closure`: A first-class function.
+* `True`: True boolean.
+* `False`: False boolean.
+* `Nil`: Represents nothingness. It is falsy just like `false`.
- $ make clean
-
-## Running programs
+These basic types are objects themselves (of type `Object`). They are the
+prototype for any objects of their own kind, and are provided
+with all the functionality that those objects will need -- this is done
+in the [prelude][prelude], I'll explain what this is a bit further ahead.
-TerrorVM runs `.tvm` bytecode files such as the `hello_world.tvm` under the
-`examples` directory.
+Objects are simply collections of slots that may contain any kind of object.
- $ ./bin/vm examples/hello_world.tvm
-
-It ships with a simple compiler written in Ruby (Rubinius) that compiles a
-tiny subset of Ruby to `.tvm` files. Check out the `compiler` directory, which
-has its own Readme, and the `compiler/examples` where we have the
-`hello_world.rb` file used to produce the `hello_world.tvm`.
-
-TerrorVM doesn't need Ruby to run; even the example compiler is a proof of
-concept and could be written in any language (even in C obviously).
+I'm considering adding Traits, although I'll wait until I see a need for it. In
+the simplicity of Terror lies its power.
## Prelude
-TerrorVM tries to implement as much as possible in its own code. You can find a
-prelude under `compiler/examples/prelude.rb`, or in native format under
-`examples/prelude.tvm`.
+TerrorVM tries to implement as much as possible in its own code, rather than C.
+This makes it a perfect candidate as a multi-language VM to implement any
+language on top of it. You can find a [high-level prelude][prelude] under
+`compiler/examples/prelude.rb` that compiles down to [Terror native
+format][prelude_native] under `examples/prelude.tvm`.
This prelude wires up the VM primitives to the real objects at runtime, so that your code can use them conveniently.
@@ -61,6 +73,18 @@ just copy and modify it.
You can write your compiler in whatever language you prefer, of course.
+## Garbage collection
+
+The algorithm of choice for TerrorVM is [Baker's treadmill][gc], a real-time,
+non-moving GC algorithm. Unfortunately it is not implemented yet. It will be as
+soon as I understand how to do it. Remember it's a work in progress :)
+
+## Concurrency
+
+This is a really important topic these days, not to be overlooked. Although its
+concurrency support is not in place yet, it will feature forking, threads and
+coroutines, but I might change my mind as I learn more.
+
## Bytecode format
(I rewrote it entirely so I have to write the new format here soon.)
@@ -120,11 +144,43 @@ You can write your compiler in whatever language you prefer, of course.
* **DUMP**: Prints the contents of the value stack to the standard output.
+## Building the VM
+
+It uses the latest C standard (C11). It is supported by GCC and Clang, so you'll
+be alright.
+
+ $ git clone git://github.com/txus/terrorvm.git
+ $ cd terrorvm
+ $ make
+
+To run the tests:
+
+ $ make dev
+
+And to clean the mess:
+
+ $ make clean
+
+## Running programs
+
+TerrorVM runs `.tvm` bytecode files such as the `numbers.tvm` under the
+`examples` directory.
+
+ $ ./bin/tvm examples/numbers.tvm
+
+It ships with a simple compiler written in Ruby (Rubinius) that compiles a
+tiny subset of Ruby to `.tvm` files. Check out the `compiler` directory, which
+has its own Readme, and the `compiler/examples` where we have the
+`hello_world.rb` file used to produce the `hello_world.tvm`.
+
+**TerrorVM doesn't need Ruby to run**; even the example compiler is a proof of
+concept and could be written in any language (even in C obviously).
+
## Who's this
This was made by [Josep M. Bach (Txus)](http://txustice.me) under the MIT
-license. I'm [@txustice](http://twitter.com/txustice) on twitter (where you
-should probably follow me!).
+license. I'm [@txustice][twitter] on twitter (where you should probably follow
+me!).
## Contributing
@@ -133,3 +189,13 @@ should probably follow me!).
3. Commit your changes (`git commit -am 'Added some feature'`)
4. Push to the branch (`git push origin my-new-feature`)
5. Create new Pull Request
+
+[twitter]: https://twitter.com/txustice
+[email]: mailto:josep.m.bach@gmail.com
+[prelude]: https://github.com/txus/terrorvm/blob/master/compiler/kernel/prelude.rb
+[prelude_native]: https://github.com/txus/terrorvm/blob/master/kernel/prelude.tvm
+[gc]: http://www.pipeline.com/~hbaker1/NoMotionGC.html
+[jtregunna]: https://twitter.com/jtregunna
+[brixen]: https://twitter.com/brixen
+[dbussink]: https://twitter.com/dbussink
+[evanphx]: https://twitter.com/evanphx
Please sign in to comment.
Something went wrong with that request. Please try again.