Commit | Line | Data |
---|---|---|
2ed0e35f AD |
1 | -*- outline -*- |
2 | ||
3 | This file attempts to describe the rules to use when hacking Bison. | |
9126263e | 4 | Don't put this file into the distribution. |
2ed0e35f | 5 | |
f414d77d AD |
6 | Everything related to the development of Bison is on Savannah: |
7 | ||
31d3e510 | 8 | http://savannah.gnu.org/projects/bison/ |
f414d77d AD |
9 | |
10 | ||
2ed0e35f AD |
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 | ||
548e2104 JD |
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. | |
fee2ed87 | 36 | |
f414d77d | 37 | |
427c0dda AD |
38 | * Hacking |
39 | ||
2ed0e35f AD |
40 | ** Visible changes |
41 | Which include serious bug fixes, must be mentioned in NEWS. | |
427c0dda AD |
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. | |
2ed0e35f AD |
48 | |
49 | ||
31d3e510 AD |
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 | ||
2ed0e35f AD |
162 | * Test suite |
163 | ||
164 | ** make check | |
165 | Use liberally. | |
166 | ||
167 | ** Release checks | |
168 | Try to run the test suite with more severe conditions before a | |
169 | release: | |
170 | ||
171 | - Configure the package with --enable-gcc-warnings, so that one checks | |
172 | that 1. Bison compiles cleanly, 2. the parsers it produces compile | |
173 | cleanly too. | |
174 | ||
5c99151a JD |
175 | - Build with -DGNULIB_POSIXCHECK. It suggests gnulib modules that can |
176 | fix portability issues. | |
177 | ||
f377f69f AD |
178 | - run `make maintainer-check' which: |
179 | - runs `valgrind -q bison' to run Bison under Valgrind. | |
1f1b791b | 180 | - runs the parsers under Valgrind. |
f377f69f | 181 | - runs the test suite with G++ as C compiler... |
2ed0e35f | 182 | |
9126263e JD |
183 | - run `make maintainer-push-check', which runs `make maintainer-check' |
184 | while activating the push implementation and its pull interface wrappers | |
185 | in many test cases that were originally written to exercise only the | |
186 | pull implementation. This makes certain the push implementation can | |
187 | perform every task the pull implementation can. | |
188 | ||
189 | - run `make maintainer-xml-check', which runs `make maintainer-check' | |
190 | while checking Bison's XML automaton report for every working grammar | |
191 | passed to Bison in the test suite. The check just diffs the output of | |
192 | Bison's included XSLT style sheets with the output of --report=all and | |
193 | --graph. | |
194 | ||
2ed0e35f AD |
195 | - Change tests/atlocal/CFLAGS to add your preferred options. For |
196 | instance, `-traditional' to check that the parsers are K&R. Note | |
197 | that it does not make sense for glr.c, which should be ANSI, | |
548e2104 | 198 | but currently is actually GNU C, nor for lalr1.cc. |
2ed0e35f | 199 | |
95611b56 JD |
200 | - Test with a very recent version of GCC for both C and C++. Testing |
201 | with older versions that are still in use is nice too. | |
202 | ||
2ed0e35f AD |
203 | |
204 | * Release Procedure | |
205 | ||
e32050b0 JD |
206 | ** Try to get the *.pot files to the Translation Project at least one |
207 | week before a stable release, to give them time to translate them. | |
208 | Before generating the *.pot files, make sure that po/POTFILES.in and | |
209 | runtime-po/POTFILES.in list all files with translatable strings. | |
210 | This helps: grep -l '\<_(' * | |
ddc65ffd | 211 | |
2ed0e35f AD |
212 | ** Tests |
213 | See above. | |
214 | ||
215 | ** Update the foreign files | |
e476c87d PE |
216 | Running `./bootstrap' in the top level should update them all for you. |
217 | This covers PO files too. Sometimes a PO file contains problems that | |
218 | causes it to be rejected by recent Gettext releases; please report | |
219 | these to the Translation Project. | |
2ed0e35f | 220 | |
548e2104 | 221 | ** Update README |
80b70223 JD |
222 | Make sure the information in README is current. Most notably, make sure |
223 | it recommends a version of GNU M4 that is compatible with the latest | |
224 | Bison sources. | |
225 | ||
226 | ** Check copyright years. | |
227 | We update years in copyright statements throughout Bison once at the | |
228 | start of every year by running `make update-copyright'. However, before | |
229 | a release, it's good to verify that it's actually been run. Besides the | |
230 | copyright statement for each Bison file, check the copyright statements | |
231 | that the skeletons insert into generated parsers, and check all | |
232 | occurrences of PACKAGE_COPYRIGHT_YEAR in configure.ac. | |
548e2104 | 233 | |
2ed0e35f AD |
234 | ** Update NEWS |
235 | The version number, *and* the date of the release (including for | |
236 | betas). | |
237 | ||
238 | ** Update ChangeLog | |
239 | Should have an entry similar to `Version 1.49b.'. | |
548e2104 | 240 | |
548e2104 JD |
241 | ** Tag the release |
242 | Before Bison will build with the right version number, you must tag the release | |
243 | in git. Do this after all other changes. The command is similar to: | |
244 | ||
245 | git tag -a v2.3b | |
246 | ||
247 | The log message can be simply: | |
248 | ||
249 | Bison 2.3b | |
250 | ||
251 | ** Push | |
252 | Once `make distcheck' passes, push your changes and the tag. | |
253 | `git push' without arguments will not push the tag. | |
2ed0e35f AD |
254 | |
255 | ** make alpha | |
548e2104 JD |
256 | FIXME: `make alpha' is not maintained and is broken. These |
257 | instructions need to be replaced or removed. | |
258 | ||
2ed0e35f AD |
259 | Running `make alpha' is absolutely perfect for beta releases: it makes |
260 | the tarballs, the xdeltas, and prepares (in /tmp/) a proto | |
261 | announcement. It is so neat, that that's what I use anyway for | |
262 | genuine releases, but adjusting things by hand (e.g., the urls in the | |
263 | announcement file, the ChangeLog which is not needed etc.). | |
264 | ||
265 | If it fails, you're on your own... | |
266 | ||
267 | It requires GNU Make. | |
268 | ||
269 | ** Upload | |
548e2104 | 270 | The generic GNU upload procedure is at: |
2ed0e35f | 271 | |
548e2104 JD |
272 | http://www.gnu.org/prep/maintain/maintain.html#Automated-FTP-Uploads |
273 | ||
06c3084f JD |
274 | Follow the instructions there to register your information so you're permitted |
275 | to upload. Make sure your public key has been uploaded at least to | |
276 | keys.gnupg.net. You can upload it with: | |
277 | ||
278 | gpg --keyserver keys.gnupg.net --send-keys F125BDF3 | |
279 | ||
280 | where F125BDF3 should be replaced with your key ID. | |
281 | ||
282 | Here's a brief reminder of how to roll the tarballs and upload them: | |
548e2104 JD |
283 | |
284 | *** make distcheck | |
285 | *** gpg -b bison-2.3b.tar.gz | |
286 | *** In a file named `bison-2.3b.tar.gz.directive', type: | |
287 | ||
288 | version: 1.1 | |
289 | directory: bison | |
290 | filename: bison-2.3b.tar.gz | |
291 | ||
292 | *** gpg --clearsign bison-2.3b.tar.gz.directive | |
293 | *** ftp ftp-upload.gnu.org # Log in as anonymous. | |
294 | *** cd /incoming/alpha # cd /incoming/ftp for full release. | |
295 | *** put bison-2.3b.tar.gz # This can take a while. | |
296 | *** put bison-2.3b.tar.gz.sig | |
297 | *** put bison-2.3b.tar.gz.directive.asc | |
298 | *** Repeat all these steps for bison-2.3b.tar.bz2. | |
2ed0e35f | 299 | |
1c93f35b JD |
300 | ** Update Bison manual on www.gnu.org. |
301 | ||
302 | *** You need a non-anonymous checkout of the web pages directory. | |
303 | ||
304 | $ cvs -d YOUR_USERID@cvs.savannah.gnu.org:/web/bison checkout bison | |
305 | ||
306 | *** Get familiar with the instructions for web page maintainers. | |
307 | http://www.gnu.org/server/standards/readme_index.html | |
308 | http://www.gnu.org/server/standards/README.software.html | |
309 | especially the note about symlinks. | |
310 | ||
311 | *** Build the web pages. | |
312 | Assuming BISON_CHECKOUT refers to a checkout of the Bison dir, and | |
313 | BISON_WWW_CHECKOUT refers to the web directory created above, do: | |
314 | ||
315 | $ cd $BISON_CHECKOUT/doc | |
316 | $ make stamp-vti | |
317 | $ ../build-aux/gendocs.sh -o "$BISON_WWW_CHECKOUT/manual" \ | |
318 | bison "Bison - GNU parser generator" | |
319 | $ cd $BISON_WWW_CHECKOUT | |
320 | ||
321 | Verify that the result looks sane. | |
322 | ||
323 | *** Commit the modified and the new files. | |
324 | ||
325 | *** Remove old files. | |
326 | Find the files which have not been overwritten (because they belonged to | |
327 | sections that have been removed or renamed): | |
328 | ||
329 | $ cd manual/html_node | |
330 | $ ls -lt | |
331 | ||
332 | Remove these files and commit their removal to CVS. For each of these | |
333 | files, add a line to the file .symlinks. This will ensure that | |
334 | hyperlinks to the removed files will redirect to the entire manual; this | |
335 | is better than a 404 error. | |
336 | ||
337 | There is a problem with 'index.html' being written twice (once for POSIX | |
338 | function 'index', once for the table of contents); you can ignore this | |
339 | issue. | |
340 | ||
2ed0e35f | 341 | ** Announce |
548e2104 JD |
342 | To generate a template announcement file: |
343 | ||
344 | make RELEASE_TYPE=alpha gpg_key_ID=F125BDF3 announcement | |
345 | ||
96a381c5 JD |
346 | where alpha can be replaced by beta or stable and F125BDF3 should be |
347 | replaced with your key ID. For an example of how to fill out the | |
348 | template, search the mailing list archives for the most recent release | |
349 | announcement. | |
548e2104 | 350 | |
2ed0e35f | 351 | Complete/fix the announcement file, and send it at least to |
597ba9e3 | 352 | info-gnu@gnu.org (if a real release, or a ``serious beta''), |
bf46a7c1 | 353 | bug-bison@gnu.org, help-bison@gnu.org, bison-patches@gnu.org, |
138d4cd9 | 354 | and coordinator@translationproject.org. |
2ed0e35f | 355 | |
bf46a7c1 PE |
356 | Send the same announcement on the comp.compilers newsgroup by sending |
357 | email to compilers@iecc.com. Do not make any Cc as the moderator will | |
358 | throw away anything cross-posted or Cc'ed. It really needs to be a | |
359 | separate message. | |
43a91d61 | 360 | |
548e2104 JD |
361 | ** Bump the version number |
362 | In configure.ac. Run `make'. So that developers don't accidentally add new | |
363 | items to the old NEWS entry, create a new empty NEWS entry something like: | |
364 | ||
365 | Changes in version ?.? (????-??-??): | |
366 | ||
367 | Push these changes. | |
368 | ||
2ed0e35f AD |
369 | |
370 | ----- | |
371 | ||
e141f4d4 | 372 | Copyright (C) 2002-2005, 2007-2010 Free Software Foundation, Inc. |
2ed0e35f AD |
373 | |
374 | This file is part of GNU Bison. | |
375 | ||
f16b0819 | 376 | This program is free software: you can redistribute it and/or modify |
2ed0e35f | 377 | it under the terms of the GNU General Public License as published by |
f16b0819 PE |
378 | the Free Software Foundation, either version 3 of the License, or |
379 | (at your option) any later version. | |
2ed0e35f | 380 | |
f16b0819 | 381 | This program is distributed in the hope that it will be useful, |
2ed0e35f AD |
382 | but WITHOUT ANY WARRANTY; without even the implied warranty of |
383 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | |
384 | GNU General Public License for more details. | |
385 | ||
386 | You should have received a copy of the GNU General Public License | |
f16b0819 | 387 | along with this program. If not, see <http://www.gnu.org/licenses/>. |