]> git.saurik.com Git - bison.git/blob - README-hacking
gnulib, autoconf: update.
[bison.git] / README-hacking
1 -*- outline -*-
2
3 This file attempts to describe the rules to use when hacking Bison.
4 Don't put this file into the distribution.
5
6 Everything related to the development of Bison is on Savannah:
7
8 http://savannah.gnu.org/projects/bison/
9
10
11 * Administrivia
12
13 ** If you incorporate a change from somebody on the net:
14 First, if it is a large change, you must make sure they have signed
15 the appropriate paperwork. Second, be sure to add their name and
16 email address to THANKS.
17
18 ** If a change fixes a test, mention the test in the ChangeLog entry.
19
20 ** Bug reports
21 If somebody reports a new bug, mention his name in the ChangeLog entry
22 and in the test case you write. Put him into THANKS.
23
24 The correct response to most actual bugs is to write a new test case
25 which demonstrates the bug. Then fix the bug, re-run the test suite,
26 and check everything in.
27
28 ** You may find it useful to install the git-merge-changelog merge driver:
29
30 http://git.sv.gnu.org/gitweb/?p=gnulib.git;a=blob;f=lib/git-merge-changelog.c
31
32 When following the generic installation instructions there, keep in mind that
33 your clone of Bison's git repository already contains appropriate
34 .gitattributes files, and running Bison's bootstrap script will make the
35 necessary changes to .git/config.
36
37
38 * Hacking
39
40 ** Visible changes
41 Which include serious bug fixes, must be mentioned in NEWS.
42
43 ** Translations
44 Only user visible strings are to be translated: error messages, bits
45 of the .output file etc. This excludes impossible error messages
46 (comparable to assert/abort), and all the --trace output which is
47 meant for the maintainers only.
48
49
50 * Working from the repository
51
52 These notes intend to help people working on the checked-out sources.
53 These requirements do not apply when building from a distribution tarball.
54
55 ** Requirements
56
57 We've opted to keep only the highest-level sources in the repository.
58 This eases our maintenance burden, (fewer merges etc.), but imposes more
59 requirements on anyone wishing to build from the just-checked-out sources.
60 For example, you have to use the latest stable versions of the maintainer
61 tools we depend upon, including:
62
63 - Automake <http://www.gnu.org/software/automake/>
64 - Autoconf <http://www.gnu.org/software/autoconf/>
65 - Flex <http://www.gnu.org/software/flex/>
66 - Gettext <http://www.gnu.org/software/gettext/>
67 - Gzip <http://www.gnu.org/software/gzip/>
68 - Perl <http://www.cpan.org/>
69 - Rsync <http://samba.anu.edu.au/rsync/>
70 - Tar <http://www.gnu.org/software/tar/>
71
72 Valgrind <http://valgrind.org/> is also highly recommended, if
73 Valgrind supports your architecture.
74
75 Bison is written using Bison grammars, so there are bootstrapping
76 issues. The bootstrap script attempts to discover when the C code
77 generated from the grammars is out of date, and to bootstrap with an
78 out-of-date version of the C code, but the process is not foolproof.
79 Also, you may run into similar problems yourself if you modify Bison.
80
81 Only building the initial full source tree will be a bit painful.
82 Later, after synchronizing from the repository a plain `make' should
83 be sufficient.
84
85 ** First checkout
86
87 Obviously, if you are reading these notes, you did manage to check out
88 this package from the repository. For the record, you will find all the
89 relevant information on:
90
91 http://savannah.gnu.org/git/?group=bison
92
93 Bison uses Git submodules: subscriptions to other Git repositories.
94 In particular it uses gnulib, the GNU portability library. To ask Git
95 to perform the first checkout of the submodules, run
96
97 $ git submodule update --init
98
99 Git submodule support is weak before versions 1.6 and later, you
100 should probably upgrade Git if your version is older.
101
102 The next step is to get other files needed to build, which are
103 extracted from other source packages:
104
105 $ ./bootstrap
106
107 And there you are! Just
108
109 $ ./configure
110 $ make
111 $ make check
112
113 At this point, there should be no difference between your local copy,
114 and the master copy:
115
116 $ git diff
117
118 should output no difference.
119
120 Enjoy!
121
122 ** Updating
123
124 The use of submodules make things somewhat different because git does
125 not support recursive operations: submodules must be taken care of
126 explicitly by the user.
127
128 *** Updating Bison
129
130 If you pull a newer version of a branch, say via `git pull', you might
131 import requests for updated submodules. A simple `git diff' will
132 reveal if the current version of the submodule (i.e., the actual
133 contents of the gnulib directory) and the current request from the
134 subscriber (i.e., the reference of the version of gnulib that the
135 Bison reporitory requests) differ. To upgrade the submodules (i.e.,
136 to check out the version that is actually requested by the subscriber,
137 run `git submodule update'.
138
139 $ git pull
140 $ git submodule update
141
142 *** Updating a submodule
143 To update a submodule, say gnulib, do as follows:
144
145 Get the most recent version of the master branch from git.
146
147 $ cd gnulib
148 $ git fetch
149 $ git checkout -b master --track origin/master
150
151 Make sure Bison can live with that version of gnulib.
152
153 $ cd ..
154 $ ./bootstrap
155 $ make distcheck
156
157 Register your changes.
158
159 $ git checkin ...
160
161 For a suggestion of what gnulib commit might be stable enough for a
162 formal release, see the ChangeLog in the latest gnulib snapshot at:
163
164 http://erislabs.net/ianb/projects/gnulib/
165
166 The autoconf files we use are currently:
167
168 m4/m4.m4
169 lib/m4sugar/m4sugar.m4
170 lib/m4sugar/foreach.m4
171
172 These files don't change very often in autoconf, so it should be
173 relatively straight-forward to examine the differences in order to
174 decide whether to update.
175
176 * Test suite
177
178 ** make check
179 Use liberally.
180
181 ** Release checks
182 Try to run the test suite with more severe conditions before a
183 release:
184
185 - Configure the package with --enable-gcc-warnings, so that one checks
186 that 1. Bison compiles cleanly, 2. the parsers it produces compile
187 cleanly too.
188
189 - Build with -DGNULIB_POSIXCHECK. It suggests gnulib modules that can
190 fix portability issues.
191
192 - run `make maintainer-check' which:
193 - runs `valgrind -q bison' to run Bison under Valgrind.
194 - runs the parsers under Valgrind.
195 - runs the test suite with G++ as C compiler...
196
197 - run `make maintainer-push-check', which runs `make maintainer-check'
198 while activating the push implementation and its pull interface wrappers
199 in many test cases that were originally written to exercise only the
200 pull implementation. This makes certain the push implementation can
201 perform every task the pull implementation can.
202
203 - run `make maintainer-xml-check', which runs `make maintainer-check'
204 while checking Bison's XML automaton report for every working grammar
205 passed to Bison in the test suite. The check just diffs the output of
206 Bison's included XSLT style sheets with the output of --report=all and
207 --graph.
208
209 - Change tests/atlocal/CFLAGS to add your preferred options. For
210 instance, `-traditional' to check that the parsers are K&R. Note
211 that it does not make sense for glr.c, which should be ANSI,
212 but currently is actually GNU C, nor for lalr1.cc.
213
214 - Test with a very recent version of GCC for both C and C++. Testing
215 with older versions that are still in use is nice too.
216
217
218 * Release Procedure
219
220 ** Update the submodules. See above.
221
222 ** Try to get the *.pot files to the Translation Project at least one
223 week before a stable release, to give them time to translate them.
224 Before generating the *.pot files, make sure that po/POTFILES.in and
225 runtime-po/POTFILES.in list all files with translatable strings.
226 This helps: grep -l '\<_(' *
227
228 ** Tests
229 See above.
230
231 ** Update the foreign files
232 Running `./bootstrap' in the top level should update them all for you.
233 This covers PO files too. Sometimes a PO file contains problems that
234 causes it to be rejected by recent Gettext releases; please report
235 these to the Translation Project.
236
237 ** Update README
238 Make sure the information in README is current. Most notably, make sure
239 it recommends a version of GNU M4 that is compatible with the latest
240 Bison sources.
241
242 ** Check copyright years.
243 We update years in copyright statements throughout Bison once at the
244 start of every year by running `make update-copyright'. However, before
245 a release, it's good to verify that it's actually been run. Besides the
246 copyright statement for each Bison file, check the copyright statements
247 that the skeletons insert into generated parsers, and check all
248 occurrences of PACKAGE_COPYRIGHT_YEAR in configure.ac.
249
250 ** Update NEWS
251 The version number, *and* the date of the release (including for
252 betas).
253
254 ** Update ChangeLog
255 Should have an entry similar to `Version 1.49b.'.
256
257 ** Tag the release
258 Before Bison will build with the right version number, you must tag the release
259 in git. Do this after all other changes. The command is similar to:
260
261 git tag -a v2.3b
262
263 The log message can be simply:
264
265 Bison 2.3b
266
267 ** Push
268 Once `make distcheck' passes, push your changes and the tag.
269 `git push' without arguments will not push the tag.
270
271 ** make alpha
272 FIXME: `make alpha' is not maintained and is broken. These
273 instructions need to be replaced or removed.
274
275 Running `make alpha' is absolutely perfect for beta releases: it makes
276 the tarballs, the xdeltas, and prepares (in /tmp/) a proto
277 announcement. It is so neat, that that's what I use anyway for
278 genuine releases, but adjusting things by hand (e.g., the urls in the
279 announcement file, the ChangeLog which is not needed etc.).
280
281 If it fails, you're on your own...
282
283 It requires GNU Make.
284
285 ** Upload
286 The generic GNU upload procedure is at:
287
288 http://www.gnu.org/prep/maintain/maintain.html#Automated-FTP-Uploads
289
290 Follow the instructions there to register your information so you're permitted
291 to upload. Make sure your public key has been uploaded at least to
292 keys.gnupg.net. You can upload it with:
293
294 gpg --keyserver keys.gnupg.net --send-keys F125BDF3
295
296 where F125BDF3 should be replaced with your key ID.
297
298 Here's a brief reminder of how to roll the tarballs and upload them:
299
300 *** make distcheck
301 *** gpg -b bison-2.3b.tar.gz
302 *** In a file named `bison-2.3b.tar.gz.directive', type:
303
304 version: 1.1
305 directory: bison
306 filename: bison-2.3b.tar.gz
307
308 *** gpg --clearsign bison-2.3b.tar.gz.directive
309 *** ftp ftp-upload.gnu.org # Log in as anonymous.
310 *** cd /incoming/alpha # cd /incoming/ftp for full release.
311 *** put bison-2.3b.tar.gz # This can take a while.
312 *** put bison-2.3b.tar.gz.sig
313 *** put bison-2.3b.tar.gz.directive.asc
314 *** Repeat all these steps for bison-2.3b.tar.bz2.
315
316 ** Update Bison manual on www.gnu.org.
317
318 *** You need a non-anonymous checkout of the web pages directory.
319
320 $ cvs -d YOUR_USERID@cvs.savannah.gnu.org:/web/bison checkout bison
321
322 *** Get familiar with the instructions for web page maintainers.
323 http://www.gnu.org/server/standards/readme_index.html
324 http://www.gnu.org/server/standards/README.software.html
325 especially the note about symlinks.
326
327 *** Build the web pages.
328 Assuming BISON_CHECKOUT refers to a checkout of the Bison dir, and
329 BISON_WWW_CHECKOUT refers to the web directory created above, do:
330
331 $ cd $BISON_CHECKOUT/doc
332 $ make stamp-vti
333 $ ../build-aux/gendocs.sh -o "$BISON_WWW_CHECKOUT/manual" \
334 bison "Bison - GNU parser generator"
335 $ cd $BISON_WWW_CHECKOUT
336
337 Verify that the result looks sane.
338
339 *** Commit the modified and the new files.
340
341 *** Remove old files.
342 Find the files which have not been overwritten (because they belonged to
343 sections that have been removed or renamed):
344
345 $ cd manual/html_node
346 $ ls -lt
347
348 Remove these files and commit their removal to CVS. For each of these
349 files, add a line to the file .symlinks. This will ensure that
350 hyperlinks to the removed files will redirect to the entire manual; this
351 is better than a 404 error.
352
353 There is a problem with 'index.html' being written twice (once for POSIX
354 function 'index', once for the table of contents); you can ignore this
355 issue.
356
357 ** Announce
358 To generate a template announcement file:
359
360 make RELEASE_TYPE=alpha gpg_key_ID=F125BDF3 announcement
361
362 where alpha can be replaced by beta or stable and F125BDF3 should be
363 replaced with your key ID.
364
365 Complete/fix the announcement file. The generated list of recipients
366 (info-gnu@gnu.org, bug-bison@gnu.org, help-bison@gnu.org,
367 bison-patches@gnu.org, and coordinator@translationproject.org) is
368 appropriate for a stable release or a ``serious beta''. For any other
369 release, drop at least info-gnu@gnu.org. For an example of how to fill
370 out the rest of the template, search the mailing list archives for the
371 most recent release announcement.
372
373 For a stable release, send the same announcement on the comp.compilers
374 newsgroup by sending email to compilers@iecc.com. Do not make any Cc as
375 the moderator will throw away anything cross-posted or Cc'ed. It really
376 needs to be a separate message.
377
378 ** Bump the version number
379 In configure.ac. Run `make'. So that developers don't accidentally add new
380 items to the old NEWS entry, create a new empty NEWS entry something like:
381
382 Changes in version ?.? (????-??-??):
383
384 Push these changes.
385
386
387 -----
388
389 Copyright (C) 2002-2005, 2007-2011 Free Software Foundation, Inc.
390
391 This file is part of GNU Bison.
392
393 This program is free software: you can redistribute it and/or modify
394 it under the terms of the GNU General Public License as published by
395 the Free Software Foundation, either version 3 of the License, or
396 (at your option) any later version.
397
398 This program is distributed in the hope that it will be useful,
399 but WITHOUT ANY WARRANTY; without even the implied warranty of
400 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
401 GNU General Public License for more details.
402
403 You should have received a copy of the GNU General Public License
404 along with this program. If not, see <http://www.gnu.org/licenses/>.