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 60 languages:
  10
  11 * Ada
  12 * GNU awk
  13 * Bash shell
  14 * C
  15 * C++
  16 * C#
  17 * ChucK
  18 * GNU CLISP
  19 * Clojure
  20 * CoffeeScript
  21 * Crystal
  22 * D
  23 * Elixir
  24 * Emacs Lisp
  25 * Erlang
  26 * ES6 (ECMAScript 6 / ECMAScript 2015)
  27 * F#
  28 * Factor
  29 * Forth
  30 * Go
  31 * Groovy
  32 * GNU Guile
  33 * Haskell
  34 * Haxe
  35 * Io
  36 * Java
  37 * JavaScript ([Online Demo](http://kanaka.github.io/mal))
  38 * Julia
  39 * Kotlin
  40 * Logo
  41 * Lua
  42 * GNU Make
  43 * mal itself
  44 * MATLAB
  45 * [miniMAL](https://github.com/kanaka/miniMAL)
  46 * Nim
  47 * Object Pascal
  48 * Objective C
  49 * OCaml
  50 * Perl
  51 * Perl 6
  52 * PHP
  53 * Picolisp
  54 * PL/pgSQL (Postgres)
  55 * PL/SQL (Oracle)
  56 * Postscript
  57 * PowerShell
  58 * Python
  59 * RPython
  60 * R
  61 * Racket
  62 * Ruby
  63 * Rust
  64 * Scala
  65 * Swift
  66 * Swift 3
  67 * Tcl
  68 * VHDL
  69 * Vimscript
  70 * Visual Basic.NET
  71
  72
  73 Mal is a learning tool. See the [make-a-lisp process
  74 guide](process/guide.md). Each implementation of mal is separated into
  75 11 incremental, self-contained (and testable) steps that demonstrate
  76 core concepts of Lisp. The last step is capable of self-hosting
  77 (running the mal implementation of mal).
  78
  79 The mal (make a lisp) steps are:
  80
  81 * [step0_repl](process/guide.md#step0)
  82 * [step1_read_print](process/guide.md#step1)
  83 * [step2_eval](process/guide.md#step2)
  84 * [step3_env](process/guide.md#step3)
  85 * [step4_if_fn_do](process/guide.md#step4)
  86 * [step5_tco](process/guide.md#step5)
  87 * [step6_file](process/guide.md#step6)
  88 * [step7_quote](process/guide.md#step7)
  89 * [step8_macros](process/guide.md#step8)
  90 * [step9_try](process/guide.md#step9)
  91 * [stepA_mal](process/guide.md#stepA)
  92
  93
  94 Mal was presented publicly for the first time in a lightning talk at
  95 Clojure West 2014 (unfortunately there is no video). See
  96 examples/clojurewest2014.mal for the presentation that was given at the
  97 conference (yes the presentation is a mal program). At Midwest.io
  98 2015, Joel Martin gave a presentation on Mal titled "Achievement
  99 Unlocked: A Better Path to Language Learning".
 100 [Video](https://www.youtube.com/watch?v=lgyOAiRtZGw),
 101 [Slides](http://kanaka.github.io/midwest.io.mal/).
 102
 103 If you are interesting in creating a mal implementation (or just
 104 interested in using mal for something), please drop by the #mal
 105 channel on freenode. In addition to the [make-a-lisp process
 106 guide](process/guide.md) there is also a [mal/make-a-lisp
 107 FAQ](docs/FAQ.md) where I attempt to answer some common questions.
 108
 109 ## Building/running implementations
 110
 111 The simplest way to run any given implementation is to use docker.
 112 Every implementation has a docker image pre-built with language
 113 dependencies installed. You can launch the REPL using a convenience
 114 target in the top level Makefile (where IMPL is the implementation
 115 directory name and stepX is the step to run):
 116
 117 ```
 118 make DOCKERIZE=1 "repl^IMPL^stepX"
 119     # OR stepA is the default step:
 120 make DOCKERIZE=1 "repl^IMPL"
 121 ```
 122
 123
 124 ### Ada
 125
 126 *The Ada implementation was created by [Chris Moore](https://github.com/zmower)*
 127
 128 The Ada implementation was developed with GNAT 4.9 on debian. It also
 129 compiles unchanged on windows if you have windows versions of git,
 130 GNAT and (optionally) make.  There are no external dependencies
 131 (readline not implemented).
 132
 133 ```
 134 cd ada
 135 make
 136 ./stepX_YYY
 137 ```
 138
 139 ### GNU awk
 140
 141 *The GNU awk implementation was created by [Miutsuru kariya](https://github.com/kariya-mitsuru)*
 142
 143 The GNU awk implementation of mal has been tested with GNU awk 4.1.1.
 144
 145 ```
 146 cd gawk
 147 gawk -O -f stepX_YYY.awk
 148 ```
 149
 150 ### Bash 4
 151
 152 ```
 153 cd bash
 154 bash stepX_YYY.sh
 155 ```
 156
 157 ### C
 158
 159 The C implementation of mal requires the following libraries (lib and
 160 header packages): glib, libffi6, libgc, and either the libedit or GNU readline
 161 library.
 162
 163 ```
 164 cd c
 165 make
 166 ./stepX_YYY
 167 ```
 168
 169 ### C++
 170
 171 *The C++ implementation was created by [Stephen Thirlwall (sdt)](https://github.com/sdt)*
 172
 173 The C++ implementation of mal requires g++-4.9 or clang++-3.5 and
 174 a readline compatible library to build. See the `cpp/README.md` for
 175 more details:
 176
 177 ```
 178 cd cpp
 179 make
 180     # OR
 181 make CXX=clang++-3.5
 182 ./stepX_YYY
 183 ```
 184
 185
 186 ### C# ###
 187
 188 The C# implementation of mal has been tested on Linux using the Mono
 189 C# compiler (mcs) and the Mono runtime (version 2.10.8.1). Both are
 190 required to build and run the C# implementation.
 191
 192 ```
 193 cd cs
 194 make
 195 mono ./stepX_YYY.exe
 196 ```
 197
 198 ### ChucK
 199
 200 *The ChucK implementation was created by [Vasilij Schneidermann](https://github.com/wasamasa)*
 201
 202 The ChucK implementation has been tested with ChucK 1.3.5.2 on Arch
 203 Linux.
 204
 205 ```
 206 cd chuck
 207 ./run
 208 ```
 209
 210 ### GNU CLISP
 211
 212 *The GNU CLISP implementation was created by [Iqbal Ansari](https://github.com/iqbalansari)*
 213
 214 The implementation has been tested with GNU CLISP v2.49 on Ubuntu 16.04, 14.04 and 12.04
 215
 216 ```
 217 cd clisp
 218 make
 219 ./run
 220 ```
 221
 222 ### Clojure
 223
 224 For the most part the Clojure implementation requires Clojure 1.5,
 225 however, to pass all tests, Clojure 1.8.0-RC4 is required.
 226
 227 ```
 228 cd clojure
 229 lein with-profile +stepX trampoline run
 230 ```
 231
 232 ### CoffeeScript
 233
 234 ```
 235 sudo npm install -g coffee-script
 236 cd coffee
 237 coffee ./stepX_YYY
 238 ```
 239
 240 ### Crystal
 241
 242 *The Crystal implementation of mal was created by [Linda_pp](https://github.com/rhysd)*
 243
 244 The Crystal implementation of mal has been tested with Crystal 0.18.4.
 245
 246 ```
 247 cd crystal
 248 crystal run ./stepX_YYY.cr
 249     # OR
 250 make   # needed to run tests
 251 ./stepX_YYY
 252 ```
 253
 254 ### D
 255
 256 *The D implementation was created by [Dov Murik](https://github.com/dubek)*
 257
 258 The D implementation of mal was tested with GDC 4.8.  It requires the GNU
 259 readline library.
 260
 261 ```
 262 cd d
 263 make
 264 ./stepX_YYY
 265 ```
 266
 267 ### Emacs Lisp
 268
 269 *The Emacs Lisp implementation was created by [Vasilij Schneidermann](https://github.com/wasamasa)*
 270
 271 The Emacs Lisp implementation of mal has been tested with Emacs 24.3
 272 and 24.5.  While there is very basic readline editing (`<backspace>`
 273 and `C-d` work, `C-c` cancels the process), it is recommended to use
 274 `rlwrap`.
 275
 276 ```
 277 cd elisp
 278 emacs -Q --batch --load stepX_YYY.el
 279 # with full readline support
 280 rlwrap emacs -Q --batch --load stepX_YYY.el
 281 ```
 282
 283 ### Elixir
 284
 285 *The Elixir implementation was created by [Martin Ek (ekmartin)](https://github.com/ekmartin)*
 286
 287 The Elixir implementation of mal has been tested with Elixir 1.0.5.
 288
 289 ```
 290 cd elixir
 291 mix stepX_YYY
 292 # Or with readline/line editing functionality:
 293 iex -S mix stepX_YYY
 294 ```
 295
 296 ### Erlang
 297
 298 *The Erlang implementation was created by [Nathan Fiedler (nlfiedler)](https://github.com/nlfiedler)*
 299
 300 The Erlang implementation of mal requires [Erlang/OTP R17](http://www.erlang.org/download.html)
 301 and [rebar](https://github.com/rebar/rebar) to build.
 302
 303 ```
 304 cd erlang
 305 make
 306     # OR
 307 MAL_STEP=stepX_YYY rebar compile escriptize # build individual step
 308 ./stepX_YYY
 309 ```
 310
 311 ### ES6 (ECMAScript 6 / ECMAScript 2015)
 312
 313 The ES6 implementation uses the [babel](https://babeljs.io) compiler
 314 to generate ES5 compatible JavaScript. The generated code has been
 315 tested with Node 0.12.4.
 316
 317 ```
 318 cd es6
 319 make
 320 node build/stepX_YYY.js
 321 ```
 322
 323
 324 ### F# ###
 325
 326 *The F# implementation was created by [Peter Stephens (pstephens)](https://github.com/pstephens)*
 327
 328 The F# implementation of mal has been tested on Linux using the Mono
 329 F# compiler (fsharpc) and the Mono runtime (version 3.12.1). The mono C#
 330 compiler (mcs) is also necessary to compile the readline dependency. All are
 331 required to build and run the F# implementation.
 332
 333 ```
 334 cd fsharp
 335 make
 336 mono ./stepX_YYY.exe
 337 ```
 338
 339 ### Factor
 340
 341 *The Factor implementation was created by [Jordan Lewis (jordanlewis)](https://github.com/jordanlewis)*
 342
 343 The Factor implementation of mal has been tested with Factor 0.97
 344 ([factorcode.org](http://factorcode.org)).
 345
 346 ```
 347 cd factor
 348 FACTOR_ROOTS=. factor -run=stepX_YYY
 349 ```
 350
 351 ### Forth
 352
 353 *The Forth implementation was created by [Chris Houser (chouser)](https://github.com/chouser)*
 354
 355 ```
 356 cd forth
 357 gforth stepX_YYY.fs
 358 ```
 359
 360 ### Go
 361
 362 The Go implementation of mal requires that go is installed on on the
 363 path. The implementation has been tested with Go 1.3.1.
 364
 365 ```
 366 cd go
 367 make
 368 ./stepX_YYY
 369 ```
 370
 371
 372 ### Groovy
 373
 374 The Groovy implementation of mal requires Groovy to run and has been
 375 tested with Groovy 1.8.6.
 376
 377 ```
 378 cd groovy
 379 make
 380 groovy ./stepX_YYY.groovy
 381 ```
 382
 383 ### GNU Guile 2.1+
 384
 385 *The Guile implementation was created by [Mu Lei (NalaGinrut)](https://github.com/NalaGinrut).*
 386
 387 ```
 388 cd guile
 389 guile -L ./ stepX_YYY.scm
 390 ```
 391
 392 ### Haskell
 393
 394 The Haskell implementation requires the ghc compiler version 7.10.1 or
 395 later and also the Haskell parsec and readline (or editline) packages.
 396
 397 ```
 398 cd haskell
 399 make
 400 ./stepX_YYY
 401 ```
 402
 403 ### Haxe
 404
 405 The Haxe implementation of mal requires Haxe version 3.2 to compile.
 406 Four different Haxe targets are supported: Neko, Python, C++, and
 407 JavaScript.
 408
 409 ```
 410 cd haxe
 411 # Neko
 412 make all-neko
 413 neko ./stepX_YYY.n
 414 # Python
 415 make all-python
 416 python3 ./stepX_YYY.py
 417 # C++
 418 make all-cpp
 419 ./cpp/stepX_YYY
 420 # JavaScript
 421 make all-js
 422 node ./stepX_YYY.js
 423 ```
 424
 425 ### Io
 426
 427 *The Io implementation was created by [Dov Murik](https://github.com/dubek)*
 428
 429 The Io implementation of mal has been tested with Io version 20110905.
 430
 431 ```
 432 cd io
 433 io ./stepX_YYY.io
 434 ```
 435
 436 ### Java 1.7
 437
 438 The Java implementation of mal requires maven2 to build.
 439
 440 ```
 441 cd java
 442 mvn compile
 443 mvn -quiet exec:java -Dexec.mainClass=mal.stepX_YYY
 444     # OR
 445 mvn -quiet exec:java -Dexec.mainClass=mal.stepX_YYY -Dexec.args="CMDLINE_ARGS"
 446 ```
 447
 448 ### JavaScript/Node
 449
 450 ```
 451 cd js
 452 npm update
 453 node stepX_YYY.js
 454 ```
 455
 456 ### Julia
 457
 458 The Julia implementation of mal requires Julia 0.4.
 459
 460 ```
 461 cd julia
 462 julia stepX_YYY.jl
 463 ```
 464
 465 ### Kotlin
 466
 467 *The Kotlin implementation was created by [Javier Fernandez-Ivern](https://github.com/ivern)*
 468
 469 The Kotlin implementation of mal has been tested with Kotlin 1.0.
 470
 471 ```
 472 cd kotlin
 473 make
 474 java -jar stepX_YYY.jar
 475 ```
 476
 477 ### Logo
 478
 479 *The Logo implementation was created by [Dov Murik](https://github.com/dubek)*
 480
 481 The Logo implementation of mal has been tested with UCBLogo 6.0.
 482
 483 ```
 484 cd logo
 485 logo stepX_YYY.lg
 486 ```
 487
 488 ### Lua
 489
 490 Running the Lua implementation of mal requires lua 5.1 or later,
 491 luarocks and the lua-rex-pcre library installed.
 492
 493 ```
 494 cd lua
 495 make  # to build and link linenoise.so
 496 ./stepX_YYY.lua
 497 ```
 498
 499 ### Mal
 500
 501 Running the mal implementation of mal involves running stepA of one of
 502 the other implementations and passing the mal step to run as a command
 503 line argument.
 504
 505 ```
 506 cd IMPL
 507 IMPL_STEPA_CMD ../mal/stepX_YYY.mal
 508
 509 ```
 510
 511 ### GNU Make 3.81
 512
 513 ```
 514 cd make
 515 make -f stepX_YYY.mk
 516 ```
 517
 518 ### Nim 0.11.0
 519
 520 *The Nim implementation was created by [Dennis Felsing (def-)](https://github.com/def-)*
 521
 522 Running the Nim implementation of mal requires Nim 0.11.0 or later.
 523
 524 ```
 525 cd nim
 526 make
 527   # OR
 528 nimble build
 529 ./stepX_YYY
 530 ```
 531
 532 ### Object Pascal
 533
 534 The Object Pascal implementation of mal has been built and tested on
 535 Linux using the Free Pascal compiler version 2.6.2 and 2.6.4.
 536
 537 ```
 538 cd objpascal
 539 make
 540 ./stepX_YYY
 541 ```
 542
 543 ### Objective C
 544
 545 The Objective C implementation of mal has been built and tested on
 546 Linux using clang/LLVM 3.6. It has also been built and tested on OS
 547 X using XCode 7.
 548
 549 ```
 550 cd objc
 551 make
 552 ./stepX_YYY
 553 ```
 554
 555 ### OCaml 4.01.0
 556
 557 *The OCaml implementation was created by [Chris Houser (chouser)](https://github.com/chouser)*
 558
 559 ```
 560 cd ocaml
 561 make
 562 ./stepX_YYY
 563 ```
 564
 565 ### MATLAB
 566
 567 The MATLAB implementation of mal has been tested with MATLAB version
 568 R2014a on Linux. Note that MATLAB is a commercial product. It should
 569 be fairly simple to support GNU Octave once it support classdef object
 570 syntax.
 571
 572 ```
 573 cd matlab
 574 ./stepX_YYY
 575 matlab -nodisplay -nosplash -nodesktop -nojvm -r "stepX_YYY();quit;"
 576     # OR with command line arguments
 577 matlab -nodisplay -nosplash -nodesktop -nojvm -r "stepX_YYY('arg1','arg2');quit;"
 578 ```
 579
 580 ### miniMAL
 581
 582 [miniMAL](https://github.com/kanaka/miniMAL) is small Lisp interpreter
 583 implemented in less than 1024 bytes of JavaScript. To run the miniMAL
 584 implementation of mal you need to download/install the miniMAL
 585 interpreter (which requires Node.js).
 586 ```
 587 cd miniMAL
 588 # Download miniMAL and dependencies
 589 npm install
 590 export PATH=`pwd`/node_modules/minimal-lisp/:$PATH
 591 # Now run mal implementation in miniMAL
 592 miniMAL ./stepX_YYY
 593 ```
 594
 595 ### Perl 5.8
 596
 597 For readline line editing support, install Term::ReadLine::Perl or
 598 Term::ReadLine::Gnu from CPAN.
 599
 600 ```
 601 cd perl
 602 perl stepX_YYY.pl
 603 ```
 604
 605 ### Perl 6
 606
 607 *The Perl 6 implementation was created by [Hinrik Örn Sigurðsson](https://github.com/hinrik)*
 608
 609 The Perl 6 implementation was tested on Rakudo Perl 6 2016.04.
 610
 611 ```
 612 cd perl6
 613 perl6 stepX_YYY.pl
 614 ```
 615
 616 ### PHP 5.3
 617
 618 The PHP implementation of mal requires the php command line interface
 619 to run.
 620
 621 ```
 622 cd php
 623 php stepX_YYY.php
 624 ```
 625
 626 ### Picolisp
 627
 628 *The Picolisp implementation was created by [Vasilij Schneidermann](https://github.com/wasamasa)*
 629
 630 The Picolisp implementation requires libreadline and Picolisp 3.1.11
 631 or later.
 632
 633 ```
 634 cd pil
 635 ./run
 636 ```
 637
 638 ### PL/pgSQL (Postgres SQL Procedural Language)
 639
 640 The PL/pgSQL implementation of mal requires a running Postgres server
 641 (the "kanaka/mal-test-plpgsql" docker image automatically starts
 642 a Postgres server). The implementation connects to the Postgres server
 643 and create a database named "mal" to store tables and stored
 644 procedures. The wrapper script uses the psql command to connect to the
 645 server and defaults to the user "postgres" but this can be overridden
 646 with the PSQL_USER environment variable. A password can be specified
 647 using the PGPASSWORD environment variable. The implementation has been
 648 tested with Postgres 9.4.
 649
 650 ```
 651 cd plpgsql
 652 ./wrap.sh stepX_YYY.sql
 653     # OR
 654 PSQL_USER=myuser PGPASSWORD=mypass ./wrap.sh stepX_YYY.sql
 655 ```
 656
 657 ### PL/SQL (Oracle SQL Procedural Language)
 658
 659 The PL/pgSQL implementation of mal requires a running Oracle DB
 660 server (the "kanaka/mal-test-plsql" docker image automatically
 661 starts an Oracle Express server). The implementation connects to the
 662 Oracle server to create types, tables and stored procedures. The
 663 default SQL*Plus logon value (username/password@connect_identifier) is
 664 "system/oracle" but this can be overridden with the ORACLE_LOGON
 665 environment variable. The implementation has been tested with Oracle
 666 Express Edition 11g Release 2. Note that any SQL*Plus connection
 667 warnings (user password expiration, etc) will interfere with the
 668 ability of the wrapper script to communicate with the DB.
 669
 670 ```
 671 cd plsql
 672 ./wrap.sh stepX_YYY.sql
 673     # OR
 674 ORACLE_LOGON=myuser/mypass@ORCL ./wrap.sh stepX_YYY.sql
 675 ```
 676
 677 ### Postscript Level 2/3
 678
 679 The Postscript implementation of mal requires ghostscript to run. It
 680 has been tested with ghostscript 9.10.
 681
 682 ```
 683 cd ps
 684 gs -q -dNODISPLAY -I./ stepX_YYY.ps
 685 ```
 686
 687 ### PowerShell
 688
 689 The PowerShell implementation of mal requires the PowerShell script
 690 language. It has been tested with PowerShell 6.0.0 Alpha 9 on Linux.
 691
 692 ```
 693 cd powershell
 694 powershell ./stepX_YYY.ps1
 695 ```
 696
 697 ### Python (2.X or 3.X)
 698
 699 ```
 700 cd python
 701 python stepX_YYY.py
 702 ```
 703
 704 ### RPython
 705
 706 You must have [rpython](https://rpython.readthedocs.org/) on your path
 707 (included with [pypy](https://bitbucket.org/pypy/pypy/)).
 708
 709 ```
 710 cd rpython
 711 make        # this takes a very long time
 712 ./stepX_YYY
 713 ```
 714
 715 ### R
 716
 717 The R implementation of mal requires R (r-base-core) to run.
 718
 719 ```
 720 cd r
 721 make libs  # to download and build rdyncall
 722 Rscript stepX_YYY.r
 723 ```
 724
 725 ### Racket (5.3)
 726
 727 The Racket implementation of mal requires the Racket
 728 compiler/interpreter to run.
 729
 730 ```
 731 cd racket
 732 ./stepX_YYY.rkt
 733 ```
 734
 735 ### Ruby (1.9+)
 736
 737 ```
 738 cd ruby
 739 ruby stepX_YYY.rb
 740 ```
 741
 742 ### Rust (1.0.0 nightly)
 743
 744 The rust implementation of mal requires the rust compiler and build
 745 tool (cargo) to build.
 746
 747 ```
 748 cd rust
 749 cargo run --release --bin stepX_YYY
 750 ```
 751
 752 ### Scala ###
 753
 754 Install scala and sbt (http://www.scala-sbt.org/0.13/tutorial/Installing-sbt-on-Linux.html):
 755
 756 ```
 757 cd scala
 758 sbt 'run-main stepX_YYY'
 759     # OR
 760 sbt compile
 761 scala -classpath target/scala*/classes stepX_YYY
 762 ```
 763
 764 ### Swift
 765
 766 *The Swift implementation was created by [Keith Rollin](https://github.com/keith-rollin)*
 767
 768 The Swift implementation of mal requires the Swift 2.0 compiler (XCode
 769 7.0) to build. Older versions will not work due to changes in the
 770 language and standard library.
 771
 772 ```
 773 cd swift
 774 make
 775 ./stepX_YYY
 776 ```
 777
 778 ### Swift 3
 779
 780 The Swift 3 implementation of mal requires the Swift 3.0 compiler. It
 781 has been tested with Swift 3 Preview 3.
 782
 783 ```
 784 cd swift3
 785 make
 786 ./stepX_YYY
 787 ```
 788
 789 ### Tcl 8.6
 790
 791 *The Tcl implementation was created by [Dov Murik](https://github.com/dubek)*
 792
 793 The Tcl implementation of mal requires Tcl 8.6 to run.  For readline line
 794 editing support, install tclreadline.
 795
 796 ```
 797 cd tcl
 798 tclsh ./stepX_YYY.tcl
 799 ```
 800
 801 ### VHDL
 802
 803 *The VHDL implementation was created by [Dov Murik](https://github.com/dubek)*
 804
 805 The VHDL implementation of mal has been tested with GHDL 0.29.
 806
 807 ```
 808 cd vhdl
 809 make
 810 ./run_vhdl.sh ./stepX_YYY
 811 ```
 812
 813 ### Vimscript
 814
 815 *The Vimscript implementation was created by [Dov Murik](https://github.com/dubek)*
 816
 817 The Vimscript implementation of mal requires Vim to run.  It has been tested
 818 with Vim 7.4.
 819
 820 ```
 821 cd vimscript
 822 ./run_vimscript.sh ./stepX_YYY.vim
 823 ```
 824
 825 ### Visual Basic.NET ###
 826
 827 The VB.NET implementation of mal has been tested on Linux using the Mono
 828 VB compiler (vbnc) and the Mono runtime (version 2.10.8.1). Both are
 829 required to build and run the VB.NET implementation.
 830
 831 ```
 832 cd vb
 833 make
 834 mono ./stepX_YYY.exe
 835 ```
 836
 837
 838
 839 ## Running tests
 840
 841 ### Functional tests
 842
 843 The are over 600 generic functional tests (for all implementations)
 844 in the `tests/` directory. Each step has a corresponding test file
 845 containing tests specific to that step. The `runtest.py` test harness
 846 launches a Mal step implementation and then feeds the tests one at
 847 a time to the implementation and compares the output/return value to
 848 the expected output/return value.
 849
 850 To simplify the process of running tests, a top level Makefile is
 851 provided with convenient test targets.
 852
 853 * To run all the tests across all implementations (be prepared to wait):
 854
 855 ```
 856 make test
 857 ```
 858
 859 * To run all tests against a single implementation:
 860
 861 ```
 862 make "test^IMPL"
 863
 864 # e.g.
 865 make "test^clojure"
 866 make "test^js"
 867 ```
 868
 869 * To run tests for a single step against all implementations:
 870
 871 ```
 872 make "test^stepX"
 873
 874 # e.g.
 875 make "test^step2"
 876 make "test^step7"
 877 ```
 878
 879 * To run tests for a specific step against a single implementation:
 880
 881 ```
 882 make "test^IMPL^stepX"
 883
 884 # e.g
 885 make "test^ruby^step3"
 886 make "test^ps^step4"
 887 ```
 888
 889 ### Self-hosted functional tests
 890
 891 * To run the functional tests in self-hosted mode, you specify `mal`
 892   as the test implementation and use the `MAL_IMPL` make variable
 893   to change the underlying host language (default is JavaScript):
 894 ```
 895 make MAL_IMPL=IMPL "test^mal^step2"
 896
 897 # e.g.
 898 make "test^mal^step2"   # js is default
 899 make MAL_IMPL=ruby "test^mal^step2"
 900 make MAL_IMPL=python "test^mal^step2"
 901 ```
 902
 903 ### Starting the REPL
 904
 905 * To start the REPL of an implementation in a specific step:
 906
 907 ```
 908 make "repl^IMPL^stepX"
 909
 910 # e.g
 911 make "repl^ruby^step3"
 912 make "repl^ps^step4"
 913 ```
 914
 915 * If you omit the step, then `stepA` is used:
 916
 917 ```
 918 make "repl^IMPL"
 919
 920 # e.g
 921 make "repl^ruby"
 922 make "repl^ps"
 923 ```
 924
 925 * To start the REPL of the self-hosted implementation, specify `mal` as the
 926   REPL implementation and use the `MAL_IMPL` make variable to change the
 927   underlying host language (default is JavaScript):
 928 ```
 929 make MAL_IMPL=IMPL "repl^mal^stepX"
 930
 931 # e.g.
 932 make "repl^mal^step2"   # js is default
 933 make MAL_IMPL=ruby "repl^mal^step2"
 934 make MAL_IMPL=python "repl^mal"
 935 ```
 936
 937 ### Performance tests
 938
 939 Warning: These performance tests are neither statistically valid nor
 940 comprehensive; runtime performance is a not a primary goal of mal. If
 941 you draw any serious conclusions from these performance tests, then
 942 please contact me about some amazing oceanfront property in Kansas
 943 that I'm willing to sell you for cheap.
 944
 945 * To run performance tests against a single implementation:
 946 ```
 947 make "perf^IMPL"
 948
 949 # e.g.
 950 make "perf^js"
 951 ```
 952
 953 * To run performance tests against all implementations:
 954 ```
 955 make "perf"
 956 ```
 957
 958 ### Generating language statistics
 959
 960 * To report line and byte statistics for a single implementation:
 961 ```
 962 make "stats^IMPL"
 963
 964 # e.g.
 965 make "stats^js"
 966 ```
 967
 968 * To report line and bytes statistics for general Lisp code (env, core
 969   and stepA):
 970 ```
 971 make "stats-lisp^IMPL"
 972
 973 # e.g.
 974 make "stats-lisp^js"
 975 ```
 976
 977 ## Dockerized testing
 978
 979 Every implementation directory contains a Dockerfile to create
 980 a docker image containing all the dependencies for that
 981 implementation. In addition, the top-level Makefile contains support
 982 for running the tests target (and perf, stats, repl, etc) within
 983 a docker container for that implementation by passing *"DOCKERIZE=1"*
 984 on the make command line. For example:
 985
 986 ```
 987 make DOCKERIZE=1 "test^js^step3"
 988 ```
 989
 990 Existing implementations already have docker images built and pushed
 991 to the docker registry. However, if
 992 you wish to build or rebuild a docker image locally, the toplevel
 993 Makefile provides a rule for building docker images:
 994
 995 ```
 996 make "docker-build^IMPL"
 997 ```
 998
 999
1000 **Notes**:
1001 * Docker images are named *"kanaka/mal-test-IMPL"*
1002 * JVM-based language implementations (Groovy, Java, Clojure, Scala):
1003   you will probably need to run these implementations once manually
1004   first (make DOCKERIZE=1 "repl^IMPL")before you can run tests because
1005   runtime dependencies need to be downloaded to avoid the tests timing
1006   out. These dependencies are download to dot-files in the /mal
1007   directory so they will persist between runs.
1008
1009
1010 ## License
1011
1012 Mal (make-a-lisp) is licensed under the MPL 2.0 (Mozilla Public
1013 License 2.0). See LICENSE.txt for more details.