source: gnome/platform/tracker3-miners.xml@ 6b59ee9

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
  <!ENTITY % general-entities SYSTEM "../../general.ent">
  %general-entities;

  <!ENTITY tracker3-miners-download-http "&gnome-download-http;/tracker-miners/3.7/tracker-miners-&tracker3-miners-version;.tar.xz">
  <!ENTITY tracker3-miners-download-ftp  " ">
  <!ENTITY tracker3-miners-md5sum        "8c1b48f2fa57d888967de9b5ff348fc1">
  <!ENTITY tracker3-miners-size          "4.3 MB">
  <!ENTITY tracker3-miners-buildsize     "36 MB (with tests)">
  <!ENTITY tracker3-miners-time          "0.3 SBU (with parallelism=4; add as much as 1.0 SBU for tests, dependent on disk speed)">
]>

<sect1 id="tracker3-miners" xreflabel="tracker-miners-&tracker3-miners-version;">
  <?dbhtml filename="tracker3-miners.html"?>


  <title>Tracker-miners-&tracker3-miners-version;</title>

  <indexterm zone="tracker3-miners">
    <primary sortas="a-tracker3-miners">tracker3-miners</primary>
  </indexterm>

  <sect2 role="package">
    <title>Introduction to Tracker-miners</title>

    <para>
      The <application>Tracker-miners</application> package contains a set of
      data extractors for Tracker.
    </para>

    &lfs122_checked;

    <bridgehead renderas="sect3">Package Information</bridgehead>
    <itemizedlist spacing="compact">
      <listitem>
        <para>
          Download (HTTP): <ulink url="&tracker3-miners-download-http;"/>
        </para>
      </listitem>
      <listitem>
        <para>
          Download (FTP): <ulink url="&tracker3-miners-download-ftp;"/>
        </para>
      </listitem>
      <listitem>
        <para>
          Download MD5 sum: &tracker3-miners-md5sum;
        </para>
      </listitem>
      <listitem>
        <para>
          Download size: &tracker3-miners-size;
        </para>
      </listitem>
      <listitem>
        <para>
          Estimated disk space required: &tracker3-miners-buildsize;
        </para>
      </listitem>
      <listitem>
        <para>
          Estimated build time: &tracker3-miners-time;
        </para>
      </listitem>
    </itemizedlist>

    <bridgehead renderas="sect3">Additional Downloads</bridgehead>
    <itemizedlist spacing="compact">
      <listitem>
        <para>
          Required patch:
          <ulink url="&patch-root;/tracker-miners-&tracker3-miners-version;-upstream_fixes-1.patch"/>
        </para>
      </listitem>
    </itemizedlist>

    <bridgehead renderas="sect3">Tracker-miners Dependencies</bridgehead>

    <bridgehead renderas="sect4">Required</bridgehead>
    <para role="required">
      <xref linkend="gst10-plugins-base"/>,
      <xref linkend="tracker3"/>,
      <xref linkend="exempi"/>, and
      <xref linkend="gexiv2"/>
    </para>

    <bridgehead renderas="sect4">Recommended</bridgehead>
    <para role="recommended">
      <xref linkend="giflib"/>,
      <xref role='runtime' linkend="gst10-plugins-good"/> (runtime),
      <xref role='runtime' linkend="gst10-libav"/> (runtime),
      <xref linkend="icu"/>,
      <xref linkend="libexif"/>,
      <xref linkend="libgxps"/>,
      <xref linkend="libseccomp"/>,
      <xref linkend="poppler"/>, and
      <xref linkend="upower"/>
    </para>

    <bridgehead renderas="sect4">Optional</bridgehead>
    <para role="optional">
      <xref linkend="asciidoc"/>,
      <xref linkend="cmake"/>,
      <xref linkend="dconf"/>,
      <xref linkend="ffmpeg"/>,
      <xref linkend="libgsf"/>,
      <xref linkend="NetworkManager"/>,
      <xref linkend="taglib"/>,
      <xref linkend="totem-pl-parser"/>,
      <ulink url="https://github.com/lipnitsk/libcue">libcue</ulink>,
      <ulink url="https://gitlab.gnome.org/GNOME/libgrss">libgrss</ulink>,
      <ulink url="https://libiptcdata.sourceforge.net/">libitpcdata</ulink>,
      <ulink url="https://libosinfo.org">libosinfo</ulink>, and
      <ulink url="https://gitlab.gnome.org/GNOME/gupnp">gupnp</ulink>
    </para>

  </sect2>

  <sect2 role="kernel" id="tracker3-miners-kernel">
    <title>Kernel Configuration</title>

    <para>
      Enable the following options in the kernel configuration, then recompile
      the kernel and reboot if necessary:
    </para>

    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
      href="tracker3-miners-kernel.xml"/>

    <indexterm zone="tracker3-miners tracker3-miners-kernel">
      <primary sortas="d-traker-miners">tracker-miners</primary>
    </indexterm>
  </sect2>

  <sect2 role="installation">
    <title>Installation of Tracker-miners</title>

    <note>
      <para>
        If you plan to run the tests, some timeouts are too short when
        using spinning disks. There are two places where timeouts are
        used: first, individual tests inside a group of tests have a
        default timeout of 10s. This can be changed by setting the environment
        variable <envar>TRACKER_TESTS_AWAIT_TIMEOUT</envar> to the desired
        value when running the tests (see below). Second, a global timeout
        for a group of tests is fixed at configuration time. The default value
        in the <filename class="directory">functional-tests</filename>
        directory (other directories have only short lived tests) may be
        increased with the following command (replace 200 with a value
        suitable for your machine):
      </para>

