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