# 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 27 different languages:
+Mal is implemented in 43 different languages:
+* GNU awk
* Bash shell
* C
+* C++
* C#
* Clojure
* CoffeeScript
+* Crystal
+* Elixir
+* Erlang
+* ES6 (ECMAScript 6 / ECMAScript 2015)
+* F#
+* Factor
* Forth
* Go
+* Groovy
+* GNU Guile
* Haskell
* Java
-* Javascript ([Online Demo](http://kanaka.github.io/mal))
+* JavaScript ([Online Demo](http://kanaka.github.io/mal))
+* Julia
+* Kotlin
* Lua
* GNU Make
* mal itself
* PHP
* Postscript
* Python
+* RPython
* R
* Racket
* Ruby
* Rust
* Scala
+* Swift
+* Tcl
+* Vimscript
* Visual Basic.NET
-Mal is a learning tool. See the ([make-a-lisp process
-guide](process/guide.md)). Each implementation of mal is separated
-into 11 incremental, self-contained (and testable) steps that
-demonstrate core concepts of Lisp. The last step is capable of
-self-hosting (running the mal implementation of mal).
+Mal is a learning tool. See the [make-a-lisp process
+guide](process/guide.md). Each implementation of mal is separated into
+11 incremental, self-contained (and testable) steps that demonstrate
+core concepts of Lisp. The last step is capable of self-hosting
+(running the mal implementation of mal).
The mal (make a lisp) steps are:
mal/clojurewest2014.mal for the presentation that was given at the
conference (yes the presentation is a mal program).
+If you are interesting in creating a mal implementation (or just
+interested in using mal for something), please drop by the #mal
+channel on freenode. In addition to the [make-a-lisp process
+guide](process/guide.md) there is also a [mal/make-a-lisp
+FAQ](docs/FAQ.md) where I attempt to answer some common questions.
+
## Building/running implementations
+### 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.
+
+```
+cd gawk
+gawk -O -f stepX_YYY.awk
+```
+
### Bash 4
```
./stepX_YYY
```
+### C++
+
+*The C++ implementation was created by [Stephen Thirlwall (sdt)](https://github.com/sdt)*
+
+The C++ implementation of mal requires g++-4.9 or clang++-3.5 and
+a readline compatible library to build. See the `cpp/README.md` for
+more details:
+
+```
+cd cpp
+make
+ # OR
+make CXX=clang++-3.5
+./stepX_YYY
+```
+
+
### C# ###
The C# implementation of mal has been tested on Linux using the Mono
coffee ./stepX_YYY
```
+### Crystal
+
+*The Crystal implementation of mal was created by [Linda_pp](https://github.com/rhysd)*
+
+The Crystal implementation of mal has been tested with Crystal 0.8.0.
+
+```
+cd crystal
+crystal run ./stepX_YYY.cr
+ # OR
+make # needed to run tests
+./stepX_YYY
+```
+
+### 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.
+
+```
+cd erlang
+make
+ # OR
+MAL_STEP=stepX_YYY rebar compile escriptize # build individual step
+./stepX_YYY
+```
+
+### ES6 (ECMAScript 6 / ECMAScript 2015)
+
+The ES6 implementation uses the [babel](https://babeljs.io) compiler
+to generate ES5 compatible JavaScript. The generated code has been
+tested with Node 0.12.4.
+
+```
+cd es6
+make
+node build/stepX_YYY.js
+```
+
+
+### F# ###
+
+*The F# implementation was created by [Peter Stephens (pstephens)](https://github.com/pstephens)*
+
+The F# implementation of mal has been tested on Linux using the Mono
+F# compiler (fsharpc) and the Mono runtime (version 3.12.1). The mono C#
+compiler (mcs) is also necessary to compile the readline dependency. All are
+required to build and run the F# implementation.
+
+```
+cd fsharp
+make
+mono ./stepX_YYY.exe
+```
+
+### Factor
+
+*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)).
+
+```
+cd factor
+FACTOR_ROOTS=. factor -run=stepX_YYY
+```
+
### Forth
+*The Forth implementation was created by [Chris Houser (chouser)](https://github.com/chouser)*
+
```
cd forth
gforth stepX_YYY.fs
### Go
-You Go implementation of mal requires that go is installed on on the
+The Go implementation of mal requires that go is installed on on the
path. The implementation has been tested with Go 1.3.1.
```
```
+### Groovy
+
+The Groovy implementation of mal requires Groovy to run and has been
+tested with Groovy 1.8.6.
+
+```
+cd groovy
+make
+groovy ./stepX_YYY.groovy
+```
+
+### GNU Guile 2.1+
+
+*The Guile implementation was created by [Mu Lei (NalaGinrut)](https://github.com/NalaGinrut).*
+
+```
+cd guile
+guile -L ./ stepX_YYY.scm
+```
+
### Haskell
Install the Haskell compiler (ghc/ghci), the Haskell platform and
mvn -quiet exec:java -Dexec.mainClass=mal.stepX_YYY -Dexec.args="CMDLINE_ARGS"
```
-### Javascript/Node
+### JavaScript/Node
```
cd js
node stepX_YYY.js
```
+### Julia
+
+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.0-beta.
+
+```
+cd kotlin
+make
+java -jar stepX_YYY.jar
+```
+
### Lua
Running the Lua implementation of mal requires lua 5.1 or later,
make -f stepX_YYY.mk
```
-### Nim 0.10.3
+### Nim 0.11.0
+
+*The Nim implementation was created by [Dennis Felsing (def-)](https://github.com/def-)*
-Running the Nim implementation of mal requires Nim's current devel branch
-(0.10.3) or later, and the nre library installed.
+Running the Nim implementation of mal requires Nim 0.11.0 or later.
```
cd nim
### OCaml 4.01.0
+*The OCaml implementation was created by [Chris Houser (chouser)](https://github.com/chouser)*
+
```
cd ocaml
make
gs -q -dNODISPLAY -I./ stepX_YYY.ps
```
-### Python (2 or 3)
+### Python (2.X or 3.X)
```
cd python
python stepX_YYY.py
```
+### RPython
+
+You must have [rpython](https://rpython.readthedocs.org/) on your path
+(included with [pypy](https://bitbucket.org/pypy/pypy/)).
+
+```
+cd rpython
+make # this takes a very long time
+./stepX_YYY
+```
+
### R
The R implementation of mal requires R (r-base-core) to run.
```
cd racket
-./stepX_YYY.rb
+./stepX_YYY.rkt
```
### Ruby (1.9+)
ruby stepX_YYY.rb
```
-### Rust (0.13)
+### Rust (1.0.0 nightly)
The rust implementation of mal requires the rust compiler and build
tool (cargo) to build.
scala -classpath target/scala*/classes stepX_YYY
```
+### Swift
+
+*The Swift implementation was created by [Keith Rollin](https://github.com/keith-rollin)*
+
+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
+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
The are nearly 500 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
-uses pexpect to launch a Mal step implementation and then feeds the
-tests one at a time to the implementation and compares the
-output/return value to the expected output/return value.
+launches a Mal step implementation and then feeds the tests one at
+a time to the implementation and compares the output/return value to
+the expected output/return value.
To simplify the process of running tests, a top level Makefile is
provided with convenient test targets.
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
### Performance tests
+Warning: These performance tests are neither statistically valid nor
+comprehensive; runtime performance is a not a primary goal of mal. If
+you draw any serious conclusions from these performance tests, then
+please contact me about some amazing oceanfront property in Kansas
+that I'm willing to sell you for cheap.
+
* To run performance tests against a single implementation:
```
make perf^IMPL
### 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^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^js
```
+## Docker test environment
+
+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).
+
+Build 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
+```
+
+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
+```
+
+**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.
+
## License
Mal (make-a-lisp) is licensed under the MPL 2.0 (Mozilla Public
License 2.0). See LICENSE.txt for more details.
-