Commit | Line | Data |
---|---|---|
60154d24 JM |
1 | # mal - Make a Lisp |
2 | ||
bcddc3e4 JM |
3 | ## Description |
4 | ||
5 | Mal is an interpreter for a subset of the Clojure programming | |
abdd56eb | 6 | language. Mal is implemented from scratch in 15 different languages: |
bcddc3e4 | 7 | |
edc3b064 | 8 | * Bash shell |
bcddc3e4 | 9 | * C |
edc3b064 JM |
10 | * C# |
11 | * Clojure | |
1771ab50 | 12 | * Go |
bcddc3e4 | 13 | * Java |
d32f9b87 | 14 | * Javascript ([Online Demo](http://kanaka.github.io/mal)) |
bcddc3e4 JM |
15 | * GNU Make |
16 | * mal itself | |
6301e0b6 | 17 | * Perl |
edc3b064 JM |
18 | * PHP |
19 | * Postscript | |
20 | * Python | |
8adb0827 | 21 | * Ruby |
abdd56eb | 22 | * Rust |
bcddc3e4 JM |
23 | |
24 | ||
8d8679f2 | 25 | Mal is also a learning tool. Each implementation of mal is separated |
bcddc3e4 JM |
26 | into 11 incremental, self-contained (and testable) steps that |
27 | demonstrate core concepts of Lisp. The last step is capable of | |
28 | self-hosting (running the mal implemenation of mal). | |
29 | ||
30 | The mal (make a lisp) steps are: | |
31 | ||
32 | * step0_repl | |
33 | * step1_read_print | |
34 | * step2_eval | |
35 | * step3_env | |
36 | * step4_if_fn_do | |
37 | * step5_tco | |
38 | * step6_file | |
39 | * step7_quote | |
40 | * step8_macros | |
f41866db JM |
41 | * step9_try |
42 | * stepA_interop | |
bcddc3e4 JM |
43 | |
44 | ||
45 | Mal was presented publicly for the first time in a lightning talk at | |
46 | Clojure West 2014 (unfortunately there is no video). See | |
47 | mal/clojurewest2014.mal for the presentation that was given at the | |
48 | conference (yes the presentation is a mal program). | |
60154d24 JM |
49 | |
50 | ## Building/running implementations | |
51 | ||
bcddc3e4 | 52 | ### Bash 4 |
60154d24 JM |
53 | |
54 | ``` | |
55 | cd bash | |
56 | bash stepX_YYY.sh | |
57 | ``` | |
58 | ||
bcddc3e4 | 59 | ### C |
60154d24 | 60 | |
01c97316 JM |
61 | The C implementation of mal requires the following libraries (lib and |
62 | header packages): glib, libffi6 and either the libedit or GNU readline library. | |
54c75382 | 63 | |
60154d24 JM |
64 | ``` |
65 | cd c | |
66 | make | |
67 | ./stepX_YYY | |
68 | ``` | |
69 | ||
9b1563a3 | 70 | ### C# ### |
edc3b064 JM |
71 | |
72 | The C# implementation of mal has been tested on Linux using the Mono | |
73 | C# compiler (mcs) and the Mono runtime (version 2.10.8.1). Both are | |
74 | required to build and run the C# implementation. | |
75 | ||
76 | ``` | |
77 | cd cs | |
78 | make | |
79 | mono ./stepX_YYY | |
80 | ``` | |
81 | ||
82 | ||
bcddc3e4 | 83 | ### Clojure |
60154d24 JM |
84 | |
85 | ``` | |
86 | cd clojure | |
87 | lein with-profile +stepX trampoline run | |
88 | ``` | |
89 | ||
1771ab50 JM |
90 | ### Go |
91 | ||
92 | ``` | |
93 | cd go | |
94 | make | |
95 | ./stepX_YYY | |
96 | ``` | |
97 | ||
98 | ||
bcddc3e4 | 99 | ### Java 1.7 |
60154d24 | 100 | |
01c97316 JM |
101 | The Java implementation of mal requires maven2 to build. |
102 | ||
60154d24 JM |
103 | ``` |
104 | cd java | |
105 | mvn compile | |
106 | mvn -quiet exec:java -Dexec.mainClass=mal.stepX_YYY | |
107 | # OR | |
108 | mvn -quiet exec:java -Dexec.mainClass=mal.stepX_YYY -Dexec.args="CMDLINE_ARGS" | |
109 | ``` | |
110 | ||
bcddc3e4 | 111 | ### Javascript/Node |
60154d24 JM |
112 | |
113 | ``` | |
114 | cd js | |
54c75382 | 115 | npm update |
60154d24 JM |
116 | node stepX_YYY.js |
117 | ``` | |
118 | ||
bcddc3e4 | 119 | ### Mal |
60154d24 JM |
120 | |
121 | Running the mal implementation of mal involves running stepA of one of | |
122 | the other implementations and passing the mal step to run as a command | |
5d446bd8 | 123 | line argument. |
60154d24 JM |
124 | |
125 | ``` | |
126 | cd IMPL | |
127 | IMPL_STEPA_CMD ../mal/stepX_YYY.mal | |
128 | ||
129 | ``` | |
130 | ||
bcddc3e4 | 131 | ### GNU Make 3.81 |
60154d24 JM |
132 | |
133 | ``` | |
134 | cd make | |
135 | make -f stepX_YYY.mk | |
136 | ``` | |
137 | ||
9b1563a3 | 138 | ### Perl 5.8 |
9e5b2151 JM |
139 | |
140 | For readline line editing support, install Term::ReadLine::Perl or | |
141 | Term::ReadLine::Gnu from CPAN. | |
142 | ||
143 | ``` | |
144 | cd perl | |
145 | perl stepX_YYY.pl | |
146 | ``` | |
147 | ||
148 | ||
bcddc3e4 | 149 | ### PHP 5.3 |
60154d24 | 150 | |
01c97316 JM |
151 | The PHP implementation of mal requires the php command line interface |
152 | to run. | |
153 | ||
60154d24 JM |
154 | ``` |
155 | cd php | |
156 | php stepX_YYY.php | |
157 | ``` | |
158 | ||
bcddc3e4 | 159 | ### Postscript Level 2/3 |
60154d24 | 160 | |
01c97316 JM |
161 | The Postscript implementation of mal requires ghostscript to run. It |
162 | has been tested with ghostscript 9.10. | |
163 | ||
60154d24 JM |
164 | ``` |
165 | cd ps | |
fa64b741 | 166 | gs -q -dNODISPLAY -I./ stepX_YYY.ps |
60154d24 JM |
167 | ``` |
168 | ||
a05f7822 | 169 | ### Python (2 or 3) |
60154d24 JM |
170 | |
171 | ``` | |
172 | cd python | |
173 | python stepX_YYY.py | |
174 | ``` | |
8adb0827 JM |
175 | |
176 | ### Ruby (1.8) | |
177 | ||
178 | ``` | |
179 | cd ruby | |
180 | ruby stepX_YYY.rb | |
181 | ``` | |
592eb5cf | 182 | |
abdd56eb JM |
183 | ### Rust (0.13) |
184 | ||
185 | The rust implementation of mal requires the rust compiler and build | |
186 | tool (cargo) to build. | |
187 | ||
188 | ``` | |
189 | cd rust | |
111dbaf1 JM |
190 | # Need patched pcre lib (should be temporary) |
191 | git clone https://github.com/kanaka/rust-pcre cadencemarseille-pcre | |
abdd56eb JM |
192 | cargo build |
193 | ./target/stepX_YYY | |
194 | ``` | |
195 | ||
592eb5cf JM |
196 | ## Running tests |
197 | ||
198 | The are nearly 400 generic Mal tests (for all implementations) in the | |
199 | `tests/` directory. Each step has a corresponding test file containing | |
200 | tests specific to that step. The `runtest.py` test harness uses | |
201 | pexpect to launch a Mal step implementation and then feeds the tests | |
202 | one at a time to the implementation and compares the output/return | |
203 | value to the expected output/return value. | |
204 | ||
205 | To simplify the process of running tests, a top level Makefile is | |
206 | provided with convenient test targets. | |
207 | ||
208 | * To run all the tests across all implementations (be prepared to wait): | |
209 | ||
210 | ``` | |
211 | make test | |
212 | ``` | |
213 | ||
214 | * To run all tests against a single implementation: | |
215 | ||
216 | ``` | |
217 | make test^IMPL | |
218 | ||
219 | # e.g. | |
220 | make test^clojure | |
221 | make test^js | |
222 | ``` | |
223 | ||
224 | * To run tests for a single step against all implementations: | |
225 | ||
226 | ``` | |
227 | make test^stepX | |
228 | ||
229 | # e.g. | |
230 | make test^step2 | |
231 | make test^step7 | |
232 | ``` | |
233 | ||
234 | * To run a specifc step against a single implementation: | |
235 | ||
236 | ``` | |
237 | make test^IMPL^stepX | |
238 | ||
239 | # e.g | |
240 | make test^ruby^step3 | |
241 | make test^ps^step4 | |
242 | ``` |