/[slime]/slime/HACKING
ViewVC logotype

Contents of /slime/HACKING

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1.5 - (hide annotations)
Mon Mar 29 00:59:38 2004 UTC (10 years ago) by lgorrie
Branch: MAIN
CVS Tags: SLIME-1-0-ALPHA, SLIME-0-14, SLIME-0-13, SLIME-0-12
Changes since 1.4: +2 -2 lines
Some small updates (more needed).
1 heller 1.3 * The SLIME Hacker's Handbook -*- outline -*-
2 lgorrie 1.1
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 lgorrie 1.5 each day as a sort of digest summary of the slime-cvs list.
13 lgorrie 1.1
14 lgorrie 1.2 There are good tips on writing ChangeLog entries in the GNU Coding Standards:
15 lgorrie 1.1 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 heller 1.3
22     * Sending Patches
23    
24 heller 1.4 If you would like to send us improvements, you can create a patch with
25 lgorrie 1.5 C-x v = in the buffer or manually with 'cvs diff -u'. You can also
26 heller 1.4 include a ChangeLog entry describing your change.
27 lgorrie 1.1
28     * Adding a backend function
29    
30     To add a new "backend" function that must be implemented separately
31     for each Lisp, we add a generic function in swank-backend.lisp and
32     export the function name. We then provide a method for the function in
33     the specific backend file for each Lisp that supports it. If a
34     reasonable default implementation can be provided, we do so in
35     swank-backend.lisp by specializing NO-APPLICABLE-METHOD [or is that a
36     bad idea? -luke].
37    
38     Because these generic functions define our interface for people
39     porting to new Lisps, it is especially helpful to clearly document
40     them.
41    
42     Currently not all backend functions are defined in this way. We are
43     ongoingly refactoring the code so that swank.lisp will only call
44     backend functions via the generic functions defined in
45     swank-backend.lisp. When this refactoring is complete we intend to
46     make the separation stronger by putting the portable and non-portable
47     code in separate Lisp packages.
48    
49     Refactoring code to avoid direct calls from swank.lisp to functions
50     defined in swank-<impl>.lisp is good for karma.
51    
52 lgorrie 1.2 * Lisp code structure
53    
54     The ideal is to structure things like this:
55    
56     swank-backend.lisp:
57     Definition of the interface to non-portable features.
58     Stand-alone.
59    
60     swank-<cmucl|...>.lisp:
61     Backend implementation for a specific Common Lisp system.
62     Uses swank-backend.lisp.
63    
64     swank.lisp:
65     The top-level server program, built from the other components.
66     Uses swank-backend.lisp as an interface to the actual backends.
67    
68     Today things are more messy. Originally everything was in one file,
69     and we haven't finished the reorganisation yet.
70    
71 lgorrie 1.1 * Calling Lisp from Emacs
72    
73     By convention our Elisp code only calls functions in the SWANK package
74     that are defined with DEFSLIMEFUN, and calls them with constants for
75     arguments. The idea is to keep all of the Common Lisp code in separate
76     source files so that it's easy to see what Lisp code runs, without
77     needing to look for snippets of CL in the Elisp sources.
78    
79     Our current Elisp code sometimes calls SWANK-exported functions that
80     are not defined by DEFSLIMEFUN, but by DEFGENERIC in
81     swank-backend.lisp. [Is it just me that does this, and should I stop
82     it? -luke]
83    
84     * Test Suite
85    
86     The Elisp code includes a command `slime-run-tests' to run a test
87     suite. This can give a pretty good sanity-check for your changes.
88    
89     Some backends do not pass the full test suite because of missing
90     features. In these cases the test suite is still useful to ensure that
91     changes don't introduce new errors. CMUCL has historically passed the
92     full test suite, and so it makes a good sanity check for fundamental
93     changes (e.g. to the protocol).
94    
95     Running the test suite, adding new cases, and increasing the number of
96     cases that backends support are all very good for karma.
97    
98     * outline-minor-mode
99    
100     The SLIME source files have special comments that outline-minor-mode
101     can use to "fold" source buffers down to a section-by-section
102     outline. See the `Outline Mode' node of the Emacs manual for details:
103     http://www.gnu.org/software/emacs/manual/html_node/emacs_246.html#SEC246
104    
105 lgorrie 1.2 Some tips to make the most of outline mode:
106     You can set `outline-minor-mode-prefix' for more convenient
107     keybindings, e.g. to [(control \;)].
108     `<prefix> C-a' displays all levels.
109     `C-3 <prefix> C-q' displays only top-level headings.
110     `<prefix> C-t' displays only/all headings.
111     `<prefix> {n,p}' for next/previous heading.
112    
113 lgorrie 1.1 * Coding style
114    
115     We like the fact that each function in SLIME will fit on a single
116     screen, and would like to preserve this property! Beyond that we're
117     not dogmatic :-)
118    
119     In early discussions we all made happy noises about the advice in
120     Norvig and Pitman's _Tutorial on Good Lisp Programming Style_:
121     http://www.norvig.com/luv-slides.ps
122    
123     Remember that to rewrite a program better is the sincerest form of
124 lgorrie 1.2 code appreciation. When you can see a way to rewrite a part of SLIME
125 lgorrie 1.1 better, please do so!
126    

  ViewVC Help
Powered by ViewVC 1.1.5