-Here are some guidelines for members of the Guile developers team.
+Guile Hacking Guide
+Copyright (c) 1996, 1997, 1998, 1999, 2000, 2001 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 devel/tasks.text. Note
+that this file is available only from CVS checkout and not distributed
+w/ Guile releases.
+
+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 ==================================================
+
+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.50 --- 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-p2 --- 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.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"
+
+flex 2.5.4 --- a tokenizer generator. earlier versions will most
+ probably work too.
+
+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-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.
+
+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 /egcs/carton/cvsfiles; 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:
+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@egcs.cygnus.com:/egcs/carton/cvsfiles
+ :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
- 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-comp --- the Hobbit compiler (talk to mdj)
- - guile-emacs --- Guile/Emacs interface (talk to mdj)
- - guile-oops --- The Guile Object-Oriented Programming System (talk to mdj)
- guile-www --- A Guile module for making HTTP requests.
-- We check Makefile.in and configure files into CVS, as well as the
-files they are built from (Makefile.am, configure.in); we do not 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",
-without running any other tools.
+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
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
- The Guile tree should compile without warnings under the following
GCC switches, which are the default in the current configure script:
- -Wall -Wpointer-arith -Wmissing-prototypes
-The only exceptions are the warnings about variables being clobbered
-by longjmp/vfork in eval.c. (Tho' if you can figure out how to get
-rid of those, too, I'd be happy.)
+
+ -O2 -Wall -Wpointer-arith -Wmissing-prototypes
+
+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. At the top of RELEASE, 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.
- 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
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_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 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
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 underscaores `_'. All non-static identifiers should
+ start with scm_ or SCM_. Then might follow zero or more one letter
+ 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
+
+
Helpful hints ========================================================
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.
-
-
-Jim Blandy
+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 ===
HCoop / bpt / guile.git / blobdiff