#

# 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 supporting g++11 syntax (for gcc that means version 4.9. minimum, clang is also supported). For version older than dar-2.5.0 g++11 support is not required but if using gcc you need at least version 3.4.x. A standard C++ library is also required, compilation has been tested with libc++ and stdlibc++.
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
- libxz library for xz/lzma 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
- gpgme library version 1.2.0 or greater for asymetric strong encryption and signature (RSA, DSA, etc.)
- doxygen for generation of source code documentation
- upx to generate dar_suite upx compressed binaries
- groff to generate html version of man pages
- ext2/ext3/ext4 file system libraries for Linux Filesystem Specific Attributes and nodump flag support
- libthreadar for libdar using several threads and remote repository feature (needs libcurl in addition see below)
- librsync for delta binary
- libcurl for remote repository access using ftp or sftp protocols
- python3 (python3-dev) and pybind11 to access libdar from python

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 liblzma5 library dar will compile but will not be able to compress or uncompress an archive using the xz 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 gpgme dar will still compile but you will not be able to use strong encryption and signature with public keys
- 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
- If you lack extX file system libraries you will not be able to save and restore Linux FSA, nor to avoid saving files having their nodump flag set
- if you lack libthreadar libdar will execute each action in a single thread, nor you will be able to use remote ftp or sftp directly from dar
- if you lack librsync library dar will still compile but you will not be able to create archive with binary delta nor to read/restore files stored with binary delta
- if you lack libcurl you won't be able to remotely read or write a archive stored using ftp or sftp
- if you lack python3 or pybind11 you won't be able to access libdar from python environment

### 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=infinint
if set, replace 64 bits integers used by default by 32 bits integers or "infinint" integers (limitless integers). Before release 2.6.0 the default integer used was infinint and this option was added for speed optimization at the cost of some limitations (See the limitations for more).
Since release 2.6.0, the default is 64 bits integers (limitations stay the same) instead of infinint. But if you hit the 64 bits integer limitations you can still use infinint which overcome this at the cost of slower performance and increase memory requirement.

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-libxz-linking | Disable linking to liblzma5 this -zxz:* option (xz 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-gpgme-linking | Disable linking with gpgme library. Asymetric strong encryption algorithms will not be available
--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
--disable-threadar | Avoid linking with libthreadar even if available, libdar will not create threads
--disable-birthtime | Disable the HFS+ Filesystem Specific Attribute support
--disable-librsync-linking | Disable linking with librsync, thus delta binary will not be available
--disable-libcurl-linking | Disable linking with libcurl, thus remote repository support using ftp or sftp will not be available
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-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 and even the older RCS in 2002). Since September 2nd 2017, the GIT repository has been cloned to GitHub while the original repository at Sourceforge still stays updated. Both should contain the exact same code, that's up to you to choose the repository you prefer. For sanity also, starting September 3rd 2017, git tags including those for release candidates will be signed with GPG.

### 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.6.x" holds the stable code for releases 2.6.0, 2.6.1, 2.6.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 https://github.com/Edrusb/DAR.git
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.6.x
`
That's all. You now have the most recent stable code (for branch_2.6.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```
There is also a web interface to git at github

### 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 - Related Softwares

> - TAR home page (DAR's grant and venerable brother)
> - Extended Attributes home page
> - GNU Privacy Guard home page
> - Cygwin home page
> - Parchive home page and https://github.com/BlackIkeEagle/par2cmdline (fork from the official site maintained since decembre 2013)
> - the Ultimate Packer for eXecutables home page
> - Doxygen home page
> - Groff home page
> - Gnu Make home page
> - GCC home page