1- WHAT IS DJVU.

================

DjVu (pronounced "déjà vu") a set of compression technologies, a file format,

and a software platform for the delivery over the Web of digital documents,

scanned documents, and high resolution images.

DjVu documents download and display extremely quickly, and look exactly the

same on all platforms. DjVu can be seen as superior alternative to PDF and

Postscript for digital documents, to TIFF (and PDF) for scanned documents, to

JPEG for photographs and pictures, and to GIF for large palettized

images. DjVu is the only Web format that is practical for distributing

high-resolution scanned documents in color. No other format comes close.

Typical DjVu file sizes are as follows: 

- Bitonal scanned documents: 

        5 to 30KB per page at 300dpi, 

        3 to 10 times smaller than PDF or TIFF.

- Color scanned documents: 

           30 to 100KB per page at 300dpi,

           5 to 10 times smaller than JPEG.

- Photos:

        2 times smaller than JPEG, 

        about the same as JPEG-2000. 

- Palettized images: 

        2 times smaller than GIF,

        up to 10 times if there is text.

DjVu is used by hundreds of commercial, governmental, and non-commercial web

sites around the world to distribute scanned documents, digital documents, and

high-resolution photos.

Demos, and general information about DjVu can be found at 

http://www.djvuzone.org, or at http://www.lizardtech.com. 

DjVu was originally developed at AT&T Labs-Research. AT&T sold DjVu to

LizardTech Inc. in March 2000.

2- WHAT IS DJVULIBRE? 

=====================

In an effort to promote DjVu as a Web standard, LizardTech's management was

enlightened enough to release the reference implementation of DjVu under the

