From 26fccd4d7bbae99c25837862d4b979765e35831f Mon Sep 17 00:00:00 2001 From: Akim Demaille Date: Thu, 26 Mar 2009 23:36:18 +0100 Subject: [PATCH] doc: merge HACKING and README-hacking. Two files is confusing. Reported by Alexandre Duret-Lutz. * README-hacking: Merge into... * HACKING (Working from the repository): here. --- ChangeLog | 9 ++++ HACKING | 117 +++++++++++++++++++++++++++++++++++++++++++- README-hacking | 128 ------------------------------------------------- 3 files changed, 124 insertions(+), 130 deletions(-) delete mode 100644 README-hacking diff --git a/ChangeLog b/ChangeLog index c163347d..7b39f16e 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,12 @@ +2009-03-26 Akim Demaille + + doc: merge HACKING and README-hacking. + Two files is confusing. + Reported by Alexandre Duret-Lutz. + + * README-hacking: Merge into... + * HACKING (Working from the repository): here. + 2009-03-26 Akim Demaille doc: update README-hacking. diff --git a/HACKING b/HACKING index 091ba66c..14693965 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 +- Autoconf +- Flex +- Gettext +- Gzip +- Perl +- Rsync +- Tar + +Valgrind 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 @@ -195,7 +307,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. diff --git a/README-hacking b/README-hacking deleted file mode 100644 index a63cabbd..00000000 --- a/README-hacking +++ /dev/null @@ -1,128 +0,0 @@ --*- outline -*- - -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 -- Autoconf -- Flex -- Gettext -- Gzip -- Perl -- Rsync -- Tar - -Valgrind 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 ... - ------ - -Copyright (C) 2002, 2003, 2004, 2005, 2006, 2007, 2009 Free Software -Foundation, Inc. - -This program is free software: you can redistribute it and/or modify -it under the terms of the GNU General Public License as published by -the Free Software Foundation, either version 3 of the License, or -(at your option) any later version. - -This program is distributed in the hope that it will be useful, -but WITHOUT ANY WARRANTY; without even the implied warranty of -MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -GNU General Public License for more details. - -You should have received a copy of the GNU General Public License -along with this program. If not, see . -- 2.45.2