| The libnih source tree is available using Bazaar-NG with the |
| following URL, if you plan to hack on libnih please work off this |
| branch. |
| |
| http://www.netsplit.com/bzr/libnih/ |
| |
| Releases are available from the FTP site: |
| |
| ftp://ftp.netsplit.com/pub/libnih/ |
| |
| libnih uses the Malone bug tracking system: |
| |
| http://launchpad.net/products/libnih/+bugs |
| |
| If you want to contribute code or bug fixes, please either provide the |
| URL to your own Bazaar-NG 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 libnih uses the GNU Build System (sometimes known |
| as the GNU Autotools). You will need the following versions |
| installed. |
| |
| * GNU Autoconf 2.60 |
| * GNU Automake 1.10 |
| * GNU Libtool 1.5.22 |
| * GNU Gettext 0.16.1 |
| |
| After checking out libnih from Bazaar-NG 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. |
| |
| |
| Configure options |
| ----------------- |
| |
| There are some configure script options that you may find useful when |
| hacking on libnih. |
| |
| * --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 libnih 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 libnih-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. |