blob: 86dcfb35cb17c8317c2fbc949ae47ed982a8a9b3 [file] [log] [blame]
This HACKING file describes the development environment. -*- org -*-
Copyright (C) 2008, 2009, 2011 ViewPlus Technologies, Inc. and Abilitiessoft, Inc.
Copyright (C) 2012, 2013, 2014 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 is offered as-is,
without any warranty.
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 git at
** Build requirements
This distribution uses Automake, Autoconf, and Libtool. If you are
getting the sources from git (or change, 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
On Mac OS, the programs can be optained with Homebrew (
brew install automake libtool pkg-config texinfo
Note that if you are using Homebrew to install liblouis (see below),
the build dependencies are installed automatically.
** Gnulib
This distribution also uses Gnulib ( 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 git, with
git clone
and installing the tools above, change to the liblouis directory and
and bootstrap the project with the following command
to do a fresh build. Then run configure as usual:
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.
** Install with Homebrew
Homebrew ( is a package manager for Mac OS X that
installs software from source. There is nothing special about the
installation process in the sense that under the hood it happens
exactly as described above, with the only difference that Homebrew
automates it completely.
First, use the ~brew tap~ command to add the repository that includes
the liblouis formula:
brew tap liblouis/liblouis
Now you are ready to install liblouis:
brew install liblouis
** Docker
Docker ( can be useful both for creating a
development environment for liblouis, and for shipping the
Setting up a developer environment can take long and can be
problematic especially for Windows. Thanks to Docker we can set up the
environment for you, we can easily distribute it as an image, which
can be run by anybody and will behave exactly the same for everybody.
Docker images of liblouis are being built automatically each time
something changes in the code (see
In order to use them, first get Docker at Download the latest
liblouis image with:
docker pull liblouis/libouis
Then, enter the development environment by running the image in a
Docker container:
docker run -it liblouis/libouis bash
Local files and directories can be "mounted" inside the container, in
order to make it easier to edit files and to persist changes across
runs. For example, to use local table files:
docker run -it -v $(pwd)/tables:/tmp/liblouis/tables liblouis/liblouis bash
See the Docker documentation for more info.
The same Docker image can be used as a development environment and as
the application itself. For example, to run the lou_translate tool
from inside a Docker container:
docker run -it liblouis/libouis lou_translate en-us-g1.ctb
To rebuild the image yourself, run the following command in the root
directory of the liblouis source:
docker build -t liblouis/liblouis
** How to run tests
Tests are run with
make check
This however doesn't include the harness tests. Running the harness
tests requires Python and nose ( Also,
you need to have compiled with --enable-ucs4. To run all harness
tests, go into the tests/harness directory and run:
make runall
To run a single test:
make <name of harness file>
** 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 analyze performance
Gprof helps you analyze the performance of programs. You have to
compile liblouis as follows:
$ ./configure --disable-shared
$ make clean all CFLAGS='-g -O0 -pg' LDFLAGS='-all-static'
Then translate some stuff with a large table:
$ ./tools/lou_translate tests/tables/large.ctb
Finally look at the call profile:
$ libtool --mode=execute gprof ./tools/lou_translate gmon.out
** How to build for win32
See the file and the windows subdirectory.
*** How to cross-compile for Windows
To 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/liblouis-mingw32msvc
make install
zip -r /tmp/liblouis-mingw32msvc
To compile for win64, use the MinGW-w64 cross-compiler:
./configure --host x86_64-w64-mingw32 --prefix=/tmp/liblouis-w64-mingw32
make install
zip -r /tmp/liblouis-w64-mingw32
*** TODO How to build for Windows using Cygwin
(possibly use a Vagrantfile as demonstration + explain that Cygwin
binaries can not be used outside the Cygwin environment)
*** TODO How to build for Windows using MinGW
(possibly use a Vagrant file as demonstration)
* 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
Don't forget to update the libtool versioning info in,
** Commit and tag
Commit the changes and tag this version
git tag -s v2.6.0 -m "Release 2.6.0"
git push origin v2.6.0
If you know the exact version number that needs to be tagged use
git tag -s v2.6.0 -m "Release 2.6.0" <commit>
git push origin v2.6.0
** Make the release
Check out a clean copy in a different directory, like /tmp. Run 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.
./ && ./configure && make && make distcheck && make dist
** Upload
Add the tarball to the liblouis web site, i.e. add it under
$WEBSITE/downloads and add a link to it in $WEBSITE/downloads/
See below for instructions on how to update the web site.
** Online documentation
The online documentation is part of the liblouis web site. To add it to the
site simply copy doc/liblouis.html to $WEBSITE/documentation/liblouis.html.
Make sure you add the proper YAML front matter. Again see below for
instructions on how to update the web site.
** Web site maintenance
The liblouis web site at is maintained with the help of
github pages ( To edit the site just check
out the repo at You'll
need to know a few things about Jekyll ( and
textile ( the markup that is used to edit
the content. In order to update the site simply edit, commit and push.
For the new release update the project web site. Add a post containing
the current NEWS to the _posts directory.
** Announce
Send an announcement to the liblouis list See ANNOUNCEMENT for an example.