HACKING - external/liblouis-github - Git at Google

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

   Copyright (C) 2008, 2009, 2011 ViewPlus Technologies, Inc. and Abilitiessoft, Inc.
   Copyright (C) 2012, 2013 Swiss Library for the Blind, Visually Impaired and Print Disabled


   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
 First you have to build liblouis with debugging info enabled.

   $ ./configure CFLAGS='-g -O0 -Wall -Wextra'
   $ make

 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 find memory leaks
 Valgrind is a tool that can be used to find memory errors. It is
 recommended that you compile liblouis without any optimizations and
 with all warnings enabled before running it through Valgrind:

   $ ./configure CFLAGS='-g -O0 -Wall'
   $ make

 Then use Valgrind to analyze liblouis. For example you can run
 lou_translate trough Valgrind:

   $ libtool --mode=execute valgrind -v --tool=memcheck \
     --leak-check=full --leak-resolution=high --log-file=valgrind.log \
     ./tools/lou_translate en-us-g2.ctb

 Type a few words at the prompt, check translation and terminate
 lou_translate. Now open the file valgrind.log and see if there are any
 memory leaks reported.

 You can also just run lou_checktable for example:

   $ libtool --mode=execute valgrind -v --tool=memcheck \
     --leak-check=full --leak-resolution=high --log-file=valgrind.log \
     ./tools/lou_checktable tables/nl-BE-g1.ctb

 Again open valgrind.log to see if any memory leaks were reported.

 For the full experience run lou_allround under Valgrind:

   $ libtool --mode=execute valgrind -v --tool=memcheck \
     --leak-check=full --show-reachable=yes \
     --leak-resolution=high --track-origins=yes \
     --log-file=valgrind.log ./tools/lou_allround

 ** How to build for win32
 See the README.windows file and the windows subdirectory.

 *** How to cross-compile for win32
 Use the mingw win32 cross compiler as shown below. Use the prefix
 option to install the binaries to a temporary place where you can
 create a zip file.

   ./configure --build i686-pc-linux-gnu --host i586-mingw32msvc --prefix=/tmp/mingw32msvc
   make
   make dist


 * 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.

 Don't forget to update the libtool versioning info in configure.ac,
 i.e. LIBLOUIS_REVISION and possibly LIBLOUIS_CURRENT and LIBLOUIS_AGE.

 ** 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"

 ** 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/).

 ** Announce
 Send an announcement to the liblouis list
 liblouis-liblouisxml@freelists.org. See ANNOUNCEMENT for an example.
	This HACKING file describes the development environment. -- org --

	Copyright (C) 2008, 2009, 2011 ViewPlus Technologies, Inc. and Abilitiessoft, Inc.
	Copyright (C) 2012, 2013 Swiss Library for the Blind, Visually Impaired and Print Disabled


	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
	First you have to build liblouis with debugging info enabled.

	$ ./configure CFLAGS='-g -O0 -Wall -Wextra'
	$ make

	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 find memory leaks
	Valgrind is a tool that can be used to find memory errors. It is
	recommended that you compile liblouis without any optimizations and
	with all warnings enabled before running it through Valgrind:

	$ ./configure CFLAGS='-g -O0 -Wall'
	$ make

	Then use Valgrind to analyze liblouis. For example you can run
	lou_translate trough Valgrind:

	$ libtool --mode=execute valgrind -v --tool=memcheck \
	--leak-check=full --leak-resolution=high --log-file=valgrind.log \
	./tools/lou_translate en-us-g2.ctb

	Type a few words at the prompt, check translation and terminate
	lou_translate. Now open the file valgrind.log and see if there are any
	memory leaks reported.

	You can also just run lou_checktable for example:

	$ libtool --mode=execute valgrind -v --tool=memcheck \
	--leak-check=full --leak-resolution=high --log-file=valgrind.log \
	./tools/lou_checktable tables/nl-BE-g1.ctb

	Again open valgrind.log to see if any memory leaks were reported.

	For the full experience run lou_allround under Valgrind:

	$ libtool --mode=execute valgrind -v --tool=memcheck \
	--leak-check=full --show-reachable=yes \
	--leak-resolution=high --track-origins=yes \
	--log-file=valgrind.log ./tools/lou_allround

	** How to build for win32
	See the README.windows file and the windows subdirectory.

	*** How to cross-compile for win32
	Use the mingw win32 cross compiler as shown below. Use the prefix
	option to install the binaries to a temporary place where you can
	create a zip file.

	./configure --build i686-pc-linux-gnu --host i586-mingw32msvc --prefix=/tmp/mingw32msvc
	make
	make dist


	* 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.

	Don't forget to update the libtool versioning info in configure.ac,
	i.e. LIBLOUIS_REVISION and possibly LIBLOUIS_CURRENT and LIBLOUIS_AGE.

	** 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"

	** 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/).

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