Commit | Line | Data |
---|---|---|
23bcd7ad | 1 | Here are some guidelines for members of the Guile developers team. |
795b4217 | 2 | |
0822a9c1 JB |
3 | Contributing Your Changes ============================================ |
4 | ||
5 | - If you have put together a change that meets the coding standards | |
6 | described below, we encourage you to submit it to Guile. The best | |
c5ee0952 JB |
7 | place to post it is guile@sourceware.cygnus.com. Please don't send it |
8 | directly to me; I often don't have time to look things over. If you | |
9 | have tested your change, then you don't need to be shy. | |
0822a9c1 JB |
10 | |
11 | - Please submit patches using either context or unified diffs (diff -c | |
12 | or diff -u). Don't include a patch for ChangeLog; such patches don't | |
13 | apply cleanly, since we've probably changed the top of ChangeLog too. | |
14 | Instead, provide the unaltered text at the top of your patch. | |
15 | ||
16 | Please don't include patches for generated files like configure, | |
17 | aclocal.m4, or any Makefile.in. Such patches are often large, and | |
18 | we're just going to regenerate those files anyway. | |
19 | ||
20 | ||
d2bd3d8d JB |
21 | CVS conventions ====================================================== |
22 | ||
eb4194d6 | 23 | - We use CVS to manage the Guile sources. The repository lives on |
349d9c1f | 24 | egcs.cygnus.com, in /cvs/guile; you will need an |
aa31443a JB |
25 | account on that machine to access the repository. Also, for security |
26 | reasons, egcs presently only supports CVS connections via the SSH | |
27 | protocol, so you must first install the SSH client. Then, you should | |
28 | set your CVS_RSH environment variable to ssh, and use the following as | |
29 | your CVS root: | |
eb4194d6 | 30 | |
349d9c1f | 31 | :ext:USER@egcs.cygnus.com:/cvs/guile |
eb4194d6 JB |
32 | |
33 | Either set your CVSROOT environment variable to that, or give it as | |
34 | the value of the global -d option to CVS when you check out a working | |
35 | directory. | |
36 | ||
848f2a01 | 37 | For more information on SSH, see http://www.cs.hut.fi/ssh. |
eb4194d6 JB |
38 | |
39 | The Guile sources live in several modules: | |
40 | ||
41 | - guile-core --- the interpreter, QuickThreads, and ice-9 | |
e19268af JB |
42 | - guile-doc --- documentation in progress. When complete, this will |
43 | be incorporated into guile-core. | |
15fb0024 | 44 | - guile-oops --- The Guile Object-Oriented Programming System (talk to mdj) |
eb4194d6 | 45 | - guile-tcltk --- the Guile/Tk interface |
b1f4ddc1 | 46 | - guile-tk --- the new Guile/Tk interface, based on STk's modified Tk |
eb4194d6 JB |
47 | - guile-rgx-ctax --- the Guile/Rx interface, and the ctax implementation |
48 | - guile-scsh --- the port of SCSH to guile, talk to Gary Houston | |
b1f4ddc1 | 49 | - guile-www --- A Guile module for making HTTP requests. |
eb4194d6 | 50 | |
afdfe3f4 JB |
51 | There is a mailing list for CVS commit messages; see README for details. |
52 | ||
d2bd3d8d JB |
53 | - We check Makefile.in and configure files into CVS, as well as the |
54 | files they are built from (Makefile.am, configure.in); we do not check | |
55 | in Makefiles or header files generated by configuration scripts. The | |
350294b1 | 56 | general rule is that you should be able to check out a working |
d2bd3d8d JB |
57 | directory of Guile from CVS, and then type "configure" and "make", |
58 | without running any other tools. | |
350294b1 | 59 | |
d4c83f63 JB |
60 | - (Automake 1.4 only) Be sure to run automake at the top of the tree |
61 | with no arguments. Do not use `automake Makefile' to regenerate | |
62 | specific Makefile.in files, and do not trust the Makefile rules to | |
63 | rebuild them when they are out of date. Automake 1.4 will add | |
64 | extraneous rules to the top-level Makefile if you specify specific | |
65 | Makefiles to rebuild on the command line. Running the command | |
66 | `autoreconf --force' should take care of everything correctly. | |
67 | ||
795b4217 JB |
68 | - Make sure your changes compile and work, at least on your own |
69 | machine, before checking them into the main branch of the Guile | |
70 | repository. If you really need to check in untested changes, make a | |
71 | branch. | |
72 | ||
d2bd3d8d JB |
73 | - Include each log entry in both the ChangeLog and in the CVS logs. |
74 | If you're using Emacs, the pcl-cvs interface to CVS has features to | |
75 | make this easier; it checks the ChangeLog, and generates good default | |
76 | CVS log entries from that. | |
77 | ||
78 | ||
79 | Coding standards ===================================================== | |
80 | ||
81 | - As for any part of Project GNU, changes to Guile should follow the | |
82 | GNU coding standards. The standards are available via anonymous FTP | |
83 | from prep.ai.mit.edu, as /pub/gnu/standards/standards.texi and | |
84 | make-stds.texi. | |
85 | ||
99be3450 JB |
86 | - The Guile tree should compile without warnings under the following |
87 | GCC switches, which are the default in the current configure script: | |
859bb431 | 88 | -O2 -Wall -Wpointer-arith -Wmissing-prototypes |
18fa97f8 JB |
89 | The only warnings which can be tolerated are those about variables |
90 | being clobbered by longjmp/vfork in eval.c. The variables in question | |
91 | are critical to the interpreter's performance; as far as I can tell, | |
92 | it is difficult/annoying to avoid these warnings without slowing the | |
93 | system down substantially. (If you can figure out a good fix, I'd be happy to see it.) | |
99be3450 | 94 | |
d043e0bb JB |
95 | Note that the warnings generated vary from one version of GCC to the |
96 | next, and from one architecture to the next (apparently). To provide | |
97 | a concrete common standard, Guile should compile without warnings from | |
18fa97f8 | 98 | GCC 2.7.2.3 in a Red Hat 5.2 i386 Linux machine. Furthermore, each |
d043e0bb JB |
99 | developer should pursue any additional warnings noted by on their |
100 | compiler. This means that people using more stringent compilers will | |
101 | have more work to do, and assures that everyone won't switch to the | |
41d368d9 | 102 | most lenient compiler they can find. :) |
d043e0bb | 103 | |
afdfe3f4 JB |
104 | Note also that EGCS (as of November 3 1998) doesn't handle the |
105 | `noreturn' attribute properly, so it doesn't understand that functions | |
106 | like scm_error won't return. This may lead to some silly warnings | |
107 | about uninitialized variables. You should look into these warnings to | |
108 | make sure they are indeed spurious, but you needn't correct warnings | |
109 | caused by this EGCS bug. | |
110 | ||
0822a9c1 JB |
111 | - If you add code which uses functions or other features that are not |
112 | entirely portable, please make sure the rest of Guile will still | |
113 | function properly on systems where they are missing. This usually | |
114 | entails adding a test to configure.in, and then adding #ifdefs to your | |
115 | code to disable it if the system's features are missing. | |
afdfe3f4 | 116 | |
795b4217 JB |
117 | - When you make a user-visible change (i.e. one that should be |
118 | documented, and appear in NEWS, put an asterisk in column zero of the | |
119 | start of the ChangeLog entry, like so: | |
120 | ||
121 | Sat Aug 3 01:27:14 1996 Gary Houston <ghouston@actrix.gen.nz> | |
122 | ||
123 | * * fports.c (scm_open_file): don't return #f, throw error. | |
124 | ||
fa3f45cc JB |
125 | When you've written a NEWS entry and updated the documentation, go |
126 | ahead and remove the asterisk. I will use the asterisks to find and | |
127 | document changes that haven't been dealt with before a release. | |
128 | ||
d49a7907 JB |
129 | - Please write log entries for functions written in C under the |
130 | functions' C names, and write log entries for functions written in | |
131 | Scheme under the functions' Scheme names. Please don't do this: | |
132 | ||
133 | * procs.c, procs.h (procedure-documentation): Moved from eval.c. | |
134 | ||
135 | Entries like this make it harder to search the ChangeLogs, because you | |
afdfe3f4 JB |
136 | can never tell which name the entry will refer to. Instead, write this: |
137 | ||
138 | * procs.c, procs.h (scm_procedure_documentation): Moved from eval.c. | |
d49a7907 | 139 | |
4085a3da JB |
140 | Changes like adding this line are special: |
141 | ||
142 | SCM_PROC (s_serial_map, "serial-map", 2, 0, 1, scm_map); | |
143 | ||
144 | Since the change here is about the name itself --- we're adding a new | |
145 | alias for scm_map that guarantees the order in which we process list | |
146 | elements, but we're not changing scm_map at all --- it's appropriate | |
147 | to use the Scheme name in the log entry. | |
148 | ||
30d14d55 JB |
149 | - There's no need to keep a change log for documentation files. This |
150 | is because documentation is not susceptible to bugs that are hard to | |
151 | fix. Documentation does not consist of parts that must interact in a | |
152 | precisely engineered fashion; to correct an error, you need not know | |
153 | the history of the erroneous passage. (This is copied from the GNU | |
154 | coding standards.) | |
155 | ||
795b4217 JB |
156 | - Make sure you have papers from people before integrating their |
157 | changes or contributions. This is very frustrating, but very | |
158 | important to do right. From maintain.texi, "Information for | |
159 | Maintainers of GNU Software": | |
160 | ||
161 | When incorporating changes from other people, make sure to follow the | |
162 | correct procedures. Doing this ensures that the FSF has the legal | |
163 | right to distribute and defend GNU software. | |
164 | ||
165 | For the sake of registering the copyright on later versions ofthe | |
166 | software you need to keep track of each person who makes significant | |
167 | changes. A change of ten lines or so, or a few such changes, in a | |
168 | large program is not significant. | |
169 | ||
170 | *Before* incorporating significant changes, make sure that the person | |
171 | has signed copyright papers, and that the Free Software Foundation has | |
172 | received them. | |
173 | ||
174 | If you receive contributions you want to use from someone, let me know | |
175 | and I'll take care of the administrivia. Put the contributions aside | |
176 | until we have the necessary papers. | |
177 | ||
fa3f45cc JB |
178 | - When you make substantial changes to a file, add the current year to |
179 | the list of years in the copyright notice at the top of the file. | |
795b4217 | 180 | |
d2bd3d8d JB |
181 | |
182 | Helpful hints ======================================================== | |
183 | ||
f84f77f5 JB |
184 | - [From Mikael Djurfeldt] When working on the Guile internals, it is |
185 | quite often practical to implement a scheme-level procedure which | |
186 | helps you examine the feature you're working on. | |
187 | ||
188 | Examples of such procedures are: pt-size, debug-hand and | |
189 | current-pstate. | |
190 | ||
191 | I've now put #ifdef GUILE_DEBUG around all such procedures, so that | |
192 | they are not compiled into the "normal" Guile library. Please do the | |
193 | same when you add new procedures/C functions for debugging purpose. | |
194 | ||
195 | You can define the GUILE_DEBUG flag by passing --enable-guile-debug to | |
196 | the configure script. | |
197 | ||
52591c80 JB |
198 | - You'll see uses of the macro SCM_P scattered throughout the code; |
199 | those are vestiges of a time when Guile was meant to compile on | |
200 | pre-ANSI compilers. Guile now requires ANSI C, so when you write new | |
201 | functions, feel free to use ANSI declarations, and please provide | |
1cf84ea5 | 202 | prototypes for everything. You don't need to use SCM_P in new code. |
52591c80 | 203 | |
795b4217 JB |
204 | |
205 | Jim Blandy |