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