HACKING.md

   1 This file explains some details about developing the Augeas C library.
   2
   3 # Check out the sources
   4
   5 The sources are in a git repo; to check it out run
   6
   7 ```
   8   git clone git://github.com/hercules-team/augeas
   9 ```
  10
  11 # Building from git
  12
  13 Besides the usual build tools (gcc, autoconf, automake etc.) you need the
  14 following tools and libraries to build Augeas:
  15
  16 * Bison
  17 * Flex
  18 * readline-devel
  19 * libxml2-devel
  20 * libselinux-devel (optional)
  21
  22 Augeas uses gnulib, and you need a checkout of gnulib. The build scripts
  23 can create a checkout for you behind the scenes - though if you already
  24 have a gnulib checkout, you can pass its location to autogen.sh with the
  25 --gnulib-srcdir option.
  26
  27 At its simplest, you build Augeas from git by running the following
  28 commands in the toplevel directory of your Augeas checkout:
  29
  30     ./autogen.sh [--gnulib-srcdir=$GNULIB_CHECKOUT]
  31     make && make check && make install
  32
  33 It is recommended though to turn on a few development features when
  34 building; in particular, stricter compiler warnings and some debug
  35 logging. You can pass these options either to autogen.sh or to
  36 configure. You'd then run autogen like this:
  37
  38     ./autogen.sh --enable-compile-warnings=error --enable-debug=yes
  39
  40 # Running augtool
  41
  42 The script ./src/try can be used to run ./src/augtool against a fresh
  43 filesystem root. It copies the files from tests/root/ to build/try/ and
  44 starts augtool against that root, using the lenses from lenses/ (and none
  45 of the ones that might be installed on your system)
  46
  47 The script can be used for the following; OPTS are options that are passed
  48 to augtool verbatim
  49
  50 * `./src/try OPTS`: run the commands from `build/augcmds.txt`
  51 * `./src/try cli OPTS`: start an interactive session with augtool
  52 * `./src/try gdb`: start gdb and set it up from `build/gdbcmds.txt` for
  53   debugging augtool with commands in `build/augcmds.txt`
  54 * `./src/try valgrind`: run the commands from `build/augcmds.txt` through
  55   augtool under valgrind to check for memory leaks
  56
  57 Furthermore, the test suite invoked with `make check` includes a test
  58 called `test-get.sh`, which ensures that reading the files in
  59 `tests/root/` with `augtool` does not lead to any errors. (It does not
  60 verify the parsed syntax tree however; you'll have to extend the
  61 individual lens tests under `lenses/tests/` for that.)
  62
  63 # Platform specific notes
  64
  65 ## Mac OSX
  66
  67 OSX comes with a crippled reimplementation of readline, `libedit`; while
  68 Augeas will build against `libedit`, you can get full readline
  69 functionality by installing the `readline` package from
  70 [Homebrew](http://brew.sh/) and setting the following:
  71 ```sh
  72 > export CPPFLAGS=-I/usr/local/opt/readline/include
  73 > export LDFLAGS=-L/usr/local/opt/readline/lib
  74 ```