1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
|
GNU M4
******
1. Introduction
===============
This file attempts to describe the processes we use to maintain M4,
and is not part of a release distribution.
2. Maintenance Notes
====================
* If you incorporate a change from somebody on the net:
If it is a large change, you must make sure they have signed the
appropriate paperwork, and be sure to add their name and email
address to THANKS. AUTHORS is built from the FSF list of copyright
assignments, on fencepost.gnu.org.
* If somebody reports a new bug, write a test case, then mention his
name in the ChangeLog entry.
* The correct response to most actual bugs is to write a new test case
which demonstrates the bug. Then fix the bug, re-run the test suite,
and check everything in.
* Changes with user-visible effects must be mentioned in NEWS.
* New macros must be blind, or else prefixed with `m4' or `__', in
order to minimize backward compatibility issues with previous
releases of M4 when processing English text.
* GNU Coding Standards should be followed:
http://www.gnu.org/prep/standards/
Additionally, while GNU M4 is not yet POSIX compliant, we are trying
to get closer to it (although some design decisions state that POSIX
compliance should only happen when POSIXLY_CORRECT is in the
environment or the -G option was passed on the command line):
http://www.opengroup.org/onlinepubs/009695399/utilities/m4.html
* Except for third-party files (libtool, gnulib, ...), all .c files
should #include <config.h> before anything else (since there are some
#defines in config.h that potentially impact system headers, such as
when the user does ./configure --disable-assert). This means that no
.h files need to #include <config.h>. However, users compiling
external modules should be able to compile without <config.h>, since
<config.h> is specific to the M4 build and is not installable.
3. Bootstrapping
================
* The master M4 repository is stored in git. You can obtain a read-only
copy with:
git clone git://git.sv.gnu.org/m4.git
or
cvs -d:pserver:anonymous@pserver.git.sv.gnu.org:/srv/git/m4.git \
co -d m4 HEAD
If you are a member of the savannah group for M4, a read-write
copy can be obtained by:
git clone <savannah-user>@git.sv.gnu.org:/srv/git/m4.git
* Before you can build from git, you need to bootstrap. This requires:
- A pre-installed version of GNU M4 1.4.5 or later, built from a
package (recommend 1.4.13 or later)
- A git checkout of Autoconf (2.63b-41 or later)
- Automake 1.10b or later
- Libtool 2.2 or later
- Gettext 0.16 or later
- Gperf 3.0 or later
- Help2man 1.29 or later
- Xz 4.999.8beta or later (from <http://tukaani.org/xz/>)
- Texinfo 4.8 or later
- Any prerequisites of the above (such as perl, tex)
Note that none of these bootstrapping dependencies should be required
by a distributed release.
* M4 includes gnulib as a git submodule. By default, the bootstrap
script will attempt to run
git submodule update --init
to grab a gnulib clone from the official read-only location of
git://git.sv.gnu.org/gnulib.git
However, this can be network and disk intensive. If you already have
another gnulib clone on your disk, you can use the environment
variable GNULIB_SRCDIR to point to the previous checkout to speed up
the process. Additionally, both the bootstrap script and gnulib-tool
require a shell that supports functions, so you can set the
environment variable CONFIG_SHELL to choose a better shell on systems
(like Solaris) where /bin/sh is lacking. Thus, you may find it
convenient to run:
GNULIB_SRCDIR=path/to/gnulib CONFIG_SHELL=path/to/sh \
path/to/sh ./bootstrap
A read-only copy of gnulib can be obtained by:
git clone git://git.sv.gnu.org/gnulib.git
or
cvs -d:pserver:anonymous@pserver.git.sv.gnu.org:/srv/git/gnulib.git \
co -d gnulib HEAD
Using a CVS checkout might work, but it is relatively untested,
particularly now that we use a git submodule for gnulib.
If you are a member of the savannah group for gnulib, a read-write
copy can be obtained by:
git clone <savannah-user>@git.sv.gnu.org:/srv/git/gnulib.git
If you are behind a firewall that blocks the git protocol, you may
find it useful to do:
git config --global url.http://git.savannah.gnu.org/r/.insteadof \
git://git.sv.gnu.org/
to force git to transparently rewrite all savannah git references to
instead use http.
* Either add the gnulib directory to your PATH, or run
GNULIB_TOOL=path/to/gnulib/gnulib-tool ./bootstrap
* When it is time for a release, it is a good idea to bootstrap with
official releases of the autotools, rather than git builds, to reduce
the pain of a user re-running bootstrap on the packaged M4. However,
files installed by Automake should be updated to the latest version
from their respective upstream source, rather than the version that
shipped with the automake release.
* Normally, after running bootstrap, 'git status' should not show any
differences; if things changed, please provide a patch or at least
report it as a bug. One case where things are changed is if the
gnulib submodule comes from an older date than the current installed
libtool, such that libtoolize will replace the symlinks to an older
version of build-aux files with their newer counterpart; the fix to
this is updating the submodule to a newer gnulib version.
* If you would like to check that you are not missing out on any useful
gnulib modules, comment out the gl_ASSERT_NO_GNULIB_POSIXCHECK in
configure.ac, then run 'make CFLAGS='-DGNULIB_POSIXCHECK=1' with gcc,
and look at the resulting warnings.
4. Test Suite
=============
* Use
make check
liberally, on as many platforms as you can. Use as many compilers and
linkers you can.
* Some of the testsuite is generated from the documentation.
All instances of @example in doc/m4.texinfo that are not preceeded by
"@comment ignore" are turned into tests in the tests directory.
5. Editing 'ChangeLog'
======================
* When in doubt, check that emacs can syntax-color properly in
change-log-mode. And preferably use emacs 'C-x 4 a'
(add-change-log-entry-other-window) to open ChangeLog with an
appropriate new template.
* If this change is by a different author, or on a different date to the
last entry start a new entry at the top of the file with the format
(note two spaces between each field):
yyyy-mm-dd Name of Author <email@address>
* If more than one person collaborated on the change, additional
authors can be listed on subsequent lines, thus:
yyyy-mm-dd Name of Main Author <email@address>,
Name of Contributor <another@email.address>
* Where a change author did not supply a copyright assignment, but the
changes they submitted were sufficiently trivial to commit in any case
(see the GCS for guidelines on this), then flag this against their
name in the header, thus:
yyyy-mm-dd Name of Author <email@address> (tiny change)
* Preferably the next part should be a description of the overall
purpose of the change, separated from the header by a blank line,
indented by 1 tab, and filled at column 72. The last character of the
description should be a colon, :.
* Changes to each file come next. Each new file starts on a new line,
indented by 1 tab and starting with an asterisk and a space. Multiple
files can be listed here relative to $top_srcdir, and comma separated.
Names of functions (or sections as appropriate) to which the change
applies should be named inside parentheses and comma separated. If
this goes beyond column 72, then parens should be closed and re-opened
on the next line:
* file, another/file, test/testcases/foo.test (func_foo)
(func_bar, func_baz): Description of changes.
* If the change does not apply to particular functions (or sections),
the section list can be omitted:
* file, another/file, test/testcases/foo.test: General changes.
* If the changes are particular to certain architectures, they should be
listed after the functions in square brackets:
* file, another/file (func_foo) [linux, solaris]: Description of
changes.
* Subsequent changes in other files that are related to the same overall
enhancement or bugfix should be listed concurrently, without blank
lines. Always start a fresh line for a new file:
* file, another/file (func_foo) [linux, solaris]: Description of
changes.
* doc/foo.texi (Invoking Foo): Document.
* NEWS: Updated.
* If the change is in response to a problem reported by someone other
than the author, then credit them at the end of the description with:
Reported by Reporter Name <email@address>.
* See the GNU Coding Standards document for more details on ChangeLog
formatting.
6. Formatting
=============
* Use space-only indentation in nearly all files (Makefile and
ChangeLogs being the exception).
If you use Emacs and your m4 working directory name matches,
this code in your ~/.emacs enables the right mode:
;; In m4, indent with spaces everywhere (not TABs).
;; Exceptions: Makefile and ChangeLog modes.
(add-hook 'find-file-hook '(lambda ()
(if (and buffer-file-name
(string-match "/m4\\>" (buffer-file-name))
(not (string-equal mode-name "Change Log"))
(not (string-equal mode-name "Makefile")))
(setq indent-tabs-mode nil))))
* Since the source code was massively converted from tabs in December
2009, you may find it helpful to use 'git diff -w' and 'git blame -w'
helpful for overlooking the whitespace changes.
* Avoid #ifdefs inside function bodies, whenever possible. If you
encounter a portability issue, it is better to propose a gnulib module
that works around it, and have m4 use that module.
7. Release Procedure
====================
* If you are an m4 maintainer, but have not yet registered your
gpg public key and (preferred) email address with the FSF, send an
email, preferably GPG-signed, to <ftp-upload@gnu.org> that includes
the following:
(a) name of package(s) that you are the maintainer for, and your
preferred email address.
(b) an ASCII armored copy of your GnuPG key, as an attachment.
("gpg --export -a YOUR_KEY_ID > mykey.asc" should give you
this.)
When you have received acknowledgement of your message, the proper GPG
keys will be registered on ftp-upload.gnu.org and only then will you be
authorized to upload files to the FSF ftp machines.
* If you do not have access to the mailing list administrative interface,
approach the list owners for the password. Be sure to check the lists
(esp. bug-m4) for outstanding bug reports also in the list of
pending moderation requests. This step is not strictly necessary, but
helps, since by default, m4-announce rejects all posts, so you have to
get an administrator to allow your announcement through.
* Make sure you have rsync installed.
* Make sure you have a copy of the previous release tarball in the build
directory.
* Make sure you have GNU make installed.
* Make sure you have an up-to-date version of help2man installed.
* Make sure your locale is sane, e.g. by exporting LC_ALL=C.
* Make sure you are happy with the particular gnulib version recorded as
the gnulib submodule. If necessary to update to the latest, run:
git submodule foreach git pull origin master
git commit -m 'Update gnulib submodule to latest.' gnulib
In particular, ensure that the gnulib version is at least as new as
the latest stable libtool release.
* Update the version number in NEWS and ChangeLog, and mention in README
whether the release is stable. See
http://www.gnu.org/software/libtool/contribute.html for details of the
numbering scheme (M4 uses a similar scheme to libtool, although
intra-release versions carry more information thanks to
git-version-gen).
* Run ./bootstrap, perhaps with environment variables set.
* Run ./configure (a VPATH build should work, but is less tested).
* Run `make'. The file doc/m4.1 needs to exist for a distribution, and
be up-to-date with m4 --help output, but `make dist' intentionally
does not depend on running a built binary.
* Run `git commit' from the source tree if there are any changes from
the previous steps.
* Run `git tag -s -m <version> -u <gpg_key> v<version>' with the desired
version number. Do not push anything upstream at this point.
* Run `make distcheck'. If there are any problems, fix them, then run
`git tag -d v<version>' and start again from the `git commit' step.
* Run `make <target>', with target set to `stable, `alpha', or `beta' as
appropriate. This will run various additional checks and create diff
files from the previous version.
* Run './build-aux/gnupload --to [dest].gnu.org:m4 [files]' to create
detached gpg signature and clear signed directive files, and upload
the combination to the correct location. For an alpha release,
gnupload will place files in alpha.gnu.org, in /incoming/alpha; for a
full release, gnupload will place files in ftp.gnu.org, in
/incoming/ftp. Verify that the files uploaded successfully before
sending an announcement.
* Send announcement to m4-discuss@gnu.org, m4-announce@gnu.org, and
autotools-announce@gnu.org. If not an alpha send to info-gnu@gnu.org
as well. Use gnulib/build-aux/announce-gen to form an initial
template for the announcement (you may also need to install the perl
module Digest::SHA1). Contact a list administrator for m4-announce in
advance to ensure your post will make it through (the list is normally
set to silently discard all posts, even from subscribers).
* Update version number in configure.ac to next alpha number.
See http://www.gnu.org/software/libtool/contribute.html for details of
the numbering scheme.
* Update NEWS, README, and ChangeLog to start the intra-release changes,
and run `git commit'. Then run `git push origin refs/tags/v<version>'
to push the release tag and complete the release.
* For stable releases, update the webpages.
Run `build-aux/gnu-web-doc-update', which runs `make web-manual' on a
temporary git branch corresponding to the release, then copies the
contents of doc/manual into a CVS checkout of the M4 manual
repository. Follow up with any needed edits to m4.html, using:
export CVS_RSH=ssh
cvs -z3 -d:ext:<user>@cvs.savannah.gnu.org:/web/m4 co m4
* Update the Free Software Directory. Browse to:
http://directory.fsf.org/project/m4/
and send an email to <bug-directory@gnu.org> mentioning any content
that needs to be updated.
-----------
Copyright (C) 2004-2010, 2013 Free Software Foundation, Inc.
The canonical source of this file is maintained with the
GNU M4 package. Report bugs to bug-m4@gnu.org.
GNU M4 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.
GNU M4 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 <http://www.gnu.org/licenses/>.
Local Variables:
mode: text
fill-column: 72
End:
vim:tw=72
|