chiark - git - mdw - runlisp/blob - HACKING

   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