README.md

   1 # mal - Make a Lisp
   2
   3 [![Build Status](https://travis-ci.org/kanaka/mal.svg?branch=master)](https://travis-ci.org/kanaka/mal)
   4
   5 ## Description
   6
   7 Mal is a Clojure inspired Lisp interpreter.
   8
   9 Mal is implemented in 55 languages:
  10
  11 * Ada
  12 * GNU awk
  13 * Bash shell
  14 * C
  15 * C++
  16 * C#
  17 * Clojure
  18 * CoffeeScript
  19 * Crystal
  20 * D
  21 * Elixir
  22 * Emacs Lisp
  23 * Erlang
  24 * ES6 (ECMAScript 6 / ECMAScript 2015)
  25 * F#
  26 * Factor
  27 * Forth
  28 * Go
  29 * Groovy
  30 * GNU Guile
  31 * Haskell
  32 * Haxe
  33 * Io
  34 * Java
  35 * JavaScript ([Online Demo](http://kanaka.github.io/mal))
  36 * Julia
  37 * Kotlin
  38 * Lua
  39 * GNU Make
  40 * mal itself
  41 * MATLAB
  42 * [miniMAL](https://github.com/kanaka/miniMAL)
  43 * Nim
  44 * Object Pascal
  45 * Objective C
  46 * OCaml
  47 * Perl
  48 * Perl 6
  49 * PHP
  50 * PL/pgSQL (Postgres)
  51 * PL/SQL (Oracle)
  52 * Postscript
  53 * Python
  54 * RPython
  55 * R
  56 * Racket
  57 * Ruby
  58 * Rust
  59 * Scala
  60 * Swift
  61 * Swift 3
  62 * Tcl
  63 * VHDL
  64 * Vimscript
  65 * Visual Basic.NET
  66
  67
  68 Mal is a learning tool. See the [make-a-lisp process
  69 guide](process/guide.md). Each implementation of mal is separated into
  70 11 incremental, self-contained (and testable) steps that demonstrate
  71 core concepts of Lisp. The last step is capable of self-hosting
  72 (running the mal implementation of mal).
  73
  74 The mal (make a lisp) steps are:
  75
  76 * [step0_repl](process/guide.md#step0)
  77 * [step1_read_print](process/guide.md#step1)
  78 * [step2_eval](process/guide.md#step2)
  79 * [step3_env](process/guide.md#step3)
  80 * [step4_if_fn_do](process/guide.md#step4)
  81 * [step5_tco](process/guide.md#step5)
  82 * [step6_file](process/guide.md#step6)
  83 * [step7_quote](process/guide.md#step7)
  84 * [step8_macros](process/guide.md#step8)
  85 * [step9_try](process/guide.md#step9)
  86 * [stepA_mal](process/guide.md#stepA)
  87
  88
  89 Mal was presented publicly for the first time in a lightning talk at
  90 Clojure West 2014 (unfortunately there is no video). See
  91 examples/clojurewest2014.mal for the presentation that was given at the
  92 conference (yes the presentation is a mal program). At Midwest.io
  93 2015, Joel Martin gave a presentation on Mal titled "Achievement
  94 Unlocked: A Better Path to Language Learning".
  95 [Video](https://www.youtube.com/watch?v=lgyOAiRtZGw),
  96 [Slides](http://kanaka.github.io/midwest.io.mal/).
  97
  98 If you are interesting in creating a mal implementation (or just
  99 interested in using mal for something), please drop by the #mal
 100 channel on freenode. In addition to the [make-a-lisp process
 101 guide](process/guide.md) there is also a [mal/make-a-lisp
 102 FAQ](docs/FAQ.md) where I attempt to answer some common questions.
 103
 104 ## Building/running implementations
 105
 106 The simplest way to run any given implementation is to use docker.
 107 Every implementation has a docker image pre-built with language
 108 dependencies installed. You can launch the REPL using a convenience
 109 target in the top level Makefile (where IMPL is the implementation
 110 directory name and stepX is the step to run):
 111
 112 ```
 113 make DOCKERIZE=1 "repl^IMPL^stepX"
 114     # OR stepA is the default step:
 115 make DOCKERIZE=1 "repl^IMPL"
 116 ```
 117
 118
 119 ### Ada
 120
 121 *The Ada implementation was created by [Chris Moore](https://github.com/zmower)*
 122
 123 The Ada implementation was developed with GNAT 4.9 on debian. It also
 124 compiles unchanged on windows if you have windows versions of git,
 125 GNAT and (optionally) make.  There are no external dependencies
 126 (readline not implemented).
 127
 128 ```
 129 cd ada
 130 make
 131 ./stepX_YYY
 132 ```
 133
 134 ### GNU awk
 135
 136 *The GNU awk implementation was created by [Miutsuru kariya](https://github.com/kariya-mitsuru)*
 137
 138 The GNU awk implementation of mal has been tested with GNU awk 4.1.1.
 139
 140 ```
 141 cd gawk
 142 gawk -O -f stepX_YYY.awk
 143 ```
 144
 145 ### Bash 4
 146
 147 ```
 148 cd bash
 149 bash stepX_YYY.sh
 150 ```
 151
 152 ### C
 153
 154 The C implementation of mal requires the following libraries (lib and
 155 header packages): glib, libffi6, libgc, and either the libedit or GNU readline
 156 library.
 157
 158 ```
 159 cd c
 160 make
 161 ./stepX_YYY
 162 ```
 163
 164 ### C++
 165
 166 *The C++ implementation was created by [Stephen Thirlwall (sdt)](https://github.com/sdt)*
 167
 168 The C++ implementation of mal requires g++-4.9 or clang++-3.5 and
 169 a readline compatible library to build. See the `cpp/README.md` for
 170 more details:
 171
 172 ```
 173 cd cpp
 174 make
 175     # OR
 176 make CXX=clang++-3.5
 177 ./stepX_YYY
 178 ```
 179
 180
 181 ### C# ###
 182
 183 The C# implementation of mal has been tested on Linux using the Mono
 184 C# compiler (mcs) and the Mono runtime (version 2.10.8.1). Both are
 185 required to build and run the C# implementation.
 186
 187 ```
 188 cd cs
 189 make
 190 mono ./stepX_YYY.exe
 191 ```
 192
 193
 194 ### Clojure
 195
 196 For the most part the Clojure implementation requires Clojure 1.5,
 197 however, to pass all tests, Clojure 1.8.0-RC4 is required.
 198
 199 ```
 200 cd clojure
 201 lein with-profile +stepX trampoline run
 202 ```
 203
 204 ### CoffeeScript
 205
 206 ```
 207 sudo npm install -g coffee-script
 208 cd coffee
 209 coffee ./stepX_YYY
 210 ```
 211
 212 ### Crystal
 213
 214 *The Crystal implementation of mal was created by [Linda_pp](https://github.com/rhysd)*
 215
 216 The Crystal implementation of mal has been tested with Crystal 0.17.4.
 217
 218 ```
 219 cd crystal
 220 crystal run ./stepX_YYY.cr
 221     # OR
 222 make   # needed to run tests
 223 ./stepX_YYY
 224 ```
 225
 226 ### D
 227
 228 *The D implementation was created by [Dov Murik](https://github.com/dubek)*
 229
 230 The D implementation of mal was tested with GDC 4.8.  It requires the GNU
 231 readline library.
 232
 233 ```
 234 cd d
 235 make
 236 ./stepX_YYY
 237 ```
 238
 239 ### Emacs Lisp
 240
 241 *The Emacs Lisp implementation was created by [Vasilij Schneidermann](https://github.com/wasamasa)*
 242
 243 The Emacs Lisp implementation of mal has been tested with Emacs 24.3
 244 and 24.5.  While there is very basic readline editing (`<backspace>`
 245 and `C-d` work, `C-c` cancels the process), it is recommended to use
 246 `rlwrap`.
 247
 248 ```
 249 cd elisp
 250 emacs -Q --batch --load stepX_YYY.el
 251 # with full readline support
 252 rlwrap emacs -Q --batch --load stepX_YYY.el
 253 ```
 254
 255 ### Elixir
 256
 257 *The Elixir implementation was created by [Martin Ek (ekmartin)](https://github.com/ekmartin)*
 258
 259 The Elixir implementation of mal has been tested with Elixir 1.0.5.
 260
 261 ```
 262 cd elixir
 263 mix stepX_YYY
 264 # Or with readline/line editing functionality:
 265 iex -S mix stepX_YYY
 266 ```
 267
 268 ### Erlang
 269
 270 *The Erlang implementation was created by [Nathan Fiedler (nlfiedler)](https://github.com/nlfiedler)*
 271
 272 The Erlang implementation of mal requires [Erlang/OTP R17](http://www.erlang.org/download.html)
 273 and [rebar](https://github.com/rebar/rebar) to build.
 274
 275 ```
 276 cd erlang
 277 make
 278     # OR
 279 MAL_STEP=stepX_YYY rebar compile escriptize # build individual step
 280 ./stepX_YYY
 281 ```
 282
 283 ### ES6 (ECMAScript 6 / ECMAScript 2015)
 284
 285 The ES6 implementation uses the [babel](https://babeljs.io) compiler
 286 to generate ES5 compatible JavaScript. The generated code has been
 287 tested with Node 0.12.4.
 288
 289 ```
 290 cd es6
 291 make
 292 node build/stepX_YYY.js
 293 ```
 294
 295
 296 ### F# ###
 297
 298 *The F# implementation was created by [Peter Stephens (pstephens)](https://github.com/pstephens)*
 299
 300 The F# implementation of mal has been tested on Linux using the Mono
 301 F# compiler (fsharpc) and the Mono runtime (version 3.12.1). The mono C#
 302 compiler (mcs) is also necessary to compile the readline dependency. All are
 303 required to build and run the F# implementation.
 304
 305 ```
 306 cd fsharp
 307 make
 308 mono ./stepX_YYY.exe
 309 ```
 310
 311 ### Factor
 312
 313 *The Factor implementation was created by [Jordan Lewis (jordanlewis)](https://github.com/jordanlewis)*
 314
 315 The Factor implementation of mal has been tested with Factor 0.97
 316 ([factorcode.org](http://factorcode.org)).
 317
 318 ```
 319 cd factor
 320 FACTOR_ROOTS=. factor -run=stepX_YYY
 321 ```
 322
 323 ### Forth
 324
 325 *The Forth implementation was created by [Chris Houser (chouser)](https://github.com/chouser)*
 326
 327 ```
 328 cd forth
 329 gforth stepX_YYY.fs
 330 ```
 331
 332 ### Go
 333
 334 The Go implementation of mal requires that go is installed on on the
 335 path. The implementation has been tested with Go 1.3.1.
 336
 337 ```
 338 cd go
 339 make
 340 ./stepX_YYY
 341 ```
 342
 343
 344 ### Groovy
 345
 346 The Groovy implementation of mal requires Groovy to run and has been
 347 tested with Groovy 1.8.6.
 348
 349 ```
 350 cd groovy
 351 make
 352 groovy ./stepX_YYY.groovy
 353 ```
 354
 355 ### GNU Guile 2.1+
 356
 357 *The Guile implementation was created by [Mu Lei (NalaGinrut)](https://github.com/NalaGinrut).*
 358
 359 ```
 360 cd guile
 361 guile -L ./ stepX_YYY.scm
 362 ```
 363
 364 ### Haskell
 365
 366 Install the Haskell compiler (ghc/ghci), the Haskell platform and
 367 either the editline package (BSD) or the readline package (GPL). On
 368 Ubuntu these packages are: ghc, haskell-platform,
 369 libghc-readline-dev/libghc-editline-dev
 370
 371 ```
 372 cd haskell
 373 make
 374 ./stepX_YYY
 375 ```
 376
 377 ### Haxe
 378
 379 The Haxe implementation of mal requires Haxe version 3.2 to compile.
 380 Four different Haxe targets are supported: Neko, Python, C++, and
 381 JavaScript.
 382
 383 ```
 384 cd haxe
 385 # Neko
 386 make all-neko
 387 neko ./stepX_YYY.n
 388 # Python
 389 make all-python
 390 python3 ./stepX_YYY.py
 391 # C++
 392 make all-cpp
 393 ./cpp/stepX_YYY
 394 # JavaScript
 395 make all-js
 396 node ./stepX_YYY.js
 397 ```
 398
 399 ### Io
 400
 401 *The Io implementation was created by [Dov Murik](https://github.com/dubek)*
 402
 403 The Io implementation of mal has been tested with Io version 20110905.
 404
 405 ```
 406 cd io
 407 io ./stepX_YYY.io
 408 ```
 409
 410 ### Java 1.7
 411
 412 The Java implementation of mal requires maven2 to build.
 413
 414 ```
 415 cd java
 416 mvn compile
 417 mvn -quiet exec:java -Dexec.mainClass=mal.stepX_YYY
 418     # OR
 419 mvn -quiet exec:java -Dexec.mainClass=mal.stepX_YYY -Dexec.args="CMDLINE_ARGS"
 420 ```
 421
 422 ### JavaScript/Node
 423
 424 ```
 425 cd js
 426 npm update
 427 node stepX_YYY.js
 428 ```
 429
 430 ### Julia
 431
 432 The Julia implementation of mal requires Julia 0.4.
 433
 434 ```
 435 cd julia
 436 julia stepX_YYY.jl
 437 ```
 438
 439 ### Kotlin
 440
 441 *The Kotlin implementation was created by [Javier Fernandez-Ivern](https://github.com/ivern)*
 442
 443 The Kotlin implementation of mal has been tested with Kotlin 1.0.
 444
 445 ```
 446 cd kotlin
 447 make
 448 java -jar stepX_YYY.jar
 449 ```
 450
 451 ### Lua
 452
 453 Running the Lua implementation of mal requires lua 5.1 or later,
 454 luarocks and the lua-rex-pcre library installed.
 455
 456 ```
 457 cd lua
 458 make  # to build and link linenoise.so
 459 ./stepX_YYY.lua
 460 ```
 461
 462 ### Mal
 463
 464 Running the mal implementation of mal involves running stepA of one of
 465 the other implementations and passing the mal step to run as a command
 466 line argument.
 467
 468 ```
 469 cd IMPL
 470 IMPL_STEPA_CMD ../mal/stepX_YYY.mal
 471
 472 ```
 473
 474 ### GNU Make 3.81
 475
 476 ```
 477 cd make
 478 make -f stepX_YYY.mk
 479 ```
 480
 481 ### Nim 0.11.0
 482
 483 *The Nim implementation was created by [Dennis Felsing (def-)](https://github.com/def-)*
 484
 485 Running the Nim implementation of mal requires Nim 0.11.0 or later.
 486
 487 ```
 488 cd nim
 489 make
 490   # OR
 491 nimble build
 492 ./stepX_YYY
 493 ```
 494
 495 ### Object Pascal
 496
 497 The Object Pascal implementation of mal has been built and tested on
 498 Linux using the Free Pascal compiler version 2.6.2 and 2.6.4.
 499
 500 ```
 501 cd objpascal
 502 make
 503 ./stepX_YYY
 504 ```
 505
 506 ### Objective C
 507
 508 The Objective C implementation of mal has been built and tested on
 509 Linux using clang/LLVM 3.6. It has also been built and tested on OS
 510 X using XCode 7.
 511
 512 ```
 513 cd objc
 514 make
 515 ./stepX_YYY
 516 ```
 517
 518 ### OCaml 4.01.0
 519
 520 *The OCaml implementation was created by [Chris Houser (chouser)](https://github.com/chouser)*
 521
 522 ```
 523 cd ocaml
 524 make
 525 ./stepX_YYY
 526 ```
 527
 528 ### MATLAB
 529
 530 The MATLAB implementation of mal has been tested with MATLAB version
 531 R2014a on Linux. Note that MATLAB is a commercial product. It should
 532 be fairly simple to support GNU Octave once it support classdef object
 533 syntax.
 534
 535 ```
 536 cd matlab
 537 ./stepX_YYY
 538 matlab -nodisplay -nosplash -nodesktop -nojvm -r "stepX_YYY();quit;"
 539     # OR with command line arguments
 540 matlab -nodisplay -nosplash -nodesktop -nojvm -r "stepX_YYY('arg1','arg2');quit;"
 541 ```
 542
 543 ### miniMAL
 544
 545 [miniMAL](https://github.com/kanaka/miniMAL) is small Lisp interpreter
 546 implemented in less than 1024 bytes of JavaScript. To run the miniMAL
 547 implementation of mal you need to download/install the miniMAL
 548 interpreter (which requires Node.js).
 549 ```
 550 cd miniMAL
 551 # Download miniMAL and dependencies
 552 npm install
 553 export PATH=`pwd`/node_modules/minimal-lisp/:$PATH
 554 # Now run mal implementation in miniMAL
 555 miniMAL ./stepX_YYY
 556 ```
 557
 558 ### Perl 5.8
 559
 560 For readline line editing support, install Term::ReadLine::Perl or
 561 Term::ReadLine::Gnu from CPAN.
 562
 563 ```
 564 cd perl
 565 perl stepX_YYY.pl
 566 ```
 567
 568 ### Perl 6
 569
 570 *The Perl 6 implementation was created by [Hinrik Örn Sigurðsson](https://github.com/hinrik)*
 571
 572 The Perl 6 implementation was tested on Rakudo Perl 6 2016.04.
 573
 574 ```
 575 cd perl6
 576 perl6 stepX_YYY.pl
 577 ```
 578
 579 ### PHP 5.3
 580
 581 The PHP implementation of mal requires the php command line interface
 582 to run.
 583
 584 ```
 585 cd php
 586 php stepX_YYY.php
 587 ```
 588
 589 ### Postscript Level 2/3
 590
 591 The Postscript implementation of mal requires ghostscript to run. It
 592 has been tested with ghostscript 9.10.
 593
 594 ```
 595 cd ps
 596 gs -q -dNODISPLAY -I./ stepX_YYY.ps
 597 ```
 598
 599 ### PL/pgSQL (Postgres SQL Procedural Language)
 600
 601 The PL/pgSQL implementation of mal requires a running Postgres server
 602 (the "kanaka/mal-test-plpgsql" docker image automatically starts
 603 a Postgres server). The implementation connects to the Postgres server
 604 and create a database named "mal" to store tables and stored
 605 procedures. The wrapper script uses the psql command to connect to the
 606 server and defaults to the user "postgres" but this can be overridden
 607 with the PSQL_USER environment variable. A password can be specified
 608 using the PGPASSWORD environment variable. The implementation has been
 609 tested with Postgres 9.4.
 610
 611 ```
 612 cd plpgsql
 613 ./wrap.sh stepX_YYY.sql
 614     # OR
 615 PSQL_USER=myuser PGPASSWORD=mypass ./wrap.sh stepX_YYY.sql
 616 ```
 617
 618 ### PL/SQL (Oracle SQL Procedural Language)
 619
 620 The PL/pgSQL implementation of mal requires a running Oracle DB
 621 server (the "kanaka/mal-test-plsql" docker image automatically
 622 starts an Oracle Express server). The implementation connects to the
 623 Oracle server to create types, tables and stored procedures. The
 624 default SQL*Plus logon value (username/password@connect_identifier) is
 625 "system/oracle" but this can be overridden with the ORACLE_LOGON
 626 environment variable. The implementation has been tested with Oracle
 627 Express Edition 11g Release 2. Note that any SQL*Plus connection
 628 warnings (user password expiration, etc) will interfere with the
 629 ability of the wrapper script to communicate with the DB.
 630
 631 ```
 632 cd plsql
 633 ./wrap.sh stepX_YYY.sql
 634     # OR
 635 ORACLE_LOGON=myuser/mypass@ORCL ./wrap.sh stepX_YYY.sql
 636 ```
 637
 638 ### Python (2.X or 3.X)
 639
 640 ```
 641 cd python
 642 python stepX_YYY.py
 643 ```
 644
 645 ### RPython
 646
 647 You must have [rpython](https://rpython.readthedocs.org/) on your path
 648 (included with [pypy](https://bitbucket.org/pypy/pypy/)).
 649
 650 ```
 651 cd rpython
 652 make        # this takes a very long time
 653 ./stepX_YYY
 654 ```
 655
 656 ### R
 657
 658 The R implementation of mal requires R (r-base-core) to run.
 659
 660 ```
 661 cd r
 662 make libs  # to download and build rdyncall
 663 Rscript stepX_YYY.r
 664 ```
 665
 666 ### Racket (5.3)
 667
 668 The Racket implementation of mal requires the Racket
 669 compiler/interpreter to run.
 670
 671 ```
 672 cd racket
 673 ./stepX_YYY.rkt
 674 ```
 675
 676 ### Ruby (1.9+)
 677
 678 ```
 679 cd ruby
 680 ruby stepX_YYY.rb
 681 ```
 682
 683 ### Rust (1.0.0 nightly)
 684
 685 The rust implementation of mal requires the rust compiler and build
 686 tool (cargo) to build.
 687
 688 ```
 689 cd rust
 690 cargo run --release --bin stepX_YYY
 691 ```
 692
 693 ### Scala ###
 694
 695 Install scala and sbt (http://www.scala-sbt.org/0.13/tutorial/Installing-sbt-on-Linux.html):
 696
 697 ```
 698 cd scala
 699 sbt 'run-main stepX_YYY'
 700     # OR
 701 sbt compile
 702 scala -classpath target/scala*/classes stepX_YYY
 703 ```
 704
 705 ### Swift
 706
 707 *The Swift implementation was created by [Keith Rollin](https://github.com/keith-rollin)*
 708
 709 The Swift implementation of mal requires the Swift 2.0 compiler (XCode
 710 7.0) to build. Older versions will not work due to changes in the
 711 language and standard library.
 712
 713 ```
 714 cd swift
 715 make
 716 ./stepX_YYY
 717 ```
 718
 719 ### Swift 3
 720
 721 The Swift 3 implementation of mal requires the Swift 3.0 compiler. It
 722 has been tested with the development version of the Swift 3 from
 723 2016-02-08.
 724
 725 ```
 726 cd swift3
 727 make
 728 ./stepX_YYY
 729 ```
 730
 731 ### Tcl 8.6
 732
 733 *The Tcl implementation was created by [Dov Murik](https://github.com/dubek)*
 734
 735 The Tcl implementation of mal requires Tcl 8.6 to run.  For readline line
 736 editing support, install tclreadline.
 737
 738 ```
 739 cd tcl
 740 tclsh ./stepX_YYY.tcl
 741 ```
 742
 743 ### VHDL
 744
 745 *The VHDL implementation was created by [Dov Murik](https://github.com/dubek)*
 746
 747 The VHDL implementation of mal has been tested with GHDL 0.29.
 748
 749 ```
 750 cd vhdl
 751 make
 752 ./run_vhdl.sh ./stepX_YYY
 753 ```
 754
 755 ### Vimscript
 756
 757 *The Vimscript implementation was created by [Dov Murik](https://github.com/dubek)*
 758
 759 The Vimscript implementation of mal requires Vim to run.  It has been tested
 760 with Vim 7.4.
 761
 762 ```
 763 cd vimscript
 764 ./run_vimscript.sh ./stepX_YYY.vim
 765 ```
 766
 767 ### Visual Basic.NET ###
 768
 769 The VB.NET implementation of mal has been tested on Linux using the Mono
 770 VB compiler (vbnc) and the Mono runtime (version 2.10.8.1). Both are
 771 required to build and run the VB.NET implementation.
 772
 773 ```
 774 cd vb
 775 make
 776 mono ./stepX_YYY.exe
 777 ```
 778
 779
 780
 781 ## Running tests
 782
 783 ### Functional tests
 784
 785 The are over 600 generic functional tests (for all implementations)
 786 in the `tests/` directory. Each step has a corresponding test file
 787 containing tests specific to that step. The `runtest.py` test harness
 788 launches a Mal step implementation and then feeds the tests one at
 789 a time to the implementation and compares the output/return value to
 790 the expected output/return value.
 791
 792 To simplify the process of running tests, a top level Makefile is
 793 provided with convenient test targets.
 794
 795 * To run all the tests across all implementations (be prepared to wait):
 796
 797 ```
 798 make test
 799 ```
 800
 801 * To run all tests against a single implementation:
 802
 803 ```
 804 make "test^IMPL"
 805
 806 # e.g.
 807 make "test^clojure"
 808 make "test^js"
 809 ```
 810
 811 * To run tests for a single step against all implementations:
 812
 813 ```
 814 make "test^stepX"
 815
 816 # e.g.
 817 make "test^step2"
 818 make "test^step7"
 819 ```
 820
 821 * To run tests for a specific step against a single implementation:
 822
 823 ```
 824 make "test^IMPL^stepX"
 825
 826 # e.g
 827 make "test^ruby^step3"
 828 make "test^ps^step4"
 829 ```
 830
 831 ### Self-hosted functional tests
 832
 833 * To run the functional tests in self-hosted mode, you specify `mal`
 834   as the test implementation and use the `MAL_IMPL` make variable
 835   to change the underlying host language (default is JavaScript):
 836 ```
 837 make MAL_IMPL=IMPL "test^mal^step2"
 838
 839 # e.g.
 840 make "test^mal^step2"   # js is default
 841 make MAL_IMPL=ruby "test^mal^step2"
 842 make MAL_IMPL=python "test^mal^step2"
 843 ```
 844
 845 ### Starting the REPL
 846
 847 * To start the REPL of an implementation in a specific step:
 848
 849 ```
 850 make "repl^IMPL^stepX"
 851
 852 # e.g
 853 make "repl^ruby^step3"
 854 make "repl^ps^step4"
 855 ```
 856
 857 * If you omit the step, then `stepA` is used:
 858
 859 ```
 860 make "repl^IMPL"
 861
 862 # e.g
 863 make "repl^ruby"
 864 make "repl^ps"
 865 ```
 866
 867 * To start the REPL of the self-hosted implementation, specify `mal` as the
 868   REPL implementation and use the `MAL_IMPL` make variable to change the
 869   underlying host language (default is JavaScript):
 870 ```
 871 make MAL_IMPL=IMPL "repl^mal^stepX"
 872
 873 # e.g.
 874 make "repl^mal^step2"   # js is default
 875 make MAL_IMPL=ruby "repl^mal^step2"
 876 make MAL_IMPL=python "repl^mal"
 877 ```
 878
 879 ### Performance tests
 880
 881 Warning: These performance tests are neither statistically valid nor
 882 comprehensive; runtime performance is a not a primary goal of mal. If
 883 you draw any serious conclusions from these performance tests, then
 884 please contact me about some amazing oceanfront property in Kansas
 885 that I'm willing to sell you for cheap.
 886
 887 * To run performance tests against a single implementation:
 888 ```
 889 make "perf^IMPL"
 890
 891 # e.g.
 892 make "perf^js"
 893 ```
 894
 895 * To run performance tests against all implementations:
 896 ```
 897 make "perf"
 898 ```
 899
 900 ### Generating language statistics
 901
 902 * To report line and byte statistics for a single implementation:
 903 ```
 904 make "stats^IMPL"
 905
 906 # e.g.
 907 make "stats^js"
 908 ```
 909
 910 * To report line and bytes statistics for general Lisp code (env, core
 911   and stepA):
 912 ```
 913 make "stats-lisp^IMPL"
 914
 915 # e.g.
 916 make "stats-lisp^js"
 917 ```
 918
 919 ## Dockerized testing
 920
 921 Every implementation directory contains a Dockerfile to create
 922 a docker image containing all the dependencies for that
 923 implementation. In addition, the top-level Makefile contains support
 924 for running the tests target (and perf, stats, repl, etc) within
 925 a docker container for that implementation by passing *"DOCKERIZE=1"*
 926 on the make command line. For example:
 927
 928 ```
 929 make DOCKERIZE=1 "test^js^step3"
 930 ```
 931
 932 Existing implementations already have docker images built and pushed
 933 to the docker registry. However, if
 934 you wish to build or rebuild a docker image locally, the toplevel
 935 Makefile provides a rule for building docker images:
 936
 937 ```
 938 make "docker-build^IMPL"
 939 ```
 940
 941
 942 **Notes**:
 943 * Docker images are named *"kanaka/mal-test-IMPL"*
 944 * JVM-based language implementations (Groovy, Java, Clojure, Scala):
 945   you will probably need to run these implementations once manually
 946   first (make DOCKERIZE=1 "repl^IMPL")before you can run tests because
 947   runtime dependencies need to be downloaded to avoid the tests timing
 948   out. These dependencies are download to dot-files in the /mal
 949   directory so they will persist between runs.
 950
 951
 952 ## License
 953
 954 Mal (make-a-lisp) is licensed under the MPL 2.0 (Mozilla Public
 955 License 2.0). See LICENSE.txt for more details.