+++ /dev/null
-# -*-org-*-
-#+TITLE: Hacking on =runlisp=
-#+AUTHOR: Mark Wooding
-#+LaTeX_CLASS: strayman
-
-* Adding a new Lisp implementation
-
-When a program needs to know about a bunch of /things/, I generally try
-to arrange that there's exactly one place where you put all of the
-knowledge about each particular /thing/. In the case of ~runlisp~, I've
-failed rather abjectly. Sorry.
-
-So, here's the list of places which need to be modified in order to
-teach ~runlisp~ about a new Lisp system.
-
- + The main C source file ~runlisp.c~ has a master list macro named
- ~LISP_SYSTEMS~, which just contains an entry ~_(foo)~ for each Lisp
- system. Add a new entry for your new system here. This list
- ordered according to my personal preference -- the /opinionated
- order/.
-
- + There's also a function ~run_foo~ defined in ~runlisp.c~ for each
- Lisp system ~foo~. These are defined in a section headed `Invoking
- Lisp systems', in the opinionated order.
-
- + The manual page ~runlisp.1~ lists each supported Lisp system by name
- in the section `Supported Common Lisp implementations'. These are
- listed in alphabetical order by command name (so GNU CLisp is
- ~clisp~, and therefore comes before ~ecl~) -- the /command order/.
-
- + The ~README.org~ file also has a list of supported Lisp systems,
- again in command order.
-
- + In ~configure.ac~, there's a line ~mdw_CHECK_LISP([FOO], [foo])~ for
- each known Lisp system in the `Checking for Lisp implementations'
- section, in opinionated order.
-
- + If the Lisp system needs any additional configure-time hacking, then
- that goes at the end of the section. Currently only ECL needs
- special treatment here, but these are notionally in opinionated
- order.
-
- + The file ~vars.am~ builds a list ~LISPS~ of the supported Lisp
- systems in opinionated order.
-
- + For each Lisp system that can have a custom image dumped, there's a
- paragraph in the `Image dumping' section of ~Makefile.am~, which
- says
-
- : if DUMP_FOO
- : image_DATA += foo+asdf.dump
- : CLEANFILES += foo+asdf.dump
- : foo+asdf.dump: dump-runlisp-image
- : (v_dump)./dump-runlisp-image -o$@ foo
- : endif
-
- The ~DUMP_FOO~ conditional is already set up by ~mdw_CHECK_LISP~.
- The ~.dump~ suffix should be whatever extension your Lisp system
- usually uses to mark its image files. These paragraphs are in
- opinionated order.
-
- + For each Lisp system that can be dumped, there's a section in
- ~dump-runlisp-image.in~ which goes
-
- : ## Foo Common Lisp.
- : deflisp foo foo+asdf.dump
- : dump_foo () {
- : ## ...
- : }
-
- These sections are in opinionated order.
-
- + The ~tests.at~ file has /five/ lists of Lisp systems.
-
- - The first, named ~LISP_SYSTEMS~ has a pair of entries, ~foo~,
- ~foo/noimage~ for each Lisp system, in opinionated order.
-
- - The second is in the macro ~WHICH_LISP~, which contains an entry
- ~#+foo "foo"~ for each system, in opinionated order. The former
- symbol is the Lisp system's (preferred) ~*features*~ keyword
- name, which is usually the same as its command name, but, for
- example, is ~cmu~ rather than ~cmucl~ for CMU CL.
-
- - The third is a ~case~ block in the ~smoke~ test, which contains
- an entry
-
- : foo) initfile=.foorc ;;
-
- naming the system's user initialization file, relative to the
- user's home directory. (If your Lisp doesn't have one of these,
- then this can be anything you like.)
-
- - The fourth is another ~case~ block in the ~smoke~ test, which
- contains an entry
-
- : foo) impl="Foo Common Lisp" ;;
-
- giving the Lisp system's ~lisp-implementation-type~ string.
-
- - The fifth is in the ~preferences~ test: there's a ~set~ line
- which simply lists the Lisp systems' command names. This is in
- order of increasing startup time, because the test will be
- running lots of trivial scripts, simply checking that the right
- Lisp system is being run, so it's valuable to choose fast Lisps.
-
- + The script ~bench/massage-benchmarks~ has a hash ~%LISP~ mapping
- Lisp command names to short labels to use in graphs, in opinionated
- order. Add an entry
-
- : "foo" => "Foo CL",
-
- to this hash.
-
-And now the actual pain: the benchmarks need to be run again, and the
-data and graphs in ~README.org~ need to be updated. Leave this to me.
-