Dar Documentation


HOW TO COMPILE DAR AND LIBDAR



1 - Requirements


To compile dar from a source package (from GIT see below for additional steps) you need at least:
  1. a C++ compiler (tested done with gcc-4.3.x, but other version and compiler should work. Note:  gcc-3.3.x has a bug that avoids it to compile dar starting dar-2.3.7, more precisely generated objects miss some symbols and cannot be linked together [SF 1890720]). To compile dar-2.3.8 and above you need at least gcc-3.4.x
  2. a linker like "ld" the GNU Linker
  3. make (tested with gnu make)

In option you may also have installed the following tools and libraries:
  • libz library for gzip compression support
  • libbzip2 library for bzip2 compression support
  • liblzo2 library for lzo compression support
  • gnu Getopt support (Linux has it for all distro thanks to its glibc, this is not true for FreeBSD for example)
  • libgcryt version 1.4.0 or greater for symetric strong encryption (blowfish, aes, etc.) and hash (sha1, md5) support
  • doxygen for generation of source code documentation
  • upx to generate dar_suite upx compressed binaries
  • groff to generate html version of man pages

The consequences of building dar without these optional tools are the following:
  • If you lack libz library, dar will compile but will not be able to compress or uncompress an archive using the gzip algorithm
  • If you lack libbzip2 library dar will compile but will not be able to compress or uncompress an archive using the bzip2 algorithm
  • If you lack liblzo2 library dar will compile but will not be able to compress or uncompress an archive using the lzo algorithm
  • If you lack libgcrypt dar will still compile but you will not be able to use strong encryption nor hash file generation for each slice
  • If you lack Doxygen dar will still compile but you will not have the reference documentation for libdar after calling make
  • If you lack upx dar will still compile but the resulting binary will not be compressed after calling make install-strip
  • If you lack groff dar will not generate man pages in html format


2 - Compilation in brief


Once you have the minimum requirements, Dar has to be compiled from source code in the following way:

./configure [eventually with some options]
make
make install-strip

Important: due to a bug in the autoconf/libtool softwares used to build the configure script you must not have spaces in the name of the path where are extracted dar' sources. You can install dar binary anywhere you want, the problem  does not concern dar itself but the ./configure script used to build dar: To work properly it must not be ran from a path which has a space in it.
Important too: By default the configure script set optimization to -O2, depending on the compiler this may lead to problems in the resulting binary (or even in the compilation process), before reporting a bug try first to compile with less optimization:

CXXFLAGS=-O
export CXXFLAGS
make clean distclean
./configure [options...]
make
make install-strip

The configure script may receive several options, they are listed here.

Note for packagers that the DESTDIR variable may be set at installation time to install dar in another directory. This makes the creation of dar binary packages very easy. Here is an example

./configure --prefix=/usr [eventually with some options]
make
make DESTDIR=/some/where install-strip

This will install dar in /some/where/usr/{bin | lib | ...} directories. You can build a package from files under /some/where and install/remove the package at the root of your filesystem (thus here files will go in /usr/{bin | lib | ... }).

3 - Options for the configure script



Available options for the configure script
Optimization option:
 --enable-mode  --enable-mode=32 or --enable-mode=64
if set, replace "infinint" integers by 32 or 64 bits integers. This makes a faster executable and less fond of memory, but with several restrictions (about for example ability to handle large files, or high dates. See the limitations for more).
Deactivation options:
--disable-largefile Whatever your system is, dar will not be able to handle file of size larger than 4GB
--disable-ea-support
 Whatever your system is, dar will not be able to save or restore Extended Attributes (see the Notes paragraphs I and V)
--disable-nodump-flag
 Whatever your system is, dar will not be able to take care of the nodump-flag (thanks to the --nodump option)
--disable-dar-static
 dar_static binary (statically linked version of dar) will not be built
--disable-special-alloc
 dar uses a special allocation scheme by default (gather the many small allocations in big fewer ones), this improves dar's execution speed
--disable-upx
 If upx is found in the PATH, binary are upx compressed at installation step. This can be disabled by this option, when upx is available and you don't want compressed binaries.
--disable-gnugetopt
  on non GNU systems (Solaris, etc.) configure looks for libgnugetopt to have the long options support thanks to the gnu getopt_long() call, this can be disabled.
--disable-thread-safe
  libdar may need POSIX mutex to be thread safe. If you don't want libdar relaying on POSIX mutex even if they are available, use this option. The resulting library may not be thread safe. But it will always be thread safe if you use --disable-special-alloc, and it will never be thread safe if --enable-test-memory is used.
--disable-libdl-linking
 Ignore any libdl library and avoid linking with it
--disable-libz-linking
 Disable linking to libz, thus -zgzip:* option (gzip compression) will not be available
--disable-libbz2-linking
 Disable linking to libbz2, thus -zbzip2:* option (libbz2 compression) will not be available
