| 1 | -*-text-*- |
| 2 | Guile Hacking Guide |
| 3 | Copyright (c) 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2008 Free software Foundation, Inc. |
| 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 | |
| 34 | When Guile is obtained from Git, a few extra steps must be taken |
| 35 | before the usual configure, make, make install. You will need to have |
| 36 | up-to-date versions of the tools as listed below, correctly installed. |
| 37 | |
| 38 | Sometimes older or newer versions will work. (See below for versions |
| 39 | to avoid.) |
| 40 | |
| 41 | Then you must run the autogen.sh script, as described below. |
| 42 | |
| 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 |
| 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). |
| 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 | |
| 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 | |
| 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 |
| 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: |
| 152 | |
| 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. |
| 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 | |
| 164 | |
| 165 | Coding standards ===================================================== |
| 166 | |
| 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 | |
| 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 |
| 225 | explain what do do instead. |
| 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 | |
| 231 | - Write commit messages for functions written in C using the |
| 232 | functions' C names, and write entries for functions written in Scheme |
| 233 | using the functions' Scheme names. For example, |
| 234 | |
| 235 | * foo.c: Moved scm_procedure_documentation from eval.c. |
| 236 | |
| 237 | is preferred over |
| 238 | |
| 239 | * foo.c: Moved procedure-documentation from eval.c. |
| 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 |
| 248 | to use the Scheme name in the commit message. |
| 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 | |
| 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. |
| 284 | |
| 285 | Naming conventions ================================================= |
| 286 | |
| 287 | We use certain naming conventions to structure the considerable number |
| 288 | of global identifiers. All identifiers should be either all lower |
| 289 | case or all upper case. Syllables are separated by underscores `_'. |
| 290 | All non-static identifiers should start with scm_ or SCM_. Then might |
| 291 | follow zero or more syllables giving the category of the identifier. |
| 292 | The currently used category identifiers are |
| 293 | |
| 294 | t - type name |
| 295 | |
| 296 | c,C - something with a interface suited for C use. This is used |
| 297 | to name functions that behave like Scheme primitives but |
| 298 | have a more C friendly calling convention. |
| 299 | |
| 300 | i,I - internal to libguile. It is global, but not considered part |
| 301 | of the libguile API. |
| 302 | |
| 303 | f - a SCM variable pointing to a Scheme function object. |
| 304 | |
| 305 | F - a bit mask for a flag. |
| 306 | |
| 307 | m - a macro transformer procedure |
| 308 | |
| 309 | n,N - a count of something |
| 310 | |
| 311 | s - a constant C string |
| 312 | |
| 313 | k - a SCM variable pointing to a keyword. |
| 314 | |
| 315 | sym - a SCM variable pointing to a symbol. |
| 316 | |
| 317 | var - a SCM variable pointing to a variable object. |
| 318 | |
| 319 | The follwing syllables also have a technical meaning: |
| 320 | |
| 321 | str - this denotes a zero terminated C string |
| 322 | |
| 323 | mem - a C string with an explicit count |
| 324 | |
| 325 | |
| 326 | See also the file `devel/names.text'. |
| 327 | |
| 328 | |
| 329 | Helpful hints ======================================================== |
| 330 | |
| 331 | - [From Mikael Djurfeldt] When working on the Guile internals, it is |
| 332 | quite often practical to implement a scheme-level procedure which |
| 333 | helps you examine the feature you're working on. |
| 334 | |
| 335 | Examples of such procedures are: pt-size, debug-hand and |
| 336 | current-pstate. |
| 337 | |
| 338 | I've now put #ifdef GUILE_DEBUG around all such procedures, so that |
| 339 | they are not compiled into the "normal" Guile library. Please do the |
| 340 | same when you add new procedures/C functions for debugging purpose. |
| 341 | |
| 342 | You can define the GUILE_DEBUG flag by passing --enable-guile-debug to |
| 343 | the configure script. |
| 344 | |
| 345 | |
| 346 | Jim Blandy, and others |
| 347 | |