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