This chapter contains step-by-step instructions on how to configureand build the TIFF software distribution. The software is mosteasily built on a UNIX system, but with a little bit of work it caneasily be built and used on other non-UNIX platforms.
Building on all systems with CMake¶
CMake may be used togenerate build files for most common build systems and IDEs, andsupports all UNIX-like systems as well as Windows. Seethe CMake website for furtherdetails. To build the software on you need to first runcmake to configure the build and generate the system-specificbuild files. This reads the top-level CMakeLists.txt
file,which probes the target system for necessary tools and functions,checks any options you specified to configure the build, and thenoutputs build files configured for your system. If using UnixMakefiles
, once configuration is done, you simplyrun make (or gmake) to build the software andthen make install to do the installation. For other buildsystems, you do the equivalent steps with the tool for that system.For example, on any UNIX system:
$ cd ./tiff-4.0.5$ cmake ...lots of messages...$ make ...lots of messages...$ make test ...lots of messages...# make install
Building is dependent on a make utility and a C(and optionally a C++) compiler, so you will need these tools.
In general, the software is designed such that the followingtargets will always be available:
make [all] build stuffmake test run the test suitemake install build and install stuffmake clean remove object files, executables and cruft
Build Trees¶
There are two schemes for configuring and building the software. Ifyou intend to build the software for only one target system, youcan configure the software so that it is built in the samedirectories as the source code.
$ gzip -dc tiff-4.0.5.tar.gz | tar -xf -$ cd ./tiff-4.0.5$ cmake$ make$ make test$ make install
Otherwise, you can configure a build tree that is parallel tothe source tree hierarchy (or in some completely different place)but which contains only configured files and files created duringthe build procedure.
$ gzip -dc tiff-4.0.5.tar.gz | tar -xf -$ mkdir tiff-4.0.5-build$ cd ./tiff-4.0.5-build$ cmake ../tiff-4.0.5$ make$ make test$ make install
This second scheme is useful for:
building multiple targets from a single source tree
building from a read-only source tree
sharing the source files via a network, but building onmultiple systems
keeping the source tree clean(unlike autoconf, cmake does not providea
distclean
target, so out of source builds arerecommended)
Generators¶
The default generator for UNIX is Unix Makefiles
, and on Windows isNMake Makefiles
or MSBuild
depending upon the setup.Run cmake --help to list all thegenerators available for your platform. For example, to use the Ninjabuild system on UNIX orWindows:
cmake -G Ninjacmake --build .ctest -Vcmake --build . --target install
Note that cmake --build . is a build-system-independent wayof building a target; you can always use the build system directly.
Alternatively, using the MSBuild system on Windows (64-bit Releasebuild with VS2013):
cmake -G "Visual Studio 12 2013 Win64"cmake --build . --config Releasectest -V -C Releasecmake --build . --config Release --target install
With the above configuration, it's also possible to open the generatedsolution file with the Visual Studio IDE as well as building on thecommand-line.
Configuration Options¶
The configuration process is critical to the proper compilation,installation, and operation of thesoftware. The CMakeLists.txt
script runs a series of tests todecide whether or not the target system supports requiredfunctionality and, if it does not, whether it can emulate orworkaround the missing functions. After running cmake, checkthe CMakeCache.txt
file; this contains all the results of thechecks performed and the options set by the user. If cmakefailed to run, check CMakeFiles/CMakeOutput.log
and CMakeFiles/CMakeError.log
; these should record the errorwhich caused the failure.
A second function of the configure script is to set the defaultconfiguration parameters for the software. Of particular note are thedirectories where the software is to be installed. By default thesoftware is installed in the /usr/local
hierarchy. To changethis behaviour the appropriate parameters can be specified on thecommand line. Run cmake --help to get a full list of possibleoptions, and cmake -LH to list all the configurable options forthis software package, or cmake -LAH to show all advancedoptions in addition. Standard installation related options are shownbelow.
Installation options¶ Option
Description
CMAKE_INSTALL_PREFIX
Installation root directory. The options below may be used to overrideindividual installation locations.
CMAKE_INSTALL_BINDIR
user executables [
PREFIX/bin
]
CMAKE_INSTALL_SBINDIR
system admin executables [
PREFIX/sbin
]
CMAKE_INSTALL_LIBEXECDIR
program executables [
PREFIX/libexec
]
CMAKE_INSTALL_SYSCONFDIR
read-only single-machine data [
PREFIX/etc
]
CMAKE_INSTALL_SHAREDSTATEDIR
modifiable architecture-independent data [
PREFIX/com
]
CMAKE_INSTALL_LOCALSTATEDIR
modifiable single-machine data [
PREFIX/var
]
CMAKE_INSTALL_LIBDIR
object code libraries [
PREFIX/lib
]
CMAKE_INSTALL_INCLUDEDIR
C header files [
PREFIX/include
]
CMAKE_INSTALL_OLDINCLUDEDIR
C header files for non-gcc [
/usr/include
]
CMAKE_INSTALL_DATAROOTDIR
read-only architecture-independent data root [
PREFIX/share
]
CMAKE_INSTALL_DATADIR
read-only architecture-independent data [
DATAROOTDIR
]
CMAKE_INSTALL_LOCALEDIR
locale-dependent data [
DATAROOTDIR/locale
]
CMAKE_INSTALL_MANDIR
man documentation [
DATAROOTDIR/man
]
CMAKE_INSTALL_DOCDIR
documentation root [
DATAROOTDIR/doc/tiff
]
Also see theCMake documentationfor additional variableswhich may be set.
Configuring Optional Packages/Support¶
The TIFF software comes with several packages that are installedonly as needed, or only if specifically configured at the time theconfigure script is run. Packages can be configured via thecmake commandline parameters.
JPEG Support¶
jpeg[=ON|OFF]
Enable IJG JPEG library usage (required for JPEG compression, enabled by default)
JPEG_INCLUDE_DIR=DIR
:
Location of IJG JPEG library headers
JPEG_LIBRARY=DIR
Location of IJG JPEG library binary
The JPEG
package enables support for the handling ofTIFF images with JPEG-encoded data. Support for JPEG-encoded datarequires the Independent JPEG Group (IJG) libjpeg
distribution; this software is available at http://www.ijg.org/.The CMake script automatically tries to search for a working IJG JPEGinstallation. If it fails to find library, JPEG support will beautomatically disabled. If you want specify the exact paths tolibrary binary and headers, use above options for that.
ZIP Support¶
The ZIP
support enables support for the handling of TIFFimages with deflate-encoded data (enabled by default ifavailable). Support for deflate-encoded data requires the freelyavailable zlib
distribution written by Jean-loup Gailly andMark Adler; this software is available at http://www.zlib.org/.
Building on a UNIX System with Autoconf¶
To build the software on a UNIX system you need to first run theconfigure shell script that is located in the top level of thesource directory. This script probes the target system fornecessary tools and functions and constructs a build environment inwhich the software may be compiled. Once configuration is done, yousimply run make (or gmake) to build the softwareand then make install to do the installation; for example:
% cd ./tiff-4.0.5% ./configure ...lots of messages...% make ...lots of messages...% make check ...lots of messages...# make install
Supplied Makefiles are dependent on a make utility and a C(and optionally a C++ compiler), so you will need these tools.
In general, the software is designed such that the followingshould be "make-able" in each directory:
Make targets¶ Target
Description
make [all]
build everything
make check
run the test suite
make install
build and install everything
make clean
remove object files, executables and cruft
make distclean
remove everything that can be recreated
Note that after running make distclean theconfigure script must be run again to create the Makefile
and other make-related files.
Build Trees¶
There are two schemes for configuring and building the software. Ifyou intend to build the software for only one target system, youcan configure the software so that it is built in the samedirectories as the source code.
% gzip -dc tiff-4.0.5.tar.gz | tar -xf -% cd ./tiff-4.0.5% ./configure% make% make check% make install
Otherwise, you can configure a build tree that is parallel tothe source tree hierarchy (or in some completely different place)but which contains only configured files and files created duringthe build procedure.
% gzip -dc tiff-4.0.5.tar.gz | tar -xf -% mkdir tiff-4.0.5-build% cd ./tiff-4.0.5-build% ../tiff-4.0.5/configure% make% make check% make install
This second scheme is useful for:
building multiple targets from a single source tree
building from a read-only source tree
sharing the source files via a network, but building onmultiple systems
Configuration Options¶
The configuration process is critical to the proper compilation,installation, and operation of the software. The configure scriptruns a series of tests to decide whether or not the target systemsupports required functionality and, if it does not, whether it canemulate or workaround the missing functions. This procedure isfairly complicated and, due to the nonstandard nature of most UNIXsystems, prone to error. The first time that you configure thesoftware for use you should check the output from the configurescript and look for anything that does not make sense for yoursystem.
A second function of the configure script is to set the defaultconfiguration parameters for the software. Of particular note arethe directories where the software is to be installed. By defaultthe software is installed in the /usr/local
hierarchy. Tochange this behaviour the appropriate parameters can be specifiedon the command line to configure. Run ./configure --help toget a full list of possible options. Standard installation relatedoptions are shown below.
Installation directories:
- --prefix=PREFIX¶
install architecture-independent files in PREFIX [
/usr/local
]
- --exec-prefix=EPREFIX¶
install architecture-dependent files in EPREFIX [
PREFIX
]
By default, make install will install all the files in/usr/local/bin
, /usr/local/lib
etc. You can specifyan installation prefix other than /usr/local
using --prefix,for instance --prefix=$HOME
. For better control, use the options below.
Fine tuning of the installation directories:
- --bindir=DIR¶
user executables [
EPREFIX/bin
]
- --sbindir=DIR¶
system admin executables [
EPREFIX/sbin
]
- --libexecdir=DIR¶
program executables [
EPREFIX/libexec
]
- --sysconfdir=DIR¶
read-only single-machine data [
PREFIX/etc
]
modifiable architecture-independent data [
PREFIX/com
]
- --localstatedir=DIR¶
modifiable single-machine data [
PREFIX/var
]
- --libdir=DIR¶
object code libraries [
EPREFIX/lib
]
- --includedir=DIR¶
C header files [
PREFIX/include
]
- --oldincludedir=DIR¶
C header files for non-gcc [
/usr/include
]
- --datarootdir=DIR¶
read-only architecture-independent data root [
PREFIX/share
]
- --datadir=DIR¶
read-only architecture-independent data [
DATAROOTDIR
]
- --localedir=DIR¶
locale-dependent data [
DATAROOTDIR/locale
]
- --mandir=DIR¶
man documentation [
DATAROOTDIR/man
]
- --docdir=DIR¶
documentation root [
DATAROOTDIR/doc/tiff
]
- --htmldir=DIR¶
html documentation [
DOCDIR
]
Program names:
- --program-prefix=PREFIX¶
prepend PREFIX to installed program names
- --program-suffix=SUFFIX¶
append SUFFIX to installed program names
- --program-transform-name=PROGRAM¶
run sed PROGRAM on installed program names
Configuring Optional Packages/Support¶
The TIFF software comes with several packages that are installedonly as needed, or only if specifically configured at the time theconfigure script is run. Packages can be configured via theconfigure script commandline parameters.
Static/Shared Objects Support¶
Build shared libraries [enabled]
- --enable-static[=PKGS]¶
Build static libraries [enabled]
These options control whether or not to configure the softwareto build a shared and static binaries for the TIFF library. Use ofshared libraries can significantly reduce the disk space needed forusers of the TIFF software. If shared libraries are not used thenthe code is statically linked into each application that uses it.By default both types of binaries are configured.
- --enable-rpath¶
Enable runtime linker paths (
-R
libtool option)Add library directories (see other options below) to the TIFFlibrary run-time linker path.
- --enable-ld-version-script¶
Enable linker version script [yes]
Add shared library symbol versioning on ELF-based systems (e.g.Linux and FreeBSD) which use the GNU linker. This is needed ifseveral major versions of libtiff might be loaded at once into thesame program.
JPEG Support¶
- --disable-jpeg¶
Disable IJG JPEG library usage (required for JPEG compression, enabled by default)
- --with-jpeg-include-dir=DIR¶
Location of IJG JPEG library headers
- --with-jpeg-lib-dir=DIR¶
Location of IJG JPEG library binary)
The JPEG
package enables support for the handling ofTIFF images with JPEG-encoded data. Support for JPEG-encoded datarequires the Independent JPEG Group (IJG) libjpeg
distribution; this software is available athttp://www.ijg.org/. The configurescript automatically tries to search for a working IJG JPEGinstallation. If it fails to find library, JPEG support will beautomatically disabled. If you want specify the exact paths tolibrary binary and headers, use above switches for that.
ZIP Support¶
The ZIP
support enables support for the handling ofTIFF images with deflate-encoded data. Support for deflate-encodeddata requires the freely available zlib
distributionwritten by Jean-loup Gailly and Mark Adler; this software isavailable at http://www.zlib.org/. Support will beenabled automatically if zlib
is found.
Building the Software on Other Systems¶
This section contains information that might be useful if you areworking on a non-UNIX system that is not directly supported. Alllibrary-related files described below are located in thelibtiff
directory.
The library requires two files that are generatedon-the-fly. The file tif_fax3sm.c
has the statetables for the Group 3 and Group 4 decoders. This file is generatedby the mkg3states program on a UNIX system; forexample:
cd libtiffcc -o mkg3states mkg3states.crm -f tif_fax3sm.c./mkg3states -c const tif_fax3sm.c
The -c
option can be used to control whether or not theresulting tables are generated with a const
declaration.The -s
option can be used to specify a C storage class forthe table declarations. The -b
option can be used to forcedata values to be explicitly bracketed with {}
(apparentlyneeded for some MS-Windows compilers); otherwise the structures areemitted in as compact a format as possible. Consult the source codefor this program if you have questions.
The second file required to build the library, version.h
,contains the version information returned by theTIFFGetVersion() routine. This file is built on most systemsusing the mkversion
program and the contents of theVERSION
and tiff.alpha
files; for example,
cd libtiffcc -o mkversion mkversion.crm -f version.h./mkversion -v ../VERSION -a ../dist/tiff.alpha version.h
Otherwise, when building the library on a non-UNIX system besure to consult the files tiffcomp.h
and tiffconf.h
.The former contains system compatibility definitions while thelatter is provided so that the software configuration can becontrolled on systems that do not support the make facility forbuilding the software.
Systems without a 32-bit compiler may not be able to handle someof the codecs in the library; especially the Group 3 and 4 decoder.If you encounter problems try disabling support for a particularcodec; consult the Modifying The TIFF Library.
Programs in the tools directory are written to assume an ANSI Ccompilation environment. There may be a few POSIX'isms as well. Thecode in the port
directory is provided to emulate routinesthat may be missing on some systems. On UNIX systems theconfigure script automatically figures out which routinesare not present on a system and enables the use of the equivalentemulation routines from the port
directory. It may benecessary to manually do this work on a non-UNIX system.
Testing the software¶
Assuming you have working versions of tiffgt, you can now useit to view any of the sample images available for testing, or trytiffinfo to display the file metadata. See theTIFF Test Images section on obtaining the test images. Otherwise, you cando a cursory check of the library with the tiffcp andtiff2cmp programs. For example,
tiffcp -lzw cramps.tif x.tiftiffcmp cramps.tif x.tif
(tiffcmp should be silent if the files comparecorrectly).
LibTIFF source files¶
The following files make up the core library:
Core library source files¶ File
Description
libtiff/tiff.h
TIFF spec 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/tiffvers.h
version string
libtiff/uvcode.h
LogL/LogLuv codec-specific definitions
libtiff/tif_aux.c
auxiliary directory-related functions
libtiff/tif_close.c
close an open TIFF file
libtiff/tif_codec.c
configuration table of builtin codecs
libtiff/tif_color.c
colorspace transforms
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_jbig.c
JBIG codec
libtiff/tif_jpeg.c
JPEG codec (interface to the IJG distribution)
libtiff/tif_jpeg_12.c
12-bit JPEG codec (interface to the IJG distribution)
libtiff/tif_lerc.c
LERC codec
libtiff/tif_luv.c
SGI LogL/LogLuv codec
libtiff/tif_lzma.c
LZMA codec
libtiff/tif_lzw.c
LZW codec
libtiff/tif_next.c
NeXT 2-bit scheme codec (decoding only)
libtiff/tif_ojpeg.c
Old JPEG codec (obsolete, 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_warning.c
library warning handler
libtiff/tif_win32.c
Win32 (Windows)-related OS support
libtiff/tif_write.c
image data writing support
libtiff/tif_zip.c
Deflate codec
libtiff/tif_zstd.c
ZSTD codec
libtiff/mkg3states.c
program to generate G3/G4 decoder state tables
libtiff/mkspans.c
program to generate black-white span tables