Jitterbug no more.
[fvwm.git] / docs / DEVELOPERS
blob172023ae8290c0cae5855821f843c0d4c4cc5e18
1                         Notes for Developers                         -*-text-*-
2                         --------------------
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:
11   * GNU gcc
12   * GNU make
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.
21     aclocal
22     autoheader
23     automake --add-missing
24     autoconf
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
28 those problems.
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
43     type ":ChangeLog".
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
65     state of the tree.
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
75     on the main branch.
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! **
87 Dealing with CVS
88 ----------------
90 All details about dealing with CVS should be found in cvs.html or
91 DEVELOPER-CVS.  Go look there!
93 Changing a Makefile
94 -------------------
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:
108         bin_PROGRAMS = fvwm
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
123 what you're doing.
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
139 order!
141 Preparations:
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
147     been added to CVS.
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
151     configure.ac.
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
155     released tarballs.
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.
165 Configuration tests:
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".
172   - Run
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.
178   - Run
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.
185 Compile tests:
187   - Run
188      $ make clean
189     even if you checked out from scratch.  It is a useful
190     additional check.
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!
214   - Run
215      $ make distcheck2
216   - Ensure that you see the messages
217       "fvwm-x.y.z.tar.gz is ready for distribution"
218     and
219       "fvwm-x.y.z.tar.bz2 - ready for distribution"
221 Tag the release:
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
230     hours in a row?
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
234   be a stable release.
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
248 Upload the release:
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
267     document.
269 Update fvwm-web:
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.
278      $ cd fvwm-web
279      $ ./regenerate_pages
280   - Update the html documentation: go to the directory
281     doc and run the script
282     $ ./updatedoc
283   - Generate the man pages: go to the directory
284     documentation/manpages and run the script
285      $ ./manpages2php
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.