Fixed missing include in quartzcheck.cc

[xapian.git] / xapian-core / HACKING

Instructions for hacking on Xapian
==================================

This file is aimed to help developers get started with working on
Xapian. The Xapian SourceForge project page is at
<http://sourceforge.net/projects/xapian/>, and contains various tools
that help support us.

Extra options to give to configure:
===================================

Note: Non-developer configure options are described in INSTALL

You will probably want to use some of these if you're going to be developing
Xapian.

--enable-debug
        This enables compiling of assertion code, to produce warnings if
        the code gets into an unexpected state, and also compiling into
        the system of debugging symbols.

--enable-debug=partial
        This option enables debugging symbols, and some assertions.  It does
        not enable verbose debugging messages or very expensive assertions.

--enable-debug-verbose
        This enables compiling into the system of code to generate verbose
        debugging messages.  See "Debugging Messages", below.

--enable-debug=full
        This is the same as --enable-debug --enable-debug-verbose

Debugging Messages
==================

Lots of places in the code generate debugging messages to tell us what
they're up to, and this information can be very useful.  However, its got
to such a stage that we need to be able to turn it on and off easily: and
so I've set up a system for controlling the debugging output by means of
environment variables.  You can:

 o) set OM_DEBUG_FILE to be the path to a file that you would like debugging
    output to be stored in (to override the default of stderr).

 o) set OM_DEBUG_TYPES to a bitmap to select the types of debugging message
    you would like to display.  Currently, all messages are selected by
    setting bit 0 (ie, OM_DEBUG_TYPES=1), but they will be differentiated
    into separate classes in future.

Of course, if you didn't compile with --enable-debug=full, these environment
variables will have no effect.

Debugging memory allocations
============================

The testsuite's leak checking has unfortunately proved not to work well with
many STL implementations, and it gives spurious reports.  For the time being
we've removed it, and suggest using a third party product to trap leaks.

Building with various profiling and leak-finding tools:
=======================================================

For use with valgrind, no special build flags are required.  You just need to
run the program to be checked with valgrind, e.g.:

  env srcdir=. valgrind ./apitest -v deldoc1

To enable profiling for gprof (was --enable-profiling):

  env CFLAGS=-pg CXXFLAGS=-pg LDFLAGS=-pg ./configure

To use Purify (was --enable-purify):

  env CXXLD='purify c++' CCLD='purify cc' ./configure --disable-shared

To use Insure (was --enable-insure):

  env CXX=insure CC=insure ./configure

Building from CVS:
==================

