Quickstart

----------

To build Duc with its default options, run:

$ ./configure

$ make

$ sudo make install

Generate the configure script when it is not available (cloned git repo):

$ autoreconf -i

To get the required dependencies on Debian or Ubuntu, run:

$ sudo apt-get install libncursesw5-dev libcairo2-dev libpango1.0-dev \

build-essential libtkrzw-dev libzstd-dev

On Debian 11 (bullseye), you need to have the following line in your

/etc/apt/sources.list file:

deb http://deb.debian.org/debian bullseye-backports main

Then you would do:

$ sudo apt update

$ sudo apt-get install libncursesw5-dev libcairo2-dev libpango1.0-dev \

build-essential libtkrzw-dev tkrzw-doc tkrzw-utils libzstd-dev

On older RHEL or CentOS systems, you need to do:

$ sudo yum install pango-devel cairo-devel tokyocabinet-devel

RHEL 8 & 9 / Rockly Linux 8 & 9 / Alma Linux 8 & 9

Install epel-release & update

$ sudo yum install epel-release

$ sudo yum update

Install tkrzw and other required packages:

$ sudo yum install tkrzw tkrzw-devel tkrzw-doc tkrzw-libs pango-devel \

cairo-devel libzstd-devel

NOTE: for older deprecated backends you might need to install one

or more of the following:

tokyocabinet-devel lmdb-devel

Configuration Options

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

Duc comes with support for various user interfaces and a number of

backends for database access and graph drawing. You can choose which

options should be used with the ./configure script to build Duc to fit

best in your environment.

This document describes the various options which can be passed to the

./configure script, and the impact these options have on Duc

functionality. But the ./configure --help is the definitive source.

User interfaces

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

Duc comes with the following user interfaces:

- Command line interface (duc ls): This user interface has no external

dependencies and is always enabled.

- Ncurses console interface (duc ui): an interactive console interface, which

depends on ncurses or ncursesw. This user interface is enabled by default. If

your system does not provide ncurses, you can disable this with

--disable-ui

- X11 GUI (duc gui): This is the default interface for Linux and other Unix

systems. This user interface depends on the cairo library (see below). If

your system has no X11 or cairo available, disable this user interface with:

--disable-x11

- OpenGL GUI (duc gui): an OpenGL/GLFW user interface which should be portable

on a large range of operating systems. The OpenGL gui is disabled by default.

If you want to enable OpenGL, run ./configure with:

--enable-opengl --disable-x11

Database backends

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

As of v1.5.0, Duc has deprecated support of various key-value database backends:

- Tokyo Cabinet: tokyocabinet

- LevelDB: leveldb

- Sqlite3: sqlite3

- Lightning Memory-Mapped Database: lmdb

- Kyoto Cabinet: kyotocabinet

The default backend moving forward is the following:

- Tkrzw: tkrzw + zstd

since the performance is acceptable and it handles extremely large

databases of volumes with terabytes of storage and millions of files.

To help keep down the DB size, we also require zstd compression

library as well. And more importantly it's actually supported and

still developed.

--with-db-backend=ARG

If your system supports none of the above, contact the authors to see

if we can add your favourite backend, but we strongly urge you to look

at using Tkrzw.

Please note: Not all database formats can be shared between machines

with different architectures. Notably, Tokyo Cabinet is built with

non-standard options which breaks compatibility with other linux

distributions, even on the same architecture [1]. If you are planning

to share databases between different platforms (index machine A,

display on machine B) we recommend using the sqlite3 backend. Or

possibly tkrzw, but this is not tested. Reports welcome.

Note, Tokyo Cabinet, Kyoto Cabinet, LevelDB and LMDB are all being

deprecated from future versions of duc because the lack of development

and support for these libraries, especially for super large volumes to

be indexed.

1. https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=667979

When picking a backend you probably need to choose between speed, size

and robustness. Some (out of date) measurements on a system with a

372G directory containing 1.6M files:

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

Database Run time Db size

(s) (kB)

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

tokyocabinet 8.4 19.2

leveldb 7.1 31.5

sqlite3 13.5 71.1

lmdb 5.9 78.7

kyotocabinet 8.3 26.7

tkrzw [*] ??? ???

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

[*] Tkrzw currently is the default used by Duc because of it's current

development, good compression and reasonable performance.

Tokyo Cabinet is not very stable and can create corrupt databases when

interrupting the indexing. If this is a problem for you, choose a

different db backend.

Graphics

--------

Duc supports various backends for creating graphics, but some have dependencies

which cannot be met on all systems. Especially on headless server systems or

embedded systems not all graphics libraries are available.

- SVG: Duc has native SVG support, which can be used by the 'duc graph' command

to create static images of disk usage. The SVG backend has no external

dependencies and is always enabled.

- HTML canvas: Duc has native support for generating graphs in HTML5 using

JavaScript and the canvas object. The HTML backend has not external

dependencies and is always enabled.

- Cairo/pango: The cairo/pango backend is required for the X11 user interface,

and also adds an option to the duc-graph command to generate images in .PNG

or .PDF file format. If your systems does not have cairo and pango available,

add the following flag to ./configure:

--disable-cairo

- OpenGL: Duc can draw to OpenGL contexts and can be used by the 'duc gui'

command. To enable the OpenGL backend for the 'duc gui' command, run

./configure with:

--enable-opengl --disable-x11

Testing

-------

Duc comes with a rudimentary test harness which can be run at the top

level directory with:

./test.sh

If you have valgrind and you want to run the tests using it do:

USE_VALGRIND=1 ./test.sh

It will complain if you try this and valgrind isn't installed. The

test harness still needs work and more tests, but should hopefully

help keep us from re-introducing bugs as they are fixed and checked

for. We would love to see more tests and a better harness, patches

welcome!