| 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 | |