# -*-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.