xref: /libtiff-4.0.7/html/build.html (revision 0ef31e1f)

<HTML>
<HEAD>
<TITLE>
Building the TIFF Software Distribution
</TITLE>
</HEAD>

<H1>
<IMG SRC=images/cramps.gif WIDTH=159 HEIGHT=203 ALIGN=left BORDER=1 HSPACE=6>
Building the Software Distribution
</H1>

<UL>
<LI><A HREF=#UNIX>Building on a UNIX system</A>.
<LI><A HREf=#MacMPW>Building on a Macintosh system with MPW</A>.
<LI><A HREf=#MacCW>Building on a Macintosh system with CodeWarrior</A>.
<LI><A HREF=#PC>Building on an MS-DOS or Windows system</A>.
<LI><A HREF=#DJGPP>Building on MS-DOS with the DJGPP v2 compiler</A>.
<LI><A HREF=#VMS>Building on a VMS system</A>.
<LI><A HREF=#Acorn>Building on an Acorn RISC OS system</A>.
<LI><A HREF=#Other>Building the Software on Other Systems</A>
</UL>

<BR CLEAR=left>

This chapter contains step-by-step instructions on how to configure
and build the TIFF software distribution.
The software is most easily built on a UNIX system, but with a little
bit of work it can easily be built and used on other non-UNIX platforms.

<A NAME=UNIX><HR><H2>Building on a UNIX System</H2></A>

To build the software on a UNIX system
you need to first run the configure shell script
that is located in the top level of the source directory.
This script probes the target system for necessary tools and functions
and constructs a build environment in which the software may be
compiled.
Once configuration is done, you simply run <TT>make</TT>
 to build the software
and then <TT>make install</TT> to do the installation; for example:

<UL><PRE>
hyla% <B>cd tiff-v3.4beta099</B>
hyla% <B>./configure</B>
    <I>...lots of messages...</I>
hyla% <B>make</B>
    <I>...lots of messages...</I>
hyla# <B>make install</B>
</PRE></UL>

In general, the software is designed such that the following should
be ``<I>make-able</I>'' in each directory:

<UL><PRE>
make [all]	build stuff
make install	build&install stuff
make clean	remove .o files and cruft, but not executables
make clobber	remove everything that can be recreated
make distclean	remove <EM>absolutely everything</EM> that can be recreated
</PRE></UL>

Note that after running "<TT>make clobber</TT>" or
"<TT>make distclean</TT>" the <TT>configure</TT> script must
be run again to create the Makefiles and other make-related files.

<A NAME="BuildTrees"><P><HR WIDTH=65% ALIGN=right><H3>Build Trees</H3></A>

There are two schemes for configuring and building the software.
If you intend to build the software for only one target system, you
can configure the software so that it is built in the same directories
as the source code.

<UL><PRE>
hyla% <B>cd tiff-v3.4beta099</B>
hyla% <B>ls</B>
COPYRIGHT       VERSION         config.sub      dist            man
Makefile.in     config.guess    configure       html            port
README          config.site     contrib         libtiff         tools
hyla% <B>./configure</B>
</PRE></UL>

<P>
Otherwise, you can configure a build tree that
is parallel to the source tree hierarchy but which contains only
configured files and files created during the build procedure.

<UL><PRE>
hyla% <B>cd tiff-v3.4beta099</B>
hyla% <B>mkdir obj obj/mycpu</B>
hyla% <B>cd obj/mycpu</B>
hyla% <B>../../configure</B>
</PRE></UL>

This second scheme is useful for:

<UL>
<LI>building multiple targets from a single source tree
<LI>building from a read-only source tree (e.g. if you receive
  the distribution on CD-ROM)
</UL>

<A NAME="ConfigFiles"><P><HR WIDTH=65% ALIGN=right><H3>Configuration Files</H3></A>

The configuration process is critical to the proper compilation,
installation, and operation of the software.
The configure script runs a series of tests to
decide whether or not the target system
supports required functionality and, if it does not, whether it
can emulate or workaround the missing functions.
This procedure is fairly complicated and, due to the nonstandard
nature of most UNIX systems, prone to error.
The first time that you configure the software for use you should
check the output from the configure script and look for anything
that does not make sense for your system.
A sample configure run is shown below together with an explanation
of some of the work that is done.

<P>
A second function of the configure script is to set the default
configuration parameters for the software.
Of particular note are the directories where the software is to be
installed.
By default the software is installed in the <B>/usr/local</B> hierarchy.
To change this behaviour the appropriate parameters can be
specified either:
<UL>
<LI>on the command line to configure,
<LI>in a site-wide configuration file, or
<LI>in a target-specific configuration file.
</UL>
configure reads any site-wide configure file first, and
then any target-specific configuration file.
This permits target-specific definitions to override
site-wide definitions.

<P>
Site-wide configuration files are named
<B>config.site</B> and are automatically searched for first
in any directory specified on the command line to configure
(using the <TT>-site</TT> option), or if that fails, in
the directory in in which the configure script is located.

<P>
Target-specific configuration files are named <B>config.local</B>
and are looked for first in the top-level configuration directory,
or, if that fails, in the directory in which the configure script
is located.

<P>
Configuration files are just shell scripts that define
shell variables that control the configuration process.
For example, the following file might be used on a BSDI system to
configure the software for installation in the <B>/usr/contrib</B> area.

<PRE>
#
# Parameters suitable for BSDI 1.1
#
DIR_BIN="/usr/contrib/bin"		# directory for client apps
DIR_LIB="/usr/contrib/lib"		# directory for libraries
DIR_MAN="/usr/contrib/man"		# directory for manual pages
</PRE>