<screen remap="test"><userinput>sed -i s/120/<replaceable>200</replaceable>/ tests/functional-tests/meson.build</userinput></screen>
    </note>

    <para>
      First, fix one issue in the TIFF extractor and another issue in the
      Landlock sandbox:
    </para>

<screen><userinput remap="pre">patch -Np1 -i ../tracker-miners-&tracker3-miners-version;-upstream_fixes-1.patch</userinput></screen>

    <para>
      Install <application>Tracker-miners</application> by running the following
      commands:
    </para>


<screen revision="systemd"><userinput>mkdir build &amp;&amp;
cd    build &amp;&amp;

meson setup --prefix=/usr       \
            --buildtype=release \
            -D man=false        \
            -D miner_rss=false  \
            ..                  &amp;&amp;
ninja</userinput></screen>

<screen revision="sysv"><userinput>mkdir build &amp;&amp;
cd    build &amp;&amp;

meson setup --prefix=/usr                  \
            --buildtype=release            \
            -D systemd_user_services=false \
            -D man=false                   \
            -D miner_rss=false             \
            ..                             &amp;&amp;
ninja</userinput></screen>


    <para>
      Now, as the <systemitem class="username">root</systemitem> user:
    </para>

    <screen role="root"><userinput>ninja install</userinput></screen>

    <para>
      To test the results, issue (adjust the individual test timeout to a
      value suitable for your machine, see the note above):
    </para>

<screen remap="test"><userinput>meson configure -D debug=true &amp;&amp;
dbus-run-session env LC_ALL=C.UTF-8 TRACKER_TESTS_AWAIT_TIMEOUT=<replaceable>20</replaceable> \
                 ninja test &amp;&amp;
