/[slime]/slime/HACKING
ViewVC logotype

Contents of /slime/HACKING

Parent Directory Parent Directory | Revision Log Revision Log


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

  ViewVC Help
Powered by ViewVC 1.1.5