This file explains some of the conventions to follow for those wishing
to contribute to the project.


	RPM spec files.

Our conventions for RPM spec files are quite similar to Red Hat's, but
a few differences and additional requirements for native Owl packages
do exist.

1. Start the spec file with a comment containing the dollar-Owl-dollar
tag ("Owl" is configured to be a replacement of the "CVSHeader" keyword
in our CVS repository), followed by an empty line.

2. The preferred tag names (whenever synonyms exist) and order of tags
is: Summary, Name, Version, Release, Epoch, License, Group, URL,
Source*, Patch*, PreReq, Requires, Conflicts, Provides, Obsoletes,
Auto*, Prefix, BuildRequires, BuildArchitectures, ExcludeArch,
ExclusiveArch, BuildRoot.  Other tags we (currently) don't use.

3. Release numbers for native Owl packages are of the form:

	owlREVISION

or, when packaging an alpha/beta/prerelease version of a certain piece
of software and the Version tag is set to the upcoming version number:

	owl0.REVISION

or, when updating an older branch of Owl:

	BRANCH_POINT_RELEASE.BRANCH.REVISION

where REVISION is an Owl-specific package revision number incremented
after each update, BRANCH_POINT_RELEASE is the Release string as of
when the branch was created, and BRANCH is the branch version (that
is, "0.1" for Owl 0.1-stable).

When updating to a new Version, REVISION should be reset to 1 and, for
older branches, BRANCH_POINT_RELEASE set to "owl0".

4. The correct BuildRoot tag for an Owl package is:

	BuildRoot: /override/%name-%version

Our build environment will override the BuildRoot regardless of this
tag, but setting it in this way will remind people to override the
BuildRoot for manual builds of the package, especially on non-Owl.

5. Separate tag names and values you set them to with a single space
character.  Use commas (also followed by a space) to separate items in
dependency lists.  Do terminate Summary lines with a dot.  In both
Summary and %description (as well as in any other documentation),
avoid capitalizing the names of commands, even if they happen to be
the first word in a sentence, unless the capitalized form is the
official name for the software in question.  Use double spaces to
separate sentences.

6. Our build environment sets the C/C++ compiler optimization flags in
%optflags in a way that is optimal for compiling standalone programs
and doesn't produce too much warnings with typical source files.  When
building libraries, another set of optimization flags may be used by
placing the following two lines right before the %build section:

	# Use optflags_lib for this package if defined.
	%{expand:%%define optflags %{?optflags_lib:%optflags_lib}%{!?optflags_lib:%optflags}}

This will disable optimizations that would prevent debugging of
programs linked against the libraries (even when the programs
themselves are correctly built for debugging) and, on the x86, will
ensure stack alignment suitable for efficient floating-point and MMX
operations that a program linked against the library may do.  (The
latter is just to be friendly to third-party programs.  We don't have
a noticeable amount of floating-point math in programs that are a part
of Owl and thus we don't do the extra stack alignment when building
our programs.  But libraries need to be different because of possible
callbacks.)

It also is recommended that you make the source files clean enough to
not produce a single compiler warning when building with "gcc -Wall".
If you do, then the right way to pass the -Wall is in most cases by
placing the following line right before the %build section:

	%{expand:%%define optflags %optflags -Wall}

7. Subshells in build, pre/post-install/uninstall, and trigger scripts
are to be avoided by all means as they mask possible errors.  If you
intended to use a subshell to temporarily change current directory,
use pushd and popd commands instead.  If you really must use a
subshell, it is suggested that you issue a "set -e" within the
subshell or propagate the status of commands it runs to the parent
shell manually.

8. Use tabs to indent conditional blocks and continuation lines in
scripts.  However, do not indent pushd ... popd "blocks".

9. Use -eq or -ne and not = or != to compare numeric values.  In
particular, this applies to the $1 argument that RPM itself passes to
scripts.  And don't place the $1 in quotes, the package has to trust
its package manager to pass it the correct input anyway.

10. Use the %buildroot macro instead of $RPM_BUILD_ROOT.  Use the
%_sourcedir macro instead of $RPM_SOURCE_DIR.  Do not refer to source
files by number (e.g., with %SOURCE1), use %_sourcedir/WHATEVERFILE
instead.  Use the %optflags macro instead of $RPM_OPT_FLAGS.

11. Do use the appropriate RPM macros for invoking build tools which
we might want to override (e.g., use %__make instead of just make, use
%__cc instead of gcc, etc.)  However, do not use the macros for
essential shell commands such as cp, mv, rm.

12. Do not unnecessarily use "-f" (force) with shell commands,
especially not with "rm".  Not using "-f" lets us catch rm's which
become obsolete or need to be revised (e.g., because an unneeded file
changed its name or location in a new upstream revision).  It also
helps catch some build failures where other files could be missing
from their expected locations as well.  If you do use "-f" for a
reason, consider explaining the reason in a one-line comment right
before the shell command.

