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