X-Git-Url: https://git.saurik.com/bison.git/blobdiff_plain/548e2104e2a7f8f751054f72098227dd323ec861..812775a0391e122eff1983afea2da96c600c7307:/HACKING?ds=sidebyside

diff --git a/HACKING b/HACKING
index 091ba66c..82f07bb4 100644
--- a/HACKING
+++ b/HACKING
@@ -5,7 +5,7 @@ Don't put this file into the distribution.
 
 Everything related to the development of Bison is on Savannah:
 
-	http://savannah.gnu.org/projects/bison/
+        http://savannah.gnu.org/projects/bison/
 
 
 * Administrivia
@@ -47,6 +47,118 @@ of the .output file etc.  This excludes impossible error messages
 meant for the maintainers only.
 
 
+* Working from the repository
+
+These notes intend to help people working on the checked-out sources.
+These requirements do not apply when building from a distribution tarball.
+
+** Requirements
+
+We've opted to keep only the highest-level sources in the repository.
+This eases our maintenance burden, (fewer merges etc.), but imposes more
+requirements on anyone wishing to build from the just-checked-out sources.
+For example, you have to use the latest stable versions of the maintainer
+tools we depend upon, including:
+
+- Automake <http://www.gnu.org/software/automake/>
+- Autoconf <http://www.gnu.org/software/autoconf/>
+- Flex <http://www.gnu.org/software/flex/>
+- Gettext <http://www.gnu.org/software/gettext/>
+- Gzip <http://www.gnu.org/software/gzip/>
+- Perl <http://www.cpan.org/>
+- Rsync <http://samba.anu.edu.au/rsync/>
+- Tar <http://www.gnu.org/software/tar/>
+
+Valgrind <http://valgrind.org/> is also highly recommended, if
+Valgrind supports your architecture.
+
+Bison is written using Bison grammars, so there are bootstrapping
+issues.  The bootstrap script attempts to discover when the C code
+generated from the grammars is out of date, and to bootstrap with an
+out-of-date version of the C code, but the process is not foolproof.
+Also, you may run into similar problems yourself if you modify Bison.
+
+Only building the initial full source tree will be a bit painful.
+Later, after synchronizing from the repository a plain `make' should
+be sufficient.
+
+** First checkout
+
+Obviously, if you are reading these notes, you did manage to check out
+this package from the repository.  For the record, you will find all the
+relevant information on:
+
+        http://savannah.gnu.org/git/?group=bison
+
+Bison uses Git submodules: subscriptions to other Git repositories.
+In particular it uses gnulib, the GNU portability library.  To ask Git
+to perform the first checkout of the submodules, run
+
+       $ git submodule update --init
+
+Git submodule support is weak before versions 1.6 and later, you
+should probably upgrade Git if your version is older.
+
+The next step is to get other files needed to build, which are
+extracted from other source packages:
+
+        $ ./bootstrap
+
+And there you are!  Just
+
+        $ ./configure
+        $ make
+        $ make check
+
+At this point, there should be no difference between your local copy,
+and the master copy:
+
+        $ git diff
+
+should output no difference.
+
+Enjoy!
+
+** Updating
+
+The use of submodules make things somewhat different because git does
+not support recursive operations: submodules must be taken care of
+explicitly by the user.
+
+*** Updating Bison
+
+If you pull a newer version of a branch, say via `git pull', you might
+import requests for updated submodules.  A simple `git diff' will
+reveal if the current version of the submodule (i.e., the actual
+contents of the gnulib directory) and the current request from the
+subscriber (i.e., the reference of the version of gnulib that the
+Bison reporitory requests) differ.  To upgrade the submodules (i.e.,
+to check out the version that is actually requested by the subscriber,
+run `git submodule update'.
+
+        $ git pull
+        $ git submodule update
+
+*** Updating a submodule
+To update a submodule, say gnulib, do as follows:
+
+Get the most recent version of the master branch from git.
+
+        $ cd gnulib
+        $ git fetch
+        $ git checkout -b master --track origin/master
+
+Make sure Bison can live with that version of gnulib.
+
+        $ cd ..
+        $ ./bootstrap
+        $ make distcheck
+
+Register your changes.
+
+        $ git checkin ...
+
+
 * Test suite
 
 ** make check
@@ -145,9 +257,15 @@ The generic GNU upload procedure is at:
 
   http://www.gnu.org/prep/maintain/maintain.html#Automated-FTP-Uploads
 
-After following the instructions there to register your information so you're
-permitted to upload, here's a brief reminder of how to roll the tarballs and
-upload them:
+Follow the instructions there to register your information so you're permitted
+to upload.  Make sure your public key has been uploaded at least to
+keys.gnupg.net.  You can upload it with:
+
+  gpg --keyserver keys.gnupg.net --send-keys F125BDF3
+
+where F125BDF3 should be replaced with your key ID.
+
+Here's a brief reminder of how to roll the tarballs and upload them:
 
 *** make distcheck
 *** gpg -b bison-2.3b.tar.gz
@@ -165,6 +283,47 @@ upload them:
 *** put bison-2.3b.tar.gz.directive.asc
 *** Repeat all these steps for bison-2.3b.tar.bz2.
 
+** Update Bison manual on www.gnu.org.
+
+*** You need a non-anonymous checkout of the web pages directory.
+
+  $ cvs -d YOUR_USERID@cvs.savannah.gnu.org:/web/bison checkout bison
+
+*** Get familiar with the instructions for web page maintainers.
+http://www.gnu.org/server/standards/readme_index.html
+http://www.gnu.org/server/standards/README.software.html
+especially the note about symlinks.
+
+*** Build the web pages.
+Assuming BISON_CHECKOUT refers to a checkout of the Bison dir, and
+BISON_WWW_CHECKOUT refers to the web directory created above, do:
+
+  $ cd $BISON_CHECKOUT/doc
+  $ make stamp-vti
+  $ ../build-aux/gendocs.sh -o "$BISON_WWW_CHECKOUT/manual" \
+    bison "Bison - GNU parser generator"
+  $ cd $BISON_WWW_CHECKOUT
+
+Verify that the result looks sane.
+
+*** Commit the modified and the new files.
+
+*** Remove old files.
+Find the files which have not been overwritten (because they belonged to
+sections that have been removed or renamed):
+
+   $ cd manual/html_node
+   $ ls -lt
+
+Remove these files and commit their removal to CVS.  For each of these
+files, add a line to the file .symlinks.  This will ensure that
+hyperlinks to the removed files will redirect to the entire manual; this
+is better than a 404 error.
+
+There is a problem with 'index.html' being written twice (once for POSIX
+function 'index', once for the table of contents); you can ignore this
+issue.
+
 ** Announce
 To generate a template announcement file:
 
@@ -195,7 +354,8 @@ Push these changes.
 
 -----
 
-Copyright (C) 2002, 2003, 2004, 2005, 2007, 2008 Free Software Foundation, Inc.
+Copyright (C) 2002, 2003, 2004, 2005, 2007, 2008, 2009
+Free Software Foundation, Inc.
 
 This file is part of GNU Bison.