% $Id: building.tex 4482 2015-12-07 20:56:23Z mskala $

\chapter{Building FontAnvil}

There are no immediate plans to build binary distribution packages; to use
this code you will have to build it yourself from sources.

\section{From a version control checkout}

FontAnvil is available by anonymous Subversion checkout from
\url{http://svn.osdn.jp/svnroot/tsukurimashou/trunk/}. 
That is the main public repository for FontAnvil source code, and checking
out from there is (at least for the moment, while the code is in flux) the
preferred way to obtain FontAnvil.  The Tsukurimashou repository as a whole
is also mirrored on Github at
\url{https://github.com/mskala/Tsukurimashou.git}.

The version control system does not track some files that would be included
in a distribution tarball but can be built automatically from source files
already under version control.  That includes some parts of the build
system, such as ``configure,'' and several source files that are
automatically generated by Icemap.  \emph{You must build Icemap
before you can build FontAnvil from a version control checkout.} If you have
checked out the entire project, then Icemap can be found in
the \texttt{icemap/} subdirectory, sibling to \texttt{fontanvil/}.

To go this route you will also need to have all the dependencies of Icemap
installed, which include but are not limited to BuDDy (available at
\url{https://sourceforge.net/projects/buddy/}) and PCRE (available at
\url{http://www.pcre.org}).  It should go without saying that these must be
installed in such a way that they \emph{actually work}.  I've had reports of
Arch Linux, in particular, using a nonstandard dynamic linker configuration
such that installing these libraries in the normal way will allow software
using them (such as Icemap) to compile but not run.  Icemap's configure
script will attempt to test for this condition and warn you, but it is not
foolproof.

If you wish to build from a version control checkout, it is probably easiest
to check out and configure the entire Tsukurimashou Project even if you are
primarily interested in FontAnvil.  These instructions assume you have done
that.  It is also assumed you have a complete installation of the standard
GNU tools for building C programs, including the gcc compiler, Autoconf,
Automake, flex, and so on.  Many of these would not be needed for building
from a distribution package.

From the root of the Tsukurimashou checkout, run:
\begin{verbatim}
autoreconf -i
\end{verbatim}

This will create configure scripts and other infrastructure for all packages
in the project.  The \texttt{-i} option tells \texttt{autoreconf} to
automatically create any missing scripts (notably, the one named
\texttt{missing}) that it thinks it needs.

The \texttt{autoreconf} command
is likely to produce many error and warning messages, but it should work
nonetheless if the Autotools versions are suitable.  In particular, note
that when \texttt{autoreconf} runs it may generate repeated ``underquoted
definition'' warnings in relation to files in /usr/share/aclocal or similar. 
\emph{This is the fault of some other package on your system;} it is not
related to FontAnvil and should be harmless to the FontAnvil build.  The
issue is that many packages (IMLIB is one common culprit) install M4 files
globally to provide customized Autoconf tests, and then if those files are
buggy, \texttt{autoreconf} complains whenever it is invoked even if, as
here, the buggy files are not actually being used.

The top-level Tsukurimashou build will automatically take care of building
Icemap and FontAnvil in order to build Tsukurimashou, but assuming you don't
want to build the entire project that way, the next step is to build Icemap:

\begin{verbatim}
cd icemap
./configure
make
\end{verbatim}

The configure script supports \texttt{-{}-help} and most of the usual
options; run that and make appropriate modifications if you wish to
customize the Icemap build.  Do not ignore error messages from configure.

After building Icemap, you can build FontAnvil.  The FontAnvil build will
automatically detect Icemap if it is in the sibling directory created by a
source control checkout; it should not be necessary to install Icemap
elsewhere first.  However, running Icemap requires several files of
character-database information from the Unicode Consortium.  The
\texttt{make download} target will automatically go on the Net using
\texttt{wget} to download them; alternatively, you could read the Makefile
to find which files are needed and install them some other way.  Thus, the
simplest sequence of commands is:

\begin{verbatim}
cd ../fontanvil
./configure
make download
make
\end{verbatim}

At this point FontAnvil should be ready to install with \texttt{make
install} (root privilege may be necessary for that), or to test with
\texttt{make check} (test suite is likely to fail at this level of
development progress).

\section{From a distribution package}

Distribution packages are available from the FontAnvil home page at
\url{http://tsukurimashou.osdn.jp/fontanvil.php}.  Be aware that these
packages will \emph{usually} be out of date; and as a consequence of
Murphy's Law, it is usual for me to discover many critical bugs immediately
after releasing a package.

Building from a package is much the same as building from a version
control checkout, minus the need to run Autotools and Icemap.  Most of the
automatically generated source files are included in the package, so it is
not necessary to have Unicode character set files, Icemap, flex, and so on.
Unpack the tarball and do the usual Autotools build:

\begin{verbatim}
./configure
make
# as root:
make install
\end{verbatim}

\section{Special notes for Windows users}

I cannot realistically offer support for any platforms except Linux and
MacOS, which are the ones for which I have access to testing machines. 
However, FontAnvil's build system is intended to be as portable as
realistically possible, and as of shortly before version 0.4, Jeremy Tan has
reported some success at compiling FontAnvil under Windows.  He has posted
unofficial Windows binaries of a patched 0.3 version at
\url{http://sourceforge.net/projects/fontforgebuilds/files/fontanvil/} and
indicated some willingness to possibly continue updating them.  I will also
fold back into the mainline any changes that are reasonably unintrusive and
help with building on Windows.

Spaces in pathnames, such as ``\texttt{C:\textbackslash{}Program
Files},'' are a serious problem for all Autotools-based build systems. 
FontAnvil \emph{probably will not} be able to build if you locate the source
code in a path with a space in it.  It may have \emph{some}, but not
\emph{complete}, ability to handle tools such as compilers and \LaTeX\ that
may be located in pathnames with spaces.  The \texttt{configure} scripts
will attempt to detect and warn you about such paths, but be aware that some
may cause problems even if \texttt{configure} produces no warnings, and the
build may be able to compensate even if \texttt{configure} does produce
warnings.

All I can recommend is to try it and then attempt to work around
any problems that occur, by moving things that break into paths that do
not include spaces.  I'd also like to emphasize that this is a problem
with \emph{all} Autotools build systems, not only FontAnvil's.  If you want
to make a general practice of building Unix software on Windows, the only
course of action that will really work is to eliminate filename spaces from
your environment.  You cannot expect every software package to work around
Windows's wacky filenames, and you cannot expect FontAnvil to do so.

After FontAnvil is built there should be no problem with using it in an
environment that has spaces in pathnames; this is only an issue for the
build.

\section{Testing}

FontAnvil includes a test suite, available by running \texttt{make check}. 
Most of the tests are inherited from FontForge, and the test suite had been
unmaintained and unused in FontForge for several years before FontAnvil
picked it up.  As a result, it does not have good coverage, and some of the
tests require files that I cannot legally ship.  In some cases I have not
even been able to identify what the missing files are.  If you run the test
suite, you should expect many of the tests to be skipped for missing
necessary files, and some of them to fail; and even if by some chance you
managed to get the entire suite to pass, it is unlikely that that would
really mean the software was working properly.  Having a better test suite
and software that passes it are long-term goals for the project.

After running the tests, you can read the file \texttt{tests/coverage.log}
to see a summary of how many of the PE script built-in functions were
covered by the test suite.  As of this writing, it is about 15\%.

The option \texttt{--enable-valgrind} to \texttt{configure} will make the
test suite run inside Valgrind, if you have that installed.  Valgrind
makes the tests much slower, and (with the latest versions as of this
writing) it causes at least one of them to fail on Mac OS X through no fault
of FontAnvil's, because of Valgrind's lack of support for features used by
the Mac system libraries.  For these reasons it is not the default. 
However, if enabled it will produce a lot more information in the log files
about the many ways in which FontAnvil abuses memory, and that may be useful
in debugging.

The fact that the test suite fails prevents \texttt{make distcheck} from
working.  If you set the environment variable \texttt{distcheck\_hack} to
\texttt{0.4} (or the new version number, if I continue using this hack in
future versions), then the tests I \emph{expect} to fail will be disabled,
so that \texttt{make distcheck} can be tricked into accepting the package
for distribution.  In the long run, this is probably a Bad Thing.

\section{FontAnvil and Tsukurimashou}

FontAnvil's reason for existence is to support Tsukurimashou, and its source
control repository is a subdirectory of the Tsukurimashou source control
repository.  FontAnvil does not require Tsukurimashou to build. 
Tsukurimashou will look for FontAnvil and use it if found, whether installed
on the system or inside a subdirectory of its own build.  The Tsukurimashou
top-level build will also automatically build Icemap and FontAnvil, as
needed, if started on a system without them and you don't override this
behaviour.  Note that this represents a change from earlier version of
Tsukurimashou, which required FontAnvil to be built and installed separately
first.

All bug reports and other tickets for FontAnvil should be filed through
the Tsukurimashou ticket tracker at
\url{http://osdn.jp/projects/tsukurimashou/ticket/}.  Set the
``Component'' field to ``FontAnvil.''

As a courtesy to Github users, Tsukurimashou's entire source control system
(including FontAnvil) is mirrored in my Github account at
\url{https://github.com/mskala}.  But osdn.jp remains the
authoritative public home of the project.  You are welcome to clone the
repository---that is why it's there---but the semi-automated gateway from
Subversion to Git is one-way.  Do not file tickets for FontAnvil on Github.

Do not file tickets for FontAnvil in the FontForge tracker on Github!  They
are completely separate pieces of software with different maintainers and
different goals, notwithstanding the historically shared code and
notwithstanding that the FontForge people have graciously given me developer
status on their project.

\clearpage
