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 ### Scala ###
 899
 900 Install scala and sbt (http://www.scala-sbt.org/0.13/tutorial/Installing-sbt-on-Linux.html):
 901
 902 ```
 903 cd scala
 904 sbt 'run-main stepX_YYY'
 905     # OR
 906 sbt compile
 907 scala -classpath target/scala*/classes stepX_YYY
 908 ```
 909
 910 ### Scheme (R7RS) ###
 911
 912 *The Scheme implementation was created by [Vasilij Schneidermann](https://github.com/wasamasa)*
 913
 914 The Scheme implementation of mal has been tested with Chibi-Scheme
 915 0.7.3, Kawa 2.4, Gauche 0.9.5, CHICKEN 4.11.0, Sagittarius 0.8.3,
 916 Cyclone 0.6.3 (Git version) and Foment 0.4 (Git version).  You should
 917 be able to get it running on other conforming R7RS implementations
 918 after figuring out how libraries are loaded and adjusting the
 919 `Makefile` and `run` script accordingly.
 920
 921 ```
 922 cd scheme
 923 make symlinks
 924 # chibi
 925 scheme_MODE=chibi ./run
 926 # kawa
 927 make kawa
 928 scheme_MODE=kawa ./run
 929 # gauche
 930 scheme_MODE=gauche ./run
 931 # chicken
 932 make chicken
 933 scheme_MODE=chicken ./run
 934 # sagittarius
 935 scheme_MODE=sagittarius ./run
 936 # cyclone
 937 make cyclone
 938 scheme_MODE=cyclone ./run
 939 # foment
 940 scheme_MODE=foment ./run
 941 ```
 942
 943 ### Skew ###
 944
 945 *The Skew implementation was created by [Dov Murik](https://github.com/dubek)*
 946
 947 The Skew implementation of mal has been tested with Skew 0.7.42.
 948
 949 ```
 950 cd skew
 951 make
 952 node stepX_YYY.js
 953 ```
 954
 955
 956 ### Swift
 957
 958 *The Swift implementation was created by [Keith Rollin](https://github.com/keith-rollin)*
 959
 960 The Swift implementation of mal requires the Swift 2.0 compiler (XCode
 961 7.0) to build. Older versions will not work due to changes in the
 962 language and standard library.
 963
 964 ```
 965 cd swift
 966 make
 967 ./stepX_YYY
 968 ```
 969
 970 ### Swift 3
 971
 972 The Swift 3 implementation of mal requires the Swift 3.0 compiler. It
 973 has been tested with Swift 3 Preview 3.
 974
 975 ```
 976 cd swift3
 977 make
 978 ./stepX_YYY
 979 ```
 980
 981 ### Tcl 8.6
 982
 983 *The Tcl implementation was created by [Dov Murik](https://github.com/dubek)*
 984
 985 The Tcl implementation of mal requires Tcl 8.6 to run.  For readline line
 986 editing support, install tclreadline.
 987
 988 ```
 989 cd tcl
 990 tclsh ./stepX_YYY.tcl
 991 ```
 992
 993 ### TypeScript
 994
 995 *The TypeScript implementation was created by [vvakame](https://github.com/vvakame)*
 996
 997 The TypeScript implementation of mal requires the TypeScript 2.2 compiler.
 998 It has been tested with Node.js v6.
 999
1000 ```
1001 cd ts
1002 make
1003 node ./stepX_YYY.js
1004 ```
1005
1006 ### VHDL
1007
1008 *The VHDL implementation was created by [Dov Murik](https://github.com/dubek)*
1009
1010 The VHDL implementation of mal has been tested with GHDL 0.29.
1011
1012 ```
1013 cd vhdl
1014 make
1015 ./run_vhdl.sh ./stepX_YYY
1016 ```
1017
1018 ### Vimscript
1019
1020 *The Vimscript implementation was created by [Dov Murik](https://github.com/dubek)*
1021
1022 The Vimscript implementation of mal requires Vim 8.0 to run.
1023
1024 ```
1025 cd vimscript
1026 ./run_vimscript.sh ./stepX_YYY.vim
1027 ```
1028
1029 ### Visual Basic.NET ###
1030
1031 The VB.NET implementation of mal has been tested on Linux using the Mono
1032 VB compiler (vbnc) and the Mono runtime (version 2.10.8.1). Both are
1033 required to build and run the VB.NET implementation.
1034
1035 ```
1036 cd vb
1037 make
1038 mono ./stepX_YYY.exe
1039 ```
1040
1041 ### WebAssembly (wasm) ###
1042
1043 The WebAssembly implementation is written in
1044 [Wam](https://github.com/kanaka/wam) (WebAssembly Macro language) and
1045 runs under the [wac/wace](https://github.com/kanaka/wac) WebAssembly
1046 runtime.
1047
1048 ```
1049 cd wasm
1050 make
1051 wace ./stepX_YYY.wasm
1052 ```
1053
1054 ### Yorick
1055
1056 *The Yorick implementation was created by [Dov Murik](https://github.com/dubek)*
1057
1058 The Yorick implementation of mal was tested on Yorick 2.2.04.
1059
1060 ```
1061 cd yorick
1062 yorick -batch ./stepX_YYY.i
1063 ```
1064
1065
1066
1067 ## Running tests
1068
1069 ### Functional tests
1070
1071 The are over 600 generic functional tests (for all implementations)
1072 in the `tests/` directory. Each step has a corresponding test file
1073 containing tests specific to that step. The `runtest.py` test harness
1074 launches a Mal step implementation and then feeds the tests one at
1075 a time to the implementation and compares the output/return value to
1076 the expected output/return value.
1077
1078 To simplify the process of running tests, a top level Makefile is
1079 provided with convenient test targets.
1080
1081 * To run all the tests across all implementations (be prepared to wait):
1082
1083 ```
1084 make test
1085 ```
1086
1087 * To run all tests against a single implementation:
1088
1089 ```
1090 make "test^IMPL"
1091
1092 # e.g.
1093 make "test^clojure"
1094 make "test^js"
1095 ```
1096
1097 * To run tests for a single step against all implementations:
1098
1099 ```
1100 make "test^stepX"
1101
1102 # e.g.
1103 make "test^step2"
1104 make "test^step7"
1105 ```
1106
1107 * To run tests for a specific step against a single implementation:
1108
1109 ```
1110 make "test^IMPL^stepX"
1111
1112 # e.g
1113 make "test^ruby^step3"
1114 make "test^ps^step4"
1115 ```
1116
1117 ### Self-hosted functional tests
1118
1119 * To run the functional tests in self-hosted mode, you specify `mal`
1120   as the test implementation and use the `MAL_IMPL` make variable
1121   to change the underlying host language (default is JavaScript):
1122 ```
1123 make MAL_IMPL=IMPL "test^mal^step2"
1124
1125 # e.g.
1126 make "test^mal^step2"   # js is default
1127 make MAL_IMPL=ruby "test^mal^step2"
1128 make MAL_IMPL=python "test^mal^step2"
1129 ```
1130
1131 ### Starting the REPL
1132
1133 * To start the REPL of an implementation in a specific step:
1134
1135 ```
1136 make "repl^IMPL^stepX"
1137
1138 # e.g
1139 make "repl^ruby^step3"
1140 make "repl^ps^step4"
1141 ```
1142
1143 * If you omit the step, then `stepA` is used:
1144
1145 ```
1146 make "repl^IMPL"
1147
1148 # e.g
1149 make "repl^ruby"
1150 make "repl^ps"
1151 ```
1152
1153 * To start the REPL of the self-hosted implementation, specify `mal` as the
1154   REPL implementation and use the `MAL_IMPL` make variable to change the
1155   underlying host language (default is JavaScript):
1156 ```
1157 make MAL_IMPL=IMPL "repl^mal^stepX"
1158
1159 # e.g.
1160 make "repl^mal^step2"   # js is default
1161 make MAL_IMPL=ruby "repl^mal^step2"
1162 make MAL_IMPL=python "repl^mal"
1163 ```
1164
1165 ### Performance tests
1166
1167 Warning: These performance tests are neither statistically valid nor
1168 comprehensive; runtime performance is a not a primary goal of mal. If
1169 you draw any serious conclusions from these performance tests, then
1170 please contact me about some amazing oceanfront property in Kansas
1171 that I'm willing to sell you for cheap.
1172
1173 * To run performance tests against a single implementation:
1174 ```
1175 make "perf^IMPL"
1176
1177 # e.g.
1178 make "perf^js"
1179 ```
1180
1181 * To run performance tests against all implementations:
1182 ```
1183 make "perf"
1184 ```
1185
1186 ### Generating language statistics
1187
1188 * To report line and byte statistics for a single implementation:
1189 ```
1190 make "stats^IMPL"
1191
1192 # e.g.
1193 make "stats^js"
1194 ```
1195
1196 * To report line and bytes statistics for general Lisp code (env, core
1197   and stepA):
1198 ```
1199 make "stats-lisp^IMPL"
1200
1201 # e.g.
1202 make "stats-lisp^js"
1203 ```
1204
1205 ## Dockerized testing
1206
1207 Every implementation directory contains a Dockerfile to create
1208 a docker image containing all the dependencies for that
1209 implementation. In addition, the top-level Makefile contains support
1210 for running the tests target (and perf, stats, repl, etc) within
1211 a docker container for that implementation by passing *"DOCKERIZE=1"*
1212 on the make command line. For example:
1213
1214 ```
1215 make DOCKERIZE=1 "test^js^step3"
1216 ```
1217
1218 Existing implementations already have docker images built and pushed
1219 to the docker registry. However, if
1220 you wish to build or rebuild a docker image locally, the toplevel
1221 Makefile provides a rule for building docker images:
1222
1223 ```
1224 make "docker-build^IMPL"
1225 ```
1226
1227
1228 **Notes**:
1229 * Docker images are named *"kanaka/mal-test-IMPL"*
1230 * JVM-based language implementations (Groovy, Java, Clojure, Scala):
1231   you will probably need to run this command once manually
1232   first `make DOCKERIZE=1 "repl^IMPL"` before you can run tests because
1233   runtime dependencies need to be downloaded to avoid the tests timing
1234   out. These dependencies are downloaded to dot-files in the /mal
1235   directory so they will persist between runs.
1236
1237
1238 ## External Implementations
1239
1240 The following implementations are maintained as separate projects:
1241
1242 ### HolyC
1243
1244 * [by Alexander Bagnalla](https://github.com/bagnalla/holyc_mal)
1245
1246 ### Rust
1247
1248 * [by Tim Morgan](https://github.com/seven1m/mal-rust)
1249 * [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).
1250
1251
1252 ## Projects using mal
1253
1254  * [malc](https://github.com/dubek/malc) - Mal (Make A Lisp) compiler. Compiles a Mal program to LLVM assembly language, then binary.
1255  * [frock](https://github.com/chr15m/frock) - Clojure-flavoured PHP. Uses mal/php to run programs.
1256
1257 ## License
1258
1259 Mal (make-a-lisp) is licensed under the MPL 2.0 (Mozilla Public
1260 License 2.0). See LICENSE.txt for more details.