Code maintenance

Table of Contents Commit access Commit workflow White space policy Testing Running with and without libtool Check memory leak git submodules Objects allocation Error handling Export API function

Commit access

The members of the gitaugeas group have commit access.

Commit workflow

The master branch history of Augeas is keept linear, and avoids merge commits. This is important for git bisect to work. To merge patches into master branch, the workflow is:

$ git checkout master
$ git pull
$ git branch mybranch
$ git checkout mybranch
# edit files
$ git add <modified_files>
$ git commit
$ git log # Get the <since_ID> of previous commit
$ git format-patch -o /tmp/augeas <since_ID>
$ git send-email --to=<list_address> /tmp/augeas
$ git rebase mybranch master
$ git pull --rebase
$ git push
$ git branch -D mybranch

White space policy

Indentation is done with 4 spaces by level, tabs are never used. Source files must not have one and exactly on blank lines at the end of files and no trailing spaces at the end of lines.

• Emacs: See nuke-whitespace.el
• VIM: highlight end of line white space by adding "match Todo /\s\+$/" to .vimrc
• Eclipse: Window -> Preferences -> C/C++ -> Editor -> Save Actions, then check Remove trailing whitespace and Ensure newline at the end of file.

Testing

Testing is done with target make check.

Lens tests are under lens/tests/test_*.aug. To add a new lens, the corresponding entry must be added to tests/Makefile.am.

Other internal tests are under tests/*. They can be run and compile manually, for example test-api

 # inside augeas top source directory
 export abs_top_srcdir=$(pwd)
 cd tests/
 make test-api
 ./test-api

Running with and without libtool

Executables under src/ and tests/ directory are autogenerated libtool scripts. libtool sets LD_LIBRARY_PATH automatically and launch the program.

 libtool --mode=execute ...

If you ever need to set LD_LABRARY_PATH manually, libaugeas is found under src/.libs. Hence, perform export at the toplevel directory:

 export LD_LIBRARY_PATH=$(pwd)/src/.libs

Check memory leak

The target make valgrind inside tests/ directory runs fatest with valgrind. To test other binaries, binaries inside build directory needs to be launched with libtool. Here is an example to run augparse under valgrind.

 libtool --mode=execute valgrind ./src/augparse -I lenses/ --nostdinc lenses/tests/test_hosts.aug

git submodules

Augeas needs gnulib git submodule. If git reports .gnulib file changed, then you need to update the submodule. To update submodules, run the following command.

 git submodule update

Objects allocation

Shared references to objects should be ref counted, otherwise direct allocation and free should be performed. To allocate mystruct on the heap, two functions must be declared, make_mystruct and free_mystruct. Usage of ref counting macro require a ref_t ref struct member. As an example, look at the struct string.

Error handling

Error codes are defined by aug_errcode_t enum in augeas.h.

Memory allocation must be always checked for success within make_* functions. On failure, a NULL must be returned. The caller must check the result and bail out on failure.

When aug object is available, the error should be reported with ERR_* macros.

Export API function

Only functions part of the API are exported from libaugeas. To add a function, the function must be declared in augeas.h and appended to augeas_sym.version.