diff options
author | Ludovic Courtès <ludo@gnu.org> | 2007-10-16 17:00:21 +0000 |
---|---|---|
committer | Ludovic Courtès <ludo@gnu.org> | 2007-10-16 17:00:21 +0000 |
commit | a84251b06a61fd29099f37b653b934bf6c9c6070 (patch) | |
tree | 94f077850cd4ec00d54592e1c135f0bae151fe27 /HACKING | |
parent | c8bb98a9fa280ec938d715b379e87c0daba399fe (diff) |
Add missing file `HACKING'.
Diffstat (limited to 'HACKING')
-rw-r--r-- | HACKING | 665 |
1 files changed, 665 insertions, 0 deletions
diff --git a/HACKING b/HACKING new file mode 100644 index 000000000..ebd78e45c --- /dev/null +++ b/HACKING @@ -0,0 +1,665 @@ +-*-text-*- +Guile Hacking Guide +Copyright (c) 1996, 1997, 1998, 1999, 2000, 2001, 2002 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 CVS, 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 listed below, correctly installed. +i.e., they must be found in the current PATH and not shadowed or +otherwise broken by files left behind from other versions. + +"up-to-date" means the latest released versions at the time that Guile +was obtained from CVS. Sometimes older or newer versions will work. +(See below for versions to avoid.) + +Then you must run the autogen.sh script, as described below. + +In case of problems, it may be worth getting a fresh copy of Guile +from CVS: synchronisation problems have been known to occur +occasionally. + +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" + +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. + +- (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. The best +place to post it is guile-devel@gnu.org. Please don't send it +directly to me; I often don't have time to look things over. If you +have tested your change, then you don't need to be shy. + +- Please submit patches using either context or unified diffs (diff -c +or diff -u). Don't include a patch for ChangeLog; such patches don't +apply cleanly, since we've probably changed the top of ChangeLog too. +Instead, provide the unaltered text at the top of your patch. + +- 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). + +Please don't include patches for generated files like configure, +aclocal.m4, or any Makefile.in. Such patches are often large, and +we're just going to regenerate those files anyway. + + +CVS conventions ====================================================== + +- We use CVS to manage the Guile sources. The repository lives on +subversions.gnu.org, in /cvs; you will need an +account on that machine to access the repository. Also, for security +reasons, subversions presently only supports CVS connections via the SSH +protocol, so you must first install the SSH client. Then, you should +set your CVS_RSH environment variable to ssh, and use the following as +your CVS root: + + :ext:USER@subversions.gnu.org:/cvs + +Either set your CVSROOT environment variable to that, or give it as +the value of the global -d option to CVS when you check out a working +directory. + +For more information on SSH, see http://www.openssh.com. + +The Guile sources live in several modules: + + - guile-core --- the interpreter, QuickThreads, and ice-9 + - guile-tcltk --- the Guile/Tk interface + - guile-tk --- the new Guile/Tk interface, based on STk's modified Tk + - guile-rgx-ctax --- the Guile/Rx interface, and the ctax implementation + - guile-scsh --- the port of SCSH to guile, talk to Gary Houston + - guile-www --- A Guile module for making HTTP requests. + - guile-statprof --- an experimental statistical profiler. + +There is a mailing list for CVS commit messages; see README for details. + +- The guile-core tree is now versioned similarly to the Linux kernel. +Guile now always uses three numbers to represent the version, +i.e. "1.6.5". The first number, 1, is the major version number, the +second number, 6, is the minor version number, and the third number, +5, is the micro version number. Changes in major version number +indicate major changes in Guile. + +Minor version numbers that are even denote stable releases, and odd +minor version numbers denote development versions (which may be +unstable). The micro version number indicates a minor sub-revision of +a given MAJOR.MINOR release. + +- A default CVS checkout will get the current unstable development +tree. However, for each stable release, a CVS branch is created so +that release (and ongoing maintenance) of the stable version can +proceed independent of the development of the next unstable version. +To check out a particular stable branch, you just need to specify "-r +branch_release-X-Y" to your CVS checkout command (or to any update). +For example, if you wanted to check out the 1.6 stable branch, you +would specify "-r branch_release-1-6". + +So, for example, during a normal development cycle, work will proceed +on an unstable version, say 1.5.X, until it is decided that it's time +for a stable release. At that point, a branch named +branch_release-1-6 will be created, and the version numbers on the +HEAD of the CVS tree (the trunk, i.e. what you get by default), will +be changed to reflect the new unstable version 1.7.X. Then unstable +development will proceed on the unstable version, while the stable +1.5.X branch is fixed up for the eventual 1.6.0 release. + +Anytime you want to yank an existing checked out tree to the stable +branch, you can run a command like this: + + cvs -z3 update -r branch_release-1-6 -Pd + +This will yank the working directory over on to the stable release +branch. Note that this directory will track that branch from then on +unless you do something to yank it back to the main (unstable) trunk. + +To go back to the unstable branch, you can use + + cvs -z3 update -A -Pd + +Note that in either case, you should probably make sure you've +commited or removed all local changes before running the commands or +you're likely to have some unexpected results. + +Finally note that one approach, should you need to work on both +branches, is to keep two trees checked out, one stable, the other +unstable and you can work in whichever is appropriate. + +To save some initial bandwidth, you can check out either the stable +tree or the unstable tree, and then do something like this: + + cp -a core-unstable core-1.5 + cd core-1.5 + cvs -z3 update -r branch_release-1-6 -Pd + +- The stable and unstable CVS trees are distinct, and no changes will +automatically propagate between them. If you make changes that need +to show up both places, you'll need to apply the changes both places. +You *might* be able to do this with a cvs command, but often you'll +probably need to apply the changes by hand or risk migrating +superfluous modifications between the two versions. This is +particularly important when moving a change from the unstable branch +to the stable branch. + +- In general, please don't be adventurous with the stable branch. We +mostly want bugfixes, documentation improvements, build improvements, +etc., though exceptions will doubtless exist. + +- There are a few CVS tagging conventions which follow the Scheme +convention that dashes are used to separate words within a single +symbol, and so dashes bind more tightly than underscores. This means +that foo-bar_baz-bax indicates that foo-bar is somehow separate from +baz-bax. The conventions are as follows: + + Branch root tags: + ----------------- + anytime just before you create a branch it's a good + idea to create a normal tag so that you can refer to the branch point + on the main trunk as well as on the branch. So please use a tag of + the form + + branch-root-release-1-X + + or more generally, for other non-release branches: + + branch-root_FOO + + Branch tags: + ------------ + for the branch tag itself please use + + branch_release-1-6 + + or more generally, for other non-release branches: + + branch_FOO + + Merge tags: + ----------- + Whenever you're merging a branch back into the trunk (or into another + branch repeatedly) you need to tag the branch each time you merge. If + you don't do that, you won't be able to merge repeatedly without + possibly tedious conflicts. For those tags, we suggest: + + branch-merge_SOME-FOO_to_SOME-BAR_1 + branch-merge_SOME-FOO_to_SOME-BAR_2 + .. + + As an example, SOME-BAR might be trunk, or even perhaps another branch + like branch-mvo-super-fixes :> + + More mundanely, you might have + + branch-merge_release-1-6_to_trunk_1 + + (Merging the stable branch to the trunk like this + will probably be much more common, when it happens, than the + reverse for the reasons mentioned above. + + Release tags: + ------------- + When releasing a new version of guile, please use: + + release_X-Y-Z + + i.e. + + release_1-6-0 + +- If you hack on a stable branch, please apply any relevant patches or +fixes to the current unstable version (the main CVS trunk) as well. +Similarly, please back-port any important fixes to the unstable CVS +tree to the current stable branch. + +- We check Makefile.am and configure.in files into CVS, but the +"autogen.sh" script must be run from the top-level to generate the +actual "configure" script that then must be run to create the various +Makefile-s to build guile. The general rule is that you should be able +to check out a working directory of Guile from CVS, and then type +"./autogen.sh", then "configure", and finally "make". No +automatically generated files should be checked into the CVS +repository. + +- The .cvsignore file is contained in the repository, to provide a +reasonable list of auto-generated files that should not be checked in. +This, however, prohibits one from having local additions to the +.cvsignore file (yes, you can modify it and never check it in, but +that doesn't seem to be a good solution to me). To get around this +problem, you might want to patch your cvs program so that it uses a +.cvsignore-local file (say) instead of the one from the repository. A +patch for this can be found at the very end of this file. + +- (Automake 1.4 only) Be sure to run automake at the top of the tree +with no arguments. Do not use `automake Makefile' to regenerate +specific Makefile.in files, and do not trust the Makefile rules to +rebuild them when they are out of date. Automake 1.4 will add +extraneous rules to the top-level Makefile if you specify specific +Makefiles to rebuild on the command line. Running the command +`autoreconf --force' should take care of everything correctly. + +- Make sure your changes compile and work, at least on your own +machine, before checking them into the main branch of the Guile +repository. A good way for testing this is to run "make distcheck". +If you really need to check in untested changes, make a branch. + +- 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. + + +Coding standards ===================================================== + +- Before contributing larger amounts of code to Guile, please read the +documents in `guile-core/devel/policy' in the CVS source tree. + +- 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. + +- 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. :) + +Note also that EGCS (as of November 3 1998) doesn't handle the +`noreturn' attribute properly, so it doesn't understand that functions +like scm_error won't return. This may lead to some silly warnings +about uninitialized variables. You should look into these warnings to +make sure they are indeed spurious, but you needn't correct warnings +caused by this EGCS bug. + +- 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: + +1. Mark the definition using + + #if (SCM_DEBUG_DEPRECATED == 0) + ... + #endif + + or, for Scheme code, wrap it using + + (begin-deprecated + ...) + +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). + +3. Write a comment at the definition explaining how a programmer can + manage without the deprecated definition. + +4. Add an entry that the definition has been deprecated in NEWS and + explain what do do instead. + +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. + +- Please write log entries for functions written in C under the +functions' C names, and write log entries for functions written in +Scheme under the functions' Scheme names. Please don't do this: + + * procs.c, procs.h (procedure-documentation): Moved from eval.c. + +Entries like this make it harder to search the ChangeLogs, because you +can never tell which name the entry will refer to. Instead, write this: + + * procs.c, procs.h (scm_procedure_documentation): Moved 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 log entry. + +- There's no need to keep a change log for a ChangeLog file. For any +other kind of file (including documentation, since our documentation +is indeed precisely engineered -- we surpass GNU standards here), add +an appropriate ChangeLog entry when you change it. Simple! + +- Make sure you have papers from people before integrating their +changes or contributions. This is very frustrating, but very +important to do right. From maintain.texi, "Information for +Maintainers of GNU Software": + + When incorporating changes from other people, make sure to follow the + correct procedures. Doing this ensures that the FSF has the legal + right to distribute and defend GNU software. + + For the sake of registering the copyright on later versions ofthe + software you need to keep track of each person who makes significant + changes. A change of ten lines or so, or a few such changes, in a + large program is not significant. + + *Before* incorporating significant changes, make sure that the person + has signed copyright papers, and that the Free Software Foundation has + received them. + +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. + + +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. + +Examples of such procedures are: pt-size, debug-hand and +current-pstate. + +I've now put #ifdef GUILE_DEBUG around all such procedures, so that +they are not compiled into the "normal" Guile library. Please do the +same when you add new procedures/C functions for debugging purpose. + +You can define the GUILE_DEBUG flag by passing --enable-guile-debug to +the configure script. + +- You'll see uses of the macro SCM_P scattered throughout the code; +those are vestiges of a time when Guile was meant to compile on +pre-ANSI compilers. Guile now requires ANSI C, so when you write new +functions, feel free to use ANSI declarations, and please provide +prototypes for everything. You don't need to use SCM_P in new code. + + +Jim Blandy, and others + + +Patches =========================================================== + +This one makes cvs-1.10 consider the file $CVSDOTIGNORE instead of +.cvsignore when that environment variable is set. + +=== patch start === +diff -r -u cvs-1.10/src/cvs.h cvs-1.10.ignore-hack/src/cvs.h +--- cvs-1.10/src/cvs.h Mon Jul 27 04:54:11 1998 ++++ cvs-1.10.ignore-hack/src/cvs.h Sun Jan 23 12:58:09 2000 +@@ -516,7 +516,7 @@ + + extern int ign_name PROTO ((char *name)); + void ign_add PROTO((char *ign, int hold)); +-void ign_add_file PROTO((char *file, int hold)); ++int ign_add_file PROTO((char *file, int hold)); + void ign_setup PROTO((void)); + void ign_dir_add PROTO((char *name)); + int ignore_directory PROTO((char *name)); +diff -r -u cvs-1.10/src/ignore.c cvs-1.10.ignore-hack/src/ignore.c +--- cvs-1.10/src/ignore.c Mon Sep 8 01:04:15 1997 ++++ cvs-1.10.ignore-hack/src/ignore.c Sun Jan 23 12:57:50 2000 +@@ -99,9 +99,9 @@ + /* + * Open a file and read lines, feeding each line to a line parser. Arrange + * for keeping a temporary list of wildcards at the end, if the "hold" +- * argument is set. ++ * argument is set. Return true when the file exists and has been handled. + */ +-void ++int + ign_add_file (file, hold) + char *file; + int hold; +@@ -149,8 +149,8 @@ + if (fp == NULL) + { + if (! existence_error (errno)) +- error (0, errno, "cannot open %s", file); +- return; ++ error (0, errno, "cannot open %s", file); ++ return 0; + } + while (getline (&line, &line_allocated, fp) >= 0) + ign_add (line, hold); +@@ -159,6 +159,7 @@ + if (fclose (fp) < 0) + error (0, errno, "cannot close %s", file); + free (line); ++ return 1; + } + + /* Parse a line of space-separated wildcards and add them to the list. */ +@@ -375,6 +376,7 @@ + struct stat sb; + char *file; + char *xdir; ++ char *cvsdotignore; + + /* Set SUBDIRS if we have subdirectory information in ENTRIES. */ + if (entries == NULL) +@@ -397,7 +399,10 @@ + if (dirp == NULL) + return; + +- ign_add_file (CVSDOTIGNORE, 1); ++ cvsdotignore = getenv("CVSDOTIGNORE"); ++ if (cvsdotignore == NULL || !ign_add_file (cvsdotignore, 1)) ++ ign_add_file (CVSDOTIGNORE, 1); ++ + wrap_add_file (CVSDOTWRAPPER, 1); + + while ((dp = readdir (dirp)) != NULL) +=== patch end === + +This one is for pcl-cvs-2.9.2, so that `i' adds to the local +.cvsignore file. + +=== patch start === +--- pcl-cvs.el~ Mon Nov 1 12:33:46 1999 ++++ pcl-cvs.el Tue Jan 25 21:46:27 2000 +@@ -1177,7 +1177,10 @@ + "Append the file in FILEINFO to the .cvsignore file. + Can only be used in the *cvs* buffer." + (save-window-excursion +- (set-buffer (find-file-noselect (expand-file-name ".cvsignore" dir))) ++ (set-buffer (find-file-noselect ++ (expand-file-name (or (getenv "CVSDOTIGNORE") ++ ".cvsignore") ++ dir))) + (goto-char (point-max)) + (unless (zerop (current-column)) (insert "\n")) + (insert str "\n") +=== patch end === |