Dar Documentation


HOW TO COMPILE DAR AND LIBDAR



1 - Requirements


To compile dar from a source package (from CVS 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.
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 - Concurrent Versions System (CVS)


Presentation

Instead of having source code copied from one host to another, which makes last versions of each file difficult to identify, dar --- as many other softwares --- uses CVS (Yes still CVS, not git or subversion). CVS defines a repository, which is a central place where all the source code is stored. Anyone can then 'synchronize' the repository with a directory of his own hard disk and this way retrieve a particular version of the source code. Getting source code this way implies you have a CVS client, thus for releases, a copy of the source code is extracted from CVS and is provided as a compressed tar (or zip) archive, which is more easy to use for anyone. Note also that even if you can download source code from CVS repository only authorized developers can upload their changes back to the repository. If you are not an authorized developer you can however submit a patch here, they will be review and maybe integrated to source code, its implementation may be modified when necessary, or  can be rejected (for some good reason of course).

Dar's repository Organization

Over the centralization of the source code, CVS brings the possibility to store different versions of a given file and to give them a label. Labels can be shared between different files which is this way it is used: a given label let us keep a record of what version of each file is used at a specific release, for example, label  v2_4_0 can be used to obtain source code of release 2.4.0 (label must start by a letter and must not contain any dot, thus we use this notation for dar's source labels). Having concurrent versions does not only mean having a stack of versions for each file, but it let us have a tree-like structure:

The Trunk of the tree contains development source code, when enough features have been added and thus comes the time for a new release, a new branch is created at that place. Branch are like labels except that they also create a fork for each file. Dar branches are of the form branch_2_4_x for example. A given branch will start with pre-releases versions, then will come releases for that branch, all of them have the same major and medium number, only the minor number changes between releases of a same branch, which indicates that only bug fixes are done between these releases. At each release the changes done from the previous release on the same branch are merged to the trunk. This way, the development code inherits from the bug fixes.

Usage

To use CVS, you must first set the repository, either on command-line thanks to the -d option or thanks to the CVSROOT environment variable, all these general information about the CVS repository are explained here (note that this documentation speaks about module, this is a set of file inside the repository, actually in dar's repository only exist one module, which name is dar).

First you must login, this has to be done once for all:

cvs -d:pserver:anonymous@dar.cvs.sourceforge.net:/cvsroot/dar login

assuming you want to get (or "check out (=co)") source code of a particular version (here version 1.2.3) :

cvs -z3 -d:pserver:anonymous@dar.cvs.sourceforge.net:/cvsroot/dar co -r v1_2_3 dar

assuming you want to get the latest version of a branch (code which contains bug fixes for the pending next release)

cvs -z3 -d:pserver:anonymous@dar.cvs.sourceforge.net:/cvsroot/dar co -r branch_1_2_x dar

Thus, if the latest release on branch 1.2.x is release 1.2.3 but some bugs have been reported an fixed, you can download the updated source code this way even before release 1.2.4 takes place (depending on the severity of the bugs and on my free time, such fix may stay pending for one or more months). Beside this, once a branch has its first release, (release v2_3_0 appears on branch_2_3_x), older branches die soon after. A status of the branch is show with color codes on dar's homepage.

Note that if you already have "checked out" a particular branch (not a particular version), you can quickly get the lastest changes (that is "update") on that branch using the following command:

cvs -z3 -d:pserver:anonymous@dar.cvs.sourceforge.net:/cvsroot/dar update
 
This will transfer only the difference since the last time you have checked out or updated the local copy of the repository to the most recent version of files on that branch.

Last, if you do not specify any label (-r option) or branch when checking out dar's source code:

cvs -z3 -d:pserver:anonymous@dar.cvs.sourceforge.net:/cvsroot/dar co dar

you get source code from the trunk, thus the code with new features implemented (read the Changelog file to know what has been implemented so far). Adding new features may have impact on some other existing ones and while at each features addition testing is done to be sure the feature works perfectly and while also a new feature is never uploaded to CVS unless it has been tested, trunk version may still have bugs, and must be considered as development source code.  Note moverover, that adding a new feature in the development source may break the compatibility with older development version (while compatibility will stay with released version), thus if you really need to use a developement version for something else than just testing it or trying it, it is strongly recommended to keep a copy of the source code in a secure place to be able to rebuild a dar binary able to read your archives.

Having the sources ready for compilation

Please read the file named "USING_SOURCE_FROM_CVS" located at the root of the directory tree you retrieved through CVS, 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