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