5.1 General installation and configuration

The package uses a automake/autoconf/libtool build system. Building should therefore be simple:

% ./configure
% make
% make install

By default, both a static and a dynamic library are built. If there is some reason why building the dynamic library fails on your platform, configure using --disable-shared and you'll build a static library only.

It's a good idea to run (cd test;make) as well. See Section 2.5.1.

To install, just copy the executable dvi2bitmap wherever you want it to live.

You can customise the program using flags to the ./configure command:

--with-kpathsea and --without-kpathsea

If you have the kpathsea library (see Section 2.5.1) but don't, for some reason, want to use it, then give the configure option --without-kpathsea. By default, the configuration enables use of the library if it is installed (that is, if the kpathsea include files and library are somewhere the compiler will find them. If kpathsea is disabled (by default or by request), then fonts will not be generated by default.

If you have the kpathsea library, but it is not in the standard place, then you can provide an argument to the --with-kpathsea option giving the name of a directory below which are directories include and lib, containing the required kpathsea include files and library. If you don't have the kpathsea library available, see below (Section 5.1.1) for notes on obtaining it.

--disable-texmfcnf

The kpathsea library finds its configuration files in two ways, either automatically if it is installed in the same directory as the rest of the TeXware, or using the TEXMFCNF environment variable. The dvi2bitmap program sets the latter variable internally, unless it finds it already set. If this will be inconvenient, you can suppress this behaviour by providing the flag --disable-texmfcnf, or equivalently --enable-texmfcnf=no.

--enable-fontgen

The program can attempt to generate fonts, and will do so using the MetaFont mode ibmvga, which has a resolution of 110 dots-per-inch.

You can give an argument to this command, which specifies a command-line which will build and install a required font, and return its path on standard output. This uses the font-string template described in Section 2.5.4. You could duplicate the default (the mktexpk script if present) with the option

--enable-fontgen='<path>mktexpk --dpi %d --bdpi %b --mag %m --mfmode %M %f'

The default for this option is `on' -- the program will attempt to generate fonts. Do note, however, that if the kpathsea library is not enabled, then the program will not be able to find the fonts it generates, unless you configure it correctly using either -fp or DVI2BITMAP_PK_PATH (see Section 2.5.1).

If you wish to disable this automatic font generation, give the option --disable-fontgen. Note that this does not completely disable font generation -- it merely sets the default for font generation to `off', and it can be switched back on again using the option -fG.

If you wish to change the default mode, you can do so using the option item ` --with-fontgen-mode=mode,res'.

--with-fontgen-mode=mode,res

If you wish to change the default parameters for font-generation, you can set both the Metafont mode and resolution using this option. For example, the option --fontgen-mode=pcprevw,118 will make pcprevw, which has a resolution of 118 dpi, the default MetaFont mode. Note that the resolution you specify must match the mode: see file modes.mf for a list of modes and resolutions (use kpsewhich mf modes.mf to find this). You can change the resolution and mode on the fly using the -fm and -r options to the compiled program (Section 2.1).

--with-fontfinder

This specifies a command to run to find fonts. It is preferable to use the kpathsea library if possible, but if this is difficult, then you can specify a script to run to find fonts. This uses the font-string template described in Section 2.5.4. To use the standard kpsewhich command, for example, you could give the option

--with-fontfinder='/usr/local/teTeX/bin/kpsewhich pk %f.%dpk'

--enable-mktexpk and --enable-maketexpk

In the default configuration, the program will generate missing fonts using one of the standard scripts present in most TeX distributions. The configuration process looks first for mktexpk then MakeTeXPK, and uses whichever it finds first. If you have both scripts but wish to use MakeTeXPK for some reason, you will have to give the option --disable-mktexpk; if you wish to disable both, you will have to give --disable-maketexpk as well. Both options take an optional argument giving the path to an alternative script with the same calling interface.

--with-png (default: enabled)

If you give this option, and if the PNG library is installed (needs a version after 0.96), then the program will be compiled with support for PNG bitmaps as an output format. You can obtain the PNG library from the PNG home page. You can disable the use of PNG with the option --without-png.

--enable-gif (default: disabled)

The program generates only XBM bitmaps by default. If you want it to be able to generate GIFs, then give the configure option --enable-gif. The GIF format is the copyright of CompuServe. As far as I understand it, one does not need a licence from CompuServe if one is distributing non-commercial, not-for-profit software, such as this. You probably shouldn't enable GIF support when you build this program unless you're in that category as well. But don't listen to me: there's a much fuller account of the whole sorry business in the Graphics File Formats FAQ (HTML).

--enable-fake-progname

This option enables a workaround which allows dvi2bitmap to have the expected behaviour when (a) you do not install dvi2bitmap along with the other dvi-ware, and (b) your texmf.cnf file has VARTEXFONTS (or a similar variable) depending on one of the SELFAUTO... variables (such a texmf.cnf file is probably broken, but that may not be your problem, or within your power to fix). This option makes dvi2bitmap claim to be a different DVI-reading program which is installed in the standard place. See Section 2.5.2 for discussion. The configuration script uses the location of the xdvi program by default, but you can override this by giving the full path to an alternative as an argument to this option (that is, --enable-fake-progname=/path/to/dviprog).

Since this uses undocumented behaviour of the library (`use the source, Luke!'), you almost certainly shouldn't enable it unless you have to.

