README.developer

Developer notes for Xdx


Build system bootstrap
======================

A clean Git working directory requires bootstrapping the build system.  The
'bootstrap.sh' script will handle the details.  See README.bootstrap for more
information.

Development has taken place with Gettext 0.18.3, Autoconf 2.69, and Automake
1.14.  Most recent versions of these tools should work.


.po file regeneration
=====================

After modifying source files, xdx.pot and *.po files are updated only by running
'make dist' or 'make distcheck'.  Even cleaning to the level of 'git clean' and
then running 'bootstrap.sh' will not update these files.


Build files modified by the build system
========================================

The files Makefile.am, configure.ac, and m4/Makefile.am are modified by the
Gettext tools.  These changes will not be committed to the repository as they
will likely differ for different versions of Gettext.  Care is required to
clean them correctly as those files are tracked in the repository.  The easiest
way is to have Git restore the pre-modification versions of these files:

	git checkout -- Makefile.am configure.ac m4/Makefile.am

This can be done prior to committing changes and should be done in conjunction
with 'git clean' and cleaning the build tree.

When modifying those files, intended modifications can be tracked without
committing by the use of 'git add'.  After adding the file changes the build
system can be bootstrapped and the Gettext changes dropped using the 'checkout'
command above.


VPATH support
=============

Development has been done by building in a separate build directory.  For
example:

	~/git
	    +-xdx
	    +-xdb

With the build taking place in 'xdb'.

Bootstrapping can be done from 'xdb':

	../xdx/bootstrap.sh

Then the usual 'configure', 'make', 'make install' commands may be used and the
binary objects will be placed in 'xdb'.


Cleaning the directory
======================

Using a separate build directory allows cleaning the binary objects in 'xdb'
with:

	rm -rf *

Removing the generated build system files from the source directory using Git:

	git clean -dxf

and then using the 'checkout' command above should result in a pristine Git
repository.


Coding style
============

The subject of numerous holy wars this side of editors, coding style is
subjective and mostly dictated by whomever stares at the code the most.  My
preference is mostly implemented in misc/astylerc using the astyle utility
(http://astyle.sourceforge.net) with a few additional tweaks.

Vertical space is cheap.  I prefer two lines between preprocessor directives and
the start of the C code.  Also two lines between function definitions and
between the beginning and end of a function definition and other declarations.

Often multiple statements form a logical block of action.  They can be lumped
together as would a paragraph.  One line break between logical blocks gives
the eye a break and the brain a cue that a new logical block has begun.

A function definition has its name begin in column 0 with its return type on
the line prior.

Multiple function arguments may be more easily read by lining up the type and
the argument's name in vertical columns as:

static void
get_main_menu(GtkWidget  *window,
              GtkWidget **menubar)
{
.
.
.
}

Rather than tabs, I've chosen 4 spaces per indent which gives a good compromise
between horizontal space and nesting toward the right hand side of the screen.
Spaces also avoid the case where editors may be configured to interpret tabs
as equivalent to different spacing.  Things will most often stay nicely lined
up when everyone uses spaces.


73, Nate, N0NB, n0nb@n0nb.us