HACKING

This HACKING file describes the development environment.  	-*- org -*-

  Copyright (C) 2008, 2009, 2011 ViewPlus Technologies, Inc. and JJB
  Software, Inc.

  Copying and distribution of this file, with or without modification,
  are permitted in any medium without royalty provided the copyright
  notice and this notice are preserved.

This file attempts to describe the maintainer-specific notes to follow
when hacking liblouis. 

* Developing
** Where to get it
The development sources are available through anonymous svn at Google
Code:

  http://code.google.com/p/liblouis/

** Build requirements
This distribution uses Automake, Autoconf, and Libtool. If you are
getting the sources from svn (or change configure.ac), you'll need to
have these tools installed to (re)build. Optionally (if you want to
generate man pages) you'll also need help2man. All of these programs
are available from ftp://ftp.gnu.org/gnu.

** Gnulib
This distribution also uses Gnulib (http://www.gnu.org/software/gnulib)
to share common files, with the files being checked in to svn. If you
want to update from the current gnulib, install gnulib, and then run
  gnulib-tool --import
in the top-level directory.

For the record, the first time invocation was
  gnulib-tool --import --lib=libgnu --source-base=gnulib \
  	      --m4-base=gnulib/m4 --aux-dir=build-aux --libtool \
	      --macro-prefix=gl getopt-gnu progname version-etc
More modules might have been added since. The currently-used gnulib
modules and other gnulib information are recorded in
gnulib/m4/gnulib-cache.m4. Given a source checkout of gnulib, you can
update the files with gnulib-tool --import.

** How to build
After getting the sources from svn, with 

  svn checkout http://liblouis.googlecode.com/svn/trunk/ liblouis

and installing the tools above, change to the liblouis directory and
and bootstrap the project with the following command

  ./autogen.sh

to do a fresh build. Then run configure as usual:

  ./configure

You have the choice to compile liblouis for either 16- or 32-bit
Unicode. By default it is compiled for the former. To get 32-bit
Unicode run configure with --enable-ucs4 .

After running configure run "make" and then "make install". You must
have root privileges for the installation step.

** How to debug
Starting the programs under the tools directory within gdb is a little
tricky as they are linked with libtool. See the info page of libtool
for more information. To start lou_checktable for table wiskunde.ctb
for example you'd have to issue the following commands:

  $ libtool --mode=execute gdb ./tools/lou_checktable
  (gdb) run tables/wiskunde.ctb

** How to build for win32
Use the mingw win32 cross compiler as follows:

  ./configure --build i686-pc-linux-gnu --host i586-mingw32msvc
  make

At the moment you need to tweak the source some to get it to work.
Delete the lines AC_FUNC_MALLOC and AC_FUNC_REALLOC from configure.ac

* Release Procedure
These steps describe what a maintainer does to make a release; they
are not needed for ordinary patch submission.

** Set the version number
Update the version number in NEWS (with version, date, and release
type), ChangeLog and configure.ac.

** Commit and tag
Commit the changes and tag this version

  svn cp https://liblouis.googlecode.com/svn/trunk \
     https://liblouis.googlecode.com/svn/tags/liblouis_1_3_8

If you know the exact version number that needs to be tagged use

  svn cp https://liblouis.googlecode.com/svn/trunk \
     https://liblouis.googlecode.com/svn/tags/liblouis_1_3_8 -r 109

** Make the release
Check out a clean copy in a different directory, like /tmp. Run
autogen.sh and configure with no special prefixes. Run make distcheck.
This will make sure that all needed files are present, and do a
general sanity check. Run make dist. This will produce a tarball.

  ./autogen.sh && ./configure && make && make distcheck && make dist

** Upload
Upload tarball to Google project page, tag as "featured". This will
put the link on the main project page. Remove "featured" tag from
previous tarball release. 

** Online documentation
The online documentation is hosted out of subversion of the Google
code site. To check it out

   svn co https://liblouis.googlecode.com/svn/documentation \
     liblouis-online-documentation

then move the latest built documentation into this directory and check
it in

   cd liblouis-online-documentation
   cp ../liblouis/doc/liblouis.html .
   svn ci liblouis.html -m "Update online documentation"

** Announce
Send an announcement to the liblouis list
liblouis-liblouisxml@freelists.org. See ANNOUNCEMENT for an example.

** Other web updates
Update the Google project page. Add the current NEWS to the front
page.

Also update the page on freshmeat (http://freshmeat.net/projects/liblouis/).