13. In %changelog entries, obfuscate the "@" in e-mail addresses with
"-at-".  Use two digits for day of month with a leading zero if
necessary.  Do specify the current package Epoch (only if it's other
than 0), Version, and Release after your e-mail address.  The lines will
look like this:

	* Wed Dec 01 2004 Your Name <you-at-example.com> 1.0-owl1

or, if Epoch is used:

	* Mon Oct 24 2005 Your Name <you-at-example.com> 1:1.0-owl1

In other places, obfuscate the "@" with " at " (that is, use spaces
instead of dashes).

14. As it relates to spec files portability, the current stance is to
have our spec files either result in a reasonable build or fail to
build entirely on systems other than Owl.  Some spec files (the ones
which get into archives/*.tar.gz during Owl builds) are meant to be
portable to non-Owl.  %clean sections should be omitted in all spec
files, whether portable or not (they are not used by the Owl build
environment and there's no major harm in not cleaning build files on
other systems).


	Patch file naming.

Use the following syntax for patch file names:

	NAME-VERSION-ORIGIN-WHAT.diff

where NAME and VERSION are the package name and version, ORIGIN is an
abbreviation of the distribution name(s) the patch originates from,
and WHAT is a description of what the patch is for or what it does.

If a single patch file is based on pieces from more than one
distribution, all are to be included in ORIGIN, most relevant first.
For patches developed as a part of Owl, ORIGIN is to be set to "owl".
If a patch is derived from another distribution but with significant
changes applied, ORIGIN should include "-owl-" as well (which would
indicate that any bugs are ours).  If a patch has been extracted from
the primary CVS repository for the package in question (for example,
this may be the case for various back-ports), ORIGIN should be set to
"cvs" and WHAT to the date it corresponds to (as YYYYMMDD) plus the
usual description of the patch.  Patches from upstream maintainers
that aren't (yet?) in the primary CVS repository (if one even exists)
may have ORIGIN set to "up".

For multi-word WHATs, separate the words with dashes.  Do not use
underscores except when referring to an existing identifier (in which
case the identifier is to be quoted verbatim, including any possible
underscores and uppercase letters).

There are also some common WHATs to use whenever applicable:

Makefile	- Makefile* patches only (note the capitalization)
bound		- bound checking (buffer and/or integer overflow fixes)
config		- configuration files patches only (compile- or runtime)
doc		- documentation patches only
env		- environment variable handling fixes
fixes		- cumulative bug, reliability, and/or security patches
format		- printf-style format string fixes (not only security)
info		- texinfo documentation patches only
install-no-root	- changes to run "make install" or equivalent as non-root
linux		- changes needed to build on Linux (for ported software)
man		- man page patches only
tmp		- patches dealing with temporary file handling issues
vitmp		- patches that add vitmp(1) support
warnings	- compilation warning fixes only

This is NOT to suggest you should try to arrange your modifications
such that the patch files fit one of these categories.  In fact, it is
often preferable to do things differently.  This is just to say that
if you happen to have a patch file that matches one of the categories,
name it accordingly (such as, "tmp" and not, say, "mkstemp").


	(Re-)generating patch files.

The patch files should be generated with:

	TZ=UTC diff -urpN NAME-VERSION.orig NAME-VERSION >
		NAME-VERSION-ORIGIN-WHAT.diff

where NAME-VERSION.orig and NAME-VERSION are directories with the
original and modified versions of the upstream package, respectively.
The "-p" and "-N" options to diff(1) may be omitted if not applicable.

When re-generating patches to apply additional changes, the existing
patches should be applied with "patch -Z", for example like this:

	cd NAME-VERSION
	patch -p1 -Z < ../NAME-VERSION-ORIGIN-WHAT.diff

The use of timestamps in UTC lets us better preserve them over patch
file updates and reduces the amount of changes between revisions.


	C source code formatting.

When developing or importing pieces of C code for further maintenance
as a part of Owl, indent(1) may initially be used with the following
options:

	indent -kr -i8 -nlp -nbbo -l79 -lc79

This does not exactly match our preferred coding style and thus isn't
to be used on sources already in Owl.


	Temporary file handling.

It's better to not use temporary files, however if you must, the
preferred way to do it from shell scripts is with code like this:

	TMPFILE="`mktemp -t program.XXXXXXXXXX`" || exit
	trap 'rm -f -- "$TMPFILE"' EXIT
	trap 'trap - EXIT; rm -f -- "$TMPFILE"; exit 1' HUP INT QUIT TERM

To create temporary directories, use:

	TMPD="`mktemp -dt program.XXXXXXXXXX`" || exit
	trap 'rm -rf -- "$TMPD"' EXIT
	trap 'trap - EXIT; rm -rf -- "$TMPD"; exit 1' HUP INT QUIT TERM

This may be used in our own scripts or in patches.  The package should
then require the proper version of mktemp(1):

	Requires: mktemp >= 1:1.3.1

(This is the version which introduced support for the "-t" option.)

As usual, use Requires, PreReq, and/or BuildRequires depending on
where in the package the uses of mktemp occur.

$Owl: Owl/doc/CONVENTIONS,v 1.30 2005/12/26 22:14:07 solar Exp $
