Commit | Line | Data |
---|---|---|
a84251b0 LC |
1 | -*-text-*- |
2 | Guile Hacking Guide | |
b3da54d1 | 3 | Copyright (c) 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2008, 2012 Free software Foundation, Inc. |
a84251b0 LC |
4 | |
5 | Permission is granted to anyone to make or distribute verbatim copies | |
6 | of this document as received, in any medium, provided that the | |
7 | copyright notice and permission notice are preserved, | |
8 | and that the distributor grants the recipient permission | |
9 | for further redistribution as permitted by this notice. | |
10 | ||
11 | Permission is granted to distribute modified versions | |
12 | of this document, or of portions of it, | |
13 | under the above conditions, provided also that they | |
14 | carry prominent notices stating who last changed them, | |
15 | and that any new or changed statements about the activities | |
16 | of the Free Software Foundation are approved by the Foundation. | |
17 | ||
18 | ||
19 | What to Hack ========================================================= | |
20 | ||
21 | You can hack whatever you want, thank GNU. | |
22 | ||
23 | However, to see what others have indicated as their interest (and avoid | |
24 | potential wasteful duplication of effort), see file TODO. Note that | |
25 | the version you find may be out of date; a CVS checkout is recommended: | |
26 | see below for details (see also the files ANON-CVS and SNAPSHOTS). | |
27 | ||
28 | It's also a good idea to join the guile-devel@gnu.org mailing list. | |
29 | See http://www.gnu.org/software/guile/mail/mail.html for more info. | |
30 | ||
31 | ||
32 | Hacking It Yourself ================================================== | |
33 | ||
b48efb55 | 34 | When Guile is obtained from Git, a few extra steps must be taken |
a84251b0 | 35 | before the usual configure, make, make install. You will need to have |
b48efb55 | 36 | up-to-date versions of the tools as listed below, correctly installed. |
a84251b0 | 37 | |
b48efb55 HWN |
38 | Sometimes older or newer versions will work. (See below for versions |
39 | to avoid.) | |
a84251b0 LC |
40 | |
41 | Then you must run the autogen.sh script, as described below. | |
42 | ||
a84251b0 LC |
43 | The same procedure can be used to regenerate the files in released |
44 | versions of Guile. In that case the headers of the original generated | |
45 | files (e.g., configure, Makefile.in, ltmain.sh) can be used to | |
46 | identify which tool versions may be required. | |
47 | ||
48 | Autoconf --- a system for automatically generating `configure' | |
49 | scripts from templates which list the non-portable features a | |
50 | program would like to use. Available in | |
51 | "ftp://ftp.gnu.org/pub/gnu/autoconf" | |
52 | ||
53 | Automake --- a system for automatically generating Makefiles that | |
54 | conform to the (rather Byzantine) GNU coding standards. The | |
55 | nice thing is that it takes care of hairy targets like 'make | |
56 | dist' and 'make distclean', and automatically generates | |
57 | Makefile dependencies. Automake is available in | |
58 | "ftp://ftp.gnu.org/pub/gnu/automake" | |
59 | ||
60 | libtool --- a system for managing the zillion hairy options needed | |
61 | on various systems to produce shared libraries. Available in | |
8a8d0ca2 NJ |
62 | "ftp://ftp.gnu.org/pub/gnu/libtool". Version 2.2 (or |
63 | later) is recommended (for correct AIX support, and correct | |
64 | interaction with the Gnulib module for using libunistring). | |
a84251b0 LC |
65 | |
66 | gettext --- a system for rigging a program so that it can output its | |
67 | messages in the local tongue. Guile presently only exports | |
68 | the gettext functionality to Scheme, it does not use it | |
69 | itself. | |
70 | ||
71 | flex --- a scanner generator. It's probably not essential to have the | |
72 | latest version. | |
73 | ||
74 | One false move and you will be lost in a little maze of automatically | |
75 | generated files, all different. | |
76 | ||
77 | Here is the authoritative list of tool/version/platform tuples that | |
78 | have been known to cause problems, and a short description of the problem. | |
79 | ||
80 | - automake 1.4 adds extraneous rules to the top-level Makefile if | |
81 | you specify specific Makefiles to rebuild on the command line. | |
82 | ||
83 | - automake 1.4-p4 (debian "1:1.4-p4-1.1") all platforms | |
84 | automake "include" facility does not recognize filenames w/ "-". | |
85 | ||
86 | - libtool 1.4 uses acconfig.h, which is deprecated by newest autoconf | |
87 | (which constructs the equivalent through 3rd arg of AC_DEFINE forms). | |
88 | ||
89 | - autoreconf from autoconf prior to 2.59 will run gettextize, which | |
90 | will mess up the Guile tree. | |
91 | ||
8a8d0ca2 NJ |
92 | - libtool 1.5.26 does not know that it should remove the -R options |
93 | that the Gnulib libunistring and havelib modules generate (because | |
94 | gcc doesn't actually support -R). | |
95 | ||
a84251b0 LC |
96 | - (add here.) |
97 | ||
98 | ||
99 | Sample GDB Initialization File========================================= | |
100 | ||
101 | Here is a sample .gdbinit posted by Bill Schottstaedt (modified to | |
102 | use `set' instead of `call' in some places): | |
103 | ||
104 | define gp | |
105 | set gdb_print($arg0) | |
106 | print gdb_output | |
107 | end | |
108 | document gp | |
109 | Executes (object->string arg) | |
110 | end | |
111 | ||
112 | define ge | |
113 | call gdb_read($arg0) | |
114 | call gdb_eval(gdb_result) | |
115 | set gdb_print(gdb_result) | |
116 | print gdb_output | |
117 | end | |
118 | document ge | |
119 | Executes (print (eval (read arg))): ge "(+ 1 2)" => 3 | |
120 | end | |
121 | ||
122 | define gh | |
123 | call g_help(scm_str2symbol($arg0), 20) | |
124 | set gdb_print($1) | |
125 | print gdb_output | |
126 | end | |
127 | document gh | |
128 | Prints help string for arg: gh "enved-target" | |
129 | end | |
130 | ||
131 | Bill further writes: | |
132 | ||
133 | so in gdb if you see something useless like: | |
134 | ||
135 | #32 0x081ae8f4 in scm_primitive_load (filename=1112137128) at load.c:129 | |
136 | ||
137 | You can get the file name with gp: | |
138 | ||
139 | (gdb) gp 1112137128 | |
140 | $1 = 0x40853fac "\"/home/bil/test/share/guile/1.5.0/ice-9/session.scm\"" | |
141 | ||
142 | ||
143 | Contributing Your Changes ============================================ | |
144 | ||
145 | - If you have put together a change that meets the coding standards | |
b48efb55 HWN |
146 | described below, we encourage you to submit it to Guile. Post your |
147 | patch to guile-devel@gnu.org. | |
148 | ||
149 | - We prefer patches generated using 'git format-patch'. | |
150 | ||
151 | - Provide a description in the commit message, like so: | |
a84251b0 | 152 | |
b48efb55 HWN |
153 | 1-line description of change |
154 | ||
155 | More extensive discussion of your change. Document why you are | |
156 | changing things. | |
157 | ||
158 | * filename (function name): file specific change comments. | |
a84251b0 LC |
159 | |
160 | - For proper credit, also make sure you update the AUTHORS file | |
161 | (for new files for which you've assigned copyright to the FSF), or | |
162 | the THANKS file (for everything else). | |
163 | ||
a84251b0 | 164 | |
a84251b0 LC |
165 | Coding standards ===================================================== |
166 | ||
a84251b0 LC |
167 | - As for any part of Project GNU, changes to Guile should follow the |
168 | GNU coding standards. The standards are available via anonymous FTP | |
169 | from prep.ai.mit.edu, as /pub/gnu/standards/standards.texi and | |
170 | make-stds.texi. | |
171 | ||
172 | - The Guile tree should compile without warnings under the following | |
173 | GCC switches, which are the default in the current configure script: | |
174 | ||
175 | -O2 -Wall -Wpointer-arith -Wmissing-prototypes | |
176 | ||
177 | To make sure of this, you can use the --enable-error-on-warning option | |
178 | to configure. This option will make GCC fail if it hits a warning. | |
179 | ||
180 | Note that the warnings generated vary from one version of GCC to the | |
181 | next, and from one architecture to the next (apparently). To provide | |
182 | a concrete common standard, Guile should compile without warnings from | |
183 | GCC 2.7.2.3 in a Red Hat 5.2 i386 Linux machine. Furthermore, each | |
184 | developer should pursue any additional warnings noted by on their | |
185 | compiler. This means that people using more stringent compilers will | |
186 | have more work to do, and assures that everyone won't switch to the | |
187 | most lenient compiler they can find. :) | |
188 | ||
a84251b0 LC |
189 | - If you add code which uses functions or other features that are not |
190 | entirely portable, please make sure the rest of Guile will still | |
191 | function properly on systems where they are missing. This usually | |
192 | entails adding a test to configure.in, and then adding #ifdefs to your | |
193 | code to disable it if the system's features are missing. | |
194 | ||
195 | - The normal way of removing a function, macro or variable is to mark | |
196 | it as "deprecated", keep it for a while, and remove it in a later | |
197 | release. If a function or macro is marked as "deprecated" it | |
198 | indicates that people shouldn't use it in new programs, and should try | |
199 | to remove it in old. Make sure that an alternative exists unless it | |
200 | is our purpose to remove functionality. Don't deprecate definitions | |
201 | if it is unclear when they will be removed. (This is to ensure that a | |
202 | valid way of implementing some functionality always exists.) | |
203 | ||
204 | When deprecating a definition, always follow this procedure: | |
205 | ||
206 | 1. Mark the definition using | |
207 | ||
208 | #if (SCM_DEBUG_DEPRECATED == 0) | |
209 | ... | |
210 | #endif | |
211 | ||
212 | or, for Scheme code, wrap it using | |
213 | ||
214 | (begin-deprecated | |
215 | ...) | |
216 | ||
217 | 2. Make the deprecated code issue a warning when it is used, by using | |
218 | scm_c_issue_deprecation_warning (in C) or issue-deprecation-warning | |
219 | (in Scheme). | |
220 | ||
221 | 3. Write a comment at the definition explaining how a programmer can | |
222 | manage without the deprecated definition. | |
223 | ||
224 | 4. Add an entry that the definition has been deprecated in NEWS and | |
b3da54d1 | 225 | explain what to do instead. |
a84251b0 LC |
226 | |
227 | 5. In file TODO, there is a list of releases with reminders about what | |
228 | to do at each release. Add a reminder about the removal of the | |
229 | deprecated defintion at the appropriate release. | |
230 | ||
b48efb55 HWN |
231 | - Write commit messages for functions written in C using the |
232 | functions' C names, and write entries for functions written in Scheme | |
60b6a84f | 233 | using the functions' Scheme names. For example, |
a84251b0 | 234 | |
b48efb55 | 235 | * foo.c: Moved scm_procedure_documentation from eval.c. |
a84251b0 | 236 | |
b48efb55 | 237 | is preferred over |
a84251b0 | 238 | |
b48efb55 | 239 | * foo.c: Moved procedure-documentation from eval.c. |
a84251b0 LC |
240 | |
241 | Changes like adding this line are special: | |
242 | ||
243 | SCM_PROC (s_map_in_order, "map-in-order", 2, 0, 1, scm_map); | |
244 | ||
245 | Since the change here is about the name itself --- we're adding a new | |
246 | alias for scm_map that guarantees the order in which we process list | |
247 | elements, but we're not changing scm_map at all --- it's appropriate | |
b48efb55 | 248 | to use the Scheme name in the commit message. |
a84251b0 LC |
249 | |
250 | - Make sure you have papers from people before integrating their | |
251 | changes or contributions. This is very frustrating, but very | |
252 | important to do right. From maintain.texi, "Information for | |
253 | Maintainers of GNU Software": | |
254 | ||
255 | When incorporating changes from other people, make sure to follow the | |
256 | correct procedures. Doing this ensures that the FSF has the legal | |
257 | right to distribute and defend GNU software. | |
258 | ||
259 | For the sake of registering the copyright on later versions ofthe | |
260 | software you need to keep track of each person who makes significant | |
261 | changes. A change of ten lines or so, or a few such changes, in a | |
262 | large program is not significant. | |
263 | ||
264 | *Before* incorporating significant changes, make sure that the person | |
265 | has signed copyright papers, and that the Free Software Foundation has | |
266 | received them. | |
267 | ||
268 | If you receive contributions you want to use from someone, let me know | |
269 | and I'll take care of the administrivia. Put the contributions aside | |
270 | until we have the necessary papers. | |
271 | ||
272 | Once you accept a contribution, be sure to keep the files AUTHORS and | |
273 | THANKS uptodate. | |
274 | ||
275 | - When you make substantial changes to a file, add the current year to | |
276 | the list of years in the copyright notice at the top of the file. | |
277 | ||
278 | - When you get bug reports or patches from people, be sure to list | |
279 | them in THANKS. | |
280 | ||
60b6a84f TTN |
281 | - Do not introduce trailing whitespace (and feel free to clean it up |
282 | opportunistically, that is, if doing so is part of some other change). | |
283 | The goal is to reduce (and over time, eliminate) spurious diffs. | |
a84251b0 | 284 | |
554137a7 TTN |
285 | For Emacs users: |
286 | (add-hook 'before-save-hook 'delete-trailing-whitespace) | |
287 | ||
a84251b0 LC |
288 | Naming conventions ================================================= |
289 | ||
290 | We use certain naming conventions to structure the considerable number | |
291 | of global identifiers. All identifiers should be either all lower | |
292 | case or all upper case. Syllables are separated by underscores `_'. | |
293 | All non-static identifiers should start with scm_ or SCM_. Then might | |
294 | follow zero or more syllables giving the category of the identifier. | |
295 | The currently used category identifiers are | |
296 | ||
297 | t - type name | |
298 | ||
299 | c,C - something with a interface suited for C use. This is used | |
300 | to name functions that behave like Scheme primitives but | |
301 | have a more C friendly calling convention. | |
302 | ||
303 | i,I - internal to libguile. It is global, but not considered part | |
304 | of the libguile API. | |
305 | ||
306 | f - a SCM variable pointing to a Scheme function object. | |
307 | ||
308 | F - a bit mask for a flag. | |
309 | ||
310 | m - a macro transformer procedure | |
311 | ||
312 | n,N - a count of something | |
313 | ||
314 | s - a constant C string | |
315 | ||
316 | k - a SCM variable pointing to a keyword. | |
317 | ||
318 | sym - a SCM variable pointing to a symbol. | |
319 | ||
320 | var - a SCM variable pointing to a variable object. | |
321 | ||
322 | The follwing syllables also have a technical meaning: | |
323 | ||
324 | str - this denotes a zero terminated C string | |
325 | ||
326 | mem - a C string with an explicit count | |
327 | ||
328 | ||
329 | See also the file `devel/names.text'. | |
330 | ||
331 | ||
332 | Helpful hints ======================================================== | |
333 | ||
334 | - [From Mikael Djurfeldt] When working on the Guile internals, it is | |
335 | quite often practical to implement a scheme-level procedure which | |
336 | helps you examine the feature you're working on. | |
337 | ||
338 | Examples of such procedures are: pt-size, debug-hand and | |
339 | current-pstate. | |
340 | ||
341 | I've now put #ifdef GUILE_DEBUG around all such procedures, so that | |
342 | they are not compiled into the "normal" Guile library. Please do the | |
343 | same when you add new procedures/C functions for debugging purpose. | |
344 | ||
345 | You can define the GUILE_DEBUG flag by passing --enable-guile-debug to | |
346 | the configure script. | |
347 | ||
a84251b0 LC |
348 | |
349 | Jim Blandy, and others | |
350 |