Compiling the Library (Unix)

Directories --- The structure of the distribution is essentially flat. All the source code files, for both the library and the utility programs, are found in the main directory "libdjvu++". A few subdirectories contain accessory material. Directory "@Doc" contains the HTML documentation generated from the source files. Directory "@Samples" contains sample DjVu files for testing purposes. Directory "@Test" contains a few test programs for the library basic features. Directory "@Tools" contains tools that may be useful for building the library or its documentation. The character "@" in the directory names is a probably misguided attempt to emphasize the directory names when you type ls.

Prerequisites --- The DjVu Reference Library should compile and run on any well behaved Unix system, provided that you use a good C++ compiler supporting templates, exceptions and possibly multithreading. Workstation makers usually provide good compilers. You can certainly compile and run the library with these compilers if you find out which options apply to your system and your particular version of the compiler. We find that there are just too many different compilers around. This is why we recommend using gcc or

You can safely proceed to the compilation if you have gcc-2.8.x or any version out what is installed on your system. If you have an earlier version of g++ such as gcc-2.7.23, you must upgrade because it is not going to work. We strongly recommend upgrading directly to The easiest way consists of picking a binary distribution somewhere on the Internet. Linux users may have a look at http://www.gcc.ml.org or http://rufus.w3.org/linux/RPM.

Building your compiler (advanced) --- You should really skip this section if you can avoid reading it. You should only read it if (a) you cannot find a suitable binary distribution of experiment with the multi-threading features of the library.

Building the systems uses GNU Make by default. Many Unix systems provide GNU Make under the name gmake. You must otherwise download the source code at ftp://gatekeeper.dec.com/pub/GNU/make or ftp://prep.ai.mit.edu/pub/gnu, unpack it, read the instructions, compile and install.

You must then download the source distribution of the latest release of

"egcs/gcc/libgcc2.c" which is required by our multi-threading code. You can apply the patch using command patch.

      % cd egcs/gcc
      % patch < $HOME/libdjvu++/@Tools/libgcc2.c.diff
      Patching file libgcc2.c using Plan A...
      Hunk #1 succeeded at 3063.
      Hunk #2 succeeded at 3118.
      done
    
This patch has been tested with the EGCS people will either include the patch in their future releases, or provide a similar capability. If anything suspicious happens during the patching process, we suggest that you restore the original version of "libgcc2.c" which is automatically saved as "libgcc2.c.orig".

You must then configure and compile described at http://egcs.cygnus.com. I could use for instance the following commands on my SGI workstation running Irix-6.4:

      % cd egcs
      % configure --prefix=$HOME/egcs  mips-sgi-irix-5.3
      % gnu-make
      % gnu-make install
    
You are reading correctly: We are pretending that the workstation has Irix-5.3 because we want to create backward compatible binaries. Welcome to the wonderful world of compilers.

Compiling the DjVu Reference Library --- Compiling the DjVu Reference Library is a two step process. You must first invoke the script configure which searches the compiler, selects the compilation options and creates the makefiles.

       % configure --prefix=$HOME/djvu
    

You can specify a particular compiler by setting environment variable CXX before invoking the configuration script. This script also supports the following options:

--prefix=PREFIXDIR
indicates where the binary files will be installed.
--with-debug
enables the debugging options of the compiler.
--with-cxxflag=FLAG
passes a particular option to the compiler.
--without-threads
disables multi-threading (the default).
--with-threads=(cothreads,posix,dce)
enables multithreading and selects a multithreading implementation (see GThreads.h). You must make sure that your C++ compiler is compatible with the chosen thread implementation. The safest option consists of using the patched version of implementation.

You are now ready to compile and install everything by typing:

       % make all
       % make install
    

Using the DjVu Reference Library --- At this point, you have generated a collection of small executables documented in section Utility Programs. This is not very exciting. It is now time to remember that the DjVu Reference Library is a source code library. Almost everything you can use safely is documented in section Library Reference. You may want however to start with section Decoding DjVu Content.

Alphabetic index Hierarchy of classes