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.