The CVS repository does not contain any automatically generated files
(such as configure and Makefile.in's).  Because of this, you need to run
several programs to build these files, before you can run the normal
build process.

At the time of writing, these programs are autoconf, automake, libtool,
and GNU bison.  Some older versions of these programs may not work correctly:
at the time of writing, the versions known to work are:

        automake (GNU automake) 1.5
                This is required as automake 1.4 has problems with "make dist"
                in a VPATH build, and doesn't support AM_CFLAGS/AM_CXXFLAGS.
                Note that automake 1.6 has a bug which causes it to emit
                spurious warnings: this is fixed in automake 1.6.1.
                
        Autoconf version 2.50
                Needed for many things.
                
        ltmain.sh (GNU libtool) 1.3.3

        GNU Bison version 1.35
                Bison versions 1.31 to 1.34 don't handle parsequery.yy - for
                a summary of the gory details, see this (note this isn't a
                debian specific bug though):

                http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=130914

                There are apparently some bugs in earlier versions, which
                might affect us, so we require at least 1.35.

        GNU Flex
        
Please tell us if you find that older (or newer) versions work or fail to work.

We have provided a simple standard script to run these programs for you:
simply run ${source-directory}/buildall, in the same way you would normally
run configure.  Arguments passed to buildall are in turn passed on to configure.

You may need to add extra macro directories to the path searched by aclocal
(which is part of autoconf) - you may do this by specifying these in the
ACLOCAL_FLAGS environment variable.

See "buildall --help" for more information. Alternatively, there is a
good overview of the GNU autotools at <http://sources.redhat.com/autobook/>.

Miscellaneous Portability Issues:
=================================

open() and <fcntl.h>:
---------------------

No C++ file should explicitly "#include <fcntl.h>".

When largefile support is enabled, Solaris' fcntl.h will "#define open open64"
which breaks C++ code which has methods called open.  There's a cunning way
to avoid this problem, which is implemented in common/utils.h.

Any C++ file which wants to "#include <fcntl.h>" should instead '#include
"utils.h"'.  For convenience, the open call this defines takes a C++ string,
but you can also pass a char* (which will be converted to a C++ string).

Warning Free Compilation:
-------------------------

Compiling without warnings on every platform is our goal, though it's not
always possible to achieve.  For example, GCC 2.95 produces a few bogus
warnings (e.g. about not returning a value from a non-void function).

If using GCC 3.0 or newer, you should consider configure-ing with:

./configure CFLAGS=-Werror

when doing development work on Xapian.  This promotes warnings to errors,
and should ensure you don't introduce warnings.  If you find out how to
do the same with other compilers, please add a note here.

Makefile Portability:
=====================

We don't want to force those building Xapian from the source distribution to
have to use GNU make.  Requiring GNU make for "make dist" isn't such a problem
but it's probably better to use portable constructs everywhere to avoid
problems when people move or copy code between targets.  If you do make use
of non-portable constructs where it's OK, add a comment noting this.

Here's an incomplete list of things to avoid:

* Don't use "$(RM)" - it's defined by GNU make, but using it actually harms
  portability as other makes don't define it.  Use plain "rm" instead.

* Don't use "%" pattern rules - these are GNU make specific.  Use an
  implicit rule (e.g. ".c.o:") if you can.  Otherwise, write out each version
  explicitly.

* Don't use "$<" except in implicit rules.  This is an annoying restriction,
  as using "$<" makes it much easier to make VPATH builds work.  But it's only
  portable in implicit rules.  Tips for rewriting - if it's a source file,
  write it as:
    $(srcdir)/foo.ext
  If it's a generated object file or similar, just write the name as is; if it
  could be produced by the build, but also goes in the distribution tarball,
  use this trick to make sure it's found whichever directory it's in:
    `test -f foo.ext || echo '$(srcdir)/'`foo.ext

* Don't use "exit 0" to make a rule fail.  Use "false" instead.  BSD make
  doesn't like "exit 0" in a rule.

* Don't use make conditionals.  Automake offers conditionals which may be
  of use, and these are implemented to work with any make.  See the automake
  manual for details, and a few caveats.

* The list of portable utilities is: 
    cat cmp cp diff echo egrep expr false grep install-info
    ln ls mkdir mv pwd rm rmdir sed sleep sort tar test touch true
  Note that versions of these (GNU versions in particular) support switches
  which aren't portable - notably, "test -r" isn't portable; neither is
  "cp -a".  And note that "mkdir -p" isn't portable - the semantics vary.
  See the "Goat Book" for more details and other useful tips:
    http://sources.redhat.com/autobook/

* Don't use "include" - it's not present in BSD make (at least some versions
  have ".include" instead, but that doesn't really seem to help...)  Automake
  provides a configure-time include, which may provide a replacement for some
  uses of "include".

And lastly a style point - using "@" to suppress outputing of commands being
executed removes choice from the user - they may want to see what commands
are being executed.  And if they don't want to, they can use "make -s" (in
many versions of make).

Using @echo on a message sent to stdout or stderr is acceptable.  Otherwise
don't use "@" - it makes it harder to track down problems in the makefiles.

Use of Assert
=============

Use Asserts to perform internal consistency checks, and to check for invalid
arguments to functions and methods (e.g. passing a NULL pointer when this isn't
permitted).  They should *NOT* be used to check for error conditions such as
file read errors, new returning 0, etc (since we want to perform such checks
in non-debug builds too).

File format errors should also not be tested with Asserts - we want to catch
a corrupted database or a malformed input file in a non-debug build too.

There are several variants of Assert:

Assert(P) -- asserts that expression P is true
AssertEq(a,b) -- asserts that expressions a and b are equal [message reports
        values of a and b, so is more informative than Assert((a)==(b))]
AssertNe(a,b) -- asserts a and b are not equal
AssertEqDouble(a,b) -- asserts a and b differ by less than DBL_EPSILON

AssertParanoid(P) -- a particularly expensive assertion.  If you want a build
        with Asserts enabled, but without a great performance overhead, then
        passing --enable-debug=partial to configure and AssertParanoids won't
        be checked, but Asserts will.

Submitting Patches:
===================

If you have a patch to fix a problem in Xapian, or to add a new
feature, feel free to submit it to us via the SourceForge patch
management system. Any major changes should be discussed on the
xapian-devel mailing list first:
<http://lists.sourceforge.net/mailman/listinfo/xapian-devel>

We find patches generated with "diff -puN" easiest to read.  If you are
working from a CVS copy of the code, you can use "cvs diff -puN" to generate
your patch, or put the line "diff -puN" in your ~/.cvsrc file and just use
"cvs diff".

We will however do our best to give proper attribution to you.  In
particular, if we have used patches from you, or received helpful
reports or advice, we will add your name to the AUTHORS file; unless
you specifically request us not to.  If you see we have forgotten to
do this, please draw it to our attention so that we can sort it out.

Developers with CVS access:
===========================

People who are more seriously involved with the project are likely to
have write access to the repository at SourceForge. This section gives
the conventions for those developers. In addition to this, obviously
you should make sure you update any documentation, especially the
inline source code documentation that generates the API docs.

1  Make sure the tests are right
--------------------------------

 * If you're adding a feature, also add tests for it.
 * If you've fixed a bug, make sure there's a regression test which
   fails on the existing code and succeeds after your changes.
 * Make sure all existing tests continue to pass.

If you don't know how to write tests using the Xapian test rig, then
ask. It's reasonably simple once you've done it once. There is a brief
introduction to the Xapian test system in docs/tests.txt .

2  Make sure the attributions are right
---------------------------------------

 * If necessary, modify the copyright statement at the top of any
   files you've altered. If there is no copyright statement, you may
   add one (there are a couple of Makefile.am's and similar that don't
   have copyright statements; anything that small doesn't really need
   one anyway, so it's a judgement call).
   If you've added files, they should include the GPL boilerplate
   with your name only.
 * If you're not in there, add yourself to the AUTHORS file.

3  Create a log entry and commit
--------------------------------

 * Add an entry to the ChangeLog file at the top of the module. The
   text of this can be identical to the cvs commit message.
 * Commit to the repository.

Then you can update any patch, bug or feature request items in the
tracker to indicate that they've been dealt with.