GNU GPL in October 2000. DjVuLibre (pronounced like the French "déjà vu

libre"), is an enhanced version of that code maintained by the original

inventors of DjVu. It is compatible with LizardTech's DjVu software v3.5.

This package includes: 

- An up-to-date version of the C++ DjVu Reference Library 

- A full-fledged wavelet-based compressor for pictures. 

- A simple compressor for bitonal (black and white) scanned pages. 

- A compressor for palettized images (a la GIF). 

- A full set of utilities to manipulate and assemble DjVu images and documents. 

- A set of decoders to convert DjVu to a number of other formats. 

The full-fledged DjVu file viewer and browser plugin DjView4

is available as a separate package.

3- BUILDING DJVULIBRE

=====================

3.1- PREREQUISITES

------------------

DjVuLibre-3.5 relies on various components available from the web.  

Most recent Linux distribution already come with these.  

You can also download and compile them if you wish.

Be sure to read the system specific notes 

at the end of this file.

COMPILER --

Development is done with the GCC g++ compiler, which is therefore

recommended for all platforms.  The CLANG compiler has been tried and

seems to work, but its output has not been seriously tested.

LIBJPEG/LIBTIFF --

A small number of DjVu files internally use JPEG encoding instead 

of IW44 wavelet encoding.  These files are processed using either 

version 6a or 6b of the IJG libjpeg library <http://www.ijg.org>.  

Some utility programs are able to read TIFF files. These programs

rely on the LIBTIFF library <http://libtiff.org>.

You can also compile DjVuLibre with neither JPEG nor TIFF support.  

You might never notice the difference.

THREADS --

The DjVu viewer makes heavy use of multiple threads of execution.  

Modern  Unix operating systems come with the standardized Posix threads.  

DjVuLibre-3.5 fully supports detecting and using Posix threads.

3.2 - CONFIGURE

---------------

Chances are that everything will work by simply running 

commands "./configure", "make" and "make install". 

Various options and environment variables affect the execution of the

configuration script.  A complete list can be obtained by typing 

"configure --help".  Also see the INSTALL file for further details.

Here are the most important ones.

* Option "--prefix=PREFIXDIR"

  This option specifies where the DjVuLibre software will be installed.

  The default prefix is /usr/local.  

* Option "--enable-desktopfiles[=(yes|no)]"

  Installs icon and mime type files in the customary xdg directories.

  The default is "yes".

* Option "--with-jpeg=JPEGDIR"

  This option specifies a directory where the JPEG library has been

  compiled. This directory contains both the include files and the 

  library.  Without this option, the configuration script will search 

  the JPEG library in standard places.

  When everything else fails, you can simply define the environment

  variables JPEG_CFLAGS and JPEG_LIBS.

* Option "--with-tiff=TIFFDIR"

  This option specifies a directory where the LIBTIFF library has been

  compiled. This directory contains both the include files and the 

  library.  Without this option, the configuration script will search 

  the LIBTIFF library in standard places.

  When everything else fails, you can simply define the environment

  variables TIFF_CFLAGS and TIFF_LIBS.

Always check the output of the configuration script for warnings and errors.

In particular, the configuration script might disable the compilation of

djview if it cannot locate the required libraries and utilities.  The warning

messages are the only way to know.

3.3 - MAKE

----------

You can then perform the compilation by typing 

        $ make

The compilation can last a few minutes.  Again check the output for warnings

and errors.  Finally a brief message lets you know that the compilation was

successful.  You can then proceed with the installation.

3.4 - INSTALL

------------

Typing:

        $ make install

or if necessary:

        $ sudo make install

should:

- install the executable programs into "${prefix}/bin/".

- possibly install the shared library into "${prefix}/lib/".

- install the man pages under "${prefix}/man or ${prefix}/share/man/".

- install various ancillary files under "${prefix}/share/djvu/".

- install "${prefix}/share/pkgconfig.pc".

- optionally install the icon and mime type information files

Where ${prefix} refers to the directory specified by the prefix option

of the configuration script, which defaults to "/usr/local", and the

paths above can be fine-tuned using appropriate arguments to

./configure and make.

4 - BUILDING FOR MAC OS X

=========================

(note: these instructions are slightly outdated.)

The Mac OS X version of djvulibre can be built in one of two ways:

- the Unix way

- the Xcode way

These instructions are to help setup and build djvulibre for a

multi-architecture binary (ppc, i386).  Your milage with the following

configure options (note: libjpeg.a and libtiff.a are installed

universal on the machine this was tested with.)

We recommend that you first install macports with the 

libraries zlib, libpng, jpeg and tiff with option +universal.

The commands to install these libraries are

  $ sudo port install zlib +universal

  $ sudo port install libpng +universal

  $ sudo port install jpeg +universal

  $ sudo port install tiff +universal

Then you can run configure

./configure \

   --enable-static=yes \

   --disable-desktopfiles \

   --with-extra-includes=/usr/include \

   --with-extra-libraries=/usr/lib \

   CFLAGS="-arch ppc -arch i386" \

   CXXFLAGS="-arch ppc -arch i386" \

   LDFLAGS="-arch ppc -arch i386"

The --with-extra-include and --with-extra-libraries are here

to favor system libraries (in /usr) over those that come with macports.

Then you can compile with 

$ make

Running "make install" will install djvulibre in directory /usr/local.

Note that the produced libraries will depend on the macports jpeg and tiff

libraries.  You can change that using the command "install_name_tool"

and other macosx tricks...

Alternatively you can just open the macosx/DjVuLibre/DjVuLibre.xcodeproj 

and build everything using Xcode. This can be painful if you do not have

the same version of Xcode as the one we used to generate that file.

In Leon's opinion, this is hell.  Jeff agrees, those dyld dependancies 

trap us forever in the eighth circle.

Note that the macosx directory contains a few useful tools

that are not compiled using the main makefile:

The djvu.mdimporter program is a spotlight importer for djvu metadata.

The djvu.qlgenerator program generates quicklook data (leopard only).

5 - BUILDING FOR WINDOWS

========================

5.1- Using Microsoft Visual C++ 2012

------------------------------------

   See the directory win32.

   Populate the zlib, jpeg and tiff directories with

   the open source code suggested in the README files.

   Check win32/djvulibre/dirs.props to see

   how to name the directories.

   Then open win32/djvulibre/djvulibre.sln and compile.

   Next step would then be to follow the instructions

   in the djview package to create a djview project and

   add it to this solution. Finally you can use the script

   djvulibre-install.sh and djvulibre.nsi to prepare

   the djvulibre+djview installer.

5.2- Using Mingw

----------------

   You must first install the mingw compiler and the msys environment.

   See www.mingw.org for more information.

   From the msys shell, run the usual commands 

     $ configure

     $ make

   Then collect the djvulibre dll from directory libdjvu/.libs

   and the executables from directory tools/.libs 

   Please refer to the file INSTALL for information

   about the arguments of the script 'configure'.

5.3- Using Cygwin 

-----------------

   Simply run the usual commands 

     $ configure

     $ make

     $ make install

   Please refer to the file INSTALL for information

   about the arguments of the script 'configure'.