X-Git-Url: http://git.hcoop.net/jackhill/mal.git/blobdiff_plain/3b7ef8c720695442da6bb531dc8315fa0f9b687f..53105a772876948738c04931757915245c73e3df:/README.md

diff --git a/README.md b/README.md
index 7a5c1d28..be33adfd 100644
--- a/README.md
+++ b/README.md
@@ -1,11 +1,14 @@
 # mal - Make a Lisp
 
+[![Build Status](https://travis-ci.org/kanaka/mal.svg?branch=master)](https://travis-ci.org/kanaka/mal)
+
 ## Description
 
 Mal is a Clojure inspired Lisp interpreter.
 
-Mal is implemented in 39 different languages:
+Mal is implemented in 51 languages:
 
+* Ada
 * GNU awk
 * Bash shell
 * C
@@ -14,6 +17,9 @@ Mal is implemented in 39 different languages:
 * Clojure
 * CoffeeScript
 * Crystal
+* D
+* Elixir
+* Emacs Lisp
 * Erlang
 * ES6 (ECMAScript 6 / ECMAScript 2015)
 * F#
@@ -23,15 +29,20 @@ Mal is implemented in 39 different languages:
 * Groovy
 * GNU Guile
 * Haskell
+* Haxe
+* Io
 * Java
 * JavaScript ([Online Demo](http://kanaka.github.io/mal))
 * Julia
+* Kotlin
 * Lua
 * GNU Make
 * mal itself
 * MATLAB
 * [miniMAL](https://github.com/kanaka/miniMAL)
 * Nim
+* Object Pascal
+* Objective C
 * OCaml
 * Perl
 * PHP
@@ -44,6 +55,9 @@ Mal is implemented in 39 different languages:
 * Rust
 * Scala
 * Swift
+* Swift 3
+* Tcl
+* Vimscript
 * Visual Basic.NET
 
 
@@ -70,8 +84,12 @@ The mal (make a lisp) steps are:
 
 Mal was presented publicly for the first time in a lightning talk at
 Clojure West 2014 (unfortunately there is no video). See
-mal/clojurewest2014.mal for the presentation that was given at the
-conference (yes the presentation is a mal program).
+examples/clojurewest2014.mal for the presentation that was given at the
+conference (yes the presentation is a mal program). At Midwest.io
+2015, Joel Martin gave a presentation on Mal titled "Achievement
+Unlocked: A Better Path to Language Learning".
+[Video](https://www.youtube.com/watch?v=lgyOAiRtZGw),
+[Slides](http://kanaka.github.io/midwest.io.mal/).
 
 If you are interesting in creating a mal implementation (or just
 interested in using mal for something), please drop by the #mal
@@ -81,8 +99,38 @@ FAQ](docs/FAQ.md) where I attempt to answer some common questions.
 
 ## Building/running implementations
 
+The simplest way to run any given implementation is to use docker.
+Every implementation has a docker image pre-built with language
+dependencies installed. You can launch the REPL using a convenience
+target in the top level Makefile (where IMPL is the implementation
+directory name and stepX is the step to run):
+
+```
+make DOCKERIZE=1 "repl^IMPL^stepX"
+    # OR stepA is the default step:
+make DOCKERIZE=1 "repl^IMPL"
+```
+
+
+### Ada
+
+*The Ada implementation was created by [Chris Moore](https://github.com/zmower)*
+
+The Ada implementation was developed with GNAT 4.9 on debian. It also
+compiles unchanged on windows if you have windows versions of git,
+GNAT and (optionally) make.  There are no external dependencies
+(readline not implemented).
+
+```
+cd ada
+make
+./stepX_YYY
+```
+
 ### GNU awk
 
+*The GNU awk implementation was created by [Miutsuru kariya](https://github.com/kariya-mitsuru)*
+
 The GNU awk implementation of mal has been tested with GNU awk 4.1.1.
 
 ```
@@ -100,7 +148,8 @@ bash stepX_YYY.sh
 ### C
 
 The C implementation of mal requires the following libraries (lib and
-header packages): glib, libffi6 and either the libedit or GNU readline library.
+header packages): glib, libffi6, libgc, and either the libedit or GNU readline
+library.
 
 ```
 cd c
@@ -140,6 +189,9 @@ mono ./stepX_YYY.exe
 
 ### Clojure
 
+For the most part the Clojure implementation requires Clojure 1.5,
+however, to pass all tests, Clojure 1.8.0-RC4 is required.
+
 ```
 cd clojure
 lein with-profile +stepX trampoline run
@@ -157,7 +209,7 @@ coffee ./stepX_YYY
 
 *The Crystal implementation of mal was created by [Linda_pp](https://github.com/rhysd)*
 
-The Crystal implemenation of mal has been tested with Crystal 0.7.2.
+The Crystal implementation of mal has been tested with Crystal 0.10.0.
 
 ```
 cd crystal
@@ -167,11 +219,54 @@ make   # needed to run tests
 ./stepX_YYY
 ```
 
+### D
+
+*The D implementation was created by [Dov Murik](https://github.com/dubek)*
+
+The D implementation of mal was tested with GDC 4.8.  It requires the GNU
+readline library.
+
+```
+cd d
+make
+./stepX_YYY
+```
+
+### Emacs Lisp
+
+*The Emacs Lisp implementation was created by [Vasilij Schneidermann](https://github.com/wasamasa)*
+
+The Emacs Lisp implementation of mal has been tested with Emacs 24.3
+and 24.5.  While there is very basic readline editing (`<backspace>`
+and `C-d` work, `C-c` cancels the process), it is recommended to use
+`rlwrap`.
+
+```
+cd elisp
+emacs -Q --batch --load stepX_YYY.el
+# with full readline support
+rlwrap emacs -Q --batch --load stepX_YYY.el
+```
+
+### Elixir
+
+*The Elixir implementation was created by [Martin Ek (ekmartin)](https://github.com/ekmartin)*
+
+The Elixir implementation of mal has been tested with Elixir 1.0.5.
+
+```
+cd elixir
+mix stepX_YYY
+# Or with readline/line editing functionality:
+iex -S mix stepX_YYY
+```
+
 ### Erlang
 
 *The Erlang implementation was created by [Nathan Fiedler (nlfiedler)](https://github.com/nlfiedler)*
 
-The Erlang implementation of mal requires [Erlang/OTP R17](http://www.erlang.org/download.html) and [rebar](https://github.com/rebar/rebar) to build.
+The Erlang implementation of mal requires [Erlang/OTP R17](http://www.erlang.org/download.html)
+and [rebar](https://github.com/rebar/rebar) to build.
 
 ```
 cd erlang
@@ -214,11 +309,11 @@ mono ./stepX_YYY.exe
 *The Factor implementation was created by [Jordan Lewis (jordanlewis)](https://github.com/jordanlewis)*
 
 The Factor implementation of mal has been tested with Factor 0.97
-([factorcode.org](factorcode.org)).
+([factorcode.org](http://factorcode.org)).
 
 ```
 cd factor
-FACTOR_ROOTS=src factor -run=stepX_YYY
+FACTOR_ROOTS=. factor -run=stepX_YYY
 ```
 
 ### Forth
@@ -275,6 +370,38 @@ make
 ./stepX_YYY
 ```
 
+### Haxe
+
+The Haxe implementation of mal requires Haxe version 3.2 to compile.
+Four different Haxe targets are supported: Neko, Python, C++, and
+JavaScript.
+
+```
+cd haxe
+# Neko
+make all-neko
+neko ./stepX_YYY.n
+# Python
+make all-python
+python3 ./stepX_YYY.py
+# C++
+make all-cpp
+./cpp/stepX_YYY
+# JavaScript
+make all-js
+node ./stepX_YYY.js
+```
+
+### Io
+
+*The Io implementation was created by [Dov Murik](https://github.com/dubek)*
+
+The Io implementation of mal has been tested with Io version 20110905.
+
+```
+cd io
+io ./stepX_YYY.io
+```
 
 ### Java 1.7
 
@@ -298,13 +425,25 @@ node stepX_YYY.js
 
 ### Julia
 
-The Julia implementation of mal has been tested with Julia 0.3.7.
+The Julia implementation of mal requires Julia 0.4.
 
 ```
 cd julia
 julia stepX_YYY.jl
 ```
 
+### Kotlin
+
+*The Kotlin implementation was created by [Javier Fernandez-Ivern](https://github.com/ivern)*
+
+The Kotlin implementation of mal has been tested with Kotlin 1.0.
+
+```
+cd kotlin
+make
+java -jar stepX_YYY.jar
+```
+
 ### Lua
 
 Running the Lua implementation of mal requires lua 5.1 or later,
@@ -349,6 +488,29 @@ nimble build
 ./stepX_YYY
 ```
 
+### Object Pascal
+
+The Object Pascal implementation of mal has been built and tested on
+Linux using the Free Pascal compiler version 2.6.2 and 2.6.4.
+
+```
+cd objpascal
+make
+./stepX_YYY
+```
+
+### Objective C
+
+The Objective C implementation of mal has been built and tested on
+Linux using clang/LLVM 3.6. It has also been built and tested on OS
+X using XCode 7.
+
+```
+cd objc
+make
+./stepX_YYY
+```
+
 ### OCaml 4.01.0
 
 *The OCaml implementation was created by [Chris Houser (chouser)](https://github.com/chouser)*
@@ -434,7 +596,7 @@ You must have [rpython](https://rpython.readthedocs.org/) on your path
 
 ```
 cd rpython
-make        # this takes a long time
+make        # this takes a very long time
 ./stepX_YYY
 ```
 
@@ -491,8 +653,9 @@ scala -classpath target/scala*/classes stepX_YYY
 
 *The Swift implementation was created by [Keith Rollin](https://github.com/keith-rollin)*
 
-The Swift implemenation of mal requires the Swift 1.2 compiler (XCode
-6.3) to build.
+The Swift implementation of mal requires the Swift 2.0 compiler (XCode
+7.0) to build. Older versions will not work due to changes in the
+language and standard library.
 
 ```
 cd swift
@@ -500,6 +663,42 @@ make
 ./stepX_YYY
 ```
 
+### Swift 3
+
+The Swift 3 implementation of mal requires the Swift 3.0 compiler. It
+has been tested with the development version of the Swift 3 from
+2016-02-08.
+
+```
+cd swift3
+make
+./stepX_YYY
+```
+
+### Tcl 8.6
+
+*The Tcl implementation was created by [Dov Murik](https://github.com/dubek)*
+
+The Tcl implementation of mal requires Tcl 8.6 to run.  For readline line
+editing support, install tclreadline.
+
+```
+cd tcl
+tclsh ./stepX_YYY.tcl
+```
+
+### Vimscript
+
+*The Vimscript implementation was created by [Dov Murik](https://github.com/dubek)*
+
+The Vimscript implementation of mal requires Vim to run.  It has been tested
+with Vim 7.4.
+
+```
+cd vimscript
+./run_vimscript.sh ./stepX_YYY.vim
+```
+
 ### Visual Basic.NET ###
 
 The VB.NET implementation of mal has been tested on Linux using the Mono
@@ -518,7 +717,7 @@ mono ./stepX_YYY.exe
 
 ### Functional tests
 
-The are nearly 500 generic functional tests (for all implementations)
+The are over 600 generic functional tests (for all implementations)
 in the `tests/` directory. Each step has a corresponding test file
 containing tests specific to that step. The `runtest.py` test harness
 launches a Mal step implementation and then feeds the tests one at
@@ -537,31 +736,31 @@ make test
 * To run all tests against a single implementation:
 
 ```
-make test^IMPL
+make "test^IMPL"
 
 # e.g.
-make test^clojure
-make test^js
+make "test^clojure"
+make "test^js"
 ```
 
 * To run tests for a single step against all implementations:
 
 ```
-make test^stepX
+make "test^stepX"
 
 # e.g.
-make test^step2
-make test^step7
+make "test^step2"
+make "test^step7"
 ```
 
-* To run tests for a specifc step against a single implementation:
+* To run tests for a specific step against a single implementation:
 
 ```
-make test^IMPL^stepX
+make "test^IMPL^stepX"
 
 # e.g
-make test^ruby^step3
-make test^ps^step4
+make "test^ruby^step3"
+make "test^ps^step4"
 ```
 
 ### Self-hosted functional tests
@@ -570,14 +769,47 @@ make test^ps^step4
   as the test implementation and use the `MAL_IMPL` make variable
   to change the underlying host language (default is JavaScript):
 ```
-make MAL_IMPL=IMPL test^mal^step2
+make MAL_IMPL=IMPL "test^mal^step2"
 
 # e.g.
-make test^mal^step2   # js is default
-make MAL_IMPL=ruby test^mal^step2
-make MAL_IMPL=python test^mal^step2
+make "test^mal^step2"   # js is default
+make MAL_IMPL=ruby "test^mal^step2"
+make MAL_IMPL=python "test^mal^step2"
+```
+
+### Starting the REPL
+
+* To start the REPL of an implementation in a specific step:
+
 ```
+make "repl^IMPL^stepX"
 
+# e.g
+make "repl^ruby^step3"
+make "repl^ps^step4"
+```
+
+* If you omit the step, then `stepA` is used:
+
+```
+make "repl^IMPL"
+
+# e.g
+make "repl^ruby"
+make "repl^ps"
+```
+
+* To start the REPL of the self-hosted implementation, specify `mal` as the
+  REPL implementation and use the `MAL_IMPL` make variable to change the
+  underlying host language (default is JavaScript):
+```
+make MAL_IMPL=IMPL "repl^mal^stepX"
+
+# e.g.
+make "repl^mal^step2"   # js is default
+make MAL_IMPL=ruby "repl^mal^step2"
+make MAL_IMPL=python "repl^mal"
+```
 
 ### Performance tests
 
@@ -589,77 +821,70 @@ that I'm willing to sell you for cheap.
 
 * To run performance tests against a single implementation:
 ```
-make perf^IMPL
+make "perf^IMPL"
 
 # e.g.
-make perf^js
+make "perf^js"
 ```
 
 * To run performance tests against all implementations:
 ```
-make perf
+make "perf"
 ```
 
 ### Generating language statistics
 
-* To report line and byte stastics for a single implementation:
+* To report line and byte statistics for a single implementation:
 ```
-make stats^IMPL
+make "stats^IMPL"
 
 # e.g.
-make stats^js
+make "stats^js"
 ```
 
-* To report line and bytes stastics for general Lisp code (env, core
+* To report line and bytes statistics for general Lisp code (env, core
   and stepA):
 ```
-make stats-lisp^IMPL
+make "stats-lisp^IMPL"
 
 # e.g.
-make stats-lisp^js
+make "stats-lisp^js"
 ```
 
-## Docker test environment
+## Dockerized testing
 
-There is a Dockerfile included in the `tests/docker` directory that
-builds a docker image based on Ubuntu Utopic that contains everything
-needed to run tests against all the implementations (except for MATLAB
-which is proprietary/licensed).
+Every implementation directory contains a Dockerfile to create
+a docker image containing all the dependencies for that
+implementation. In addition, the top-level Makefile contains support
+for running the tests target (and perf, stats, repl, etc) within
+a docker container for that implementation by passing *"DOCKERIZE=1"*
+on the make command line. For example:
 
-Build the the docker image using a provided script. WARNING: this will
-likely take over an hour to build from scratch and use more 3 GB of disk:
-```bash
-./tests/docker-build.sh
 ```
-
-Launch a docker container from that image built above. This will
-volume mount the mal directory to `/mal` and then give you a bash
-prompt in the container. You can then run individual mal
-implementations and tests:
-```bash
-./tests/docker-run.sh
+make DOCKERIZE=1 "test^js^step3"
 ```
 
-You can also specify a command to run within the container. For
-example, to run step2 tests for every implementation (except MATLAB):
-```bash
-./tests/docker-run.sh make SKIP_IMPLS="matlab" test^step2
+Existing implementations already have docker images built and pushed
+to the docker registry. However, if
+you wish to build or rebuild a docker image locally, the toplevel
+Makefile provides a rule for building docker images:
+
 ```
+make "docker-build^IMPL"
+```
+
 
 **Notes**:
-* JVM-based language implementations (Java, Clojure, Scala): you will
-  need to run these implementations once manually first before you can
-  run tests because runtime dependencies need to be downloaded to
-  avoid the tests timing out. These dependencies are download to
-  dot-files in the /mal directory so they will persist between runs.
-* Compiled languages: if your host system is different enough from
-  Ubuntu Utopic then you may need to re-compile your compiled
-  languages from within the container to avoid linker version
-  mismatches.
+* Docker images are named *"kanaka/mal-test-IMPL"*
+* JVM-based language implementations (Groovy, Java, Clojure, Scala):
+  you will probably need to run these implementations once manually
+  first (make DOCKERIZE=1 "repl^IMPL")before you can run tests because
+  runtime dependencies need to be downloaded to avoid the tests timing
+  out. These dependencies are download to dot-files in the /mal
+  directory so they will persist between runs.
 
 
 ## License
 
 Mal (make-a-lisp) is licensed under the MPL 2.0 (Mozilla Public
 License 2.0). See LICENSE.txt for more details.
-