Commit | Line | Data |
---|---|---|
60154d24 JM |
1 | # mal - Make a Lisp |
2 | ||
f9e6bb80 JM |
3 | [![Build Status](https://travis-ci.org/kanaka/mal.svg?branch=master)](https://travis-ci.org/kanaka/mal) |
4 | ||
bcddc3e4 JM |
5 | ## Description |
6 | ||
27696157 | 7 | Mal is a Clojure inspired Lisp interpreter. |
b76aa73b | 8 | |
33dec7af | 9 | Mal is implemented in 45 different languages: |
bcddc3e4 | 10 | |
8c7587af | 11 | * GNU awk |
edc3b064 | 12 | * Bash shell |
bcddc3e4 | 13 | * C |
73fc9366 | 14 | * C++ |
edc3b064 JM |
15 | * C# |
16 | * Clojure | |
891c3f3b | 17 | * CoffeeScript |
6c4dede1 | 18 | * Crystal |
f82cb965 | 19 | * D |
bb526975 | 20 | * Elixir |
2cc3804b | 21 | * Erlang |
88e934b6 | 22 | * ES6 (ECMAScript 6 / ECMAScript 2015) |
6f78381f | 23 | * F# |
0fe47e88 | 24 | * Factor |
96032890 | 25 | * Forth |
1771ab50 | 26 | * Go |
7ab0f63e | 27 | * Groovy |
7c6882f2 | 28 | * GNU Guile |
b76aa73b | 29 | * Haskell |
33dec7af | 30 | * Haxe |
bcddc3e4 | 31 | * Java |
39381792 JM |
32 | * JavaScript ([Online Demo](http://kanaka.github.io/mal)) |
33 | * Julia | |
53c2ea70 | 34 | * Kotlin |
9d42904e | 35 | * Lua |
bcddc3e4 JM |
36 | * GNU Make |
37 | * mal itself | |
8a9d0a8a | 38 | * MATLAB |
1218ce98 | 39 | * [miniMAL](https://github.com/kanaka/miniMAL) |
a2cd0a3a | 40 | * Nim |
bc6448bc | 41 | * OCaml |
6301e0b6 | 42 | * Perl |
edc3b064 JM |
43 | * PHP |
44 | * Postscript | |
45 | * Python | |
23e38cd2 | 46 | * RPython |
9b3362e8 | 47 | * R |
f5223195 | 48 | * Racket |
8adb0827 | 49 | * Ruby |
abdd56eb | 50 | * Rust |
821930db | 51 | * Scala |
8b142f08 | 52 | * Swift |
54d9903c | 53 | * Tcl |
50a964ce | 54 | * Vimscript |
ee7cd585 | 55 | * Visual Basic.NET |
bcddc3e4 JM |
56 | |
57 | ||
bd08422d JM |
58 | Mal is a learning tool. See the [make-a-lisp process |
59 | guide](process/guide.md). Each implementation of mal is separated into | |
60 | 11 incremental, self-contained (and testable) steps that demonstrate | |
61 | core concepts of Lisp. The last step is capable of self-hosting | |
62 | (running the mal implementation of mal). | |
bcddc3e4 JM |
63 | |
64 | The mal (make a lisp) steps are: | |
65 | ||
0f4ca9d1 JM |
66 | * [step0_repl](process/guide.md#step0) |
67 | * [step1_read_print](process/guide.md#step1) | |
68 | * [step2_eval](process/guide.md#step2) | |
69 | * [step3_env](process/guide.md#step3) | |
70 | * [step4_if_fn_do](process/guide.md#step4) | |
71 | * [step5_tco](process/guide.md#step5) | |
72 | * [step6_file](process/guide.md#step6) | |
73 | * [step7_quote](process/guide.md#step7) | |
74 | * [step8_macros](process/guide.md#step8) | |
75 | * [step9_try](process/guide.md#step9) | |
90f618cb | 76 | * [stepA_mal](process/guide.md#stepA) |
bcddc3e4 JM |
77 | |
78 | ||
79 | Mal was presented publicly for the first time in a lightning talk at | |
80 | Clojure West 2014 (unfortunately there is no video). See | |
81 | mal/clojurewest2014.mal for the presentation that was given at the | |
82 | conference (yes the presentation is a mal program). | |
60154d24 | 83 | |
144f2b6a | 84 | If you are interesting in creating a mal implementation (or just |
bd62ff74 | 85 | interested in using mal for something), please drop by the #mal |
144f2b6a JM |
86 | channel on freenode. In addition to the [make-a-lisp process |
87 | guide](process/guide.md) there is also a [mal/make-a-lisp | |
88 | FAQ](docs/FAQ.md) where I attempt to answer some common questions. | |
89 | ||
60154d24 JM |
90 | ## Building/running implementations |
91 | ||
8c7587af MK |
92 | ### GNU awk |
93 | ||
4c58cd4e | 94 | *The GNU awk implementation was created by [Miutsuru kariya](https://github.com/kariya-mitsuru)* |
390d5829 | 95 | |
8c7587af MK |
96 | The GNU awk implementation of mal has been tested with GNU awk 4.1.1. |
97 | ||
98 | ``` | |
99 | cd gawk | |
100 | gawk -O -f stepX_YYY.awk | |
101 | ``` | |
102 | ||
bcddc3e4 | 103 | ### Bash 4 |
60154d24 JM |
104 | |
105 | ``` | |
106 | cd bash | |
107 | bash stepX_YYY.sh | |
108 | ``` | |
109 | ||
bcddc3e4 | 110 | ### C |
60154d24 | 111 | |
01c97316 JM |
112 | The C implementation of mal requires the following libraries (lib and |
113 | header packages): glib, libffi6 and either the libedit or GNU readline library. | |
54c75382 | 114 | |
60154d24 JM |
115 | ``` |
116 | cd c | |
117 | make | |
118 | ./stepX_YYY | |
119 | ``` | |
120 | ||
73fc9366 JM |
121 | ### C++ |
122 | ||
a848d783 JM |
123 | *The C++ implementation was created by [Stephen Thirlwall (sdt)](https://github.com/sdt)* |
124 | ||
73fc9366 JM |
125 | The C++ implementation of mal requires g++-4.9 or clang++-3.5 and |
126 | a readline compatible library to build. See the `cpp/README.md` for | |
127 | more details: | |
128 | ||
129 | ``` | |
130 | cd cpp | |
131 | make | |
132 | # OR | |
133 | make CXX=clang++-3.5 | |
134 | ./stepX_YYY | |
135 | ``` | |
136 | ||
137 | ||
9b1563a3 | 138 | ### C# ### |
edc3b064 JM |
139 | |
140 | The C# implementation of mal has been tested on Linux using the Mono | |
141 | C# compiler (mcs) and the Mono runtime (version 2.10.8.1). Both are | |
142 | required to build and run the C# implementation. | |
143 | ||
144 | ``` | |
145 | cd cs | |
146 | make | |
ee7cd585 | 147 | mono ./stepX_YYY.exe |
edc3b064 JM |
148 | ``` |
149 | ||
150 | ||
bcddc3e4 | 151 | ### Clojure |
60154d24 | 152 | |
aa716df6 JM |
153 | For the most part the Clojure implementation requires Clojure 1.5, |
154 | however, to pass all tests, Clojure 1.8.0-RC4 is required. | |
155 | ||
60154d24 JM |
156 | ``` |
157 | cd clojure | |
158 | lein with-profile +stepX trampoline run | |
159 | ``` | |
160 | ||
891c3f3b JM |
161 | ### CoffeeScript |
162 | ||
163 | ``` | |
164 | sudo npm install -g coffee-script | |
165 | cd coffee | |
166 | coffee ./stepX_YYY | |
167 | ``` | |
168 | ||
58b84dd5 | 169 | ### Crystal |
170 | ||
6427adea | 171 | *The Crystal implementation of mal was created by [Linda_pp](https://github.com/rhysd)* |
6c4dede1 | 172 | |
d3ce5b49 | 173 | The Crystal implementation of mal has been tested with Crystal 0.10.0. |
6c4dede1 | 174 | |
58b84dd5 | 175 | ``` |
176 | cd crystal | |
177 | crystal run ./stepX_YYY.cr | |
6c4dede1 JM |
178 | # OR |
179 | make # needed to run tests | |
180 | ./stepX_YYY | |
58b84dd5 | 181 | ``` |
182 | ||
f82cb965 DM |
183 | ### D |
184 | ||
185 | *The D implementation was created by [Dov Murik](https://github.com/dubek)* | |
186 | ||
187 | The D implementation of mal was tested with GDC 4.8. It requires the GNU | |
188 | readline library. | |
189 | ||
190 | ``` | |
191 | cd d | |
192 | make | |
193 | ./stepX_YYY | |
194 | ``` | |
195 | ||
bb526975 | 196 | ### Elixir |
197 | ||
198 | *The Elixir implementation was created by [Martin Ek (ekmartin)](https://github.com/ekmartin)* | |
199 | ||
200 | The Elixir implementation of mal has been tested with Elixir 1.0.5. | |
201 | ||
202 | ``` | |
203 | cd elixir | |
df2ca97b | 204 | mix stepX_YYY |
205 | # Or with readline/line editing functionality: | |
bb526975 | 206 | iex -S mix stepX_YYY |
207 | ``` | |
208 | ||
2cc3804b NF |
209 | ### Erlang |
210 | ||
425ef3d7 JM |
211 | *The Erlang implementation was created by [Nathan Fiedler (nlfiedler)](https://github.com/nlfiedler)* |
212 | ||
82484631 JM |
213 | The Erlang implementation of mal requires [Erlang/OTP R17](http://www.erlang.org/download.html) |
214 | and [rebar](https://github.com/rebar/rebar) to build. | |
2cc3804b NF |
215 | |
216 | ``` | |
217 | cd erlang | |
425ef3d7 JM |
218 | make |
219 | # OR | |
220 | MAL_STEP=stepX_YYY rebar compile escriptize # build individual step | |
2cc3804b NF |
221 | ./stepX_YYY |
222 | ``` | |
223 | ||
88e934b6 JM |
224 | ### ES6 (ECMAScript 6 / ECMAScript 2015) |
225 | ||
226 | The ES6 implementation uses the [babel](https://babeljs.io) compiler | |
227 | to generate ES5 compatible JavaScript. The generated code has been | |
228 | tested with Node 0.12.4. | |
229 | ||
230 | ``` | |
231 | cd es6 | |
232 | make | |
233 | node build/stepX_YYY.js | |
234 | ``` | |
235 | ||
236 | ||
6f78381f PS |
237 | ### F# ### |
238 | ||
239 | *The F# implementation was created by [Peter Stephens (pstephens)](https://github.com/pstephens)* | |
240 | ||
241 | The F# implementation of mal has been tested on Linux using the Mono | |
242 | F# compiler (fsharpc) and the Mono runtime (version 3.12.1). The mono C# | |
206a1657 | 243 | compiler (mcs) is also necessary to compile the readline dependency. All are |
6f78381f PS |
244 | required to build and run the F# implementation. |
245 | ||
246 | ``` | |
247 | cd fsharp | |
248 | make | |
249 | mono ./stepX_YYY.exe | |
250 | ``` | |
251 | ||
5a53c643 JL |
252 | ### Factor |
253 | ||
44c8a524 | 254 | *The Factor implementation was created by [Jordan Lewis (jordanlewis)](https://github.com/jordanlewis)* |
5a53c643 | 255 | |
0fe47e88 JM |
256 | The Factor implementation of mal has been tested with Factor 0.97 |
257 | ([factorcode.org](factorcode.org)). | |
258 | ||
5a53c643 JL |
259 | ``` |
260 | cd factor | |
199b1ce7 | 261 | FACTOR_ROOTS=. factor -run=stepX_YYY |
5a53c643 JL |
262 | ``` |
263 | ||
96032890 C |
264 | ### Forth |
265 | ||
a848d783 JM |
266 | *The Forth implementation was created by [Chris Houser (chouser)](https://github.com/chouser)* |
267 | ||
96032890 C |
268 | ``` |
269 | cd forth | |
270 | gforth stepX_YYY.fs | |
271 | ``` | |
272 | ||
1771ab50 JM |
273 | ### Go |
274 | ||
0fe47e88 | 275 | The Go implementation of mal requires that go is installed on on the |
fd888612 JM |
276 | path. The implementation has been tested with Go 1.3.1. |
277 | ||
1771ab50 JM |
278 | ``` |
279 | cd go | |
280 | make | |
281 | ./stepX_YYY | |
282 | ``` | |
283 | ||
284 | ||
7ab0f63e JM |
285 | ### Groovy |
286 | ||
287 | The Groovy implementation of mal requires Groovy to run and has been | |
288 | tested with Groovy 1.8.6. | |
289 | ||
290 | ``` | |
291 | cd groovy | |
292 | make | |
293 | groovy ./stepX_YYY.groovy | |
294 | ``` | |
295 | ||
5a9cda80 JM |
296 | ### GNU Guile 2.1+ |
297 | ||
298 | *The Guile implementation was created by [Mu Lei (NalaGinrut)](https://github.com/NalaGinrut).* | |
299 | ||
300 | ``` | |
301 | cd guile | |
302 | guile -L ./ stepX_YYY.scm | |
303 | ``` | |
7ab0f63e | 304 | |
b76aa73b JM |
305 | ### Haskell |
306 | ||
2988d38e | 307 | Install the Haskell compiler (ghc/ghci), the Haskell platform and |
5400d4bf JM |
308 | either the editline package (BSD) or the readline package (GPL). On |
309 | Ubuntu these packages are: ghc, haskell-platform, | |
310 | libghc-readline-dev/libghc-editline-dev | |
b76aa73b JM |
311 | |
312 | ``` | |
313 | cd haskell | |
314 | make | |
315 | ./stepX_YYY | |
316 | ``` | |
317 | ||
33dec7af JM |
318 | ### Haxe |
319 | ||
320 | The Haxe implementation of mal requires Haxe version 3.2 to compile. | |
321 | Four different Haxe targets are supported: Neko, Python, C++, and | |
322 | JavaScript. | |
323 | ||
324 | ``` | |
325 | cd haxe | |
326 | # Neko | |
327 | make all-neko | |
328 | neko ./stepX_YYY.n | |
329 | # Python | |
330 | make all-python | |
331 | python3 ./stepX_YYY.py | |
332 | # C++ | |
333 | make all-cpp | |
334 | ./cpp/stepX_YYY | |
335 | # JavaScript | |
336 | make all-js | |
337 | node ./stepX_YYY.js | |
338 | ``` | |
339 | ||
b76aa73b | 340 | |
bcddc3e4 | 341 | ### Java 1.7 |
60154d24 | 342 | |
01c97316 JM |
343 | The Java implementation of mal requires maven2 to build. |
344 | ||
60154d24 JM |
345 | ``` |
346 | cd java | |
347 | mvn compile | |
348 | mvn -quiet exec:java -Dexec.mainClass=mal.stepX_YYY | |
349 | # OR | |
350 | mvn -quiet exec:java -Dexec.mainClass=mal.stepX_YYY -Dexec.args="CMDLINE_ARGS" | |
351 | ``` | |
352 | ||
39381792 | 353 | ### JavaScript/Node |
60154d24 JM |
354 | |
355 | ``` | |
356 | cd js | |
54c75382 | 357 | npm update |
60154d24 JM |
358 | node stepX_YYY.js |
359 | ``` | |
360 | ||
39381792 JM |
361 | ### Julia |
362 | ||
82484631 | 363 | The Julia implementation of mal requires Julia 0.4. |
39381792 JM |
364 | |
365 | ``` | |
366 | cd julia | |
367 | julia stepX_YYY.jl | |
368 | ``` | |
369 | ||
53c2ea70 JFI |
370 | ### Kotlin |
371 | ||
372 | *The Kotlin implementation was created by [Javier Fernandez-Ivern](https://github.com/ivern)* | |
373 | ||
75787d77 | 374 | The Kotlin implementation of mal has been tested with Kotlin 1.0. |
53c2ea70 JFI |
375 | |
376 | ``` | |
377 | cd kotlin | |
378 | make | |
379 | java -jar stepX_YYY.jar | |
380 | ``` | |
381 | ||
9d42904e JM |
382 | ### Lua |
383 | ||
8a9d0a8a | 384 | Running the Lua implementation of mal requires lua 5.1 or later, |
9d42904e JM |
385 | luarocks and the lua-rex-pcre library installed. |
386 | ||
387 | ``` | |
388 | cd lua | |
389 | make # to build and link linenoise.so | |
390 | ./stepX_YYY.lua | |
391 | ``` | |
392 | ||
bcddc3e4 | 393 | ### Mal |
60154d24 JM |
394 | |
395 | Running the mal implementation of mal involves running stepA of one of | |
396 | the other implementations and passing the mal step to run as a command | |
5d446bd8 | 397 | line argument. |
60154d24 JM |
398 | |
399 | ``` | |
400 | cd IMPL | |
401 | IMPL_STEPA_CMD ../mal/stepX_YYY.mal | |
402 | ||
403 | ``` | |
404 | ||
bcddc3e4 | 405 | ### GNU Make 3.81 |
60154d24 JM |
406 | |
407 | ``` | |
408 | cd make | |
409 | make -f stepX_YYY.mk | |
410 | ``` | |
411 | ||
de69b639 | 412 | ### Nim 0.11.0 |
a2cd0a3a | 413 | |
a848d783 JM |
414 | *The Nim implementation was created by [Dennis Felsing (def-)](https://github.com/def-)* |
415 | ||
de69b639 | 416 | Running the Nim implementation of mal requires Nim 0.11.0 or later. |
a2cd0a3a | 417 | |
418 | ``` | |
419 | cd nim | |
420 | make | |
421 | # OR | |
422 | nimble build | |
423 | ./stepX_YYY | |
424 | ``` | |
425 | ||
bc6448bc C |
426 | ### OCaml 4.01.0 |
427 | ||
a848d783 JM |
428 | *The OCaml implementation was created by [Chris Houser (chouser)](https://github.com/chouser)* |
429 | ||
bc6448bc C |
430 | ``` |
431 | cd ocaml | |
432 | make | |
433 | ./stepX_YYY | |
434 | ``` | |
435 | ||
8a9d0a8a JM |
436 | ### MATLAB |
437 | ||
438 | The MATLAB implementation of mal has been tested with MATLAB version | |
439 | R2014a on Linux. Note that MATLAB is a commercial product. It should | |
440 | be fairly simple to support GNU Octave once it support classdef object | |
441 | syntax. | |
442 | ||
443 | ``` | |
444 | cd matlab | |
445 | ./stepX_YYY | |
446 | matlab -nodisplay -nosplash -nodesktop -nojvm -r "stepX_YYY();quit;" | |
447 | # OR with command line arguments | |
448 | matlab -nodisplay -nosplash -nodesktop -nojvm -r "stepX_YYY('arg1','arg2');quit;" | |
449 | ``` | |
450 | ||
1218ce98 JM |
451 | ### miniMAL |
452 | ||
453 | [miniMAL](https://github.com/kanaka/miniMAL) is small Lisp interpreter | |
454 | implemented in less than 1024 bytes of JavaScript. To run the miniMAL | |
455 | implementation of mal you need to download/install the miniMAL | |
456 | interpreter (which requires Node.js). | |
457 | ``` | |
1218ce98 | 458 | cd miniMAL |
478fd9ce JM |
459 | # Download miniMAL and dependencies |
460 | npm install | |
461 | export PATH=`pwd`/node_modules/minimal-lisp/:$PATH | |
462 | # Now run mal implementation in miniMAL | |
1218ce98 JM |
463 | miniMAL ./stepX_YYY |
464 | ``` | |
465 | ||
9b1563a3 | 466 | ### Perl 5.8 |
9e5b2151 JM |
467 | |
468 | For readline line editing support, install Term::ReadLine::Perl or | |
469 | Term::ReadLine::Gnu from CPAN. | |
470 | ||
471 | ``` | |
472 | cd perl | |
473 | perl stepX_YYY.pl | |
474 | ``` | |
475 | ||
476 | ||
bcddc3e4 | 477 | ### PHP 5.3 |
60154d24 | 478 | |
01c97316 JM |
479 | The PHP implementation of mal requires the php command line interface |
480 | to run. | |
481 | ||
60154d24 JM |
482 | ``` |
483 | cd php | |
484 | php stepX_YYY.php | |
485 | ``` | |
486 | ||
bcddc3e4 | 487 | ### Postscript Level 2/3 |
60154d24 | 488 | |
01c97316 JM |
489 | The Postscript implementation of mal requires ghostscript to run. It |
490 | has been tested with ghostscript 9.10. | |
491 | ||
60154d24 JM |
492 | ``` |
493 | cd ps | |
fa64b741 | 494 | gs -q -dNODISPLAY -I./ stepX_YYY.ps |
60154d24 JM |
495 | ``` |
496 | ||
23e38cd2 | 497 | ### Python (2.X or 3.X) |
60154d24 JM |
498 | |
499 | ``` | |
500 | cd python | |
501 | python stepX_YYY.py | |
502 | ``` | |
8adb0827 | 503 | |
23e38cd2 JM |
504 | ### RPython |
505 | ||
506 | You must have [rpython](https://rpython.readthedocs.org/) on your path | |
507 | (included with [pypy](https://bitbucket.org/pypy/pypy/)). | |
508 | ||
509 | ``` | |
510 | cd rpython | |
4e8d7c28 | 511 | make # this takes a very long time |
23e38cd2 JM |
512 | ./stepX_YYY |
513 | ``` | |
514 | ||
9b3362e8 JM |
515 | ### R |
516 | ||
517 | The R implementation of mal requires R (r-base-core) to run. | |
518 | ||
519 | ``` | |
520 | cd r | |
9d42904e | 521 | make libs # to download and build rdyncall |
f5223195 JM |
522 | Rscript stepX_YYY.r |
523 | ``` | |
524 | ||
525 | ### Racket (5.3) | |
526 | ||
527 | The Racket implementation of mal requires the Racket | |
528 | compiler/interpreter to run. | |
529 | ||
530 | ``` | |
531 | cd racket | |
3796240a | 532 | ./stepX_YYY.rkt |
9b3362e8 JM |
533 | ``` |
534 | ||
107d9694 | 535 | ### Ruby (1.9+) |
8adb0827 JM |
536 | |
537 | ``` | |
538 | cd ruby | |
539 | ruby stepX_YYY.rb | |
540 | ``` | |
592eb5cf | 541 | |
9106a221 | 542 | ### Rust (1.0.0 nightly) |
abdd56eb JM |
543 | |
544 | The rust implementation of mal requires the rust compiler and build | |
545 | tool (cargo) to build. | |
546 | ||
547 | ``` | |
548 | cd rust | |
bbeb1b87 | 549 | cargo run --release --bin stepX_YYY |
abdd56eb JM |
550 | ``` |
551 | ||
821930db JM |
552 | ### Scala ### |
553 | ||
554 | Install scala and sbt (http://www.scala-sbt.org/0.13/tutorial/Installing-sbt-on-Linux.html): | |
555 | ||
556 | ``` | |
557 | cd scala | |
558 | sbt 'run-main stepX_YYY' | |
559 | # OR | |
560 | sbt compile | |
561 | scala -classpath target/scala*/classes stepX_YYY | |
562 | ``` | |
563 | ||
2539e6af KR |
564 | ### Swift |
565 | ||
a848d783 JM |
566 | *The Swift implementation was created by [Keith Rollin](https://github.com/keith-rollin)* |
567 | ||
e31349f6 KR |
568 | The Swift implementation of mal requires the Swift 2.0 compiler (XCode |
569 | 7.0) to build. Older versions will not work due to changes in the | |
570 | language and standard library. | |
8b142f08 | 571 | |
2539e6af KR |
572 | ``` |
573 | cd swift | |
574 | make | |
575 | ./stepX_YYY | |
576 | ``` | |
577 | ||
54d9903c DM |
578 | ### Tcl 8.6 |
579 | ||
580 | *The Tcl implementation was created by [Dov Murik](https://github.com/dubek)* | |
581 | ||
582 | The Tcl implementation of mal requires Tcl 8.6 to run. For readline line | |
583 | editing support, install tclreadline. | |
584 | ||
585 | ``` | |
586 | cd tcl | |
587 | tclsh ./stepX_YYY.tcl | |
588 | ``` | |
589 | ||
50a964ce DM |
590 | ### Vimscript |
591 | ||
592 | *The Vimscript implementation was created by [Dov Murik](https://github.com/dubek)* | |
593 | ||
594 | The Vimscript implementation of mal requires Vim to run. It has been tested | |
595 | with Vim 7.4. | |
596 | ||
597 | ``` | |
598 | cd vimscript | |
599 | ./run_vimscript.sh ./stepX_YYY.vim | |
600 | ``` | |
601 | ||
ee7cd585 JM |
602 | ### Visual Basic.NET ### |
603 | ||
604 | The VB.NET implementation of mal has been tested on Linux using the Mono | |
605 | VB compiler (vbnc) and the Mono runtime (version 2.10.8.1). Both are | |
606 | required to build and run the VB.NET implementation. | |
607 | ||
608 | ``` | |
609 | cd vb | |
610 | make | |
611 | mono ./stepX_YYY.exe | |
612 | ``` | |
613 | ||
614 | ||
615 | ||
592eb5cf JM |
616 | ## Running tests |
617 | ||
294aba2c JM |
618 | ### Functional tests |
619 | ||
620 | The are nearly 500 generic functional tests (for all implementations) | |
621 | in the `tests/` directory. Each step has a corresponding test file | |
622 | containing tests specific to that step. The `runtest.py` test harness | |
bd62ff74 JM |
623 | launches a Mal step implementation and then feeds the tests one at |
624 | a time to the implementation and compares the output/return value to | |
625 | the expected output/return value. | |
592eb5cf JM |
626 | |
627 | To simplify the process of running tests, a top level Makefile is | |
628 | provided with convenient test targets. | |
629 | ||
630 | * To run all the tests across all implementations (be prepared to wait): | |
631 | ||
632 | ``` | |
633 | make test | |
634 | ``` | |
635 | ||
636 | * To run all tests against a single implementation: | |
637 | ||
638 | ``` | |
e5737b08 | 639 | make "test^IMPL" |
592eb5cf JM |
640 | |
641 | # e.g. | |
e5737b08 SL |
642 | make "test^clojure" |
643 | make "test^js" | |
592eb5cf JM |
644 | ``` |
645 | ||
646 | * To run tests for a single step against all implementations: | |
647 | ||
648 | ``` | |
e5737b08 | 649 | make "test^stepX" |
592eb5cf JM |
650 | |
651 | # e.g. | |
e5737b08 SL |
652 | make "test^step2" |
653 | make "test^step7" | |
592eb5cf JM |
654 | ``` |
655 | ||
4c58cd4e | 656 | * To run tests for a specific step against a single implementation: |
592eb5cf JM |
657 | |
658 | ``` | |
e5737b08 | 659 | make "test^IMPL^stepX" |
592eb5cf JM |
660 | |
661 | # e.g | |
e5737b08 SL |
662 | make "test^ruby^step3" |
663 | make "test^ps^step4" | |
592eb5cf | 664 | ``` |
fd888612 | 665 | |
294aba2c JM |
666 | ### Self-hosted functional tests |
667 | ||
668 | * To run the functional tests in self-hosted mode, you specify `mal` | |
669 | as the test implementation and use the `MAL_IMPL` make variable | |
670 | to change the underlying host language (default is JavaScript): | |
671 | ``` | |
e5737b08 | 672 | make MAL_IMPL=IMPL "test^mal^step2" |
294aba2c JM |
673 | |
674 | # e.g. | |
e5737b08 SL |
675 | make "test^mal^step2" # js is default |
676 | make MAL_IMPL=ruby "test^mal^step2" | |
677 | make MAL_IMPL=python "test^mal^step2" | |
294aba2c JM |
678 | ``` |
679 | ||
854cf2a6 DM |
680 | ### Starting the REPL |
681 | ||
682 | * To start the REPL of an implementation in a specific step: | |
683 | ||
684 | ``` | |
685 | make "repl^IMPL^stepX" | |
686 | ||
687 | # e.g | |
688 | make "repl^ruby^step3" | |
689 | make "repl^ps^step4" | |
690 | ``` | |
691 | ||
692 | * If you omit the step, then `stepA` is used: | |
693 | ||
694 | ``` | |
695 | make "repl^IMPL" | |
696 | ||
697 | # e.g | |
698 | make "repl^ruby" | |
699 | make "repl^ps" | |
700 | ``` | |
701 | ||
702 | * To start the REPL of the self-hosted implementation, specify `mal` as the | |
703 | REPL implementation and use the `MAL_IMPL` make variable to change the | |
704 | underlying host language (default is JavaScript): | |
705 | ``` | |
706 | make MAL_IMPL=IMPL "repl^mal^stepX" | |
707 | ||
708 | # e.g. | |
709 | make "repl^mal^step2" # js is default | |
710 | make MAL_IMPL=ruby "repl^mal^step2" | |
711 | make MAL_IMPL=python "repl^mal" | |
712 | ``` | |
294aba2c JM |
713 | |
714 | ### Performance tests | |
715 | ||
8569b2af JM |
716 | Warning: These performance tests are neither statistically valid nor |
717 | comprehensive; runtime performance is a not a primary goal of mal. If | |
718 | you draw any serious conclusions from these performance tests, then | |
719 | please contact me about some amazing oceanfront property in Kansas | |
720 | that I'm willing to sell you for cheap. | |
721 | ||
294aba2c JM |
722 | * To run performance tests against a single implementation: |
723 | ``` | |
e5737b08 | 724 | make "perf^IMPL" |
294aba2c JM |
725 | |
726 | # e.g. | |
e5737b08 | 727 | make "perf^js" |
294aba2c JM |
728 | ``` |
729 | ||
730 | * To run performance tests against all implementations: | |
731 | ``` | |
e5737b08 | 732 | make "perf" |
294aba2c JM |
733 | ``` |
734 | ||
735 | ### Generating language statistics | |
736 | ||
4c58cd4e | 737 | * To report line and byte statistics for a single implementation: |
294aba2c | 738 | ``` |
e5737b08 | 739 | make "stats^IMPL" |
294aba2c JM |
740 | |
741 | # e.g. | |
e5737b08 | 742 | make "stats^js" |
294aba2c JM |
743 | ``` |
744 | ||
4c58cd4e | 745 | * To report line and bytes statistics for general Lisp code (env, core |
294aba2c JM |
746 | and stepA): |
747 | ``` | |
e5737b08 | 748 | make "stats-lisp^IMPL" |
294aba2c JM |
749 | |
750 | # e.g. | |
e5737b08 | 751 | make "stats-lisp^js" |
294aba2c JM |
752 | ``` |
753 | ||
75363567 JM |
754 | ## Docker test environment |
755 | ||
756 | There is a Dockerfile included in the `tests/docker` directory that | |
757 | builds a docker image based on Ubuntu Utopic that contains everything | |
758 | needed to run tests against all the implementations (except for MATLAB | |
759 | which is proprietary/licensed). | |
760 | ||
4c58cd4e | 761 | Build the docker image using a provided script. WARNING: this will |
75363567 JM |
762 | likely take over an hour to build from scratch and use more 3 GB of disk: |
763 | ```bash | |
764 | ./tests/docker-build.sh | |
765 | ``` | |
766 | ||
767 | Launch a docker container from that image built above. This will | |
768 | volume mount the mal directory to `/mal` and then give you a bash | |
769 | prompt in the container. You can then run individual mal | |
770 | implementations and tests: | |
771 | ```bash | |
772 | ./tests/docker-run.sh | |
773 | ``` | |
774 | ||
775 | You can also specify a command to run within the container. For | |
776 | example, to run step2 tests for every implementation (except MATLAB): | |
777 | ```bash | |
e5737b08 | 778 | ./tests/docker-run.sh make SKIP_IMPLS="matlab" "test^step2" |
75363567 JM |
779 | ``` |
780 | ||
781 | **Notes**: | |
782 | * JVM-based language implementations (Java, Clojure, Scala): you will | |
783 | need to run these implementations once manually first before you can | |
784 | run tests because runtime dependencies need to be downloaded to | |
785 | avoid the tests timing out. These dependencies are download to | |
786 | dot-files in the /mal directory so they will persist between runs. | |
bd62ff74 | 787 | * Compiled languages: if your host system is different enough from |
75363567 JM |
788 | Ubuntu Utopic then you may need to re-compile your compiled |
789 | languages from within the container to avoid linker version | |
790 | mismatches. | |
791 | ||
294aba2c | 792 | |
fd888612 JM |
793 | ## License |
794 | ||
795 | Mal (make-a-lisp) is licensed under the MPL 2.0 (Mozilla Public | |
796 | License 2.0). See LICENSE.txt for more details. |