INSTALL
1349 lines (967 with data), 58.2 kB
More documentation can be found in the doc/ directory or at http://www.recoll.org
Link: home: Recoll user manual
Link: up: Recoll user manual
Link: prev: 4.3. API
Link: next: 5.2. Supporting packages
Chapter 5. Installation and configuration
Prev Next
----------------------------------------------------------------------
Chapter 5. Installation and configuration
5.1. Installing a binary copy
Recoll binary copies are always distributed as regular packages for your
system. They can be obtained either through the system's normal software
distribution framework (e.g. Debian/Ubuntu apt, FreeBSD ports, etc.), or
from some type of "backports" repository providing versions newer than the
standard ones, or found on the Recoll WEB site in some cases.
There used to exist another form of binary install, as pre-compiled source
trees, but these are just less convenient than the packages and don't
exist any more.
The package management tools will usually automatically deal with hard
dependancies for packages obtained from a proper package repository. You
will have to deal with them by hand for downloaded packages (for example,
when dpkg complains about missing dependancies).
In all cases, you will have to check or install supporting applications
for the file types that you want to index beyond those that are natively
processed by Recoll (text, HTML, email files, and a few others).
You should also maybe have a look at the configuration section (but this
may not be necessary for a quick test with default parameters). Most
parameters can be more conveniently set from the GUI interface.
----------------------------------------------------------------------
Prev Next
4.3. API Home 5.2. Supporting packages
Link: home: Recoll user manual
Link: up: Chapter 5. Installation and configuration
Link: prev: Chapter 5. Installation and configuration
Link: next: 5.3. Building from source
5.2. Supporting packages
Prev Chapter 5. Installation and configuration Next
----------------------------------------------------------------------
5.2. Supporting packages
Recoll uses external applications to index some file types. You need to
install them for the file types that you wish to have indexed (these are
run-time optional dependencies. None is needed for building or running
Recoll except for indexing their specific file type).
After an indexing pass, the commands that were found missing can be
displayed from the recoll File menu. The list is stored in the missing
text file inside the configuration directory.
A list of common file types which need external commands follows. Many of
the handlers need the iconv command, which is not always listed as a
dependancy.
Please note that, due to the relatively dynamic nature of this
information, the most up to date version is now kept on
http://www.recoll.org/features.html along with links to the home pages or
best source/patches pages, and misc tips. The list below is not updated
often and may be quite stale.
For many Linux distributions, most of the commands listed can be installed
from the package repositories. However, the packages are sometimes
outdated, or not the best version for Recoll, so you should take a look at
http://www.recoll.org/features.html if a file type is important to you.
As of Recoll release 1.14, a number of XML-based formats that were handled
by ad hoc handler code now use the xsltproc command, which usually comes
with libxslt. These are: abiword, fb2 (ebooks), kword, openoffice, svg.
Now for the list:
o Openoffice files need unzip and xsltproc.
o PDF files need pdftotext which is part of Poppler (usually comes with
the poppler-utils package). Avoid the original one from Xpdf.
o Postscript files need pstotext. The original version has an issue with
shell character in file names, which is corrected in recent packages.
See http://www.recoll.org/features.html for more detail.
o MS Word needs antiword. It is also useful to have wvWare installed as
it may be be used as a fallback for some files which antiword does not
handle.
o MS Excel and PowerPoint are processed by internal Python handlers.
o MS Open XML (docx) needs xsltproc.
o Wordperfect files need wpd2html from the libwpd (or libwpd-tools on
Ubuntu) package.
o RTF files need unrtf, which, in its older versions, has much trouble
with non-western character sets. Many Linux distributions carry
outdated unrtf versions. Check http://www.recoll.org/features.html for
details.
o TeX files need untex or detex. Check
http://www.recoll.org/features.html for sources if it's not packaged
for your distribution.
o dvi files need dvips.
o djvu files need djvutxt and djvused from the DjVuLibre package.
o Audio files: Recoll releases 1.14 and later use a single Python
handler based on mutagen for all audio file types.
o Pictures: Recoll uses the Exiftool Perl package to extract tag
information. Most image file formats are supported. Note that there
may not be much interest in indexing the technical tags (image size,
aperture, etc.). This is only of interest if you store personal tags
or textual descriptions inside the image files.
o chm: files in Microsoft help format need Python and the pychm module
(which needs chmlib).
o ICS: up to Recoll 1.13, iCalendar files need Python and the icalendar
module. icalendar is not needed for newer versions, which use internal
code.
o Zip archives need Python (and the standard zipfile module).
o Rar archives need Python, the rarfile Python module and the unrar
utility.
o Midi karaoke files need Python and the Midi module
o Konqueror webarchive format with Python (uses the Tarfile module).
o Mimehtml web archive format (support based on the email handler, which
introduces some mild weirdness, but still usable).
Text, HTML, email folders, and Scribus files are processed internally. Lyx
is used to index Lyx files. Many handlers need iconv and the standard sed
and awk.
----------------------------------------------------------------------
Prev Up Next
Chapter 5. Installation and configuration Home 5.3. Building from source
Link: home: Recoll user manual
Link: up: Chapter 5. Installation and configuration
Link: prev: 5.2. Supporting packages
Link: next: 5.4. Configuration overview
5.3. Building from source
Prev Chapter 5. Installation and configuration Next
----------------------------------------------------------------------
5.3. Building from source
5.3.1. Prerequisites
If you can install any or all of the following through the package manager
for your system, all the better. Especially Qt is a very big piece of
software, but you will most probably be able to find a binary package.
You may have to compile Xapian but this is easy.
The shopping list:
o C++ compiler. Up to Recoll version 1.13.04, its absence can manifest
itself by strange messages about a missing iconv_open.
o Development files for Xapian core.
Important
If you are building Xapian for an older CPU (before Pentium 4 or
Athlon 64), you need to add the --disable-sse flag to the configure
command. Else all Xapian application will crash with an illegal
instruction error.
o Development files for Qt 4 . Recoll has not been tested with Qt 5 yet.
Recoll 1.15.9 was the last version to support Qt 3. If you do not want
to install or build the Qt Webkit module, Recoll has a configuration
option to disable its use (see further).
o Development files for X11 and zlib.
o You may also need libiconv. On Linux systems, the iconv interface is
part of libc and you should not need to do anything special.
Check the Recoll download page for up to date version information.
5.3.2. Building
Recoll has been built on Linux, FreeBSD, Mac OS X, and Solaris, most
versions after 2005 should be ok, maybe some older ones too (Solaris 8 is
ok). If you build on another system, and need to modify things, I would
very much welcome patches.
Configure options:
o --without-aspell will disable the code for phonetic matching of search
terms.
o --with-fam or --with-inotify will enable the code for real time
indexing. Inotify support is enabled by default on recent Linux
systems.
o --with-qzeitgeist will enable sending Zeitgeist events about the
visited search results, and needs the qzeitgeist package.
o --disable-webkit is available from version 1.17 to implement the
result list with a Qt QTextBrowser instead of a WebKit widget if you
do not or can't depend on the latter.
o --disable-idxthreads is available from version 1.19 to suppress
multithreading inside the indexing process. You can also use the
run-time configuration to restrict recollindex to using a single
thread, but the compile-time option may disable a few more unused
locks. This only applies to the use of multithreading for the core
index processing (data input). The Recoll monitor mode always uses at
least two threads of execution.
o --disable-python-module will avoid building the Python module.
o --disable-xattr will prevent fetching data from file extended
attributes. Beyond a few standard attributes, fetching extended
attributes data can only be useful is some application stores data in
there, and also needs some simple configuration (see comments in the
fields configuration file).
o --enable-camelcase will enable splitting camelCase words. This is not
enabled by default as it has the unfortunate side-effect of making
some phrase searches quite confusing: ie, "MySQL manual" would be
matched by "MySQL manual" and "my sql manual" but not "mysql manual"
(only inside phrase searches).
o --with-file-command Specify the version of the 'file' command to use
(ie: --with-file-command=/usr/local/bin/file). Can be useful to enable
the gnu version on systems where the native one is bad.
o --disable-qtgui Disable the Qt interface. Will allow building the
indexer and the command line search program in absence of a Qt
environment.
o --disable-x11mon Disable X11 connection monitoring inside recollindex.
Together with --disable-qtgui, this allows building recoll without Qt
and X11.
o --disable-pic will compile Recoll with position-dependant code. This
is incompatible with building the KIO or the Python or PHP extensions,
but might yield very marginally faster code.
o Of course the usual autoconf configure options, like --prefix apply.
Normal procedure:
cd recoll-xxx
./configure
make
(practices usual hardship-repelling invocations)
There is little auto-configuration. The configure script will mainly link
one of the system-specific files in the mk directory to mk/sysconf. If
your system is not known yet, it will tell you as much, and you may want
to manually copy and modify one of the existing files (the new file name
should be the output of uname -s).
5.3.2.1. Building on Solaris
We did not test building the GUI on Solaris for recent versions. You will
need at least Qt 4.4. There are some hints on an old web site page, they
may still be valid.
Someone did test the 1.19 indexer and Python module build, they do work,
with a few minor glitches. Be sure to use GNU make and install.
5.3.3. Installation
Either type make install or execute recollinstall prefix, in the root of
the source tree. This will copy the commands to prefix/bin and the sample
configuration files, scripts and other shared data to prefix/share/recoll.
If the installation prefix given to recollinstall is different from either
the system default or the value which was specified when executing
configure (as in configure --prefix /some/path), you will have to set the
RECOLL_DATADIR environment variable to indicate where the shared data is
to be found (ie for (ba)sh: export
RECOLL_DATADIR=/some/path/share/recoll).
You can then proceed to configuration.
----------------------------------------------------------------------
Prev Up Next
5.2. Supporting packages Home 5.4. Configuration overview
Link: home: Recoll user manual
Link: up: Chapter 5. Installation and configuration
Link: prev: 5.3. Building from source
5.4. Configuration overview
Prev Chapter 5. Installation and configuration
----------------------------------------------------------------------
5.4. Configuration overview
Most of the parameters specific to the recoll GUI are set through the
Preferences menu and stored in the standard Qt place
($HOME/.config/Recoll.org/recoll.conf). You probably do not want to edit
this by hand.
Recoll indexing options are set inside text configuration files located in
a configuration directory. There can be several such directories, each of
which defines the parameters for one index.
The configuration files can be edited by hand or through the Index
configuration dialog (Preferences menu). The GUI tool will try to respect
your formatting and comments as much as possible, so it is quite possible
to use both ways.
The most accurate documentation for the configuration parameters is given
by comments inside the default files, and we will just give a general
overview here.
By default, for each index, there are two sets of configuration files.
System-wide configuration files are kept in a directory named like
/usr/[local/]share/recoll/examples, and define default values, shared by
all indexes. For each index, a parallel set of files defines the
customized parameters.
In addition (as of Recoll version 1.19.7), it is possible to specify two
additional configuration directories which will be stacked before and
after the user configuration directory. These are defined by the
RECOLL_CONFTOP and RECOLL_CONFMID environment variables. Values from
configuration files inside the top directory will override user ones,
values from configuration files inside the middle directory will override
system ones and be overriden by user ones. These two variables may be of
use to applications which augment Recoll functionality, and need to add
configuration data without disturbing the user's files. Please note that
the two, currently single, values will probably be interpreted as
colon-separated lists in the future: do not use colon characters inside
the directory paths.
The default location of the configuration is the .recoll directory in your
home. Most people will only use this directory.
This location can be changed, or others can be added with the
RECOLL_CONFDIR environment variable or the -c option parameter to recoll
and recollindex.
If the .recoll directory does not exist when recoll or recollindex are
started, it will be created with a set of empty configuration files.
recoll will give you a chance to edit the configuration file before
starting indexing. recollindex will proceed immediately. To avoid
mistakes, the automatic directory creation will only occur for the default
location, not if -c or RECOLL_CONFDIR were used (in the latter cases, you
will have to create the directory).
All configuration files share the same format. For example, a short
extract of the main configuration file might look as follows:
# Space-separated list of directories to index.
topdirs = ~/docs /usr/share/doc
[~/somedirectory-with-utf8-txt-files]
defaultcharset = utf-8
There are three kinds of lines:
o Comment (starts with #) or empty.
o Parameter affectation (name = value).
o Section definition ([somedirname]).
Depending on the type of configuration file, section definitions either
separate groups of parameters or allow redefining some parameters for a
directory sub-tree. They stay in effect until another section definition,
or the end of file, is encountered. Some of the parameters used for
indexing are looked up hierarchically from the current directory location
upwards. Not all parameters can be meaningfully redefined, this is
specified for each in the next section.
When found at the beginning of a file path, the tilde character (~) is
expanded to the name of the user's home directory, as a shell would do.
White space is used for separation inside lists. List elements with
embedded spaces can be quoted using double-quotes.
Encoding issues. Most of the configuration parameters are plain ASCII. Two
particular sets of values may cause encoding issues:
o File path parameters may contain non-ascii characters and should use
the exact same byte values as found in the file system directory.
Usually, this means that the configuration file should use the system
default locale encoding.
o The unac_except_trans parameter should be encoded in UTF-8. If your
system locale is not UTF-8, and you need to also specify non-ascii
file paths, this poses a difficulty because common text editors cannot
handle multiple encodings in a single file. In this relatively
unlikely case, you can edit the configuration file as two separate
text files with appropriate encodings, and concatenate them to create
the complete configuration.
5.4.1. Environment variables
RECOLL_CONFDIR
Defines the main configuration directory.
RECOLL_TMPDIR, TMPDIR
Locations for temporary files, in this order of priority. The
default if none of these is set is to use /tmp. Big temporary
files may be created during indexing, mostly for decompressing,
and also for processing, e.g. email attachments.
RECOLL_CONFTOP, RECOLL_CONFMID
Allow adding configuration directories with priorities below and
above the user directory (see above the Configuration overview
section for details).
RECOLL_EXTRA_DBS, RECOLL_ACTIVE_EXTRA_DBS
Help for setting up external indexes. See this paragraph for
explanations.
RECOLL_DATADIR
Defines replacement for the default location of Recoll data files,
normally found in, e.g., /usr/share/recoll).
RECOLL_FILTERSDIR
Defines replacement for the default location of Recoll filters,
normally found in, e.g., /usr/share/recoll/filters).
ASPELL_PROG
aspell program to use for creating the spelling dictionary. The
result has to be compatible with the libaspell which Recoll is
using.
VARNAME
Blabla
5.4.2. The main configuration file, recoll.conf
recoll.conf is the main configuration file. It defines things like what to
index (top directories and things to ignore), and the default character
set to use for document types which do not specify it internally.
The default configuration will index your home directory. If this is not
appropriate, start recoll to create a blank configuration, click Cancel,
and edit the configuration file before restarting the command. This will
start the initial indexing, which may take some time.
Most of the following parameters can be changed from the Index
Configuration menu in the recoll interface. Some can only be set by
editing the configuration file.
5.4.2.1. Parameters affecting what documents we index:
topdirs
Specifies the list of directories or files to index (recursively
for directories). You can use symbolic links as elements of this
list. See the followLinks option about following symbolic links
found under the top elements (not followed by default).
skippedNames
A space-separated list of wilcard patterns for names of files or
directories that should be completely ignored. The list defined in
the default file is:
skippedNames = #* bin CVS Cache cache* caughtspam tmp .thumbnails .svn \
*~ .beagle .git .hg .bzr loop.ps .xsession-errors \
.recoll* xapiandb recollrc recoll.conf
The list can be redefined at any sub-directory in the indexed
area.
The top-level directories are not affected by this list (that is,
a directory in topdirs might match and would still be indexed).
The list in the default configuration does not exclude hidden
directories (names beginning with a dot), which means that it may
index quite a few things that you do not want. On the other hand,
email user agents like thunderbird usually store messages in
hidden directories, and you probably want this indexed. One
possible solution is to have .* in skippedNames, and add things
like ~/.thunderbird or ~/.evolution in topdirs.
Not even the file names are indexed for patterns in this list. See
the noContentSuffixes variable for an alternative approach which
indexes the file names.
noContentSuffixes
This is a list of file name endings (not wildcard expressions, nor
dot-delimited suffixes). Only the names of matching files will be
indexed (no attempt at MIME type identification, no decompression,
no content indexing). This can be redefined for subdirectories,
and edited from the GUI. The default value is:
noContentSuffixes = .md5 .map \
.o .lib .dll .a .sys .exe .com \
.mpp .mpt .vsd \
.img .img.gz .img.bz2 .img.xz .image .image.gz .image.bz2 .image.xz \
.dat .bak .rdf .log.gz .log .db .msf .pid \
,v ~ #
skippedPaths and daemSkippedPaths
A space-separated list of patterns for paths of files or
directories that should be skipped. There is no default in the
sample configuration file, but the code always adds the
configuration and database directories in there.
skippedPaths is used both by batch and real time indexing.
daemSkippedPaths can be used to specify things that should be
indexed at startup, but not monitored.
Example of use for skipping text files only in a specific
directory:
skippedPaths = ~/somedir/*.txt
skippedPathsFnmPathname
The values in the *skippedPaths variables are matched by default
with fnmatch(3), with the FNM_PATHNAME flag. This means that '/'
characters must be matched explicitely. You can set
skippedPathsFnmPathname to 0 to disable the use of FNM_PATHNAME
(meaning that /*/dir3 will match /dir1/dir2/dir3).
zipSkippedNames
A space-separated list of patterns for names of files or
directories that should be ignored inside zip archives. This is
used directly by the zip handler, and has a function similar to
skippedNames, but works independantly. Can be redefined for
filesystem subdirectories. For versions up to 1.19, you will need
to update the Zip handler and install a supplementary Python
module. The details are described on the Recoll wiki.
followLinks
Specifies if the indexer should follow symbolic links while
walking the file tree. The default is to ignore symbolic links to
avoid multiple indexing of linked files. No effort is made to
avoid duplication when this option is set to true. This option can
be set individually for each of the topdirs members by using
sections. It can not be changed below the topdirs level.
indexedmimetypes
Recoll normally indexes any file which it knows how to read. This
list lets you restrict the indexed MIME types to what you specify.
If the variable is unspecified or the list empty (the default),
all supported types are processed. Can be redefined for
subdirectories.
excludedmimetypes
This list lets you exclude some MIME types from indexing. Can be
redefined for subdirectories.
compressedfilemaxkbs
Size limit for compressed (.gz or .bz2) files. These need to be
decompressed in a temporary directory for identification, which
can be very wasteful if 'uninteresting' big compressed files are
present. Negative means no limit, 0 means no processing of any
compressed file. Defaults to -1.
textfilemaxmbs
Maximum size for text files. Very big text files are often
uninteresting logs. Set to -1 to disable (default 20MB).
textfilepagekbs
If set to other than -1, text files will be indexed as multiple
documents of the given page size. This may be useful if you do
want to index very big text files as it will both reduce memory
usage at index time and help with loading data to the preview
window. A size of a few megabytes would seem reasonable (default:
1MB).
membermaxkbs
This defines the maximum size in kilobytes for an archive member
(zip, tar or rar at the moment). Bigger entries will be skipped.
indexallfilenames
Recoll indexes file names in a special section of the database to
allow specific file names searches using wild cards. This
parameter decides if file name indexing is performed only for
files with MIME types that would qualify them for full text
indexing, or for all files inside the selected subtrees,
independently of MIME type.
usesystemfilecommand
Decide if we execute a system command (file -i by default) as a
final step for determining the MIME type for a file (the main
procedure uses suffix associations as defined in the mimemap
file). This can be useful for files with suffix-less names, but it
will also cause the indexing of many bogus "text" files.
systemfilecommand
Command to use for mime for mime type determination if
usesystefilecommand is set. Recent versions of xdg-mime sometimes
work better than file.
processwebqueue
If this is set, process the directory where Web browser plugins
copy visited pages for indexing.
webqueuedir
The path to the web indexing queue. This is hard-coded in the
Firefox plugin as ~/.recollweb/ToIndex so there should be no need
to change it.
5.4.2.2. Parameters affecting how we generate terms:
Changing some of these parameters will imply a full reindex. Also, when
using multiple indexes, it may not make sense to search indexes that don't
share the values for these parameters, because they usually affect both
search and index operations.
indexStripChars
Decide if we strip characters of diacritics and convert them to
lower-case before terms are indexed. If we don't, searches
sensitive to case and diacritics can be performed, but the index
will be bigger, and some marginal weirdness may sometimes occur.
The default is a stripped index (indexStripChars = 1) for now.
When using multiple indexes for a search, this parameter must be
defined identically for all. Changing the value implies an index
reset.
maxTermExpand
Maximum expansion count for a single term (e.g.: when using
wildcards). The default of 10000 is reasonable and will avoid
queries that appear frozen while the engine is walking the term
list.
maxXapianClauses
Maximum number of elementary clauses we can add to a single Xapian
query. In some cases, the result of term expansion can be
multiplicative, and we want to avoid using excessive memory. The
default of 100 000 should be both high enough in most cases and
compatible with current typical hardware configurations.
nonumbers
If this set to true, no terms will be generated for numbers. For
example "123", "1.5e6", 192.168.1.4, would not be indexed
("value123" would still be). Numbers are often quite interesting
to search for, and this should probably not be set except for
special situations, ie, scientific documents with huge amounts of
numbers in them. This can only be set for a whole index, not for a
subtree.
nocjk
If this set to true, specific east asian (Chinese Korean Japanese)
characters/word splitting is turned off. This will save a small
amount of cpu if you have no CJK documents. If your document base
does include such text but you are not interested in searching it,
setting nocjk may be a significant time and space saver.
cjkngramlen
This lets you adjust the size of n-grams used for indexing CJK
text. The default value of 2 is probably appropriate in most
cases. A value of 3 would allow more precision and efficiency on
longer words, but the index will be approximately twice as large.
indexstemminglanguages
A list of languages for which the stem expansion databases will be
built. See recollindex(1) or use the recollindex -l command for
possible values. You can add a stem expansion database for a
different language by using recollindex -s, but it will be deleted
during the next indexing. Only languages listed in the
configuration file are permanent.
defaultcharset
The name of the character set used for files that do not contain a
character set definition (ie: plain text files). This can be
redefined for any sub-directory. If it is not set at all, the
character set used is the one defined by the nls environment (
LC_ALL, LC_CTYPE, LANG), or iso8859-1 if nothing is set.
unac_except_trans
This is a list of characters, encoded in UTF-8, which should be
handled specially when converting text to unaccented lowercase.
For example, in Swedish, the letter a with diaeresis has full
alphabet citizenship and should not be turned into an a. Each
element in the space-separated list has the special character as
first element and the translation following. The handling of both
the lowercase and upper-case versions of a character should be
specified, as appartenance to the list will turn-off both standard
accent and case processing. Example for Swedish:
unac_except_trans = aaaa AAaa a:a: A:a: o:o: O:o:
Note that the translation is not limited to a single character,
you could very well have something like u:ue in the list.
The default value set for unac_except_trans can't be listed here
because I have trouble with SGML and UTF-8, but it only contains
ligature decompositions: german ss, oe, ae, fi, fl.
This parameter can't be defined for subdirectories, it is global,
because there is no way to do otherwise when querying. If you have
document sets which would need different values, you will have to
index and query them separately.
maildefcharset
This can be used to define the default character set specifically
for email messages which don't specify it. This is mainly useful
for readpst (libpst) dumps, which are utf-8 but do not say so.
localfields
This allows setting fields for all documents under a given
directory. Typical usage would be to set an "rclaptg" field, to be
used in mimeview to select a specific viewer. If several fields
are to be set, they should be separated with a semi-colon (';')
character, which there is currently no way to escape. Also note
the initial semi-colon. Example: localfields= ;rclaptg=gnus;other
= val, then select specifier viewer with mimetype|tag=... in
mimeview.
testmodifusemtime
If true, use mtime instead of default ctime to determine if a file
has been modified (in addition to size, which is always used).
Setting this can reduce re-indexing on systems where extended
attributes are modified (by some other application), but not
indexed (changing extended attributes only affects ctime). Notes:
o This may prevent detection of change in some marginal file
rename cases (the target would need to have the same size and
mtime).
o You should probably also set noxattrfields to 1 in this case,
except if you still prefer to perform xattr indexing, for
example if the local file update pattern makes it of value
(as in general, there is a risk for pure extended attributes
updates without file modification to go undetected).
Perform a full index reset after changing the value of this
parameter.
noxattrfields
Recoll versions 1.19 and later automatically translate file
extended attributes into document fields (to be processed
according to the parameters from the fields file). Setting this
variable to 1 will disable the behaviour.
metadatacmds
This allows executing external commands for each file and storing
the output in Recoll document fields. This could be used for
example to index external tag data. The value is a list of field
names and commands, don't forget an initial semi-colon. Example:
[/some/area/of/the/fs]
metadatacmds = ; tags = tmsu tags %f; otherfield = somecmd -xx %f
As a specially disgusting hack brought by Recoll 1.19.7, if a
"field name" begins with rclmulti, the data returned by the
command is expected to contain multiple field values, in
configuration file format. This allows setting several fields by
executing a single command. Example:
metadatacmds = ; rclmulti1 = somecmd %f
If somecmd returns data in the form of:
field1 = value1
field2 = value for field2
field1 and field2 will be set inside the document metadata.
5.4.2.3. Parameters affecting where and how we store things:
dbdir
The name of the Xapian data directory. It will be created if
needed when the index is initialized. If this is not an absolute
path, it will be interpreted relative to the configuration
directory. The value can have embedded spaces but starting or
trailing spaces will be trimmed. You cannot use quotes here.
idxstatusfile
The name of the scratch file where the indexer process updates its
status. Default: idxstatus.txt inside the configuration directory.
maxfsoccuppc
Maximum file system occupation before we stop indexing. The value
is a percentage, corresponding to what the "Capacity" df output
column shows. The default value is 0, meaning no checking.
mboxcachedir
The directory where mbox message offsets cache files are held.
This is normally $RECOLL_CONFDIR/mboxcache, but it may be useful
to share a directory between different configurations.
mboxcacheminmbs
The minimum mbox file size over which we cache the offsets. There
is really no sense in caching offsets for small files. The default
is 5 MB.
webcachedir
This is only used by the web browser plugin indexing code, and
defines where the cache for visited pages will live. Default:
$RECOLL_CONFDIR/webcache
webcachemaxmbs
This is only used by the web browser plugin indexing code, and
defines the maximum size for the web page cache. Default: 40 MB.
Quite unfortunately, this is only taken into account when creating
the cache file. You need to delete the file for a change to be
taken into account.
idxflushmb
Threshold (megabytes of new text data) where we flush from memory
to disk index. Setting this can help control memory usage. A value
of 0 means no explicit flushing, letting Xapian use its own
default, which is flushing every 10000 (or XAPIAN_FLUSH_THRESHOLD)
documents, which gives little memory usage control, as memory
usage also depends on average document size. The default value is
10, and it is probably a bit low. If your system usually has free
memory, you can try higher values between 20 and 80. In my
experience, values beyond 100 are always counterproductive.
5.4.2.4. Parameters affecting multithread processing
The Recoll indexing process recollindex can use multiple threads to speed
up indexing on multiprocessor systems. The work done to index files is
divided in several stages and some of the stages can be executed by
multiple threads. The stages are:
1. File system walking: this is always performed by the main thread.
2. File conversion and data extraction.
3. Text processing (splitting, stemming, etc.)
4. Xapian index update.
You can also read a longer document about the transformation of Recoll
indexing to multithreading.
The threads configuration is controlled by two configuration file
parameters.
thrQSizes
This variable defines the job input queues configuration. There
are three possible queues for stages 2, 3 and 4, and this
parameter should give the queue depth for each stage (three
integer values). If a value of -1 is used for a given stage, no
queue is used, and the thread will go on performing the next
stage. In practise, deep queues have not been shown to increase
performance. A value of 0 for the first queue tells Recoll to
perform autoconfiguration (no need for the two other values in
this case) - this is the default configuration.
thrTCounts
This defines the number of threads used for each stage. If a value
of -1 is used for one of the queue depths, the corresponding
thread count is ignored. It makes no sense to use a value other
than 1 for the last stage because updating the Xapian index is
necessarily single-threaded (and protected by a mutex).
The following example would use three queues (of depth 2), and 4 threads
for converting source documents, 2 for processing their text, and one to
update the index. This was tested to be the best configuration on the test
system (quadri-processor with multiple disks).
thrQSizes = 2 2 2
thrTCounts = 4 2 1
The following example would use a single queue, and the complete
processing for each document would be performed by a single thread
(several documents will still be processed in parallel in most cases). The
threads will use mutual exclusion when entering the index update stage. In
practise the performance would be close to the precedent case in general,
but worse in certain cases (e.g. a Zip archive would be performed purely
sequentially), so the previous approach is preferred. YMMV... The 2 last
values for thrTCounts are ignored.
thrQSizes = 2 -1 -1
thrTCounts = 6 1 1
The following example would disable multithreading. Indexing will be
performed by a single thread.
thrQSizes = -1 -1 -1
5.4.2.5. Miscellaneous parameters:
autodiacsens
IF the index is not stripped, decide if we automatically trigger
diacritics sensitivity if the search term has accented characters
(not in unac_except_trans). Else you need to use the query
language and the D modifier to specify diacritics sensitivity.
Default is no.
autocasesens
IF the index is not stripped, decide if we automatically trigger
character case sensitivity if the search term has upper-case
characters in any but the first position. Else you need to use the
query language and the C modifier to specify character-case
sensitivity. Default is yes.
loglevel,daemloglevel
Verbosity level for recoll and recollindex. A value of 4 lists
quite a lot of debug/information messages. 2 only lists errors.
The daemversion is specific to the indexing monitor daemon.
logfilename, daemlogfilename
Where the messages should go. 'stderr' can be used as a special
value, and is the default. The daemversion is specific to the
indexing monitor daemon.
checkneedretryindexscript
This defines the name for a command executed by recollindex when
starting indexing. If the exit status of the command is 0,
recollindex retries to index all files which previously could not
be indexed because of data extraction errors. The default value is
a script which checks if any of the common bin directories have
changed (indicating that a helper program may have been
installed).
mondelaypatterns
This allows specify wildcard path patterns (processed with
fnmatch(3) with 0 flag), to match files which change too often and
for which a delay should be observed before re-indexing. This is a
space-separated list, each entry being a pattern and a time in
seconds, separated by a colon. You can use double quotes if a path
entry contains white space. Example:
mondelaypatterns = *.log:20 "this one has spaces*:10"
monixinterval
Minimum interval (seconds) for processing the indexing queue. The
real time monitor does not process each event when it comes in,
but will wait this time for the queue to accumulate to diminish
overhead and in order to aggregate multiple events to the same
file. Default 30 S.
monauxinterval
Period (in seconds) at which the real time monitor will regenerate
the auxiliary databases (spelling, stemming) if needed. The
default is one hour.
monioniceclass, monioniceclassdata
These allow defining the ionice class and data used by the indexer
(default class 3, no data).
filtermaxseconds
Maximum handler execution time, after which it is aborted. Some
postscript programs just loop...
filtermaxmbytes
Recoll 1.20.7 and later. Maximum handler memory utilisation. This
uses setrlimit(RLIMIT_AS) on most systems (total virtual memory
space size limit). Some programs may start with 500 MBytes of
mapped shared libraries, so take this into account when choosing a
value. The default is a liberal 2000MB.
filtersdir
A directory to search for the external input handler scripts used
to index some types of files. The value should not be changed,
except if you want to modify one of the default scripts. The value
can be redefined for any sub-directory.
iconsdir
The name of the directory where recoll result list icons are
stored. You can change this if you want different images.
idxabsmlen
Recoll stores an abstract for each indexed file inside the
database. The text can come from an actual 'abstract' section in
the document or will just be the beginning of the document. It is
stored in the index so that it can be displayed inside the result
lists without decoding the original file. The idxabsmlen parameter
defines the size of the stored abstract. The default value is 250
bytes. The search interface gives you the choice to display this
stored text or a synthetic abstract built by extracting text
around the search terms. If you always prefer the synthetic
abstract, you can reduce this value and save a little space.
idxmetastoredlen
Maximum stored length for metadata fields. This does not affect
indexing (the whole field is processed anyway), just the amount of
data stored in the index for the purpose of displaying fields
inside result lists or previews. The default value is 150 bytes
which may be too low if you have custom fields.
aspellLanguage
Language definitions to use when creating the aspell dictionary.
The value must match a set of aspell language definition files.
You can type "aspell config" to see where these are installed
(look for data-dir). The default if the variable is not set is to
use your desktop national language environment to guess the value.
noaspell
If this is set, the aspell dictionary generation is turned off.
Useful for cases where you don't need the functionality or when it
is unusable because aspell crashes during dictionary generation.
mhmboxquirks
This allows definining location-related quirks for the mailbox
handler. Currently only the tbird flag is defined, and it should
be set for directories which hold Thunderbird data, as their
folder format is weird.
5.4.3. The fields file
This file contains information about dynamic fields handling in Recoll.
Some very basic fields have hard-wired behaviour, and, mostly, you should
not change the original data inside the fields file. But you can create
custom fields fitting your data and handle them just like they were native
ones.
The fields file has several sections, which each define an aspect of
fields processing. Quite often, you'll have to modify several sections to
obtain the desired behaviour.
We will only give a short description here, you should refer to the
comments inside the default file for more detailed information.
Field names should be lowercase alphabetic ASCII.
[prefixes]
A field becomes indexed (searchable) by having a prefix defined in
this section.
[stored]
A field becomes stored (displayable inside results) by having its
name listed in this section (typically with an empty value).
[aliases]
This section defines lists of synonyms for the canonical names
used inside the [prefixes] and [stored] sections
[queryaliases]
This section also defines aliases for the canonic field names,
with the difference that the substitution will only be used at
query time, avoiding any possibility that the value would pick-up
random metadata from documents.
handler-specific sections
Some input handlers may need specific configuration for handling
fields. Only the email message handler currently has such a
section (named [mail]). It allows indexing arbitrary email headers
in addition to the ones indexed by default. Other such sections
may appear in the future.
Here follows a small example of a personal fields file. This would extract
a specific email header and use it as a searchable field, with data
displayable inside result lists. (Side note: as the email handler does no
decoding on the values, only plain ascii headers can be indexed, and only
the first occurrence will be used for headers that occur several times).
[prefixes]
# Index mailmytag contents (with the given prefix)
mailmytag = XMTAG
[stored]
# Store mailmytag inside the document data record (so that it can be
# displayed - as %(mailmytag) - in result lists).
mailmytag =
[queryaliases]
filename = fn
containerfilename = cfn
[mail]
# Extract the X-My-Tag mail header, and use it internally with the
# mailmytag field name
x-my-tag = mailmytag
5.4.3.1. Extended attributes in the fields file
Recoll versions 1.19 and later process user extended file attributes as
documents fields by default.
Attributes are processed as fields of the same name, after removing the
user prefix on Linux.
The [xattrtofields] section of the fields file allows specifying
translations from extended attributes names to Recoll field names. An
empty translation disables use of the corresponding attribute data.
5.4.4. The mimemap file
mimemap specifies the file name extension to MIME type mappings.
For file names without an extension, or with an unknown one, the system's
file -i command will be executed to determine the MIME type (this can be
switched off inside the main configuration file).
The mappings can be specified on a per-subtree basis, which may be useful
in some cases. Example: gaim logs have a .txt extension but should be
handled specially, which is possible because they are usually all located
in one place.
The recoll_noindex mimemap variable has been moved to recoll.conf and
renamed to noContentSuffixes, while keeping the same function, as of
Recoll version 1.21. For older Recoll versions, see the documentation for
noContentSuffixes but use recoll_noindex in mimemap.
5.4.5. The mimeconf file
mimeconf specifies how the different MIME types are handled for indexing,
and which icons are displayed in the recoll result lists.
Changing the parameters in the [index] section is probably not a good idea
except if you are a Recoll developer.
The [icons] section allows you to change the icons which are displayed by
recoll in the result lists (the values are the basenames of the png images
inside the iconsdir directory (specified in recoll.conf).
5.4.6. The mimeview file
mimeview specifies which programs are started when you click on an Open
link in a result list. Ie: HTML is normally displayed using firefox, but
you may prefer Konqueror, your openoffice.org program might be named
oofice instead of openoffice etc.
Changes to this file can be done by direct editing, or through the recoll
GUI preferences dialog.
If Use desktop preferences to choose document editor is checked in the
Recoll GUI preferences, all mimeview entries will be ignored except the
one labelled application/x-all (which is set to use xdg-open by default).
In this case, the xallexcepts top level variable defines a list of MIME
type exceptions which will be processed according to the local entries
instead of being passed to the desktop. This is so that specific Recoll
options such as a page number or a search string can be passed to
applications that support them, such as the evince viewer.
As for the other configuration files, the normal usage is to have a
mimeview inside your own configuration directory, with just the
non-default entries, which will override those from the central
configuration file.
All viewer definition entries must be placed under a [view] section.
The keys in the file are normally MIME types. You can add an application
tag to specialize the choice for an area of the filesystem (using a
localfields specification in mimeconf). The syntax for the key is
mimetype|tag
The nouncompforviewmts entry, (placed at the top level, outside of the
[view] section), holds a list of MIME types that should not be
uncompressed before starting the viewer (if they are found compressed, ie:
mydoc.doc.gz).
The right side of each assignment holds a command to be executed for
opening the file. The following substitutions are performed:
o %D. Document date
o %f. File name. This may be the name of a temporary file if it was
necessary to create one (ie: to extract a subdocument from a
container).
o %i. Internal path, for subdocuments of containers. The format depends
on the container type. If this appears in the command line, Recoll
will not create a temporary file to extract the subdocument, expecting
the called application (possibly a script) to be able to handle it.
o %M. MIME type
o %p. Page index. Only significant for a subset of document types,
currently only PDF, Postscript and DVI files. Can be used to start the
editor at the right page for a match or snippet.
o %s. Search term. The value will only be set for documents with indexed
page numbers (ie: PDF). The value will be one of the matched search
terms. It would allow pre-setting the value in the "Find" entry inside
Evince for example, for easy highlighting of the term.
o %u. Url.
In addition to the predefined values above, all strings like %(fieldname)
will be replaced by the value of the field named fieldname for the
document. This could be used in combination with field customisation to
help with opening the document.
5.4.7. The ptrans file
ptrans specifies query-time path translations. These can be useful in
multiple cases.
The file has a section for any index which needs translations, either the
main one or additional query indexes. The sections are named with the
Xapian index directory names. No slash character should exist at the end
of the paths (all comparisons are textual). An exemple should make things
sufficiently clear
[/home/me/.recoll/xapiandb]
/this/directory/moved = /to/this/place
[/path/to/additional/xapiandb]
/server/volume1/docdir = /net/server/volume1/docdir
/server/volume2/docdir = /net/server/volume2/docdir
5.4.8. Examples of configuration adjustments
5.4.8.1. Adding an external viewer for an non-indexed type
Imagine that you have some kind of file which does not have indexable
content, but for which you would like to have a functional Open link in
the result list (when found by file name). The file names end in .blob and
can be displayed by application blobviewer.
You need two entries in the configuration files for this to work:
o In $RECOLL_CONFDIR/mimemap (typically ~/.recoll/mimemap), add the
following line:
.blob = application/x-blobapp
Note that the MIME type is made up here, and you could call it
diesel/oil just the same.
o In $RECOLL_CONFDIR/mimeview under the [view] section, add:
application/x-blobapp = blobviewer %f
We are supposing that blobviewer wants a file name parameter here, you
would use %u if it liked URLs better.
If you just wanted to change the application used by Recoll to display a
MIME type which it already knows, you would just need to edit mimeview.
The entries you add in your personal file override those in the central
configuration, which you do not need to alter. mimeview can also be
modified from the Gui.
5.4.8.2. Adding indexing support for a new file type
Let us now imagine that the above .blob files actually contain indexable
text and that you know how to extract it with a command line program.
Getting Recoll to index the files is easy. You need to perform the above
alteration, and also to add data to the mimeconf file (typically in
~/.recoll/mimeconf):
o Under the [index] section, add the following line (more about the
rclblob indexing script later):
application/x-blobapp = exec rclblob
o Under the [icons] section, you should choose an icon to be displayed
for the files inside the result lists. Icons are normally 64x64 pixels
PNG files which live in /usr/[local/]share/recoll/images.
o Under the [categories] section, you should add the MIME type where it
makes sense (you can also create a category). Categories may be used
for filtering in advanced search.
The rclblob handler should be an executable program or script which exists
inside /usr/[local/]share/recoll/filters. It will be given a file name as
argument and should output the text or html contents on the standard
output.
The filter programming section describes in more detail how to write an
input handler.
----------------------------------------------------------------------
Prev Up
5.3. Building from source Home