<P>
For a complete list of the possible configuration parameters look
at the sample <B>config.site</B> file provided in the distribution; the
section below describes some of the more important parameters.

<A NAME="Packages"><P><HR WIDTH=65% ALIGN=right><H3>Configuring Optional Packages/Support</H3></A>

The TIFF software comes with several packages that are installed only
as needed, or only if specifically configured at the time
the configure script is run.  Packages can be configured in a
<B>config.site</B> or <B>config.local</B> file, or by using a
<TT>-with-&lt;PACKAGE&gt;</TT> option when invoking configure;
e.g. <TT>configure -with-AFM</TT>.

<DL>
<DT><I>DSO Support</I>
<DD>The <TT>DSO</TT> support controls whether or not to
configure the software
to build a Dynamic Shared Object for the TIFF library.
Use of DSOs can significantly reduce the disk space needed for
users of the TIFF software.
If DSOs are not used then the code is statically linked into
each application that uses it.
By default this support is configured only if the system appears
to suport DSOs in a way that fits into the normal build scheme
(<TT>auto</TT>).
If DSO support is <EM>explicitly enabled</EM> and there is no
support for using DSOs in the expected way then DSOs are not used.

<P>
<DT><I>JPEG Support</I>
<DD>The <TT>JPEG</TT> package enables support for the handling
of TIFF images with JPEG-encoded data.
Support for JPEG-encoded data requires the Independent JPEG Group (IJG)
<TT>libjpeg</TT> distribution; this software is available at
<A HREF=ftp://ftp.uu.net/graphics/jpeg/>ftp.uu.net:/graphics/jpeg/</A>.
If JPEG support is enabled the <TT>DIRS_LIBINC</TT> and <TT>DIR_JPEGLIB</TT>
parameters should also be set (see below).
By default JPEG support is not configured.

