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