Notes for Developers -*-text-*-
Last updated on 08-Jan-2006
You will need to install several GNU tools to be able to use the
cvs sources. If you do not have these tools available, build from
the tar file distribution instead, available from ftp.fvwm.org.
To build from the CVS sources, you will need:
* GNU gcc
* GNU make
* autoconf (version >= 2.53)
* automake (version >= 1.4)
After the *initial* checkout of the sources, (see cvs.html) you
will need to execute the following commands from the top of the
There will be some warnings, which are ignorable as long as you
get a working configure script: the configure script will fix all
Now, configure and build as per INSTALL.fvwm and INSTALL. If
configure fails, please look through `config.log' for clues.
Development Rules of the Road
1) _Every_ change must be properly ChangeLogged, listing the name
of the changed function. If you use Emacs, you can do this
oh-so-trivially with the "C-x 4 a" command; it will add a
header (if it's a new day), the name of the file, and even the
name of the function you're currently in. There is a
vim-script utils/changelog.vim that does the same when yoi
If you start adding them as you change functions, it'll soon
become second-nature and we'll get proper ChangeLogs.
If you don't use Emacs, please mimic the format of all the
other log entries when adding your own.
2) If you make a user-visible change please add a blurb about it
to the NEWS file. A couple sentences is fine; don't repeat
the documentation but give folks enough of an idea so they can
decide if they want to learn more. Bug fixes (unless they're
_really_ user visible) shouldn't be noted in the NEWS file.
3) If you add a new user-visible feature, don't forget to update
the appropriate man pages at the same time!
4) Bug fixes may be committed at any time (unless we're in code
freeze for a release), usually without much review (unless you
want someone else to look at it). All our code freezes,
etc. are merely procedural, not enforced, so it's important
you read fvwm-workers and keep up-to-date with the current
state of the tree.
5) New features should be discussed on the list to ensure
everyone thinks they're "appropriate" (one of the goals of
fvwm is to be relatively efficient, remember, which means we
don't necessarily want the kitchen sink).
6) If the new feature is large enough, unstable enough, or not
targeted at the next release, it should go on a private
branch. Otherwise, consensus will probably have it installed
on the main branch.
7) Before adding a new feature think twice if it could perhaps be
implemented as a module (perhaps after some extension of the
fvwm<->module communication protocol). Moving features in
modules helps to keep fvwm itself clean and efficient.
8) See CONVENTIONS for more details.
** Of course, compile and test before committing! **
Dealing with CVS
All details about dealing with CVS should be found in cvs.html.
Go look there!
Doing the JitterBug
If you haven't already noticed them, now is the time to visit our
bug tracking pages:
Anybody can submit or view bug reports there.
Developers with CVS write access can also update the bug database
(whee!). To do so, you have to go to the Jitterbug page, but then
tack a ".private" on to the end of the URL:
Then you'll be asked to authenticate. The username and password
are the same as you use for the CVS repository.
You'll probably want to bookmark that page.
Changing a Makefile
First of all, NEVER edit anything named Makefile or Makefile.in.
These are both derived from the corresponding Makefile.am. The
most common reason for editing is to change the list of sources.
Steps: 1. edit foo/blah/Makefile.am
2. re-run "make" from the top of the build directory
Step 2 will take care of rebuilding the Makefile.in and Makefile
from your changed Makefile.am.
Makefile.am has a simple format, basically:
bin_PROGRAMS = fvwm
fvwm_SOURCES = blah.c blah.h foo.c foo.h ...
Notice that you have to add all files, C-code *and* headers, to
the _SOURCES line. This is vital, because this is the list of
files that are packed into the distribution. If you leave one
out, nobody will be able to build the distributed tar file!
The most common reason to do this is to change the version string.
If you're editing it for any other reason, I will assume you know
what you're doing.
Steps: 1. edit configure.ac, and find the line containing
AM_INIT_AUTOMAKE(fvwm, x.y.z) at the top of the file
2. change x.y.z to the new version string
3. re-run "make" from the top of the build directory
Step 3 will take care of rebuilding the configure script, and
usually all the other Makefiles.
Building an official distribution
By this, I mean the files fvwm-x.y.z.tar.gz and
fvwm-x.y.z.tar.bz2. It is important to do all steps in the given
- Make sure you have all optional libraries installed.
- When building a release, update the CVS sources first. For a
stable release it is best to throw away the whole source tree
and check it out from scratch to ensure all source files have
been added to CVS.
- Change the dates in configure.ac and fill in the release date
in NEWS. Note: For releases prior to 2.5.3, the date has to be
updated in docs/fvwm.lsm.in and fvwm/fvwm.1 instead of
- Verify that the version variable at the very beginning of
configure.ac has the value of the going to be released version
and set ISRELEASED to "yes". It should be "yes" in the
- For a stable release, update docs/ANNOUNCE file. For the
first version of a major release (e.g. 2.6.0) all user visible
changes have to be mentioned. For the following maintenance
releases *all* code changes have to be listed. This is
usually done by copying all entries from the NEWS file. Don't
forget to proof read the file as it will be sent to the
fvwm-announce mailing list.
- Update the ChangeLog for all the changes above.
- Commit these changes.
Note that you need to have actually built everything before
packing the distribution. Among other things, this generates
the proper dependency information for insertion into
Makefile.in's generated by "make distcheck2".
aclocal && autoheader && automake --add-missing && autoconf
- If you are building a stable release, remove the config.cache
file if there is one (autoconf 2.52 does no longer generate
this file by default). Of course doing this for a development
release won't hurt either.
- Make sure configure detects all optional libraries except the
ones that are recommended not to be used. Repeat the previous
step until configure finds everything. Building a release
without any optional library should be a rare exception.
even if you checked out from scratch. It is a useful
- Double check that you get no warnings during the build:
make CFLAGS="-g -O2 -Wall -Wpointer-arith -fno-strict-aliasing -Werror"
On some systems, the system include files generate warnings.
On such a system you have to omit the -Werror option and check
the output of the compilation run for warnings manually. It
is important to use the -O2 option because gcc can not
generate some warnings without it. If your gcc-version does
not know the option "-fno-strict-aliasing", remove it.
- Fix all warnings and problems, commit the changes and repeat
the previous step until no more warnings occur.
Build and test the release tarballs:
The next step will create the tar file, then unpack it and
attempt to build fvwm from it and install to a scratch
directory. This makes sure that you really *did* include all
the files necessary to build the package into the tar file. It
may be hard to appreciate how useful this is, until it has
reminded you that you forgot file "foo.h" in some _SOURCES line.
But trust me, it will save your bacon in this way some day!
- Ensure that you see the messages
"fvwm-x.y.z.tar.gz is ready for distribution"
"fvwm-x.y.z.tar.bz2 - ready for distribution"
Tag the release:
* Important note: Before you proceed, please ask yourself if the
code is ready to be released:
* Have you committed patches only hours or even minutes ago?
* Have there been any big changes in the last few days?
* Are there any important parts that are not well tested?
* Are you tired from work or have you been hacking fvwm for many
hours in a row?
Should your answer to any of these questions be 'yes', please do
take a break now and reconsider, especially if this is going to
be a stable release.
The steps above are not critical and can not screw up anything
bad. This is not true for what follows. If you do something
wrong now, you will have a hard time cleaning up the mess.
Should something go wrong and you are not sure about the correct
fixes, please ask on the fvwm-workers list for help.
It's important that the files included in the release tarballs
and the tagged files are identical.
- Tag the CVS tree (replace x, y and z):
cvs tag version-x_y_z
Upload the release:
Hopefully you didn't change any files after the last commit.
Otherwise commit your changes and return to the previous sections,
i.e. rebuild tarballs using "make distcheck2" and retag the tree.
- Upload the files fvwm-x.y.z.tar.gz and fvwm-x.y.z.tar.bz2 to
- Notify firstname.lastname@example.org of the upload.
Increase the version number:
- Increase the version number in the very beginning of
configure.ac (see above) and set ISRELEASED to "no".
- Create a new section for future changes in the NEWS file.
- Add a ChangeLog entry indicating that a new version started.
- Commit these three changes.
- For a stable release, copy the NEWS from the stable branch to
the development branch and update the link in the same
- Update the release numbers at the bottom of definitions.inc file.
- If this is the head development version, then run a shell script
in fvwm-web called regenerate_pages to update the web pages for
NEWS, FAQ and AUTHORS. It should usually work without parameters
for a typical setup (when fvwm and fvwm-web trees are sibling
directories), optionally pass a parameter to regenerate_pages -
the fvwm location relative to fvwm-web.
- Generate ChangeLog entries for all these changes and commit them.
Announce the release:
- Once the tarballs are in place, mail the ANNOUNCE file to the
usual places, at least to fvwm-announce.