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