/[slime]/slime/HACKING
ViewVC logotype

Contents of /slime/HACKING

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1.8 - (hide annotations)
Wed Sep 19 11:08:27 2007 UTC (6 years, 7 months ago) by heller
Branch: MAIN
Changes since 1.7: +6 -15 lines
*** empty log message ***
1 heller 1.3 * The SLIME Hacker's Handbook -*- outline -*-
2 lgorrie 1.1
3 lgorrie 1.6 * Lisp code file structure
4    
5     The Lisp code is organised into these files:
6    
7     swank-backend.lisp:
8     Definition of the interface to non-portable features.
9     Stand-alone.
10    
11     swank-<cmucl|...>.lisp:
12     Backend implementation for a specific Common Lisp system.
13     Uses swank-backend.lisp.
14    
15     swank.lisp:
16     The top-level server program, built from the other components.
17     Uses swank-backend.lisp as an interface to the actual backends.
18    
19 lgorrie 1.1 * ChangeLog
20    
21     For each change we make an entry in the ChangeLog file. This is
22     typically done using the command `add-change-log-entry-other-window'
23     (C-x 4 a). The message can be automatically extracted from the
24     ChangeLog to use in a CVS commit message by pressing C-c C-a in a
25     vc-mode or pcl-cvs commit buffer.
26    
27     ChangeLog diffs are automatically sent to the slime-devel mailing list
28 lgorrie 1.5 each day as a sort of digest summary of the slime-cvs list.
29 lgorrie 1.1
30 lgorrie 1.2 There are good tips on writing ChangeLog entries in the GNU Coding Standards:
31 lgorrie 1.1 http://www.gnu.org/prep/standards_40.html#SEC40
32    
33     For information about Emacs's ChangeLog support see the `Change Log'
34     and `Change Logs and VC' nodes of the Emacs manual:
35     http://www.gnu.org/software/emacs/manual/html_node/emacs_333.html#SEC333
36     http://www.gnu.org/software/emacs/manual/html_node/emacs_156.html#SEC156
37 heller 1.3
38     * Sending Patches
39    
40 lgorrie 1.6 If you would like to send us improvements you can create a patch with
41     C-x v = in the buffer or manually with 'cvs diff -u'. It's helpful if
42     you also include a ChangeLog entry describing your change.
43    
44     * Test Suite
45    
46     The Elisp code includes a command `slime-run-tests' to run a test
47     suite. This can give a pretty good sanity-check for your changes.
48    
49     Some backends do not pass the full test suite because of missing
50     features. In these cases the test suite is still useful to ensure that
51     changes don't introduce new errors. CMUCL historically passes the full
52     test suite so it makes a good sanity check for fundamental changes
53     (e.g. to the protocol).
54    
55     Running the test suite, adding new cases, and increasing the number of
56     cases that backends support are all very good for karma.
57    
58    
59     * Source code layout
60 lgorrie 1.1
61 lgorrie 1.6 We use a special source file layout to take advantage of some fancy
62     Emacs features: outline-mode and "narrowing".
63 lgorrie 1.1
64 lgorrie 1.6 ** Outline structure
65 lgorrie 1.2
66 lgorrie 1.6 Our source files have a hierarchical structure using comments like
67     these:
68 lgorrie 1.2
69 lgorrie 1.6 ;;;; Heading
70     ;;;;; Subheading
71     ... etc
72 lgorrie 1.2
73 lgorrie 1.6 We do this as a nice way to structure the program. We try to keep each
74     (sub)section small enough to fit in your head: typically around 50-200
75     lines of code each. Each section usually begins with a brief
76     introduction, followed by its highest-level functions, followed by
77     their subroutines. This is a pleasing shape for a source file to have.
78 lgorrie 1.2
79 lgorrie 1.6 Of course the comments mean something to Emacs too. One handy usage is
80     to bring up a hyperlinked "table of contents" for the source file
81     using this command:
82 lgorrie 1.2
83 lgorrie 1.6 (defun show-outline-structure ()
84     "Show the outline-mode structure of the current buffer."
85     (interactive)
86     (occur (concat "^" outline-regexp)))
87 lgorrie 1.2
88 lgorrie 1.6 Another is to use `outline-minor-mode' to fold away certain parts of
89     the buffer. See the `Outline Mode' section of the Emacs manual for
90     details about that.
91 lgorrie 1.1
92 lgorrie 1.6 (This file is also formatted for outline mode. If you're reading in
93     Emacs you can play around e.g. by pressing `C-c C-d' right now.)
94 lgorrie 1.1
95 lgorrie 1.6 ** Pagebreak characters (^L)
96 lgorrie 1.1
97 lgorrie 1.6 We partition source files into chunks using pagebreak characters. Each
98     chunk is a substantial piece of code that can be considered in
99     isolation, that could perhaps be a separate source file if we were
100     fanatical about small source files (rather than big ones!)
101 lgorrie 1.1
102 lgorrie 1.6 The page breaks usually go in the same place as top-level outline-mode
103     headings, but they don't have to. They're flexible.
104 lgorrie 1.1
105 lgorrie 1.6 In the old days, when slime.el was less than 100 pages long, these
106     page breaks were helpful when printing it out to read. Now they're
107     useful for something else: narrowing.
108 lgorrie 1.1
109 lgorrie 1.6 You can use `C-x n p' (narrow-to-page) to "zoom in" on a
110     pagebreak-delimited section of the file as if it were a separate
111     buffer in itself. You can then use `C-x n w' (widen) to "zoom out" and
112     see the whole file again. This is tremendously helpful for focusing
113     your attention on one part of the program as if it were its own file.
114 lgorrie 1.1
115 lgorrie 1.6 (This file contains some page break characters. If you're reading in
116     Emacs you can press `C-x n p' to narrow to this page, and then later
117     `C-x n w' to make the whole buffer visible again.)
118 lgorrie 1.2
119 lgorrie 1.6
120 lgorrie 1.1 * Coding style
121    
122     We like the fact that each function in SLIME will fit on a single
123 heller 1.8 screen (80x20), and would like to preserve this property! Beyond that
124     we're not dogmatic :-)
125 lgorrie 1.1
126     In early discussions we all made happy noises about the advice in
127     Norvig and Pitman's _Tutorial on Good Lisp Programming Style_:
128     http://www.norvig.com/luv-slides.ps
129    
130 heller 1.8 For Emacs Lisp, we try to follow the _Tips and Conventions_ in
131     Appendix D of the GNU Emacs Lisp Reference Manual (see Info file
132     `elisp', node `Tips').
133    
134 lgorrie 1.1 Remember that to rewrite a program better is the sincerest form of
135 lgorrie 1.2 code appreciation. When you can see a way to rewrite a part of SLIME
136 lgorrie 1.1 better, please do so!

  ViewVC Help
Powered by ViewVC 1.1.5