@c install.texi
@c 
@c Part of the dvipng distribution

@include macros.texi
@ifset rawfile
@chapter Installing dvipng

@end ifset
@c -----------------------
Installing dvipng should be simple: merely @code{./configure},
@code{make}, and @code{make install}. 

@ifclear rawfile
@menu
* Prerequisites::               
* Configure::                   
* Build/install::               
* Installation outside the texmf tree::
* Advice for non-privileged users::  
@end menu
@end ifclear

@node Prerequisites
@section Prerequisites

@itemize @bullet
@item The GD Graphics Draw library, libgd

The drawing library @samp{libgd} is necessary, and is downloadable at
@uref{http://www.boutell.com/gd}, and there are binary packages for
most operating systems from their respective distributors. In any
case, the latest version of the library installs using @samp{autoconf}
so it should not be difficult for you to install it from source, and
then proceed with installing dvipng.

@item The path-searching library kpathsea

Kpathsea is most likely included in your @LaTeX{} installation, but it
may happen that ./configure does not find it; see below. If you do not
have it, download it from @uref{http://www.ctan.org} and compile it.
I have no experience with this, so I cannot help much here.

@item The font-rendering library FreeType 2

While not strictly necessary, FreeType 2 is recommended since dvipng
currently will produce better-quality images with this library
available. It will also enable direct support for PostScript and
TrueType fonts, and subfont support in dvipng. That is, if you want to
render CJK-@LaTeX{} characters, you must have FreeType 2 installed.
With FreeType 2, dvipng will not need to generate bitmapped variants
on disk of the @TeX{} fonts since modern @TeX{} distributions include
PostScript versions of them. Then, you can render images at different
(and unusual) resolutions without cluttering the disk with lots of
bitmapped fonts.

@item The font-rendering library T1lib

An alternative to FreeType 2 is T1lib, but this will enable only
PostScript fonts in dvipng, and will not include subfont support. Also
here, you can render images at different (and unusual) resolutions
without cluttering the disk with lots of bitmapped fonts. If both
FreeType 2 and T1lib are present, FreeType will be internally
preferred by dvipng, but T1lib can be chosen at runtime.

@item libpng and libz

To be able to compress and write PNG files to disk, dvipng (or really
libgd) uses libpng which in turn uses libz. These should be available on
any modern system, if not, download them and install them.

@item The @code{texinfo} package

This is needed for building the documentation. 
@end itemize

@node Configure
@section Configure

The first step is to configure the source code, telling it where
various files will be.  To do so, run

@example
./configure @var{options}
@end example

(Note: if you have fetched dvipng from CVS rather than a regular
release, you will have to first generate @file{./configure} by running
@code{autoconf} 2.53 or later.)

On many machines, you will not need to specify any options, but if
@code{configure} cannot determine something on its own, you'll need to
help it out. For a list of the options type

@example
./configure --help
@end example

On some machines, the libraries will be installed in directories that
are not in the linker's search path. This will generate an error when
running @file{./configure}, indicating that it cannot find libgd or
libkpathsea (most likely). You then need to specify the path to the
respective library's object files. They are typically called e.g.,
@file{libgd.a} or @file{libgd.so}. If they are located in e.g.,
@file{/sw/local/lib}, do

@example
./configure LDFLAGS=-L/sw/local/lib
@end example

If the library is available as a shared object file (@file{.so}), the
runtime linker may also need to be told where to find the library,
then use

@example
./configure LDFLAGS='-L/sw/local/lib -R/sw/local/lib'
@end example

When either of these is necessary, it is likely that the C header
files are also installed in directories that are not in the C
preprocessor's search path. This will also generate an error when
running @file{./configure}, indicating that it cannot find e.g.,
@file{gd.h} or @file{kpathsea.h} (most likely). You then need to
specify the path to the respective library's C header files. If they
are located in e.g., @file{/sw/local/include}, do

@example
./configure CPPFLAGS=-I/sw/local/include
@end example

On my SUN Solaris workstation, I had to combine this into

@example
./configure CPPFLAGS='-I/sw/local/include -I/sw/tex/teTeX/1.0/include'\
    LDFLAGS='-L/sw/local/lib -R/sw/local/lib -L/sw/tex/teTeX/1.0/lib/'
@end example

@noindent
where the backslash denotes a continuation of the line.

@node Build/install
@section Build/install

Once @file{configure} has been run, simply enter

@example
make
@end example

@noindent 
at the prompt to compile the C code, and build the documentation files.
To install the files into the locations chosen earlier, type

@example
make install
@end example

@noindent 
You may need special privileges to install, e.g., if you are installing
into system directories.

@node Installation outside the texmf tree
@section Installation outside the texmf tree

In some cases, a dvipng binary installed outside the texmf tree will
not be able to find virtual fonts, or the PostScript font maps
(normally used by dvips). This may be because @emph{only}
$SELFAUTOLOC, $SELFAUTODIR, and $SELFAUTOPARENT are used in the texmf
tree configuration file @samp{texmf.cnf}. If so, give the switch
@samp{--enable-selfauto-set} to @samp{./configure}. This will make
dvipng adjust these three internally so that kpathsea thinks that
dvipng @emph{is} installed in the texmf tree.

@node Advice for non-privileged users
@section Installation for non-privileged users

Often people without system administration privileges want to install
software for their private use. In that case you need to specify more
options to the @file{configure} script, usually this is done by using
the @samp{--prefix} option to the @file{configure} script, and let it
point to the personal home directory. In that way, resulting binaries
will be installed under the @file{bin} subdirectory of your home
directory, manual pages under @file{man} and so on. That way, it is
reasonably easy to maintain a bunch of additional packages, since the
prefix argument is supported by most @file{configure} scripts.

You'll have to add something like @file{/home/myself/bin} to your
@code{PATH} shell variable, if it isn't there already, and similarly
set the @code{INFOPATH} and @code{MANPATH} variables to be able to
access the documentation.

@ifset rawfile
@section Copying

This program is released under the GNU General Public License, see the
COPYING file in the dvipng distribution or
@url{http://www.gnu.org/licenses/gpl.html}.

Copyright @copyright{} 2002-2006 Jan-@AA{}ke Larsson
@end ifset
