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