recoll / Code / Diff of /src/INSTALL

Diff of /src/INSTALL [504155] .. [6d4e44]

Switch to unified view


...
                   Chapter 5. Installation and configuration
   Prev                                                                  Next 

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

Chapter 5. Installation and configuration

5.1. Installing a binary copy

   There are three types of binary Recoll installations:

     o Through your system normal software distribution framework (ie,
       Debian/Ubuntu apt, FreeBSD ports, etc.).

     o From a package downloaded from the Recoll web site.

     o From a prebuilt tree downloaded from the Recoll web site.

   In all cases, the strict software dependancies (ie on Xapian or iconv)
   will be automatically satisfied, you should not have to worry about them.

   You will only have to check or install supporting applications for the
...
   binary trees are built for installation to /usr/local.

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

   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

...
   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 the Xpdf or Poppler
       packages.

     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 standard version, has much trouble
       with non-western character sets. Check
       http://www.recoll.org/features.html.

     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.
...

   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
...
   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
...

   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

...
         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
...
   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
...
              

   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
...
           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
...
   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.
...
   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.
...
   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
...
   The filter programming section describes in more detail how to write an
   input handler.

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

   Prev                                Up                                     
   5.3. Building from source          Home                                    