X-Git-Url: http://git.hcoop.net/bpt/guile.git/blobdiff_plain/294a61d33e514b2bcf429772a59ae4b8f87aac18..e87f059319e40b582d5ee8fd815876550f1148b9:/HACKING diff --git a/HACKING b/HACKING dissimilarity index 71% index 63c0ffb68..b08f7c2d4 100644 --- a/HACKING +++ b/HACKING @@ -1,343 +1,350 @@ -Hacking It Yourself ================================================== - -As distributed, Guile needs only an ANSI C compiler and a Unix system -to compile. However, Guile's makefiles, configuration scripts, and a -few other files are automatically generated, not written by hand. If -you want to make changes to the system (which we encourage!) you will -find it helpful to have the tools we use to develop Guile. They -are the following: - -Autoconf 2.13 --- 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 1.4 --- 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" - - Before using automake, you may need to copy `threads.m4' and - `guile.m4' from the top directory of the Guile core disty to - `/usr/local/share/aclocal. - -libtool 1.3.4 --- 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" - -You are lost in a little maze of automatically generated files, all -different. -> - - -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@sourceware.cygnus.com. 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. - -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 -egcs.cygnus.com, in /cvs/guile; you will need an -account on that machine to access the repository. Also, for security -reasons, egcs 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@egcs.cygnus.com:/cvs/guile - -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.cs.hut.fi/ssh. - -The Guile sources live in several modules: - - - guile-core --- the interpreter, QuickThreads, and ice-9 - - guile-doc --- documentation in progress. When complete, this will - be incorporated into guile-core. - - guile-oops --- The Guile Object-Oriented Programming System (talk to mdj) - - 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. - -There is a mailing list for CVS commit messages; see README for details. - -- 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. 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 ===================================================== - -- 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 -The only warnings which can be tolerated are those about variables -being clobbered by longjmp/vfork in eval.c. The variables in question -are critical to the interpreter's performance; as far as I can tell, -it is difficult/annoying to avoid these warnings without slowing the -system down substantially. (If you can figure out a good fix, I'd be happy to see it.) - -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. - -- 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: - -Sat Aug 3 01:27:14 1996 Gary Houston - -* * fports.c (scm_open_file): don't return #f, throw error. - -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. - -- 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_serial_map, "serial-map", 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 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.) - -- 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. - -- 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. - - -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 - - -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 === +-*-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. + +- 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: + +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 to 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. + +- 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 +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. + +- 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. + +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. + + +Jim Blandy, and others +