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), [Part
 120 3](https://www.youtube.com/watch?v=6mARZzGgX4U), [Part
 121 4](https://www.youtube.com/watch?v=dCO1SYR5kDU),
 122
 123 [Slides](http://kanaka.github.io/lambdaconf/).
 124
 125 If you are interesting in creating a mal implementation (or just
 126 interested in using mal for something), please drop by the #mal
 127 channel on freenode. In addition to the [make-a-lisp process
 128 guide](process/guide.md) there is also a [mal/make-a-lisp
 129 FAQ](docs/FAQ.md) where I attempt to answer some common questions.
 130
 131 ## Building/running implementations
 132
 133 The simplest way to run any given implementation is to use docker.
 134 Every implementation has a docker image pre-built with language
 135 dependencies installed. You can launch the REPL using a convenience
 136 target in the top level Makefile (where IMPL is the implementation
 137 directory name and stepX is the step to run):
 138
 139 ```
 140 make DOCKERIZE=1 "repl^IMPL^stepX"
 141     # OR stepA is the default step:
 142 make DOCKERIZE=1 "repl^IMPL"
 143 ```
 144
 145
 146 ### Ada
 147
 148 *The Ada implementation was created by [Chris Moore](https://github.com/zmower)*
 149
 150 The Ada implementation was developed with GNAT 4.9 on debian. It also
 151 compiles unchanged on windows if you have windows versions of git,
 152 GNAT and (optionally) make.  There are no external dependencies
 153 (readline not implemented).
 154
 155 ```
 156 cd ada
 157 make
 158 ./stepX_YYY
 159 ```
 160
 161 ### GNU awk
 162
 163 *The GNU awk implementation was created by [Miutsuru kariya](https://github.com/kariya-mitsuru)*
 164
 165 The GNU awk implementation of mal has been tested with GNU awk 4.1.1.
 166
 167 ```
 168 cd gawk
 169 gawk -O -f stepX_YYY.awk
 170 ```
 171
 172 ### Bash 4
 173
 174 ```
 175 cd bash
 176 bash stepX_YYY.sh
 177 ```
 178
 179 ### BASIC (C64 and QBasic)
 180
 181 The BASIC implementation uses a preprocessor that can generate BASIC
 182 code that is compatible with both C64 BASIC (CBM v2) and QBasic. The
 183 C64 mode has been tested with
 184 [cbmbasic](https://github.com/kanaka/cbmbasic) (the patched version is
 185 currently required to fix issues with line input) and the QBasic mode
 186 has been tested with [qb64](http://www.qb64.net/).
 187
 188 Generate C64 code and run it using cbmbasic:
 189
 190 ```
 191 cd basic
 192 make stepX_YYY.bas
 193 STEP=stepX_YYY ./run
 194 ```
 195
 196 Generate QBasic code and load it into qb64:
 197
 198 ```
 199 cd basic
 200 make MODE=qbasic stepX_YYY.bas
 201 ./qb64 stepX_YYY.bas
 202 ```
 203
 204 Thanks to [Steven Syrek](https://github.com/sjsyrek) for the original
 205 inspiration for this implementation.
 206
 207
 208 ### C
 209
 210 The C implementation of mal requires the following libraries (lib and
 211 header packages): glib, libffi6, libgc, and either the libedit or GNU readline
 212 library.
 213
 214 ```
 215 cd c
 216 make
 217 ./stepX_YYY
 218 ```
 219
 220 ### C++
 221
 222 *The C++ implementation was created by [Stephen Thirlwall (sdt)](https://github.com/sdt)*
 223
 224 The C++ implementation of mal requires g++-4.9 or clang++-3.5 and
 225 a readline compatible library to build. See the `cpp/README.md` for
 226 more details:
 227
 228 ```
 229 cd cpp
 230 make
 231     # OR
 232 make CXX=clang++-3.5
 233 ./stepX_YYY
 234 ```
 235
 236
 237 ### C# ###
 238
 239 The C# implementation of mal has been tested on Linux using the Mono
 240 C# compiler (mcs) and the Mono runtime (version 2.10.8.1). Both are
 241 required to build and run the C# implementation.
 242
 243 ```
 244 cd cs
 245 make
 246 mono ./stepX_YYY.exe
 247 ```
 248
 249 ### ChucK
 250
 251 *The ChucK implementation was created by [Vasilij Schneidermann](https://github.com/wasamasa)*
 252
 253 The ChucK implementation has been tested with ChucK 1.3.5.2.
 254
 255 ```
 256 cd chuck
 257 ./run
 258 ```
 259
 260 ### Common Lisp
 261
 262 *The Common Lisp implementation was created by [Iqbal Ansari](https://github.com/iqbalansari)*
 263
 264 The implementation has been tested with SBCL, CCL, CMUCL, GNU CLISP, ECL and
 265 Allegro CL on Ubuntu 16.04 and Ubuntu 12.04, see
 266 the [README](common-lisp/README.org) for more details. Provided you have the
 267 dependencies mentioned installed, do the following to run the implementation
 268
 269 ```
 270 cd common-lisp
 271 make
 272 ./run
 273 ```
 274
 275 ### Clojure
 276
 277 For the most part the Clojure implementation requires Clojure 1.5,
 278 however, to pass all tests, Clojure 1.8.0-RC4 is required.
 279
 280 ```
 281 cd clojure
 282 lein with-profile +stepX trampoline run
 283 ```
 284
 285 ### CoffeeScript
 286
 287 ```
 288 sudo npm install -g coffee-script
 289 cd coffee
 290 coffee ./stepX_YYY
 291 ```
 292
 293 ### Crystal
 294
 295 *The Crystal implementation of mal was created by [Linda_pp](https://github.com/rhysd)*
 296
 297 The Crystal implementation of mal has been tested with Crystal 0.26.1.
 298
 299 ```
 300 cd crystal
 301 crystal run ./stepX_YYY.cr
 302     # OR
 303 make   # needed to run tests
 304 ./stepX_YYY
 305 ```
 306
 307 ### D
 308
 309 *The D implementation was created by [Dov Murik](https://github.com/dubek)*
 310
 311 The D implementation of mal was tested with GDC 4.8.  It requires the GNU
 312 readline library.
 313
 314 ```
 315 cd d
 316 make
 317 ./stepX_YYY
 318 ```
 319
 320 ### Dart
 321
 322 *The Dart implementation was created by [Harry Terkelsen](https://github.com/hterkelsen)*
 323
 324 The Dart implementation has been tested with Dart 1.20.
 325
 326 ```
 327 cd dart
 328 dart ./stepX_YYY
 329 ```
 330
 331 ### Emacs Lisp
 332
 333 *The Emacs Lisp implementation was created by [Vasilij Schneidermann](https://github.com/wasamasa)*
 334
 335 The Emacs Lisp implementation of mal has been tested with Emacs 24.3
 336 and 24.5.  While there is very basic readline editing (`<backspace>`
 337 and `C-d` work, `C-c` cancels the process), it is recommended to use
 338 `rlwrap`.
 339
 340 ```
 341 cd elisp
 342 emacs -Q --batch --load stepX_YYY.el
 343 # with full readline support
 344 rlwrap emacs -Q --batch --load stepX_YYY.el
 345 ```
 346
 347 ### Elixir
 348
 349 *The Elixir implementation was created by [Martin Ek (ekmartin)](https://github.com/ekmartin)*
 350
 351 The Elixir implementation of mal has been tested with Elixir 1.0.5.
 352
 353 ```
 354 cd elixir
 355 mix stepX_YYY
 356 # Or with readline/line editing functionality:
 357 iex -S mix stepX_YYY
 358 ```
 359
 360 ### Elm
 361
 362 *The Elm implementation was created by [Jos van Bakel](https://github.com/c0deaddict)*
 363
 364 The Elm implementation of mal has been tested with Elm 0.18.0
 365
 366 ```
 367 cd elm
 368 make stepX_YYY.js
 369 STEP=stepX_YYY ./run
 370 ```
 371
 372 ### Erlang
 373
 374 *The Erlang implementation was created by [Nathan Fiedler (nlfiedler)](https://github.com/nlfiedler)*
 375
 376 The Erlang implementation of mal requires [Erlang/OTP R17](http://www.erlang.org/download.html)
 377 and [rebar](https://github.com/rebar/rebar) to build.
 378
 379 ```
 380 cd erlang
 381 make
 382     # OR
 383 MAL_STEP=stepX_YYY rebar compile escriptize # build individual step
 384 ./stepX_YYY
 385 ```
 386
 387 ### ES6 (ECMAScript 6 / ECMAScript 2015)
 388
 389 The ES6 implementation uses the [babel](https://babeljs.io) compiler
 390 to generate ES5 compatible JavaScript. The generated code has been
 391 tested with Node 0.12.4.
 392
 393 ```
 394 cd es6
 395 make
 396 node build/stepX_YYY.js
 397 ```
 398
 399
 400 ### F# ###
 401
 402 *The F# implementation was created by [Peter Stephens (pstephens)](https://github.com/pstephens)*
 403
 404 The F# implementation of mal has been tested on Linux using the Mono
 405 F# compiler (fsharpc) and the Mono runtime (version 3.12.1). The mono C#
 406 compiler (mcs) is also necessary to compile the readline dependency. All are
 407 required to build and run the F# implementation.
 408
 409 ```
 410 cd fsharp
 411 make
 412 mono ./stepX_YYY.exe
 413 ```
 414
 415 ### Factor
 416
 417 *The Factor implementation was created by [Jordan Lewis (jordanlewis)](https://github.com/jordanlewis)*
 418
 419 The Factor implementation of mal has been tested with Factor 0.97
 420 ([factorcode.org](http://factorcode.org)).
 421
 422 ```
 423 cd factor
 424 FACTOR_ROOTS=. factor -run=stepX_YYY
 425 ```
 426
 427 ### Fantom
 428
 429 *The Fantom implementation was created by [Dov Murik](https://github.com/dubek)*
 430
 431 The Fantom implementation of mal has been tested with Fantom 1.0.70.
 432
 433 ```
 434 cd fantom
 435 make lib/fan/stepX_YYY.pod
 436 STEP=stepX_YYY ./run
 437 ```
 438
 439 ### Forth
 440
 441 *The Forth implementation was created by [Chris Houser (chouser)](https://github.com/chouser)*
 442
 443 ```
 444 cd forth
 445 gforth stepX_YYY.fs
 446 ```
 447
 448 ### Go
 449
 450 The Go implementation of mal requires that go is installed on on the
 451 path. The implementation has been tested with Go 1.3.1.
 452
 453 ```
 454 cd go
 455 make
 456 ./stepX_YYY
 457 ```
 458
 459
 460 ### Groovy
 461
 462 The Groovy implementation of mal requires Groovy to run and has been
 463 tested with Groovy 1.8.6.
 464
 465 ```
 466 cd groovy
 467 make
 468 groovy ./stepX_YYY.groovy
 469 ```
 470
 471 ### GNU Guile 2.1+
 472
 473 *The Guile implementation was created by [Mu Lei (NalaGinrut)](https://github.com/NalaGinrut).*
 474
 475 ```
 476 cd guile
 477 guile -L ./ stepX_YYY.scm
 478 ```
 479
 480 ### GNU Smalltalk
 481
 482 *The Smalltalk implementation was created by [Vasilij Schneidermann](https://github.com/wasamasa)*
 483
 484 The Smalltalk implementation of mal has been tested with GNU Smalltalk 3.2.91.
 485
 486 ```
 487 cd gnu-smalltalk
 488 ./run
 489 ```
 490
 491 ### Haskell
 492
 493 The Haskell implementation requires the ghc compiler version 7.10.1 or
 494 later and also the Haskell parsec and readline (or editline) packages.
 495
 496 ```
 497 cd haskell
 498 make
 499 ./stepX_YYY
 500 ```
 501
 502 ### Haxe (Neko, Python, C++ and JavaScript)
 503
 504 The Haxe implementation of mal requires Haxe version 3.2 to compile.
 505 Four different Haxe targets are supported: Neko, Python, C++, and
 506 JavaScript.
 507
 508 ```
 509 cd haxe
 510 # Neko
 511 make all-neko
 512 neko ./stepX_YYY.n
 513 # Python
 514 make all-python
 515 python3 ./stepX_YYY.py
 516 # C++
 517 make all-cpp
 518 ./cpp/stepX_YYY
 519 # JavaScript
 520 make all-js
 521 node ./stepX_YYY.js
 522 ```
 523
 524 ### Hy
 525
 526 The Hy implementation of mal has been tested with Hy 0.13.0.
 527
 528 ```
 529 cd hy
 530 ./stepX_YYY.hy
 531 ```
 532
 533 ### Io
 534
 535 *The Io implementation was created by [Dov Murik](https://github.com/dubek)*
 536
 537 The Io implementation of mal has been tested with Io version 20110905.
 538
 539 ```
 540 cd io
 541 io ./stepX_YYY.io
 542 ```
 543
 544 ### Java 1.7
 545
 546 The Java implementation of mal requires maven2 to build.
 547
 548 ```
 549 cd java
 550 mvn compile
 551 mvn -quiet exec:java -Dexec.mainClass=mal.stepX_YYY
 552     # OR
 553 mvn -quiet exec:java -Dexec.mainClass=mal.stepX_YYY -Dexec.args="CMDLINE_ARGS"
 554 ```
 555
 556 ### JavaScript/Node
 557
 558 ```
 559 cd js
 560 npm update
 561 node stepX_YYY.js
 562 ```
 563
 564 ### Julia
 565
 566 The Julia implementation of mal requires Julia 0.4.
 567
 568 ```
 569 cd julia
 570 julia stepX_YYY.jl
 571 ```
 572
 573 ### Kotlin
 574
 575 *The Kotlin implementation was created by [Javier Fernandez-Ivern](https://github.com/ivern)*
 576
 577 The Kotlin implementation of mal has been tested with Kotlin 1.0.
 578
 579 ```
 580 cd kotlin
 581 make
 582 java -jar stepX_YYY.jar
 583 ```
 584
 585 ### LiveScript
 586
 587 *The LiveScript implementation was created by [Jos van Bakel](https://github.com/c0deaddict)*
 588
 589 The LiveScript implementation of mal has been tested with LiveScript 1.5.
 590
 591 ```
 592 cd livescript
 593 make
 594 node_modules/.bin/lsc stepX_YYY.ls
 595 ```
 596
 597 ### Logo
 598
 599 *The Logo implementation was created by [Dov Murik](https://github.com/dubek)*
 600
 601 The Logo implementation of mal has been tested with UCBLogo 6.0.
 602
 603 ```
 604 cd logo
 605 logo stepX_YYY.lg
 606 ```
 607
 608 ### Lua
 609
 610 Running the Lua implementation of mal requires lua 5.1 or later,
 611 luarocks and the lua-rex-pcre library 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 these implementations 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 download 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.