--disable-liblzo2-linking
 Disable linking to liblzo2, thus -zlzo:* option (lzo compression) will not be available
--disable-libgcrypt-linking
 Disable linking with libgcrypt library. Strong encryption will not be available neither a hashing of generated slices.
--disable-build-html
 Do not build API documentation reference with Doxygen (when it is available)
--disable-furtive-read
 Do not try to detect whether the system does support furtive read mode. This will lead furtive read mode to stay disabled in any case.
 --disable-fast-dir
 Disable optimization for large directories, doing so has a little positive impact on memory requirement but a huge drawback on execution time
--disable-execinfo
 Disable reporting stack information on self diagnostic bugs even
Troubleshooting option:
--enable-os-bits
 If set, dar uses the given argument (32 or 64) to determine which integer type to use. This much match your CPU register size. By default dar uses the system <stdint.h> file to determine the correct integer type to use


Debugging options:
--enable-examples
 If set, example programs based on infinint will also be built
--enable-debug
 If set, use debug compilation option, and if possible statically link binaries
--enable-pedantic
 If set, transmits the -pedantic option to the compiler
--enable-build-usage
 If set, rebuild usage files (requires libxml2)
--enable-profiling
 Enable executable profiling
--enable-debug-memory
 If set, logs all memory allocations and releases to /tmp/dar_debug_mem_allocation.txt  . The resulting executable is expected to be very slow


4 - GIT


Presentation

To manage its source code versions DAR uses GIT (it used CVS up to Q1 2012).

Dar's repository Organization

GIT (more than CVS) eases the use of branches. In dar repository, there are thus a lot of them: the first and main one is called "master". It contains current development and most probably unstable code. There are other permanent branches that hold stable code. They are all named by "branch_A.B.x" where A and B are the numbers corresponding to a released versions family. For example, "branch_2.4.x" holds the stable code for releases 2.4.0, 2.4.1, 2.4.2 and so on. It also holds pending fixes for the next release on that branch you might be interested in.

The global organisation of the repository is thus the following:
 
 
 (HEAD of "master" branch)
    new feature 101
          |
          ^
          |
    new feature 100
          |
          ^
          |
    new feature 99
          |
          +--->-- fix 901 ->- fix 902 (release 2.4.1) ->- fix 903 ->- fix 904 (release 2.4.2) ->- fix 905 (HEAD of branch_2.4.x)
          |
    new feature 98
          |
          ^
          |
    new feature 97
          |
          +--->-- fix 801 ->- fix 802 (release 2.3.1) (also HEAD of branch_2.3.x as no pending fix is waiting for release)
          |
         ...
          |
          ^
          |
    initial version
         ____
                 

Usage

To get dar source code from GIT you have first to clone the repository hosted at sourceforge:

git clone git://git.code.sf.net/p/dar/code dar-code
cd dar

You will probably not want to use current development code so you have to change from the branch master to the branch "branch_A.B.x" of you choice:

git checkout branch_2.4.x

That's all. You now have the most recent stable code (for branch_2.4.x in this example). To see what changes have been brought since the last release, use the following command:

git log
 
If you plan to keep the repository you've cloned, updating the change is as easy as using (no need to clone the repository from scratch again): 

git pull origin branch_2.4.x

There is also a web interface to git: gitweb

Having the sources ready for compilation

Please read the fiile named "USING_SOURCE_FROM_GIT" located at the root of the directory tree you retrieved through GIT, it contains up to date information about the required tools and how to generate the configuration file. Then you can proceed to source compilation as done with regular source package.



5 - EA Support & Compilation Problems

[this paragraph should no more concern anyone today, it will be removed at next major release (release 2.5.0). However, if you have found it of some use, please send a mail to the maintainer]

If you just want to compile DAR with EA support available, you just need the attr-x.x.x.src.tar.gz package to have the libattr library and header files installed. If you want to use EA, then you need to have EA support in your kernel.

[What follows in this chapter is becoming obsolete, you may skip it as today EA support is available in standard in at least Linux kernels]

I personally got some problem to compile dar with EA support, due to EA package installation problem:

when installing EA package, the /usr/include/attr directory is not created nor the xattr.h file put in it. To solve this problem, create it manually, and copy the xattr.h (and also attributes.h even if it is not required by dar) to it, giving it proper permission (world readable). These include files can be found in the "include" subdir of the xattr package: as root type the following replacing <package> by the path where your package has been compiled:

cd /usr/include
mkdir attr
chmod 0755 attr
cp <package>/include/xattr.h <package>/include/attributes.h attr
cd attr
chmod 0644 *

The second problem is while linking, the static library version does not exist. You can built it using the following command (after package compilation):

as previously as root type:

chdir <package>/libattr
ar r libattr.a syscalls.o libattr.o
mv libattr.a /usr/lib
chmod 0644 /usr/lib/libattr.a

dar should now be able to compile with support for EA activated.

6 - Related Softwares