1 Notes for Developers -*-text-*-
4 Last updated on 08-Jan-2006
6 You will need to install several GNU tools to be able to use the
7 cvs sources. If you do not have these tools available, build from
8 the tar file distribution instead, available from ftp.fvwm.org.
10 To build from the CVS sources, you will need:
13 * autoconf (version >= 2.53)
14 * automake (version >= 1.4)
17 After the *initial* checkout of the sources, (see DEVELOPER-CVS or
18 cvs.html) you will need to execute the following commands from the
19 top of the source tree.
23 automake --add-missing
26 There will be some warnings, which are ignorable as long as you
27 get a working configure script: the configure script will fix all
30 Now, configure and build as per INSTALL.fvwm and INSTALL. If
31 configure fails, please look through `config.log' for clues.
34 Development Rules of the Road
35 -----------------------------
37 1) _Every_ change must be properly ChangeLogged, listing the name
38 of the changed function. If you use Emacs, you can do this
39 oh-so-trivially with the "C-x 4 a" command; it will add a
40 header (if it's a new day), the name of the file, and even the
41 name of the function you're currently in. There is a
42 vim-script utils/changelog.vim that does the same when yoi
45 If you start adding them as you change functions, it'll soon
46 become second-nature and we'll get proper ChangeLogs.
48 If you don't use Emacs, please mimic the format of all the
49 other log entries when adding your own.
51 2) If you make a user-visible change please add a blurb about it
52 to the NEWS file. A couple sentences is fine; don't repeat
53 the documentation but give folks enough of an idea so they can
54 decide if they want to learn more. Bug fixes (unless they're
55 _really_ user visible) shouldn't be noted in the NEWS file.
57 3) If you add a new user-visible feature, don't forget to update
58 the appropriate man pages at the same time!
60 4) Bug fixes may be committed at any time (unless we're in code
61 freeze for a release), usually without much review (unless you
62 want someone else to look at it). All our code freezes,
63 etc. are merely procedural, not enforced, so it's important
64 you read fvwm-workers and keep up-to-date with the current
67 5) New features should be discussed on the list to ensure
68 everyone thinks they're "appropriate" (one of the goals of
69 fvwm is to be relatively efficient, remember, which means we
70 don't necessarily want the kitchen sink).
72 6) If the new feature is large enough, unstable enough, or not
73 targeted at the next release, it should go on a private
74 branch. Otherwise, consensus will probably have it installed
77 7) Before adding a new feature think twice if it could perhaps be
78 implemented as a module (perhaps after some extension of the
79 fvwm<->module communication protocol). Moving features in
80 modules helps to keep fvwm itself clean and efficient.
82 8) See CONVENTIONS for more details.
84 ** Of course, compile and test before committing! **
90 All details about dealing with CVS should be found in cvs.html or
91 DEVELOPER-CVS. Go look there!
96 First of all, NEVER edit anything named Makefile or Makefile.in.
97 These are both derived from the corresponding Makefile.am. The
98 most common reason for editing is to change the list of sources.
100 Steps: 1. edit foo/blah/Makefile.am
101 2. re-run "make" from the top of the build directory
103 Step 2 will take care of rebuilding the Makefile.in and Makefile
104 from your changed Makefile.am.
106 Makefile.am has a simple format, basically:
110 fvwm_SOURCES = blah.c blah.h foo.c foo.h ...
112 Notice that you have to add all files, C-code *and* headers, to
113 the _SOURCES line. This is vital, because this is the list of
114 files that are packed into the distribution. If you leave one
115 out, nobody will be able to build the distributed tar file!
118 Changing configure.ac
119 ---------------------
121 The most common reason to do this is to change the version string.
122 If you're editing it for any other reason, I will assume you know
125 Steps: 1. edit configure.ac, and find the line containing
126 AM_INIT_AUTOMAKE(fvwm, x.y.z) at the top of the file
127 2. change x.y.z to the new version string
128 3. re-run "make" from the top of the build directory
130 Step 3 will take care of rebuilding the configure script, and
131 usually all the other Makefiles.
134 Building an official distribution
135 ---------------------------------
137 By this, I mean the files fvwm-x.y.z.tar.gz and
138 fvwm-x.y.z.tar.bz2. It is important to do all steps in the given
143 - Make sure you have all optional libraries installed.
144 - When building a release, update the CVS sources first. For a
145 stable release it is best to throw away the whole source tree
146 and check it out from scratch to ensure all source files have
148 - Change the dates in configure.ac and fill in the release date
149 in NEWS. Note: For releases prior to 2.5.3, the date has to be
150 updated in docs/fvwm.lsm.in and fvwm/fvwm.1 instead of
152 - Verify that the version variable at the very beginning of
153 configure.ac has the value of the going to be released version
154 and set ISRELEASED to "yes". It should be "yes" in the
156 - Update docs/ANNOUNCE file. For the first version of a major
157 release (e.g. 2.6.0) all user visible changes have to be
158 mentioned. For the following maintenance releases *all* code
159 changes have to be listed. This is usually done by copying
160 all entries from the NEWS file. Don't forget to proof read
161 the file as it will be sent to the fvwm-announce mailing list.
162 - Update the ChangeLog for all the changes above.
163 - Commit these changes.
167 Note that you need to have actually built everything before
168 packing the distribution. Among other things, this generates
169 the proper dependency information for insertion into
170 Makefile.in's generated by "make distcheck2".
173 $ aclocal && autoheader && automake --add-missing && autoconf
174 - If you are building a stable release, remove the config.cache
175 file if there is one (autoconf 2.52 does no longer generate
176 this file by default). Of course doing this for a development
177 release won't hurt either.
179 $ ./configure --enable-htmldoc
180 - Make sure configure detects all optional libraries except the
181 ones that are recommended not to be used. Repeat the previous
182 step until configure finds everything. Building a release
183 without any optional library should be a rare exception.
189 even if you checked out from scratch. It is a useful
191 - Double check that you get no warnings during the build:
192 $ make CFLAGS="-g -O2 -Wall -Wpointer-arith -fno-strict-aliasing -Werror"
193 On some systems, the system include files generate warnings.
194 On such a system you have to omit the -Werror option and check
195 the output of the compilation run for warnings manually. It
196 is important to use the -O2 option because gcc can not
197 generate some warnings without it. If your gcc-version does
198 not know the option "-fno-strict-aliasing", remove it. If you
199 have gcc >= 3.4 you should also use -Wdeclaration-after-statement
200 since it will catch code that won't compile on all C89 compilers.
201 - Fix all warnings and problems, commit the changes and repeat
202 the previous step until no more warnings occur.
204 Build and test the release tarballs:
206 The next step will create the tar file, then unpack it and
207 attempt to build fvwm from it and install to a scratch
208 directory. This makes sure that you really *did* include all
209 the files necessary to build the package into the tar file. It
210 may be hard to appreciate how useful this is, until it has
211 reminded you that you forgot file "foo.h" in some _SOURCES line.
212 But trust me, it will save your bacon in this way some day!
216 - Ensure that you see the messages
217 "fvwm-x.y.z.tar.gz is ready for distribution"
219 "fvwm-x.y.z.tar.bz2 - ready for distribution"
223 * Important note: Before you proceed, please ask yourself if the
224 code is ready to be released:
226 * Have you committed patches only hours or even minutes ago?
227 * Have there been any big changes in the last few days?
228 * Are there any important parts that are not well tested?
229 * Are you tired from work or have you been hacking fvwm for many
232 Should your answer to any of these questions be 'yes', please do
233 take a break now and reconsider, especially if this is going to
236 The steps above are not critical and can not screw up anything
237 bad. This is not true for what follows. If you do something
238 wrong now, you will have a hard time cleaning up the mess.
239 Should something go wrong and you are not sure about the correct
240 fixes, please ask on the fvwm-workers list for help.
242 It's important that the files included in the release tarballs
243 and the tagged files are identical.
245 - Tag the CVS tree (replace x, y and z):
246 $ cvs tag version-x_y_z
250 Hopefully you didn't change any files after the last commit.
251 Otherwise commit your changes and return to the previous sections,
252 i.e. rebuild tarballs using "make distcheck2" and retag the tree.
254 - Upload the files fvwm-x.y.z.tar.gz and fvwm-x.y.z.tar.bz2 to
255 ftp://ftp.fvwm.org/pub/incoming/fvwm
256 - Notify fvwm-owner@fvwm.org of the upload.
258 Increase the version number:
260 - Increase the version number in the very beginning of
261 configure.ac (see above) and set ISRELEASED to "no".
262 - Create a new section for future changes in the NEWS file.
263 - Add a ChangeLog entry indicating that a new version started.
264 - Commit these three changes.
265 - For a stable release, copy the NEWS from the stable branch to
266 the development branch and update the link in the same
271 - Update the release numbers at the bottom of definitions.inc file.
272 - If this is the head development version, then run a shell script
273 in fvwm-web called regenerate_pages to update the web pages for
274 NEWS, FAQ and AUTHORS. It should usually work without parameters
275 for a typical setup (when fvwm and fvwm-web trees are sibling
276 directories), optionally pass a parameter to regenerate_pages -
277 the fvwm location relative to fvwm-web.
280 - Update the html documentation: go to the directory
281 doc and run the script
283 - Generate the man pages: go to the directory
284 documentation/manpages and run the script
286 It needs the program "man2html" installed.
287 - Generate ChangeLog entries for all these changes and commit them.
289 Announce the release:
291 - Once the tarballs are in place, mail the ANNOUNCE file to the
292 usual places, at least to fvwm-announce.