Commit | Line | Data |
---|---|---|
e29834b8 MW |
1 | # -*-org-*- |
2 | #+TITLE: Hacking on =runlisp= | |
3 | #+AUTHOR: Mark Wooding | |
4 | #+LaTeX_CLASS: strayman | |
5 | ||
6 | * Adding a new Lisp implementation | |
7 | ||
8 | When a program needs to know about a bunch of /things/, I generally try | |
9 | to arrange that there's exactly one place where you put all of the | |
10 | knowledge about each particular /thing/. In the case of ~runlisp~, I've | |
11 | failed rather abjectly. Sorry. | |
12 | ||
13 | So, here's the list of places which need to be modified in order to | |
14 | teach ~runlisp~ about a new Lisp system. | |
15 | ||
16 | + The main C source file ~runlisp.c~ has a master list macro named | |
17 | ~LISP_SYSTEMS~, which just contains an entry ~_(foo)~ for each Lisp | |
18 | system. Add a new entry for your new system here. This list | |
19 | ordered according to my personal preference -- the /opinionated | |
20 | order/. | |
21 | ||
22 | + There's also a function ~run_foo~ defined in ~runlisp.c~ for each | |
23 | Lisp system ~foo~. These are defined in a section headed `Invoking | |
24 | Lisp systems', in the opinionated order. | |
25 | ||
26 | + The manual page ~runlisp.1~ lists each supported Lisp system by name | |
27 | in the section `Supported Common Lisp implementations'. These are | |
28 | listed in alphabetical order by command name (so GNU CLisp is | |
29 | ~clisp~, and therefore comes before ~ecl~) -- the /command order/. | |
30 | ||
31 | + The ~README.org~ file also has a list of supported Lisp systems, | |
32 | again in command order. | |
33 | ||
34 | + In ~configure.ac~, there's a line ~mdw_CHECK_LISP([FOO], [foo])~ for | |
35 | each known Lisp system in the `Checking for Lisp implementations' | |
36 | section, in opinionated order. | |
37 | ||
38 | + If the Lisp system needs any additional configure-time hacking, then | |
39 | that goes at the end of the section. Currently only ECL needs | |
40 | special treatment here, but these are notionally in opinionated | |
41 | order. | |
42 | ||
43 | + The file ~vars.am~ builds a list ~LISPS~ of the supported Lisp | |
44 | systems in opinionated order. | |
45 | ||
46 | + For each Lisp system that can have a custom image dumped, there's a | |
47 | paragraph in the `Image dumping' section of ~Makefile.am~, which | |
48 | says | |
49 | ||
50 | : if DUMP_FOO | |
51 | : image_DATA += foo+asdf.dump | |
52 | : CLEANFILES += foo+asdf.dump | |
53 | : foo+asdf.dump: dump-runlisp-image | |
54 | : (v_dump)./dump-runlisp-image -o$@ foo | |
55 | : endif | |
56 | ||
57 | The ~DUMP_FOO~ conditional is already set up by ~mdw_CHECK_LISP~. | |
58 | The ~.dump~ suffix should be whatever extension your Lisp system | |
59 | usually uses to mark its image files. These paragraphs are in | |
60 | opinionated order. | |
61 | ||
62 | + For each Lisp system that can be dumped, there's a section in | |
63 | ~dump-runlisp-image.in~ which goes | |
64 | ||
65 | : ## Foo Common Lisp. | |
66 | : deflisp foo foo+asdf.dump | |
67 | : dump_foo () { | |
68 | : ## ... | |
69 | : } | |
70 | ||
71 | These sections are in opinionated order. | |
72 | ||
73 | + The ~tests.at~ file has /five/ lists of Lisp systems. | |
74 | ||
75 | - The first, named ~LISP_SYSTEMS~ has a pair of entries, ~foo~, | |
76 | ~foo/noimage~ for each Lisp system, in opinionated order. | |
77 | ||
78 | - The second is in the macro ~WHICH_LISP~, which contains an entry | |
79 | ~#+foo "foo"~ for each system, in opinionated order. The former | |
80 | symbol is the Lisp system's (preferred) ~*features*~ keyword | |
81 | name, which is usually the same as its command name, but, for | |
82 | example, is ~cmu~ rather than ~cmucl~ for CMU CL. | |
83 | ||
84 | - The third is a ~case~ block in the ~smoke~ test, which contains | |
85 | an entry | |
86 | ||
87 | : foo) initfile=.foorc ;; | |
88 | ||
89 | naming the system's user initialization file, relative to the | |
90 | user's home directory. (If your Lisp doesn't have one of these, | |
91 | then this can be anything you like.) | |
92 | ||
93 | - The fourth is another ~case~ block in the ~smoke~ test, which | |
94 | contains an entry | |
95 | ||
96 | : foo) impl="Foo Common Lisp" ;; | |
97 | ||
98 | giving the Lisp system's ~lisp-implementation-type~ string. | |
99 | ||
100 | - The fifth is in the ~preferences~ test: there's a ~set~ line | |
101 | which simply lists the Lisp systems' command names. This is in | |
102 | order of increasing startup time, because the test will be | |
103 | running lots of trivial scripts, simply checking that the right | |
104 | Lisp system is being run, so it's valuable to choose fast Lisps. | |
105 | ||
106 | + The script ~bench/massage-benchmarks~ has a hash ~%LISP~ mapping | |
107 | Lisp command names to short labels to use in graphs, in opinionated | |
108 | order. Add an entry | |
109 | ||
110 | : "foo" => "Foo CL", | |
111 | ||
112 | to this hash. | |
113 | ||
114 | And now the actual pain: the benchmarks need to be run again, and the | |
115 | data and graphs in ~README.org~ need to be updated. Leave this to me. | |
116 |