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