--with-path-seps

The default configuration is for Unix, and uses the Unix defaults for filesystem path and search path separators. If you are building it on some other architecture, you can alter the defaults by giving a two-character argument to this option, giving the two separators in order. For example, the arguments appropriate for DOS would be

--with-path-seps='\;'

The ./configure command without any options is equivalent to ./configure --with-kpathsea --with-png --enable-mktexpk (meaning that kpathsea and PNG output will be enabled if library support for them is found).

The program builds successfully on (at least):

Platform	Version	Compiler
powerpc-apple-darwin6.6 (MacOS X, 10.2.6)	0.11b1	g++ 3.1 20020420 (prerelease)
sun-sparc-solaris2.9	0.11b1	CC: Sun WorkShop 6 update 2 C++ 5.3 2001/05/15
alphaev67-dec-osf5.1	0.11b1	Compaq C++ V6.5-014
i686-pc-linux-gnu (RedHat 7.3)	0.11b1	g++ 2.96
i686-pc-linux-gnu (RedHat 7.3)	0.10	gcc 2.96
i686-pc-linux-gnu (RedHat 6.2)	0.10b1	egcs-2.91.66
powerpc-apple-darwin6.4 (MacOSX 10.2)	0.10	g++ 3.1 20020420 (prerelease)
sparc-sun-solaris2.8	0.10b1	egcs-2.91.66
alphaev56-dec-osf5.0	0.10b1	egcs-2.91.66
i686-pc-linux-gnu (RedHat 6.2)	0.9-7p1	egcs-2.91.66
powerpc-unknown-linux-gnu (Mac mklinux DR-0.3?)	0.9	egcs-2.90.25 980302 (egcs-1.0.2 prerelease)
sparc-sun-solaris2.7	0.9	egcs-2.91.66
sparc-sun-solaris2.7	0.9	gcc 2.8.1
sparc-sun-solaris2.7	0.9-6	WorkShop Compilers 5.0 98/12/15 C++ 5.0
alpha-dec-osf4.0f	0.9-6	Compaq C++ V6.2-024 for Digital UNIX V4.0F
i386-pc-solaris2.6	0.9-7p1	gcc v2.8.1/libstdc++ v2.8.1.1

It should be written in standards-conforming C++, so if it doesn't build then (1) it's not as conformant as I think it is (in which case please tell me), (2) your compiler is not as conformant as you think it is (in which case please don't tell me), or (3) you need to invoke some magic to get the compiler to be conformant (in which case tell me, if there's something I can do in the autoconfigure script).

You can override the C++ compiler the configure script will choose by setting the environment variable CXX, either via

% CXX=cxx ./configure

% env CXX=cxx ./configure

Run regression tests with (cd test;make) in the build directory. This includes a separate whole-program test which additionally gives advice about setting environment variables. You can run this script separately with the command (cd test;make pathtest)

Regression test 6 currently fails to link when using Compaq cxx, for some arcane C++ reason I have yet to diagnose. The whole-script test mentioned above works, though.

• 1. Obtaining the kpathsea library