--- a/src/INSTALL
+++ b/src/INSTALL
@@ -1,28 +1,47 @@
- Chapter 4. Installation
+More documentation can be found in the doc/ directory or at http://www.recoll.org
-4.1. Building from source
- 4.1.1. Prerequisites
+ Link: HOME
+ Link: PREVIOUS
+ Link: NEXT
- At the very least, you will need to download and install the
- xapian core package (Recoll currently uses version 0.9.2), and the
- qt runtime and development packages (Recoll development currently
- uses version 3.3.5, but any 3.3 version is probably ok).
+ Recoll user manual
+ Prev Next
- You will most probably be able to find a binary package for qt for
- your system. You may have to compile Xapian but this is not
- difficult (if you are using FreeBSD, there is a port).
+ --------------------------------------------------------------------------
- You may also need libiconv. Recoll currently uses version 1.9
- (this should not be critical). On Linux systems, the iconv
- interface is part of libc and you should not need to do anything
- special.
+ Chapter 4. Installation
- External file types. 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 dependencies. None is
- needed for building Recoll):
+ Table of Contents
+
+ 4.1. Building from source
+
+ 4.2. Installing a prebuilt copy
+
+ 4.3. Configuration overview
+
+ 4.1. Building from source
+
+4.1.1. Prerequisites
+
+ At the very least, you will need to download and install the xapian core
+ package (Recoll currently uses version 0.9.2), and the qt runtime and
+ development packages (Recoll development currently uses version 3.3.5, but
+ any 3.3 version is probably ok).
+
+ You will most probably be able to find a binary package for qt for your
+ system. You may have to compile Xapian but this is not difficult (if you
+ are using FreeBSD, there is a port).
+
+ You may also need libiconv. Recoll currently uses version 1.9 (this should
+ not be critical). On Linux systems, the iconv interface is part of libc
+ and you should not need to do anything special.
+
+ External file types. 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 dependencies. None is needed for building
+ Recoll):
* PDF: pdftotext is part of the Xpdf package.
@@ -36,39 +55,35 @@
* djvu: DjVuLibre
- * MP3: Recoll will use the id3info command from the id3lib
- package to extract tag information. Without it, only the
- filenames will be indexed.
+ * MP3: Recoll will use the id3info command from the id3lib package to
+ extract tag information. Without it, only the filenames will be
+ indexed.
- Text, Html, mail folders and Openoffice files are processed
- internally.
+ Text, Html, mail folders and Openoffice files are processed internally.
- --------------------------------------------------------------
+4.1.2. Building
- 4.1.2. Building
+ Recoll has been built on Linux (redhat7.3, mandriva 2005, Fedora Core 3),
+ FreeBSD and Solaris 8. If you build on another system, I would very much
+ welcome patches.
- Recoll has been built on Linux (redhat7.3, mandriva 2005, Fedora
- Core 3), FreeBSD and Solaris 8. If you build on another system, I
- would very much welcome patches.
+ Depending on the qt configuration on your system, you may have to set the
+ QTDIR and QMAKESPECS variables in your environment:
- Depending on the qt configuration on your system, you may have to
- set the QTDIR and QMAKESPECS variables in your environment:
-
- * QTDIR should point to the directory above the one that holds
- the qt include files (ie: qt.h).
+ * QTDIR should point to the directory above the one that holds the qt
+ include files (ie: qt.h).
* QMAKESPECS should be set to the name of one of the qt mkspecs
subdirectories (ie: linux-g++).
- On many Linux systems, QTDIR is set by the login scripts, and
- QMAKESPECS is not needed because there is a default link in
- mkspecs/.
+ On many Linux systems, QTDIR is set by the login scripts, and QMAKESPECS
+ is not needed because there is a default link in mkspecs/.
- The Recoll configure script does a better job of checking these
- variables after release 1.1.1. Before this, unexplained errors
- will occur during compilation if the environment is not set up.
- Also, for 1.1.0 the qmake command should be in your PATH (later
- releases can also find it in $QTDIR/bin).
+ The Recoll configure script does a better job of checking these variables
+ after release 1.1.1. Before this, unexplained errors will occur during
+ compilation if the environment is not set up. Also, for 1.1.0 the qmake
+ command should be in your PATH (later releases can also find it in
+ $QTDIR/bin).
Normal procedure:
@@ -76,275 +91,23 @@
configure
make
(practises usual hardship-repelling invocations)
-
+
- There little autoconfiguration. 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).
+ There little autoconfiguration. 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).
- --------------------------------------------------------------
+4.1.3. Installation
- 4.1.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.
+ 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.
You can then proceed to configuration.
- --------------------------------------------------------------
+ --------------------------------------------------------------------------
-4.2. Installing a prebuilt copy
-
- 4.2.1. Installing through a package system
-
- If you are lucky enough to be using a port system or a prebuilt
- package (RPM or other), just follow the usual procedure, and have
- a look at the configuration section.
-
- --------------------------------------------------------------
-
- 4.2.2. Installing a prebuilt Recoll
-
- The unpackaged binary versions are just compressed tar files of a
- build tree, where only the useful parts were kept (executables and
- sample configuration).
-
- The executable binary files are built with a static link to
- libxapian and libiconv, to make installation easier (no
- dependencies). However, this also means that you cannot change the
- versions which are used.
-
- After extracting the tar file, you can proceed with installation
- as if you had built the package from source.
-
- --------------------------------------------------------------
-
-4.3. Configuration overview
-
- There are two sets of configuration files. The system-wide files
- are kept in a directory named like
- /usr/[local/]share/recoll/examples, they define default values for
- the system. A parallel set of files exists in the .recoll
- directory in your home (this can be changed with the
- RECOLL_CONFDIR environment variable. The database is also kept in
- .recoll by default, (this can be changed by a configuration
- parameter).
-
- 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 indexation. recollindex will proceed
- immediately.
-
- Most of the parameters specific to the recoll GUI are set through
- the Preferences menu and stored in the standard QT place
- ($HOME/.qt/recollrc). You probably do not want to edit this by
- hand.
-
- For other options, Recoll uses text configuration files. You will
- have to edit them by hand for now (there is still some hope for a
- GUI configuration tool in the future). 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.
-
- All configuration files share the same format. For exemple, 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:
-
- * Comment (starts with #) or empty.
-
- * Parameter affectation (name = value).
-
- * Section definition ([somedirname]).
-
- Section lines allow redefining some parameters for a directory
- subtree. Some of the parameters used for indexation are looked up
- hierarchically from the more to the less specific. Not all
- parameters can be meaningfully redefined, this is specified for
- each in the next section.
-
- The tilde character (~) is expanded in file names to the name of
- the user's home directory.
-
- White space is used for separation inside lists. Elements with
- embedded spaces can be quoted using double-quotes.
-
- --------------------------------------------------------------
-
- 4.3.1. Main configuration file
-
- 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, use recoll to copy the sample configuration,
- click Cancel, and edit the configuration file before restarting
- the command. This will start the initial indexation, which may
- take some time.
-
- Paramers:
-
- topdirs
-
- Specifies the list of directories to index (recursively).
-
- skippedNames
-
- A space-separated list of patterns for names of files or
- directories that should be completely ignored. The list
- defined in the default file is:
-
- *~ #* bin CVS Cache caughtspam tmp
-
- The list can be redefined for subdirectories, but is only
- actually changed for the top level ones in topdirs.
-
- 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, mail 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.
-
- loglevel
-
- Verbosity level for recoll and recollindex. A value of 4
- lists quite a lot of debug/information messages. 2 only
- lists errors.
-
- logfilename
-
- Where should the messages go. 'stderr' can be used as a
- special value.
-
- filtersdir
-
- A directory to search for the external filter 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 subdirectory.
-
- indexstemminglanguages
-
- A list of languages for which the stem expansion databases
- will be built. See recollindex(1) 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 indexation. Only languages listed in the
- configuration file are permanent.
-
- iconsdir
-
- The name of the directory where recoll result list icons
- are stored. You can change this if you want different
- images.
-
- dbdir
-
- The name of the Xapian database directory. It will be
- created if needed when the database is initialized.
-
- 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 subdirectory. 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.
-
- guesscharset
-
- Decide if we try to guess the character set of files if no
- internal value is available (ie: for plain text files).
- This does not work well in general, and should probably
- not be used.
-
- usesystemfilecommand
-
- Decide if we use the file -i system command 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
- suffixless names, but it will also cause the indexation of
- many bogus "text" files.
-
- 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 indexation, or for all files
- inside the selected subtrees, independant of mime type.
-
- --------------------------------------------------------------
-
- 4.3.2. 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).
-
- mimemap also has a list of extensions which should be ignored
- totally (to avoid losing time by executing file for things that
- certainly should not be indexed).
-
- 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.
-
- mimemap also has a recoll_noindex variable which is a list of
- suffixes. Matching files will be skipped (avoids unnecessary
- decompressions or file executions). This is partially redundant
- with skippedNames in the main configuration file, with two
- differences: it will not affect directories, and it can be changed
- for any subdirectory.
-
- --------------------------------------------------------------
-
- 4.3.3. The mimeconf file
-
- mimeconf specifies how the different mime types are handled for
- indexation, and for display.
-
- Changing the indexation parameters is probably not a good idea
- except if you are a Recoll developper.
-
- You may want to adjust the external viewers defined in (ie: html
- is either previewed internally or displayed using firefox, but you
- may prefer mozilla, your openoffice.org program might be named
- oofice instead of openoffice ...). Look for the [view] section.
-
- You can also 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).
-
- --------------------------------------------------------------
+ Prev Home Next
+ Customising the search interface Installing a prebuilt copy