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