/[slime]/slime/HACKING
ViewVC logotype

Contents of /slime/HACKING

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1.1 - (hide annotations)
Wed Dec 17 18:19:19 2003 UTC (10 years, 4 months ago) by lgorrie
Branch: MAIN
CVS Tags: SLIME-0-10
New file summarising our way of working.
1 lgorrie 1.1 * The SLIME Hacker's Handbook -*- outline -*-
2    
3     * ChangeLog
4    
5     For each change we make an entry in the ChangeLog file. This is
6     typically done using the command `add-change-log-entry-other-window'
7     (C-x 4 a). The message can be automatically extracted from the
8     ChangeLog to use in a CVS commit message by pressing C-c C-a in a
9     vc-mode or pcl-cvs commit buffer.
10    
11     ChangeLog diffs are automatically sent to the slime-devel mailing list
12     each day as a digest summary of the slime-cvs list.
13    
14     For good tips on writing ChangeLog entries see the GNU Coding Standards:
15     http://www.gnu.org/prep/standards_40.html#SEC40
16    
17     For information about Emacs's ChangeLog support see the `Change Log'
18     and `Change Logs and VC' nodes of the Emacs manual:
19     http://www.gnu.org/software/emacs/manual/html_node/emacs_333.html#SEC333
20     http://www.gnu.org/software/emacs/manual/html_node/emacs_156.html#SEC156
21    
22     * Adding a backend function
23    
24     To add a new "backend" function that must be implemented separately
25     for each Lisp, we add a generic function in swank-backend.lisp and
26     export the function name. We then provide a method for the function in
27     the specific backend file for each Lisp that supports it. If a
28     reasonable default implementation can be provided, we do so in
29     swank-backend.lisp by specializing NO-APPLICABLE-METHOD [or is that a
30     bad idea? -luke].
31    
32     Because these generic functions define our interface for people
33     porting to new Lisps, it is especially helpful to clearly document
34     them.
35    
36     Currently not all backend functions are defined in this way. We are
37     ongoingly refactoring the code so that swank.lisp will only call
38     backend functions via the generic functions defined in
39     swank-backend.lisp. When this refactoring is complete we intend to
40     make the separation stronger by putting the portable and non-portable
41     code in separate Lisp packages.
42    
43     Refactoring code to avoid direct calls from swank.lisp to functions
44     defined in swank-<impl>.lisp is good for karma.
45    
46     * Calling Lisp from Emacs
47    
48     By convention our Elisp code only calls functions in the SWANK package
49     that are defined with DEFSLIMEFUN, and calls them with constants for
50     arguments. The idea is to keep all of the Common Lisp code in separate
51     source files so that it's easy to see what Lisp code runs, without
52     needing to look for snippets of CL in the Elisp sources.
53    
54     Our current Elisp code sometimes calls SWANK-exported functions that
55     are not defined by DEFSLIMEFUN, but by DEFGENERIC in
56     swank-backend.lisp. [Is it just me that does this, and should I stop
57     it? -luke]
58    
59     * Test Suite
60    
61     The Elisp code includes a command `slime-run-tests' to run a test
62     suite. This can give a pretty good sanity-check for your changes.
63    
64     Some backends do not pass the full test suite because of missing
65     features. In these cases the test suite is still useful to ensure that
66     changes don't introduce new errors. CMUCL has historically passed the
67     full test suite, and so it makes a good sanity check for fundamental
68     changes (e.g. to the protocol).
69    
70     Running the test suite, adding new cases, and increasing the number of
71     cases that backends support are all very good for karma.
72    
73     * outline-minor-mode
74    
75     The SLIME source files have special comments that outline-minor-mode
76     can use to "fold" source buffers down to a section-by-section
77     outline. See the `Outline Mode' node of the Emacs manual for details:
78     http://www.gnu.org/software/emacs/manual/html_node/emacs_246.html#SEC246
79    
80     * Coding style
81    
82     We like the fact that each function in SLIME will fit on a single
83     screen, and would like to preserve this property! Beyond that we're
84     not dogmatic :-)
85    
86     In early discussions we all made happy noises about the advice in
87     Norvig and Pitman's _Tutorial on Good Lisp Programming Style_:
88     http://www.norvig.com/luv-slides.ps
89    
90     Remember that to rewrite a program better is the sincerest form of
91     code appreciation. If you can see a way to rewrite a part of SLIME
92     better, please do so!
93    

  ViewVC Help
Powered by ViewVC 1.1.5