X-Git-Url: https://git.hcoop.net/bpt/guile.git/blobdiff_plain/f84f77f58d9b27fbb696eba7834ec4bd2527cd7d..3f4829e082c2fdd0553a6ce97fe173f8df327e7b:/HACKING diff --git a/HACKING b/HACKING index 7855241c0..b08f7c2d4 100644 --- a/HACKING +++ b/HACKING @@ -1,49 +1,251 @@ -Here are some guidelines for working on the Guile source tree at GNU. +-*-text-*- +Guile Hacking Guide +Copyright (c) 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2008, 2012 Free software Foundation, Inc. + + Permission is granted to anyone to make or distribute verbatim copies + of this document as received, in any medium, provided that the + copyright notice and permission notice are preserved, + and that the distributor grants the recipient permission + for further redistribution as permitted by this notice. + + Permission is granted to distribute modified versions + of this document, or of portions of it, + under the above conditions, provided also that they + carry prominent notices stating who last changed them, + and that any new or changed statements about the activities + of the Free Software Foundation are approved by the Foundation. + + +What to Hack ========================================================= + +You can hack whatever you want, thank GNU. + +However, to see what others have indicated as their interest (and avoid +potential wasteful duplication of effort), see file TODO. Note that +the version you find may be out of date; a CVS checkout is recommended: +see below for details (see also the files ANON-CVS and SNAPSHOTS). + +It's also a good idea to join the guile-devel@gnu.org mailing list. +See http://www.gnu.org/software/guile/mail/mail.html for more info. + + +Hacking It Yourself ================================================== + +When Guile is obtained from Git, a few extra steps must be taken +before the usual configure, make, make install. You will need to have +up-to-date versions of the tools as listed below, correctly installed. + +Sometimes older or newer versions will work. (See below for versions +to avoid.) + +Then you must run the autogen.sh script, as described below. + +The same procedure can be used to regenerate the files in released +versions of Guile. In that case the headers of the original generated +files (e.g., configure, Makefile.in, ltmain.sh) can be used to +identify which tool versions may be required. + +Autoconf --- a system for automatically generating `configure' + scripts from templates which list the non-portable features a + program would like to use. Available in + "ftp://ftp.gnu.org/pub/gnu/autoconf" + +Automake --- a system for automatically generating Makefiles that + conform to the (rather Byzantine) GNU coding standards. The + nice thing is that it takes care of hairy targets like 'make + dist' and 'make distclean', and automatically generates + Makefile dependencies. Automake is available in + "ftp://ftp.gnu.org/pub/gnu/automake" + +libtool --- a system for managing the zillion hairy options needed + on various systems to produce shared libraries. Available in + "ftp://ftp.gnu.org/pub/gnu/libtool". Version 2.2 (or + later) is recommended (for correct AIX support, and correct + interaction with the Gnulib module for using libunistring). + +gettext --- a system for rigging a program so that it can output its + messages in the local tongue. Guile presently only exports + the gettext functionality to Scheme, it does not use it + itself. + +flex --- a scanner generator. It's probably not essential to have the + latest version. + +One false move and you will be lost in a little maze of automatically +generated files, all different. + +Here is the authoritative list of tool/version/platform tuples that +have been known to cause problems, and a short description of the problem. + +- automake 1.4 adds extraneous rules to the top-level Makefile if + you specify specific Makefiles to rebuild on the command line. + +- automake 1.4-p4 (debian "1:1.4-p4-1.1") all platforms + automake "include" facility does not recognize filenames w/ "-". + +- libtool 1.4 uses acconfig.h, which is deprecated by newest autoconf + (which constructs the equivalent through 3rd arg of AC_DEFINE forms). + +- autoreconf from autoconf prior to 2.59 will run gettextize, which + will mess up the Guile tree. + +- libtool 1.5.26 does not know that it should remove the -R options + that the Gnulib libunistring and havelib modules generate (because + gcc doesn't actually support -R). + +- (add here.) + + +Sample GDB Initialization File========================================= + +Here is a sample .gdbinit posted by Bill Schottstaedt (modified to +use `set' instead of `call' in some places): + + define gp + set gdb_print($arg0) + print gdb_output + end + document gp + Executes (object->string arg) + end + + define ge + call gdb_read($arg0) + call gdb_eval(gdb_result) + set gdb_print(gdb_result) + print gdb_output + end + document ge + Executes (print (eval (read arg))): ge "(+ 1 2)" => 3 + end + + define gh + call g_help(scm_str2symbol($arg0), 20) + set gdb_print($1) + print gdb_output + end + document gh + Prints help string for arg: gh "enved-target" + end + +Bill further writes: + + so in gdb if you see something useless like: + + #32 0x081ae8f4 in scm_primitive_load (filename=1112137128) at load.c:129 + + You can get the file name with gp: + + (gdb) gp 1112137128 + $1 = 0x40853fac "\"/home/bil/test/share/guile/1.5.0/ice-9/session.scm\"" + + +Contributing Your Changes ============================================ + +- If you have put together a change that meets the coding standards +described below, we encourage you to submit it to Guile. Post your +patch to guile-devel@gnu.org. + +- We prefer patches generated using 'git format-patch'. + +- Provide a description in the commit message, like so: + + 1-line description of change + + More extensive discussion of your change. Document why you are + changing things. + + * filename (function name): file specific change comments. + +- For proper credit, also make sure you update the AUTHORS file +(for new files for which you've assigned copyright to the FSF), or +the THANKS file (for everything else). + + +Coding standards ===================================================== - As for any part of Project GNU, changes to Guile should follow the GNU coding standards. The standards are available via anonymous FTP from prep.ai.mit.edu, as /pub/gnu/standards/standards.texi and make-stds.texi. -- Check Makefile.in and configure files into CVS, as well as any files -used to create them (Makefile.am, configure.in); don't check in -Makefiles or header files generated by configuration scripts. The -general rule is that you should be able to check out a working -directory of Guile from CVS, and then type "configure" and "make". +- The Guile tree should compile without warnings under the following +GCC switches, which are the default in the current configure script: + + -O2 -Wall -Wpointer-arith -Wmissing-prototypes + +To make sure of this, you can use the --enable-error-on-warning option +to configure. This option will make GCC fail if it hits a warning. + +Note that the warnings generated vary from one version of GCC to the +next, and from one architecture to the next (apparently). To provide +a concrete common standard, Guile should compile without warnings from +GCC 2.7.2.3 in a Red Hat 5.2 i386 Linux machine. Furthermore, each +developer should pursue any additional warnings noted by on their +compiler. This means that people using more stringent compilers will +have more work to do, and assures that everyone won't switch to the +most lenient compiler they can find. :) + +- If you add code which uses functions or other features that are not +entirely portable, please make sure the rest of Guile will still +function properly on systems where they are missing. This usually +entails adding a test to configure.in, and then adding #ifdefs to your +code to disable it if the system's features are missing. + +- The normal way of removing a function, macro or variable is to mark +it as "deprecated", keep it for a while, and remove it in a later +release. If a function or macro is marked as "deprecated" it +indicates that people shouldn't use it in new programs, and should try +to remove it in old. Make sure that an alternative exists unless it +is our purpose to remove functionality. Don't deprecate definitions +if it is unclear when they will be removed. (This is to ensure that a +valid way of implementing some functionality always exists.) + +When deprecating a definition, always follow this procedure: -- Make sure your changes compile and work, at least on your own -machine, before checking them into the main branch of the Guile -repository. If you really need to check in untested changes, make a -branch. +1. Mark the definition using -- When you make a user-visible change (i.e. one that should be -documented, and appear in NEWS, put an asterisk in column zero of the -start of the ChangeLog entry, like so: + #if (SCM_DEBUG_DEPRECATED == 0) + ... + #endif -Sat Aug 3 01:27:14 1996 Gary Houston + or, for Scheme code, wrap it using -* * fports.c (scm_open_file): don't return #f, throw error. + (begin-deprecated + ...) -When you've written a NEWS entry and updated the documentation, go -ahead and remove the asterisk. I will use the asterisks to find and -document changes that haven't been dealt with before a release. +2. Make the deprecated code issue a warning when it is used, by using + scm_c_issue_deprecation_warning (in C) or issue-deprecation-warning + (in Scheme). -- Include each log entry in both the ChangeLog and in the CVS logs. -If you're using Emacs, the pcl-cvs interface to CVS has features to -make this easier; it checks the ChangeLog, and generates good default -CVS log entries from that. +3. Write a comment at the definition explaining how a programmer can + manage without the deprecated definition. -- There's no need to keep a change log for documentation files. This -is because documentation is not susceptible to bugs that are hard to -fix. Documentation does not consist of parts that must interact in a -precisely engineered fashion; to correct an error, you need not know -the history of the erroneous passage. (This is copied from the GNU -coding standards.) +4. Add an entry that the definition has been deprecated in NEWS and + explain what to do instead. -- If you add or remove files, don't forget to update the appropriate -part of the relevant Makefile.am files, and regenerate the -Makefile.in. If you forget this, the snapshot and distribution -processes will not work. +5. In file TODO, there is a list of releases with reminders about what + to do at each release. Add a reminder about the removal of the + deprecated defintion at the appropriate release. + +- Write commit messages for functions written in C using the +functions' C names, and write entries for functions written in Scheme +using the functions' Scheme names. For example, + + * foo.c: Moved scm_procedure_documentation from eval.c. + +is preferred over + + * foo.c: Moved procedure-documentation from eval.c. + +Changes like adding this line are special: + + SCM_PROC (s_map_in_order, "map-in-order", 2, 0, 1, scm_map); + +Since the change here is about the name itself --- we're adding a new +alias for scm_map that guarantees the order in which we process list +elements, but we're not changing scm_map at all --- it's appropriate +to use the Scheme name in the commit message. - Make sure you have papers from people before integrating their changes or contributions. This is very frustrating, but very @@ -67,9 +269,68 @@ If you receive contributions you want to use from someone, let me know and I'll take care of the administrivia. Put the contributions aside until we have the necessary papers. +Once you accept a contribution, be sure to keep the files AUTHORS and +THANKS uptodate. + - When you make substantial changes to a file, add the current year to the list of years in the copyright notice at the top of the file. +- When you get bug reports or patches from people, be sure to list +them in THANKS. + +- Do not introduce trailing whitespace (and feel free to clean it up +opportunistically, that is, if doing so is part of some other change). +The goal is to reduce (and over time, eliminate) spurious diffs. + +For Emacs users: + (add-hook 'before-save-hook 'delete-trailing-whitespace) + +Naming conventions ================================================= + +We use certain naming conventions to structure the considerable number +of global identifiers. All identifiers should be either all lower +case or all upper case. Syllables are separated by underscores `_'. +All non-static identifiers should start with scm_ or SCM_. Then might +follow zero or more syllables giving the category of the identifier. +The currently used category identifiers are + + t - type name + + c,C - something with a interface suited for C use. This is used + to name functions that behave like Scheme primitives but + have a more C friendly calling convention. + + i,I - internal to libguile. It is global, but not considered part + of the libguile API. + + f - a SCM variable pointing to a Scheme function object. + + F - a bit mask for a flag. + + m - a macro transformer procedure + + n,N - a count of something + + s - a constant C string + + k - a SCM variable pointing to a keyword. + + sym - a SCM variable pointing to a symbol. + + var - a SCM variable pointing to a variable object. + +The follwing syllables also have a technical meaning: + + str - this denotes a zero terminated C string + + mem - a C string with an explicit count + + +See also the file `devel/names.text'. + + +Helpful hints ======================================================== + - [From Mikael Djurfeldt] When working on the Guile internals, it is quite often practical to implement a scheme-level procedure which helps you examine the feature you're working on. @@ -85,4 +346,5 @@ You can define the GUILE_DEBUG flag by passing --enable-guile-debug to the configure script. -Jim Blandy +Jim Blandy, and others +