rm -rf ~/tracker-tests</userinput></screen>

    <note>
      <para>
        The tests create files in the user directory (up to 24 MB), so
        they have to be removed afterwards.
      </para>
    </note>
  </sect2>

  <sect2 role="commands">
    <title>Command Explanations</title>

    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
      href="../../xincludes/meson-buildtype-release.xml"/>

    <para>
      <parameter>-D man=false</parameter>: This switch prevents the build process
      from generating man pages. Omit this switch if you have
      <xref linkend="asciidoc" role="nodep"/> installed and wish to generate and
      install the man pages.
    </para>

    <para>
      <parameter>-D miner_rss=false</parameter>: This switch prevents using
      libgrss for indexing RSS feeds because libgrss is insecure and no longer
      in BLFS.
    </para>

    <para revision="sysv">
      <parameter>-D systemd_user_services=false</parameter>: This switch prevents
      the build process from installing systemd units since they are useless
      on SysV systems.
    </para>

    <para>
      <option>-D seccomp=false</option>: This option disables the seccomp system
      call filter. On some architectures, such as i686 and ARM, the functions
      that tracker-miners uses are not guarded properly, and tracker-miners
      will get killed with a SIGSYS as a result.  Note that disabling
      seccomp may cause the system to be compromised worse in the event that a
      security vulnerability in tracker-miners or its dependencies is
      exploited.
    </para>

    <para>
      <option>-D landlock=disabled</option>: This switch disables the
      Landlock file access sandbox.  Use it if you don't want to build the
      kernel with Landlock support.  Note that disabling Landlock may
      cause the system to be compromised worse in the event that a security
      vulnerability in tracker-miners or its dependencies is exploited.
    </para>

    <para>
      <option>-D battery_detection=none</option>: Use this option if you have
      not installed the recommended dependency upower.  Do not use this
      option if your system has a battery (laptop battery or UPS), or
      tracker-miners may waste the battery power and lifespan when the A/C
      power is unavailable.
    </para>

  </sect2>

  <sect2 role="content">
    <title>Contents</title>

    <segmentedlist>
      <segtitle>Installed Programs</segtitle>
      <segtitle>Installed Libraries</segtitle>
      <segtitle>Installed Directories</segtitle>

      <seglistitem>
        <seg>
          tracker3-daemon,
          tracker3-extract,
          tracker3-index,
          tracker3-info,
          tracker3-reset,
          tracker3-search,
          tracker3-status, and
          tracker3-tag
        </seg>
        <seg>
          Several modules under /usr/lib/tracker-miners-3.0
        </seg>
        <seg>
          /usr/lib/tracker-miners-3.0,
          /usr/libexec/tracker3, and
          /usr/share/tracker3-miners
        </seg>
      </seglistitem>
    </segmentedlist>

    <variablelist>
      <bridgehead renderas="sect3">Short Descriptions</bridgehead>
      <?dbfo list-presnetation="list"?>
      <?dbhtml list-presentation="table"?>

      <varlistentry id="tracker3-daemon">
        <term><command>tracker3-daemon</command></term>
        <listitem>
          <para>
            starts, stops, restarts, and lists daemons responsible for indexing
            content
          </para>
          <indexterm zone="tracker3-miners tracker3-daemon">
            <primary sortas="b-tracker3-daemon">tracker3-daemon</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="tracker3-extract">
        <term><command>tracker3-extract</command></term>
        <listitem>
          <para>
            extracts metadata from a file
          </para>
          <indexterm zone="tracker3-miners tracker3-extract">
            <primary sortas="b-tracker3-extract">tracker3-extract</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="tracker3-index">
        <term><command>tracker3-index</command></term>
        <listitem>
          <para>
            indexes content using the Tracker filesystem miner
          </para>
          <indexterm zone="tracker3-miners tracker3-index">
            <primary sortas="b-tracker3-index">tracker3-index</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="tracker3-info">
        <term><command>tracker3-info</command></term>
        <listitem>
          <para>
            retrieves all information available for a certain file
          </para>
          <indexterm zone="tracker3-miners tracker3-info">
            <primary sortas="b-tracker3-info">tracker3-info</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="tracker3-reset">
        <term><command>tracker3-reset</command></term>
        <listitem>
          <para>
            resets the Tracker index and configuration
          </para>
          <indexterm zone="tracker3-miners tracker3-reset">
            <primary sortas="b-tracker3-reset">tracker3-reset</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="tracker3-search">
        <term><command>tracker3-search</command></term>
        <listitem>
          <para>
            searches for content by type or across all types
          </para>
          <indexterm zone="tracker3-miners tracker3-search">
            <primary sortas="b-tracker3-search">tracker3-search</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="tracker3-status">
        <term><command>tracker3-status</command></term>
        <listitem>
          <para>
            provides status and statistics on data that has been indexed
          </para>
          <indexterm zone="tracker3-miners tracker3-status">
            <primary sortas="b-tracker3-status">tracker3-status</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="tracker3-tag">
        <term><command>tracker3-tag</command></term>
        <listitem>
          <para>
            adds, removes, and lists tags
          </para>
          <indexterm zone="tracker3-miners tracker3-tag">
            <primary sortas="b-tracker3-tag">tracker3-tag</primary>
          </indexterm>
        </listitem>
      </varlistentry>
    </variablelist>
  </sect2>

</sect1>