HACKING

The upstart source tree is available using Bazaar with the following
URL, if you plan to hack on upstart please work off this branch.

	http://bazaar.launchpad.net/~scott/upstart/trunk

Releases are available from:

	http://upstart.ubuntu.com/download/

upstart uses Launchpad's bug tracking system:

	http://bugs.launchpad.net/upstart/

If you want to contribute code or bug fixes, please either provide the
URL to your own Bazaar branch or use the ‘unified’ diff format
(diff -pu) and attach the patch to a bug.  Please supply a suggested
ChangeLog entry with your patch.


Maintainer tools
----------------

The source tree for upstart uses the GNU Build System (sometimes known
as the GNU Autotools).  You will need the following versions
installed.

	* GNU Autoconf 2.61
	* GNU Automake 1.10
	* GNU Libtool 2.2.4
	* GNU Gettext 0.16.1

After checking out upstart from Bazaar you will need to use these
tools to generate the build files.  The correct way to do this is to
simply run ‘autoreconf -i’ from the top-level source directory.


libnih
------

Upstart normally uses the pre-installed version of libnih, however it's
possible to use a version from a source tree alongside Upstart by
passing the path of that tree to the configure script using the
--with-local-libnih option.


Configure options
-----------------

There are some configure script options that you may find useful when
hacking on upstart.

	* --enable-compiler-warnings: (GCC only) adds extra CFLAGS to
	increase the source checking and treat all warnings as errors.

	* --disable-compiler-optimisations: ensures that no compiler
	optimisations are performed during compilation, easing
	debugging.

	* --disable-linker-optimisations: disables the usual linker
	optimisations, slightly decreasing build time.

	* --enable-compiler-coverage: (GCC only) enables coverage file
	generation, useful for test suites.


Coding style
------------

The coding style for upstart is roughly K&R with function names in
column 0, and variable names aligned in declarations.

The right results can be almost achieved by doing the following.

	* GNU Emacs: if you're not using auto-newline, the following
	should do the right thing:

	(defun upstart-c-mode-common-hook ()
	  (c-set-style "k&r")
	  (setq indent-tabs-mode t
	        c-basic-offset 8))

	* VIM: the default works except for the case labels in switch
	statements.  Set the following option to fix that:

	setlocal cinoptions=:0

	* Indent: can be used to reformat code in a different style:

	indent -kr -i8 -psl


Documentation
-------------

All functions, typedefs, structures and file-level variables, whether
exported or not, must be preceded by a documentation comment
detailing their usage and behaviour.  The format of that command is as
follows:

	/**
	 * function_name:
	 * @foo: first parameter description,
	 * @bar: second parameter description,
	 * @baz: third parameter description.
	 *
	 * Describe the function here, when you reference parameters
	 * use the form above, e.g. give @foo or @bar.
	 *
	 * Other functions should be referenced by function-call
	 * syntax, e.g. call other_function() afterwards.
	 *
	 * Returns: if there is a return value, include this line and
	 * give the possible values returned.
	 **/

Structures should detail their members instead of function parameters.


Function Attributes
-------------------

Functions that allocate a structure and return it should use the
"warn_unused_result" and "malloc" attributes, even if the structure is
placed in a linked list.  The former ensures a failure to allocate
memory is checked by the caller, and the latter allows some
optimisation.

Functions that raise errors, or call other functions that raise
errors, must indicate that an error has been raised in their return
value and also use the "warn_unused_result" attribute to ensure that
the caller doesn't ignore the error.

Functions that can return to indicate insufficient memory, even if
they don't return a pointer, should also use the "warn_unused_result"
attribute; unless it would be common to ignore this (e.g. shrinking a
buffer).


Test Cases
----------

Where possible, all code should be covered by test cases checking the
behaviour of that code.  It's particularly important that any bug
fixes be accompanied by a test case which fails without the fix and
succeeds with it.

Tests should be placed in C files under the tests/ directory, and use
the macros defined in the nih/test.h header.  See the existing test
examples to see how.

Any functions that allocate memory, or call any functions that
allocate memory (those marked with the "malloc" attribute) should be
tested using the TEST_ALLOC_FAIL macro to ensure that the case of
insufficient memory is handled properly.