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 Running the Lua implementation of mal requires lua 5.1 or later,
 610 luarocks and the lua-rex-pcre library installed.
 611
 612 ```
 613 cd lua
 614 make  # to build and link linenoise.so
 615 ./stepX_YYY.lua
 616 ```
 617
 618 ### Mal
 619
 620 Running the mal implementation of mal involves running stepA of one of
 621 the other implementations and passing the mal step to run as a command
 622 line argument.
 623
 624 ```
 625 cd IMPL
 626 IMPL_STEPA_CMD ../mal/stepX_YYY.mal
 627
 628 ```
 629
 630 ### GNU Make 3.81
 631
 632 ```
 633 cd make
 634 make -f stepX_YYY.mk
 635 ```
 636
 637 ### NASM
 638
 639 *The NASM implementation was created by [Ben Dudson](https://github.com/bendudson)*
 640
 641 The NASM implementation of mal is written for x86-64 Linux, and has been tested
 642 with Linux 3.16.0-4-amd64 and NASM version 2.11.05.
 643
 644 ```
 645 cd nasm
 646 make
 647 ./stepX_YYY
 648 ```
 649
 650 ### Nim 0.17.0
 651
 652 *The Nim implementation was created by [Dennis Felsing (def-)](https://github.com/def-)*
 653
 654 The Nim implementation of mal has been tested with Nim 0.17.0.
 655
 656 ```
 657 cd nim
 658 make
 659   # OR
 660 nimble build
 661 ./stepX_YYY
 662 ```
 663
 664 ### Object Pascal
 665
 666 The Object Pascal implementation of mal has been built and tested on
 667 Linux using the Free Pascal compiler version 2.6.2 and 2.6.4.
 668
 669 ```
 670 cd objpascal
 671 make
 672 ./stepX_YYY
 673 ```
 674
 675 ### Objective C
 676
 677 The Objective C implementation of mal has been built and tested on
 678 Linux using clang/LLVM 3.6. It has also been built and tested on OS
 679 X using XCode 7.
 680
 681 ```
 682 cd objc
 683 make
 684 ./stepX_YYY
 685 ```
 686
 687 ### OCaml 4.01.0
 688
 689 *The OCaml implementation was created by [Chris Houser (chouser)](https://github.com/chouser)*
 690
 691 ```
 692 cd ocaml
 693 make
 694 ./stepX_YYY
 695 ```
 696
 697 ### MatLab (GNU Octave and MATLAB)
 698
 699 The MatLab implementation has been tested with GNU Octave 4.2.1.
 700 It has also been tested with MATLAB version R2014a on Linux. Note that
 701 MATLAB is a commercial product.
 702
 703 ```
 704 cd matlab
 705 ./stepX_YYY
 706 octave -q --no-gui --no-history --eval "stepX_YYY();quit;"
 707 matlab -nodisplay -nosplash -nodesktop -nojvm -r "stepX_YYY();quit;"
 708     # OR with command line arguments
 709 octave -q --no-gui --no-history --eval "stepX_YYY('arg1','arg2');quit;"
 710 matlab -nodisplay -nosplash -nodesktop -nojvm -r "stepX_YYY('arg1','arg2');quit;"
 711 ```
 712
 713 ### miniMAL
 714
 715 [miniMAL](https://github.com/kanaka/miniMAL) is small Lisp interpreter
 716 implemented in less than 1024 bytes of JavaScript. To run the miniMAL
 717 implementation of mal you need to download/install the miniMAL
 718 interpreter (which requires Node.js).
 719 ```
 720 cd miniMAL
 721 # Download miniMAL and dependencies
 722 npm install
 723 export PATH=`pwd`/node_modules/minimal-lisp/:$PATH
 724 # Now run mal implementation in miniMAL
 725 miniMAL ./stepX_YYY
 726 ```
 727
 728 ### Perl 5.8
 729
 730 For readline line editing support, install Term::ReadLine::Perl or
 731 Term::ReadLine::Gnu from CPAN.
 732
 733 ```
 734 cd perl
 735 perl stepX_YYY.pl
 736 ```
 737
 738 ### Perl 6
 739
 740 *The Perl 6 implementation was created by [Hinrik Örn Sigurðsson](https://github.com/hinrik)*
 741
 742 The Perl 6 implementation was tested on Rakudo Perl 6 2016.04.
 743
 744 ```
 745 cd perl6
 746 perl6 stepX_YYY.pl
 747 ```
 748
 749 ### PHP 5.3
 750
 751 The PHP implementation of mal requires the php command line interface
 752 to run.
 753
 754 ```
 755 cd php
 756 php stepX_YYY.php
 757 ```
 758
 759 ### Picolisp
 760
 761 *The Picolisp implementation was created by [Vasilij Schneidermann](https://github.com/wasamasa)*
 762
 763 The Picolisp implementation requires libreadline and Picolisp 3.1.11
 764 or later.
 765
 766 ```
 767 cd picolisp
 768 ./run
 769 ```
 770
 771 ### PL/pgSQL (Postgres SQL Procedural Language)
 772
 773 The PL/pgSQL implementation of mal requires a running Postgres server
 774 (the "kanaka/mal-test-plpgsql" docker image automatically starts
 775 a Postgres server). The implementation connects to the Postgres server
 776 and create a database named "mal" to store tables and stored
 777 procedures. The wrapper script uses the psql command to connect to the
 778 server and defaults to the user "postgres" but this can be overridden
 779 with the PSQL_USER environment variable. A password can be specified
 780 using the PGPASSWORD environment variable. The implementation has been
 781 tested with Postgres 9.4.
 782
 783 ```
 784 cd plpgsql
 785 ./wrap.sh stepX_YYY.sql
 786     # OR
 787 PSQL_USER=myuser PGPASSWORD=mypass ./wrap.sh stepX_YYY.sql
 788 ```
 789
 790 ### PL/SQL (Oracle SQL Procedural Language)
 791
 792 The PL/pgSQL implementation of mal requires a running Oracle DB
 793 server (the "kanaka/mal-test-plsql" docker image automatically
 794 starts an Oracle Express server). The implementation connects to the
 795 Oracle server to create types, tables and stored procedures. The
 796 default SQL*Plus logon value (username/password@connect_identifier) is
 797 "system/oracle" but this can be overridden with the ORACLE_LOGON
 798 environment variable. The implementation has been tested with Oracle
 799 Express Edition 11g Release 2. Note that any SQL*Plus connection
 800 warnings (user password expiration, etc) will interfere with the
 801 ability of the wrapper script to communicate with the DB.
 802
 803 ```
 804 cd plsql
 805 ./wrap.sh stepX_YYY.sql
 806     # OR
 807 ORACLE_LOGON=myuser/mypass@ORCL ./wrap.sh stepX_YYY.sql
 808 ```
 809
 810 ### Postscript Level 2/3
 811
 812 The Postscript implementation of mal requires ghostscript to run. It
 813 has been tested with ghostscript 9.10.
 814
 815 ```
 816 cd ps
 817 gs -q -dNODISPLAY -I./ stepX_YYY.ps
 818 ```
 819
 820 ### PowerShell
 821
 822 The PowerShell implementation of mal requires the PowerShell script
 823 language. It has been tested with PowerShell 6.0.0 Alpha 9 on Linux.
 824
 825 ```
 826 cd powershell
 827 powershell ./stepX_YYY.ps1
 828 ```
 829
 830 ### Python (2.X and 3.X)
 831
 832 ```
 833 cd python
 834 python stepX_YYY.py
 835 ```
 836
 837 ### RPython
 838
 839 You must have [rpython](https://rpython.readthedocs.org/) on your path
 840 (included with [pypy](https://bitbucket.org/pypy/pypy/)).
 841
 842 ```
 843 cd rpython
 844 make        # this takes a very long time
 845 ./stepX_YYY
 846 ```
 847
 848 ### R
 849
 850 The R implementation of mal requires R (r-base-core) to run.
 851
 852 ```
 853 cd r
 854 make libs  # to download and build rdyncall
 855 Rscript stepX_YYY.r
 856 ```
 857
 858 ### Racket (5.3)
 859
 860 The Racket implementation of mal requires the Racket
 861 compiler/interpreter to run.
 862
 863 ```
 864 cd racket
 865 ./stepX_YYY.rkt
 866 ```
 867
 868 ### Rexx
 869
 870 *The Rexx implementation was created by [Dov Murik](https://github.com/dubek)*
 871
 872 The Rexx implementation of mal has been tested with Regina Rexx 3.6.
 873
 874 ```
 875 cd rexx
 876 make
 877 rexx -a ./stepX_YYY.rexxpp
 878 ```
 879
 880 ### Ruby (1.9+)
 881
 882 ```
 883 cd ruby
 884 ruby stepX_YYY.rb
 885 ```
 886
 887 ### Rust (1.0.0 nightly)
 888
 889 The rust implementation of mal requires the rust compiler and build
 890 tool (cargo) to build.
 891
 892 ```
 893 cd rust
 894 cargo run --release --bin stepX_YYY
 895 ```
 896
 897 Alternative out-of-tee Rust implementations:
 898
 899 * [by Tim Morgan](https://github.com/seven1m/mal-rust).
 900 * [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).
 901
 902 ### Scala ###
 903
 904 Install scala and sbt (http://www.scala-sbt.org/0.13/tutorial/Installing-sbt-on-Linux.html):
 905
 906 ```
 907 cd scala
 908 sbt 'run-main stepX_YYY'
 909     # OR
 910 sbt compile
 911 scala -classpath target/scala*/classes stepX_YYY
 912 ```
 913
 914 ### Scheme (R7RS) ###
 915
 916 *The Scheme implementation was created by [Vasilij Schneidermann](https://github.com/wasamasa)*
 917
 918 The Scheme implementation of mal has been tested with Chibi-Scheme
 919 0.7.3, Kawa 2.4, Gauche 0.9.5, CHICKEN 4.11.0, Sagittarius 0.8.3,
 920 Cyclone 0.6.3 (Git version) and Foment 0.4 (Git version).  You should
 921 be able to get it running on other conforming R7RS implementations
 922 after figuring out how libraries are loaded and adjusting the
 923 `Makefile` and `run` script accordingly.
 924
 925 ```
 926 cd scheme
 927 make symlinks
 928 # chibi
 929 scheme_MODE=chibi ./run
 930 # kawa
 931 make kawa
 932 scheme_MODE=kawa ./run
 933 # gauche
 934 scheme_MODE=gauche ./run
 935 # chicken
 936 make chicken
 937 scheme_MODE=chicken ./run
 938 # sagittarius
 939 scheme_MODE=sagittarius ./run
 940 # cyclone
 941 make cyclone
 942 scheme_MODE=cyclone ./run
 943 # foment
 944 scheme_MODE=foment ./run
 945 ```
 946
 947 ### Skew ###
 948
 949 *The Skew implementation was created by [Dov Murik](https://github.com/dubek)*
 950
 951 The Skew implementation of mal has been tested with Skew 0.7.42.
 952
 953 ```
 954 cd skew
 955 make
 956 node stepX_YYY.js
 957 ```
 958
 959
 960 ### Swift
 961
 962 *The Swift implementation was created by [Keith Rollin](https://github.com/keith-rollin)*
 963
 964 The Swift implementation of mal requires the Swift 2.0 compiler (XCode
 965 7.0) to build. Older versions will not work due to changes in the
 966 language and standard library.
 967
 968 ```
 969 cd swift
 970 make
 971 ./stepX_YYY
 972 ```
 973
 974 ### Swift 3
 975
 976 The Swift 3 implementation of mal requires the Swift 3.0 compiler. It
 977 has been tested with Swift 3 Preview 3.
 978
 979 ```
 980 cd swift3
 981 make
 982 ./stepX_YYY
 983 ```
 984
 985 ### Tcl 8.6
 986
 987 *The Tcl implementation was created by [Dov Murik](https://github.com/dubek)*
 988
 989 The Tcl implementation of mal requires Tcl 8.6 to run.  For readline line
 990 editing support, install tclreadline.
 991
 992 ```
 993 cd tcl
 994 tclsh ./stepX_YYY.tcl
 995 ```
 996
 997 ### TypeScript
 998
 999 *The TypeScript implementation was created by [vvakame](https://github.com/vvakame)*
1000
1001 The TypeScript implementation of mal requires the TypeScript 2.2 compiler.
1002 It has been tested with Node.js v6.
1003
1004 ```
1005 cd ts
1006 make
1007 node ./stepX_YYY.js
1008 ```
1009
1010 ### VHDL
1011
1012 *The VHDL implementation was created by [Dov Murik](https://github.com/dubek)*
1013
1014 The VHDL implementation of mal has been tested with GHDL 0.29.
1015
1016 ```
1017 cd vhdl
1018 make
1019 ./run_vhdl.sh ./stepX_YYY
1020 ```
1021
1022 ### Vimscript
1023
1024 *The Vimscript implementation was created by [Dov Murik](https://github.com/dubek)*
1025
1026 The Vimscript implementation of mal requires Vim 8.0 to run.
1027
1028 ```
1029 cd vimscript
1030 ./run_vimscript.sh ./stepX_YYY.vim
1031 ```
1032
1033 ### Visual Basic.NET ###
1034
1035 The VB.NET implementation of mal has been tested on Linux using the Mono
1036 VB compiler (vbnc) and the Mono runtime (version 2.10.8.1). Both are
1037 required to build and run the VB.NET implementation.
1038
1039 ```
1040 cd vb
1041 make
1042 mono ./stepX_YYY.exe
1043 ```
1044
1045 ### WebAssembly (wasm) ###
1046
1047 The WebAssembly implementation is written in
1048 [Wam](https://github.com/kanaka/wam) (WebAssembly Macro language) and
1049 runs under the [wac/wace](https://github.com/kanaka/wac) WebAssembly
1050 runtime.
1051
1052 ```
1053 cd wasm
1054 make
1055 wace ./stepX_YYY.wasm
1056 ```
1057
1058 ### Yorick
1059
1060 *The Yorick implementation was created by [Dov Murik](https://github.com/dubek)*
1061
1062 The Yorick implementation of mal was tested on Yorick 2.2.04.
1063
1064 ```
1065 cd yorick
1066 yorick -batch ./stepX_YYY.i
1067 ```
1068
1069
1070
1071 ## Running tests
1072
1073 ### Functional tests
1074
1075 The are over 600 generic functional tests (for all implementations)
1076 in the `tests/` directory. Each step has a corresponding test file
1077 containing tests specific to that step. The `runtest.py` test harness
1078 launches a Mal step implementation and then feeds the tests one at
1079 a time to the implementation and compares the output/return value to
1080 the expected output/return value.
1081
1082 To simplify the process of running tests, a top level Makefile is
1083 provided with convenient test targets.
1084
1085 * To run all the tests across all implementations (be prepared to wait):
1086
1087 ```
1088 make test
1089 ```
1090
1091 * To run all tests against a single implementation:
1092
1093 ```
1094 make "test^IMPL"
1095
1096 # e.g.
1097 make "test^clojure"
1098 make "test^js"
1099 ```
1100
1101 * To run tests for a single step against all implementations:
1102
1103 ```
1104 make "test^stepX"
1105
1106 # e.g.
1107 make "test^step2"
1108 make "test^step7"
1109 ```
1110
1111 * To run tests for a specific step against a single implementation:
1112
1113 ```
1114 make "test^IMPL^stepX"
1115
1116 # e.g
1117 make "test^ruby^step3"
1118 make "test^ps^step4"
1119 ```
1120
1121 ### Self-hosted functional tests
1122
1123 * To run the functional tests in self-hosted mode, you specify `mal`
1124   as the test implementation and use the `MAL_IMPL` make variable
1125   to change the underlying host language (default is JavaScript):
1126 ```
1127 make MAL_IMPL=IMPL "test^mal^step2"
1128
1129 # e.g.
1130 make "test^mal^step2"   # js is default
1131 make MAL_IMPL=ruby "test^mal^step2"
1132 make MAL_IMPL=python "test^mal^step2"
1133 ```
1134
1135 ### Starting the REPL
1136
1137 * To start the REPL of an implementation in a specific step:
1138
1139 ```
1140 make "repl^IMPL^stepX"
1141
1142 # e.g
1143 make "repl^ruby^step3"
1144 make "repl^ps^step4"
1145 ```
1146
1147 * If you omit the step, then `stepA` is used:
1148
1149 ```
1150 make "repl^IMPL"
1151
1152 # e.g
1153 make "repl^ruby"
1154 make "repl^ps"
1155 ```
1156
1157 * To start the REPL of the self-hosted implementation, specify `mal` as the
1158   REPL implementation and use the `MAL_IMPL` make variable to change the
1159   underlying host language (default is JavaScript):
1160 ```
1161 make MAL_IMPL=IMPL "repl^mal^stepX"
1162
1163 # e.g.
1164 make "repl^mal^step2"   # js is default
1165 make MAL_IMPL=ruby "repl^mal^step2"
1166 make MAL_IMPL=python "repl^mal"
1167 ```
1168
1169 ### Performance tests
1170
1171 Warning: These performance tests are neither statistically valid nor
1172 comprehensive; runtime performance is a not a primary goal of mal. If
1173 you draw any serious conclusions from these performance tests, then
1174 please contact me about some amazing oceanfront property in Kansas
1175 that I'm willing to sell you for cheap.
1176
1177 * To run performance tests against a single implementation:
1178 ```
1179 make "perf^IMPL"
1180
1181 # e.g.
1182 make "perf^js"
1183 ```
1184
1185 * To run performance tests against all implementations:
1186 ```
1187 make "perf"
1188 ```
1189
1190 ### Generating language statistics
1191
1192 * To report line and byte statistics for a single implementation:
1193 ```
1194 make "stats^IMPL"
1195
1196 # e.g.
1197 make "stats^js"
1198 ```
1199
1200 * To report line and bytes statistics for general Lisp code (env, core
1201   and stepA):
1202 ```
1203 make "stats-lisp^IMPL"
1204
1205 # e.g.
1206 make "stats-lisp^js"
1207 ```
1208
1209 ## Dockerized testing
1210
1211 Every implementation directory contains a Dockerfile to create
1212 a docker image containing all the dependencies for that
1213 implementation. In addition, the top-level Makefile contains support
1214 for running the tests target (and perf, stats, repl, etc) within
1215 a docker container for that implementation by passing *"DOCKERIZE=1"*
1216 on the make command line. For example:
1217
1218 ```
1219 make DOCKERIZE=1 "test^js^step3"
1220 ```
1221
1222 Existing implementations already have docker images built and pushed
1223 to the docker registry. However, if
1224 you wish to build or rebuild a docker image locally, the toplevel
1225 Makefile provides a rule for building docker images:
1226
1227 ```
1228 make "docker-build^IMPL"
1229 ```
1230
1231
1232 **Notes**:
1233 * Docker images are named *"kanaka/mal-test-IMPL"*
1234 * JVM-based language implementations (Groovy, Java, Clojure, Scala):
1235   you will probably need to run this command once manually
1236   first `make DOCKERIZE=1 "repl^IMPL"` before you can run tests because
1237   runtime dependencies need to be downloaded to avoid the tests timing
1238   out. These dependencies are downloaded to dot-files in the /mal
1239   directory so they will persist between runs.
1240
1241 ## Projects using mal
1242
1243  * [malc](https://github.com/dubek/malc) - Mal (Make A Lisp) compiler. Compiles a Mal program to LLVM assembly language, then binary.
1244  * [frock](https://github.com/chr15m/frock) - Clojure-flavoured PHP. Uses mal/php to run programs.
1245
1246 ## License
1247
1248 Mal (make-a-lisp) is licensed under the MPL 2.0 (Mozilla Public
1249 License 2.0). See LICENSE.txt for more details.