[Guile-commits] 03/05: Minor updates to HACKING.

[Andy Wingo]

wingo pushed a commit to branch stable-2.2
in repository guile.

commit d4aa914907a411e3a889eb77d395ba0c538723e0
Author: Andy Wingo <address@hidden>
Date:   Mon May 22 13:12:29 2017 +0200

    Minor updates to HACKING.
    
    * HACKING: Minor updates.
---
 HACKING | 120 +++++++---------------------------------------------------------
 1 file changed, 13 insertions(+), 107 deletions(-)

diff --git a/HACKING b/HACKING
index f3011d9..181530f 100644
--- a/HACKING
+++ b/HACKING
@@ -1,7 +1,6 @@
 -*-text-*-
 Guile Hacking Guide
-Copyright (c) 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2008, 2012,
- 2015 Free software Foundation, Inc.
+Copyright (c) 1996-2002,2008,2012,2015,2017 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
@@ -21,13 +20,8 @@ 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 address@hidden mailing list.
-See http://www.gnu.org/software/guile/mail/mail.html for more info.
+It's a good idea to join the address@hidden mailing list.  See
+http://www.gnu.org/software/guile/mail/mail.html for more info.
 
 
 Hacking It Yourself ==================================================
@@ -78,67 +72,11 @@ 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\""
+In GDB, you probably want to load the gdbinit file included with Guile,
+which defines a number of GDB helpers to inspect Scheme values.
 
 
 Contributing Your Changes ============================================
@@ -179,19 +117,15 @@ 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.  :)
+next, and from one architecture to the next.  For this reason,
+--enable-error-on-warning is not enabled by default.
 
 - 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.
+code to disable it if the system's features are missing.  Do check first
+if the function has a Gnulib wrapper, though.
 
 - 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
@@ -225,10 +159,6 @@ When deprecating a definition, always follow this 
procedure:
 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,
@@ -266,12 +196,12 @@ Maintainers of GNU Software":
     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.
+If you receive contributions you want to use from someone, let a
+maintainer know and they will 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.
+THANKS up-to-date.
 
 - 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.
@@ -325,27 +255,3 @@ 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
-