<P>
<DT><I>ZIP Support</I>
<DD>The <TT>ZIP</TT> support enables support for the handling
of TIFF images with deflate-encoded data.
Support for deflate-encoded data requires the freely available
<TT>zlib</TT> distribution written by Jean-loup Gailly and Mark Adler;
this software is available at
<A HREF=ftp://ftp.uu.net/pub/archiving/zip/zlib/>ftp.uu.net:/pub/archiving/zip/zlib/</A>
(or try <A HREF=ftp://quest.jpl.nasa.gov/beta/zlib/>quest.jpl.nasa.gov:/beta/zlib/</A>).
If ZIP support is enabled the <TT>DIRS_LIBINC</TT> and <TT>DIR_GZLIB</TT>
parameters should also be set (see below).
By default this package is not configured.

</DL>

<A NAME="Sample"><P><HR WIDTH=65% ALIGN=right><H3>A Sample Configuration Session</H3></A>

This section shows a sample configuration session and describes
the work done.  The session is shown indented in a <TT>fixed width
font</TT> with user-supplied input in a <TT><B>bold font</B></TT>.
Comments are shown in a normal or <I>italic</I> font.
This session was collected on a 486 machine running BSDI 1.1.

<UL><PRE><TT>
wullbrandt% <B>mkdir tiff</B>
wullbrandt% <B>cd tiff</B>
wullbrandt% <B>ln -s /hosts/oxford/usr/people/sam/tiff src</B>
</TT></PRE></UL>

A build tree separate from the source tree is used here.
In fact, in this case the distribution is accessed from
a read-only NFS-mounted filesystem.

<UL><PRE><TT>
wullbrandt% <B>src/configure</B>
Configuring TIFF Software v3.4beta015.

Reading site-wide parameters from ../tiff-v3.4beta015/config.site.
Reading local parameters from config.local.
Gosh, aren't you lucky to have a i386-unknown-bsdi1.1 system!
</TT></PRE></UL>

Note that configure announces the distribution version and the
deduced target configuration (<TT>i386-unknown-bsdi1.1</TT> here).

<UL><PRE><TT>
Using /usr/local/bin/gcc for a C compiler (set CC to override).
Looks like /usr/local/bin/gcc supports the -g option.
Using " -g" for C compiler options.
</TT></PRE></UL>

configure checked the normal shell search path for potential
ANSI C compilers.  The compiler is selected according to it properly
compiling a small ANSI C test program.  A specific compiler may be requested
by setting the <TT>CC</TT> environment variable to the appropriate
pathname, by supplying the parameter on the command line, e.g.
<TT>-with-CC=gcc</TT>, or by setting <TT>CC</TT> in a configuration
file.

<P>
<IMG SRC="images/info.gif" ALIGN=left HSPACE=10>
<EM>Note that an ANSI C compiler is required to build the software.
If a C compiler requires options to enable ANSI C compilation, they
can be specified with the <TT>ENVOPTS</TT> parameter.</EM>

<P>
Once a compiler is selected configure checks to see
if the compiler accepts a -g option to enable the generation
    of debugging symbols, and
if the compiler includes an ANSI C preprocessor.

<UL><PRE><TT>
Using /usr/ucb/make to configure the software.
</TT></PRE></UL>

Next various system-specific libraries that may or may not be needed
are checked for (none are needed in this case).
If your system requires a library that is not
automatically included it can be specified by setting the
<TT>MACHDEPLIBS</TT> parameter.

<P><I>Creating port.h.</I>
The <B>port.h</B> file is included by all the C code
in the library (but not the tools).
It includes definitions for functions and type
definitions that are missing from system include files, <TT>#defines</TT>
to enable or disable system-specific functionality, and other
odds and ends.

<UL><PRE><TT>
Creating libtiff/port.h with necessary definitions.
... using LSB2MSB bit order for your i386 cpu
... using big-endian byte order for your i386 cpu
... configure use of mmap for memory-mapped files
... O_RDONLY is in &lt;fcntl.h&gt;
... using double for promoted floating point parameters
... enabling use of inline functions
Done creating libtiff/port.h.
</TT></PRE></UL>

This file can take a long time to create so configure
generates the file only when it is needed, either because the
file does not exist or because a different target or compiler
is to be used.
Note that running "<TT>make distclean</TT>" in the top-level directory
of the build tree will remove the <B>port.h</B> file (along
with all the other files generated by configure).

<P><I>Selecting emulated library functions.</I>
Certain library functions used by the tools are not present on all systems
and can be emulated using other system functionality.
configure checks for the presence of such functions and if they are
missing, will configure emulation code from the <B>port</B> directory
to use instead.  Building the TIFF
software on unsupported systems may require
adding to the code to the <B>port</B> directory.

<UL><PRE><TT>
Checking system libraries for functionality to emulate.
Done checking system libraries.
</TT></PRE></UL>

If a routine must be emulated and configure does not automatically
check for it, the routine name can be specified using the <TT>PORTFUNCS</TT>
parameter.  To add emulation support for a new function <TT>foo</TT>,
create a file <B>port/foo.c</B> that contains the emulation code
and then set <TT>PORTFUNCS=foo</TT> in a configuration file or modify
the configure script to automatically check for the missing function.

<UL><PRE><TT>
Checking for Dynamic Shared Object (DSO) support.
Done checking for DSO support.
</TT></PRE></UL>

If the <TT>DSO</TT> package is enabled (<TT>DSO=auto</TT> or
<TT>DSO=yes</TT>), then
configure will verify the system and compiler are capable of
constructing SVR4-style DSO's in the expected way.  Note that
while a system may support DSO's the compiler may not be
capable of generating the required position-independent
code and/or the compiler may not pass the needed options
through to the loader.

<P><I>Selecting utility programs.</I>
configure locates various system utility programs that are
used during installation of the software.

<UL><PRE><TT>
Selecting programs used during installation.
Looks like mv supports the -f option to force a move.
Looks like /bin/ln supports the -s option to create a symbolic link.
Done selecting programs.
</TT></PRE></UL>

<P><I>Selecting default configuration parameters.</I>
The remainder of the work done by configure involves setting up
configuration parameters that control the placement and
setup of files during the installation procedure.

<UL><PRE><TT>
Selecting default TIFF configuration parameters.

Looks like manual pages go in /usr/contrib/man.
Looks like manual pages should be installed with bsd-nroff-gzip-0.gz.

TIFF configuration parameters are:

[ 1] Directory for tools:               /usr/contrib/bin
[ 2] Directory for libraries:           /usr/contrib/lib
[ 3] Directory for include files:       /usr/contrib/include
[ 4] Directory for manual pages:        /usr/contrib/man
[ 5] Manual page installation scheme:   bsd-nroff-gzip-0.gz

Are these ok [yes]?
</TT></PRE></UL>



At this point you can interactively modify any of the
displayed parameters.  Hitting a carriage return or typing
<TT>yes</TT> will accept the current parameters.  Typing one
of the number displayed along the left hand side causes
configure to prompt for a new value of the specified parameter.
Typing anything else causes configure to prompt for a new
value <EM>for each parameter</EM>.
In general hitting carriage return will accept the current
value and typing anything that is unacceptable will cause a
help message to be displayed.
A description of each of the configuration parameters is given below.

<P>
Once acceptable parameters are setup configure will generate
all the files that depend on these parameters.  Note that certain
files may or may not be created based on the configuration of
optional packages and/or the functions supported by target system.

<UL><PRE><TT>
Creating Makefile from ../tiff-v3.4beta015/Makefile.in
Creating libtiff/Makefile from ../tiff-v3.4beta015/libtiff/Makefile.in
Creating man/Makefile from ../tiff-v3.4beta015/man/Makefile.in
Creating tools/Makefile from ../tiff-v3.4beta015/tools/Makefile.in
Creating port/install.sh from ../tiff-v3.4beta015/port/install.sh.in
Done.
</TT></PRE></UL>

<A NAME=DSOSupport><P><HR><H3>Shared Library Support</H3></A>

It is desirable to make the TIFF library be a shared object
on systems that have support for shared libraries.
Unfortunately the rules to use to build a shared library
vary between operating systems and even compilers.
The distributed software includes support for building a shared
version of the library on a number of different systems.
This support is split between rules in the file
<B>libtiff/Makefile.in</B> that construct the shared library
and checks done by the <TT>configure</TT> script to verify that
the expected rules are supported by compilation tools for
the target system.

<P>
To add new support for building a shared library both these files
must be updated.
In the configure script search for the section where the autoconfiguration
setting of the <TT>DSO</TT> parameter is handled and
add a new case for the target system that sets the
<TT>DSOSUF</TT>,
<TT>DSOLD</TT>,
<TT>DSOOPTS</TT>,
and
<TT>LIBCOPTS</TT>
options as appropriate for the system.
<TT>DSOSUF</TT> specifies the filename suffix used for the shared
library (e.g. ``.so'' for Dynamic Shared Objects on most SVR4-based
systems).
<TT>DSOLD</TT> specifies the program to use to build the shared library
from a compiled object file; typically ``${LD}'' though on some systems
it is better to use the C compiler directly so system-dependent options and
libraries are automatically supplied.
<TT>DSOOPTS</TT> are options that must be specified to <TT>DSOLD</TT>
when building the shared library.
<TT>LIBCOPTS</TT> are options to pass to the C compiler when constructing
a relocatable object file to include in a shared library; e.g. ``-K PIC''
on a Sun system.
The <TT>DSO</TT> parameter must also be set to a unique label that identifies
the target system and compilation tools.
This label is used to select
a target in <B>libtiff/Makefile.in</B> to do the actual work in building
the shared library.
Finally, to complete support for the shared library added the appropriate
rules to <B>libtiff/Makefile.in</B> under the target specified in the
<TT>configure</TT> script.




<A NAME="Parameters"><P><HR WIDTH=65% ALIGN=right><H3>Configuration Parameters</H3></A>

This section gives a brief description of the less obvious
configuration parameters.  Consult the distributed <B>config.site</B>
for a <EM>complete list of parameters</EM>.
The list here is sorted alphabetically.

<P>
<TABLE BORDER CELLPADDING=3>

<TR>
<TD VALIGN=top><TT>AROPTS</TT></TD>
<TD>The options passed to ar when creating an archive.
Note that configure will automatically check to see if ar
supports an <TT>s</TT> to create a symbol table instead of
using ranlib.</TD>
</TR>

<TR>
<TD VALIGN=top><TT>DIR_BIN</TT></TD>
<TD>The directory where client applications should be installed; by
default this is <B>/usr/local/bin</B>.</TD>
</TR>

<TR>
<TD VALIGN=top><TT>DIR_GZLIB</TT></TD>
<TD>The pathname of the directory containing the zlib library
(when ZIP or PixarLog compression support is enabled);
e.g. ``<TT>../src/zlib</TT>''.</TD>
</TR>

<TR>
<TD VALIGN=top><TT>DIR_JPEGLIB</TT></TD>
<TD>The pathname of the directory containing the JPEG library
(when JPEG support is enabled); e.g. ``<TT>/usr/local/lib</TT>''.</TD>
</TR>

<TR>
<TD VALIGN=top><TT>DIR_LIB</TT></TD>
<TD>The directory to install libraries and DSO's; by default
this is <B>/usr/local/lib</B>.</TD>
</TR>

<TR>
<TD VALIGN=top><TT>DIR_MAN</TT></TD>
<TD>The top-most directory of the manual area where manual
pages should be installed.</TD>
</TR>

<TR>
<TD VALIGN=top><TT>DIRS_LIBINC</TT></TD>
<TD>A space-separated list of directories in which to search for
include files when building the library and tools.
If JPEG or ZIP support is configured this parameter should include
the directories where the associated include files are located.</TD>
</TR>

<TR>
<TD VALIGN=top><TT>DIST_ALPHA</TT></TD>
<TD>The alpha version number for the distribution; e.g. if this
is version 3.4beta031 then the the major number is 31.</TD>
</TR>

<TR>
<TD VALIGN=top><TT>DIST_MAJOR</TT></TD>
<TD>The major version number for the distribution; e.g. if this
is version 3.4beta031 then the the major number is 3.</TD>
</TR>

<TR>
<TD VALIGN=top><TT>DIST_MINOR</TT></TD>
<TD>The minor version number for the distribution; e.g. if this
is version 3.4beta031 then the the major number is 4.</TD>
</TR>

<TR>
<TD VALIGN=top><TT>DSOSUF</TT></TD>
<TD>When DSO's are built, the filename suffix for a DSO.
If this is set to <TT>"a"</TT> then  statically linked archives are used.</TD>
</TR>

<TR>
<TD VALIGN=top><TT>DSOSUF_VERSION</TT></TD>
<TD>When DSO's are built, a version-specific filename suffix for a DSO.
If this is set to something other than the value of <TT>DSO</TT> then
the file <B>libtiff.<TT>DSOSUF_VERSION</TT></B> will be installed and
a link to it named <B>libtiff.<TT>DSOSUF</TT></B> will automatically
be created.  (Note that this means that rule for building the target
DSO must generate a file named <B>libtiff.<TT>DSOSUF_VERSION</TT></B>.)</TD>
</TR>

<TR>
<TD VALIGN=top><TT>ENVOPTS</TT></TD>
<TD>Options to pass to <TT>CC</TT> to force ANSI C compilation.</TD>
</TR>

<TR>
<TD VALIGN=top><TT>FILLORDER</TT></TD>
<TD>The order of bits in a byte on the server machine;
either LSB2MSB or MSB2LSB.
This is normally selected according to the target system.</TD>
</TR>

<TR>
<TD VALIGN=top><TT>GCOPTS</TT></TD>
<TD>Special options to pass the C compiler.  If this parameter
is set, then configure may append other options to this list.</TD>
</TR>

<TR>
<TD VALIGN=top><TT>INSTALL</TT></TD>
<TD>The pathname of the install program to use.  Note that this program
must emulate the command line interface used by the IRIX install program.</TD>
</TR>

<TR>
<TD VALIGN=top><TT>LIBPORT</TT></TD>
<TD>The pathname of the library that holds code to emulate missing
system functionality.
Normally this parameter is set by configure based on whether or
not emulation code is required for the target.
</TR>

<TR>
<TD VALIGN=top><TT>LLDOPTS</TT>
<TD>Extra command line options passed to <TT>CC</TT>
when linking an executable.
This option is usually set only when DSO support is enabled
(to force the executable to search for the TIFF DSO
in non-standard locations in the filesystem.)</TD>
</TR>

<TR>
<TD VALIGN=top><TT>MACHDEPLIBS</TT></TD>
<TD>Target-dependent libraries that should be used when linking
tools.
Note that if this parameter is specified configure will append to
the list of libraries.</TD>
</TR>

<TR>
<TD VALIGN=top><TT>MANSCHEME</TT></TD>
<TD>The scheme to use when preparing and installing manual pages.
Schemes are constructed according to:
<UL>
&lt;<I>organization</I>&gt;-&lt;<I>formatting</I>&gt;-&lt;<I>compression</I>&gt;[-&lt;<I>suffix</I>&gt;]
</UL>
where:
&lt;<I>organization</I>&gt; is either <TT>bsd</TT>
for BSD-style section organization (e.g.  file formats in
section 5) or <TT>sysv</TT> for System V-style
organization (e.g. file formats in section 4).
&lt;<I>formatting</I>&gt; is either <TT>nroff</TT> to force
installation of formatted materials (using nroff) or
<TT>source</TT> to get the nroff source installed.
&lt;<I>compression</I>&gt; is either the name of a program
to compress the manual pages (gipz, compress, pack) or
<TT>cat</TT> for uncompressed data.
&lt;<I>suffix</I>&gt; is either the file suffix to convert
installed pages to (e.g. 0.gz for gzip-compressed pages under BSD)
or <TT>strip</TT> to force the normal ".4f" suffix to be converted to ".4"
(or ".5" if using the BSD organization).  If no -&lt;suffix&gt;
is specified then filenames are not converted when they are installed.</TD>
</TR>

<TR>
<TD VALIGN=top><TT>PORTFUNCS</TT></TD>
<TD>A list of non-standard functions that should be emulated.
Normally this list is constructed by configure based on checks it does.
If this parameter is set, configure will append to the specified list.</TD>
</TR>

<TR>
<TD VALIGN=top><TT>SETMAKE</TT></TD>
<TD>If make does not automatically set <TT>$MAKE</TT> to
the name of the make program to invoke for subdirectories, then
configure will create an explicit definition.
If this parameter is set, then it will be used instead.
by default <TT>bin</TT> is used.</TD>
</TR>

</TABLE>


<A NAME=PC><P><HR><H2>Building the Software under MS/DOS or Windows</H2></A>

<I>
There is a Makefile for Microsoft C.
There is OS support for MS-DOS and for Windows.
Someone needs to fill this in, but no DOS-weenies seem to
give a damn so this section is blank for now ....
</I>



<A NAME=DJGPP><P><HR><H2>Building the Software under MS/DOS with the DJGPP v2 compiler</H2></A>

[<I>From the file <B>contrib/dosdjgpp/README</B>.</I>]

<P>
The directory <B>contrib/dosdjgpp</B>
contains the files necessary to build the library and tools
with the DJGPP v2 compiler under MSDOS.

<P>
All you have to do is copy the files in the directory
into the respective directories and run
make. If you want, you can use the <B>conf.bat</B> script
to do that for you, make sure that
the file is stored with MSDOS text EOL-convention (CR/LF), otherwise the
<B>command.com</B> will not do anything.

<P>
Note that you probably will not be able to build the library with the v1.x
versions of djgpp, due to two problems. First, the top makefile calls a
sub-make for each directory and you are likely to run out of memory, since
each recursive invocation of a djgpp v1.x program requires about 130k, to
avoid that, you can enter the directories manually and call make (well, there
are only two dirs). The 2nd problem is that djgpp 1.x doesn't call the
coff2exe (stubify) program when creating an executable. This means that all
programs compiled are not converted to exe and consequently are not available
for calling directly. For the tools directory, you can just call coff2exe for
each program after make finishes, but in the libtiff directory, a few programs
are created during the make process that have to be called for make to
continue (e.g. mkg3states). Make will probably report an error at each
such stage. To fix that, either add a coff2exe call before each program is
called or call coff2exe manually and rerun make (there 2-3 such programs).


<A NAME=MacMPW><P><HR><H2>Building the Software on a Macintosh with MPW</H2></A>

The directory <B>contrib/mac-mpw</B> contains support for
compiling the library and tools under the MPW Shell on a
Macintosh system.
This support was contributed by Niles Ritter
(<A HREF=mailto:[email protected]>[email protected]</A>).

<P>
[<I>From the file <B>contrib/mac-mpw/README</B>.</I>]

<P>
This directory contains all of the utilities and makefile source
to build the LIBTIFF library and tools from the MPW Shell. The
file BUILD.mpw in this directory is an executable script
which uses all of these files to create the MPW makefiles and
run them.

<P>
The <file>.make files are not MPW makefiles as such,
but are when run through the "mactrans" program, which turns
the ascii "%nn" metacharacters into the standard weird MPW
make characters.

<P>
This translation trick is necessary to protect the files when
they are put into unix tarfiles, which tend to mangle the
special characters.



<A NAME=MacCW><P><HR><H2>Building the Software on a Macintosh with CodeWarrior</H2></A>

The directory <B>contrib/mac-cw</B> contains support for
compiling the library and tools with MetroWerks CodeWarrior 6.1
on a Macintosh system.
This support was contributed by Niles Ritter
(<A HREF=mailto:[email protected]>[email protected]</A>).

<P>
[<I>From the file <B>contrib/mac-cw/README</B>.</I>]

In this directory you will find a Makefile.script Applescript
file, which should be run in order to build the libtiff code
using MetroWerks CodeWarrior.

Refer to the "metrowerks.note" instructions on building the
library for 68k and PowerPC native code, as well as building
some of the libtiff tools, which are rather unix-like, but
at least give an example of how to link everything together.



<A NAME=VMS><P><HR><H2>Building the Software on a VMS System</H2></A>

The VMS port was done by Karsten Spang
(<A HREF="mailto:[email protected]">[email protected]</a>), who also
"sort of" maintains it.
The VMS specific files are not in the main directories. Instead they
are placed under <TT>[.CONTRIB.VMS...]</TT> in the distribution tree.

Installation:

It is assumed that you have unpacked the tar file into a VMS directory
tree, in this text called DISK:[TIFF].

<OL>
<LI>Move the VMS specific files to their proper directories.
<PRE>
$ SET DEFAULT DISK:[TIFF.CONTRIB.VMS]
$ RENAME [.LIBTIFF]*.* [-.-.LIBTIFF]
$ RENAME [.TOOLS]*.* [-.-.TOOLS]
</PRE>
<LI>Compile the library.
<PRE>
$ SET DEFAULT DISK:[TIFF.LIBTIFF]
$ @MAKEVMS
</PRE>
<LI>Compile the tools.
<PRE>
$ SET DEFAULT DISK:[TIFF.TOOLS]
$ @MAKEVMS
</PRE>
<LI>Define the programs.
<PRE>
$ DEFINE TIFFSHR DISK:[TIFF.LIBTIFF]TIFFSHR
$ FAX2PS    :==$DISK:[TIFF.TOOLS]FAX2PS
$ FAX2TIFF  :==$DISK:[TIFF.TOOLS]FAX2TIFF
$ GIF2TIFF  :==$DISK:[TIFF.TOOLS]GIF2TIFF
$ PAL2RGB   :==$DISK:[TIFF.TOOLS]PAL2RGB
$ PPM2TIFF  :==$DISK:[TIFF.TOOLS]PPM2TIFF
$ RAS2TIFF  :==$DISK:[TIFF.TOOLS]RAS2TIFF
$ RGB2YCBCR :==$DISK:[TIFF.TOOLS]RGB2YCBCR
$ THUMBNAIL :==$DISK:[TIFF.TOOLS]THUMBNAIL
$ TIFF2BW   :==$DISK:[TIFF.TOOLS]TIFF2BW
$ TIFF2PS   :==$DISK:[TIFF.TOOLS]TIFF2PS
$ TIFFCMP   :==$DISK:[TIFF.TOOLS]TIFFCMP
$ TIFFCP    :==$DISK:[TIFF.TOOLS]TIFFCP
$ TIFFDITHER:==$DISK:[TIFF.TOOLS]TIFFDITHER
$ TIFFDUMP  :==$DISK:[TIFF.TOOLS]TIFFDUMP
$ TIFFINFO  :==$DISK:[TIFF.TOOLS]TIFFINFO
$ TIFFMEDIAN:==$DISK:[TIFF.TOOLS]TIFFMEDIAN
$ TIFFSPLIT :==$DISK:[TIFF.TOOLS]TIFFSPLIT
$ YCBCR     :==$DISK:[TIFF.TOOLS]YCBCR
</PRE>
</OL>

You will want to add these lines  to your <TT>LOGIN.COM</TT>
file, after changing
the name of the directory that you have used on your machine.

<P>
This release has been tested on OpenVMS/VAX 5.5-2, using VAX C 3.2.
A previous release was tested under OpenVMS/AXP ?.? using DEC C ?.?, it is
believed that this release as well works on AXP.
The code contains some GNU C specific things. This does *not* imply,
however, that the VAX/GCC configuration has been tested, *it has not*.

<P>
The command procedures (<TT>MAKEVMS.COM</TT>) for building the
library and tools,
is believed to choose the correct options for the VAX and AXP cases
automatically.

<P>
On the AXP, IEEE floating point is used by default. If you want VAX
floating point, remove the <TT>/FLOAT=IEEE_FLOAT</TT> qualifier, and change
<TT>HAVE_IEEEFP=1</TT> to <TT>HAVE_IEEEFP=0</TT> in the <TT>MAKEVMS.COM</TT>
files in both the <B>libtiff</B> and <B>tools</B> directories.


<H3>Compiling your own program on a VMS system:</H3>

When compiling a source file in which you
<TT>"#include <tiffio.h>"</TT>, use the
following command
<PRE>
    $ CC/INCLUDE=DISK:[TIFF.LIBTIFF]
</PRE>
This  ensures  that the  header  file is  found.
On the AXP, also add <TT>/FLOAT=IEEE_FLOAT</TT>
(if used when building the library).


<H3>Linking your own program to the TIFF library on a VMS system:</H3>

You can link to the library in two ways: Either using the shareable
library, or using the object  library.
On the VAX these possibilities are:

<OL>
<LI>Using the shareable TIFF library.
<PRE>
$ LINK MY_PROGRAM,DISK:[TIFF.LIBTIFF]TIFF/OPTIONS,SYS$INPUT:/OPTIONS
    SYS$SHARE:VAXCRTL/SHAREABLE
</PRE>
<LI>Using the TIFF object library.
<PRE>
$ LINK MY_PROGRAM, -
    DISK:[TIFF.LIBTIFF]TIFF/LIBRARY/INCLUDE=(TIF_FAX3SM,TIF_CODEC), -
    SYS$INPUT:/OPTIONS
    SYS$SHARE:VAXCRTL/SHAREABLE
</PRE>
</OL>

On AXP (and possibly also using DEC C on VAX) the corresponding commands are
<OL>
<LI>Using the shareable TIFF library.
<PRE>
$ LINK MY_PROGRAM,DISK:[TIFF.LIBTIFF]TIFF/OPTIONS
</PRE>
<LI>Using the TIFF object library.
<PRE>
$ LINK MY_PROGRAM,DISK:[TIFF.LIBTIFF]TIFF/LIBRARY
</PRE>
</OL>

Method 1 uses the shortest link time and smallest <TT>.EXE</TT>
files, but it
requires that <TT>TIFFSHR</TT> is defined as above at link time and
<STRONG>at run time</STRONG>.
Using the compilation procedure above, the tools are linked in this way.

<P>
Method 2 gives somewhat longer link time and larger <TT>.EXE</TT>
files, but does
not require <TT>TIFFSHR</TT> to be defined. This method is recommended if you
want to run your program on another machine, and for some reason don't
want to have the library on that machine. If you plan to have more than
one program (including the tools) on the machine, it is recommended that
you copy the library to the other machine and use method 1.



<A NAME=Acorn><P><HR><H2>Building the Software on an Acorn RISC OS system</H2></A>

The directory <B>contrib/acorn</B> contains support for compiling the library
under Acorn C/C++ under Acorn's RISC OS 3.10 or above. Subsequent pathnames
will use the Acorn format: The full-stop or period character is a pathname
delimeter, and the slash character is not interpreted; the reverse position
from Unix. Thus "libtiff/tif_acorn.c" becomes "libtiff.tif_acorn/c".

<P>
This support was contributed by Peter Greenham. (<A HREF=mailto:[email protected]>[email protected]</A>).

<P>
<H3>Installing LibTIFF:</H3>

<P>
LIBTIFF uses several files which have names longer than the normal RISC OS
maximum of ten characters. This complicates matters. Maybe one day Acorn will
address the problem and implement long filenames properly. Until then this
gets messy, especially as I'm trying to do this with obeyfiles and not have
to include binaries in this distribution.

<P>
First of all, ensure you have Truncate configured on (type <TT>*Configure
Truncate On</TT>)

<P>
Although it is, of course, preferable to have long filenames, LIBTIFF can be
installed with short filenames, and it will compile and link without
problems. However, <I>getting</I> it there is more problematic.
<B>contrib.acorn.install</B> is an installation obeyfile which will create a normal
Acorn-style library from the source (ie: with c, h and o folders etc.), but
needs the distribution library to have been unpacked into a location which is
capable of supporting long filenames, even if only temporarily.

<P>
My recommendation, until Acorn address this problem properly, is to use Jason
Tribbeck's <A
HREF=ftp://ftp.demon.co.uk/pub/mirrors/hensa/micros/arch/riscos/c/c020/longfiles.arc>LongFilenames</A>, or any other
working system that gives you long filenames, like a nearby NFS server for
instance.

<P>
If you are using Longfilenames, even if only temporarily to install LIBTIFF,
unpack the TAR into a RAMDisc which has been longfilenamed (ie: <TT>*addlongfs
ram</TT>) and then install from there to the hard disk. Unfortunately
Longfilenames seems a bit unhappy about copying a bunch of long-named files
across the same filing system, but is happy going between systems. You'll
need to create a ramdisk of about 2Mb.

<P>
Now you can run the installation script I've supplied (in contrib.acorn),
which will automate the process of installing LIBTIFF as an Acorn-style
library. The syntax is as follows:

<P><TT>
install &lt;source_dir&gt; &lt;dest_dir&gt;

</TT><P>
Install will then create &lt;dest_dir&gt; and put the library in there. For
example, having used LongFilenames on the RAMDisk and unpacked the library
into there, you can then type:

<P><TT>
Obey RAM::RamDisc0.$.contrib.acorn.install RAM::RamDisc0.$ ADFS::4.$.LIBTIFF
</TT><P>

It doesn't matter if the destination location can cope with long filenames or
not. The filenames will be truncated if necessary (*Configure Truncate On if
you get errors) and all will be well.

<P>
<H3>Compiling LibTIFF:</H3>

<P>
Once the LibTIFF folder has been created and the files put inside, making the
library should be just a matter of running '<B>SetVars</B>' to set the
appropriate system variables, then running '<B>Makefile</B>'.

<P>
<B>OSLib</B>

<P>
<A HREF=ftp://ftp.acorn.co.uk/pub/riscos/releases/oslib/oslib.arc>OSLib</A>
is a comprehensive API for RISC OS machines, written by Jonathan Coxhead of
Acorn Computers (although OSLib is not an official Acorn product). Using the
OSLib SWI veneers produces code which is more compact and more efficient than
code written using _kernel_swi or _swi. The Acorn port of LibTIFF can take
advantage of this if present. Edit the Makefile and go to the Static
dependencies section. The first entry is:

<PRE>
# Static dependencies:
@.o.tif_acorn:   @.c.tif_acorn
	cc $(ccflags) -o @.o.tif_acorn @.c.tif_acorn
</PRE>
<P>
Change the cc line to:
<PRE>
	cc $(ccflags) -DINCLUDE_OSLIB -o @.o.tif_acorn @.c.tif_acorn
</PRE>
<P>
Remember, however, that OSLib is only <I>recommended</I> for efficiency's
sake. It is not required.



<A NAME=Other><P><HR><H2>Building the Software on Other Systems</H2></A>

This section contains information that might be useful
if you are working on a non-UNIX system that is not directly supported.
All library-related files described below are located in the <B>libtiff</B>
directory.

<P>
The library requires two files that are generated <I>on-the-fly</I>.
The file <B>tif_fax3sm.c</B> has the state tables for the
Group 3 and Group 4 decoders.
This file is generated by the <TT>mkg3states</TT> program
on a UNIX system; for example,

<UL><PRE><TT>
cd libtiff
cc -o mkg3states mkg3states.c
rm -f tif_fax3sm.c
./mkg3states -c const tif_fax3sm.c
</TT></PRE></UL>

The <TT>-c</TT> option can be used to control whether or not the
resutling tables are generated with a <TT>const</TT> declaration.
The <TT>-s</TT> option can be used to specify a C storage class
for the table declarations.
The <TT>-b</TT> option can be used to force data values to be
explicitly bracketed with ``{}'' (apparently needed for some
MS-Windows compilers); otherwise the structures are emitted in
as compact a format as possible.
Consult the source code for this program if you have questions.

<P>
The second file required to build the library, <B>version.h</B>,
contains the version
information returned by the <TT>TIFFGetVersion</TT> routine.
This file is built on most systems using the
<TT>mkversion</TT> program and the contents of the
<TT>VERSION</TT> and <TT>tiff.alpha</TT> files; for example,

<UL><PRE>
cd libtiff
cc -o mkversion mkversion.c
rm -f version.h
./mkversion -v ../VERSION -a ../dist/tiff.alpha version.h
</PRE></UL>

<P>
Otherwise, when building the library on a non-UNIX system be sure to
consult the files <B>tiffcomp.h</B> and <B>tiffconf.h</B>.
The former contains system compatibility definitions while the latter
is provided so that the software configuration can be controlled
on systems that do not support the make facility for building
the software.

<P>
Systems without a 32-bit compiler may not be able to handle some
of the codecs in the library; especially the Group 3 and 4 decoder.
If you encounter problems try disabling support for a particular
codec; consult the <A HREF=internals.html#Config>documentation</A>.

<P>
Programs in the tools directory are written to assume an ANSI C
compilation environment.
There may be a few POSIX'isms as well.
The code in the <B>port</B> directory is provided to emulate routines
that may be missing on some systems.
On UNIX systems the <TT>configure</TT> script automatically figures
out which routines are not present on a system and enables the use
of the equivalent emulation routines from the <B>port</B> directory.
It may be necessary to manually do this work on a non-UNIX system.


<A NAME=Testing><P><HR><H2>Checking out the Software</H2></A>

<P>
Assuming you have working versions of <TT>tiffgt</TT> and <TT>tiffsv</TT>,
you can just
use them to view any of the sample images available for testing
(see the <A HREF=images.html>section on obtaining the test images</A>).
Otherwise, you can do a cursory check of the library with
the <TT>tiffcp</TT> and <TT>tiffcmp</TT> programs. For example,

<UL><PRE>
tiffcp -lzw cramps.tif x.tif
tiffcmp cramps.tif x.tif
</PRE></UL>

<P>
(<TT>tiffcmp</TT> should be silent if the files compare correctly).



<A NAME=TOC><P><HR><H2>Table of Contents</H2></A>

The following files makup the core library:

<PRE>
libtiff/tiff.h			TIFF spec definitions
libtiff/tiffcomp.h		non-UNIX OS-compatibility definitions
libtiff/tiffconf.h		non-UNIX configuration definitions
libtiff/tiffio.h		public TIFF library definitions
libtiff/tiffiop.h		private TIFF library definitions
libtiff/t4.h			CCITT Group 3/4 code tables+definitions
libtiff/tif_dir.h		private defs for TIFF directory handling
libtiff/tif_fax3.h		CCITT Group 3/4-related definitions
libtiff/tif_predict.h		private defs for Predictor tag support
libtiff/uvcode.h		LogL/LogLuv codec-specific definitions
libtiff/version.h		version string (generated by Makefile)

libtiff/tif_acorn.c		Acorn-related OS support
libtiff/tif_apple.c		Apple-related OS support
libtiff/tif_atari.c		Atari-related OS support
libtiff/tif_aux.c		auxilary directory-related functions
libtiff/tif_close.c		close an open TIFF file
libtiff/tif_codec.c		configuration table of builtin codecs
libtiff/tif_compress.c		compression scheme support
libtiff/tif_dir.c		directory tag interface code
libtiff/tif_dirinfo.c		directory known tag support code
libtiff/tif_dirread.c		directory reading code
libtiff/tif_dirwrite.c		directory writing code
libtiff/tif_dumpmode.c		"no" compression codec
libtiff/tif_error.c		library error handler
libtiff/tif_fax3.c		CCITT Group 3 and 4 codec
libtiff/tif_fax3sm.c		G3/G4 state tables (generated by mkg3states)
libtiff/tif_flush.c		i/o and directory state flushing
libtiff/tif_getimage.c		TIFFRGBAImage support
libtiff/tif_jpeg.c		JPEG codec (interface to the IJG distribution)
libtiff/tif_luv.c		SGI LogL/LogLuv codec
libtiff/tif_lzw.c		LZW codec
libtiff/tif_msdos.c		MSDOS-related OS support
libtiff/tif_next.c		NeXT 2-bit scheme codec (decoding only)
libtiff/tif_open.c		open and simply query code
libtiff/tif_packbits.c		Packbits codec
libtiff/tif_pixarlog.c		Pixar codec
libtiff/tif_predict.c		Predictor tag support
libtiff/tif_print.c		directory printing support
libtiff/tif_read.c		image data reading support
libtiff/tif_strip.c		some strip-related code
libtiff/tif_swab.c		byte and bit swapping support
libtiff/tif_thunder.c		Thunderscan codec (decoding only)
libtiff/tif_tile.c		some tile-related code
libtiff/tif_unix.c		UNIX-related OS support
libtiff/tif_version.c		library version support
libtiff/tif_vms.c		VMS-related OS support
libtiff/tif_warning.c		library warning handler
libtiff/tif_win3.c		Windows-3.1-related OS support
libtiff/tif_win32.c		Windows-3.2-related OS support
libtiff/tif_write.c		image data writing support
libtiff/tif_zip.c		Deflate codec

libtiff/mkg3states.c		program to generate G3/G4 decoder state tables
libtiff/mkspans.c		program to generate black-white span tables
libtiff/mkversion.c		program to generate libtiff/version.h.
</PRE>

<P>
<HR>

<ADDRESS>
<A HREF="sam.html">Sam Leffler</A> / <A HREF="mailto:[email protected]">[email protected]</A>.
Last updated: $Date: 1999-07-27 21:50:27 $
</ADDRESS>

</BODY>
</HTML>