tris/recoll
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

doc: update the build instruction, esp. python package

Browse Source
This commit is contained in:
Jean-Francois Dockes 2018-07-02 15:50:55 +02:00
parent f0bedb2201
commit 8c14750681
2 changed files with 146 additions and 100 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

144
src/doc/user/usermanual.html
View File

@ -376,9 +376,15 @@ alink="#0000FF">
<dt><span class="sect2">6.3.1. <a href= <dt><span class="sect2">6.3.1. <a href=
"#RCL.INSTALL.BUILDING.PREREQS">Prerequisites</a></span></dt> "#RCL.INSTALL.BUILDING.PREREQS">Prerequisites</a></span></dt>
<dt><span class="sect2">6.3.2. <a href= <dt><span class="sect2">6.3.2. <a href=
"#RCL.INSTALL.BUILDING.BUILD">Building</a></span></dt> "#RCL.INSTALL.BUILDING.BUILDING">Building</a></span></dt>
<dt><span class="sect2">6.3.3. <a href= <dt><span class="sect2">6.3.3. <a href=
"#RCL.INSTALL.BUILDING.INSTALL">Installation</a></span></dt> "#RCL.INSTALL.BUILDING.INSTALL">Installing</a></span></dt>
<dt><span class="sect2">6.3.4. <a href=
"#RCL.INSTALL.BUILDING.PYTHON">Python API
package</a></span></dt>
<dt><span class="sect2">6.3.5. <a href=
"#RCL.INSTALL.BUILDING.SOLARIS">Building on
Solaris</a></span></dt>
</dl> </dl>
</dd> </dd>
<dt><span class="sect1">6.4. <a href= <dt><span class="sect1">6.4. <a href=
@ -2128,8 +2134,8 @@ alink="#0000FF">
grow quite big, depending on the log level.</p> grow quite big, depending on the log level.</p>
<p>When building <span class="application">Recoll</span>, <p>When building <span class="application">Recoll</span>,
the real time indexing support can be customised during the real time indexing support can be customised during
package <a class="link" href="#RCL.INSTALL.BUILDING.BUILD" package <a class="link" href="#RCL.INSTALL.BUILDING" title=
title="6.3.2.&nbsp;Building">configuration</a> with the "6.3.&nbsp;Building from source">configuration</a> with the
<code class="option">--with[out]-fam</code> or <code class= <code class="option">--with[out]-fam</code> or <code class=
"option">--with[out]-inotify</code> options. The default is "option">--with[out]-inotify</code> options. The default is
currently to include <span class= currently to include <span class=
@ -6170,31 +6176,13 @@ recollindex -c "$confdir"
here. A paragraph at the end of this section will explain here. A paragraph at the end of this section will explain
a few differences and ways to write code compatible with a few differences and ways to write code compatible with
both versions.</p> both versions.</p>
<p>The Python interface can be found in the source <p>There is a good chance that your system repository has
package, under <code class= packages for the Recoll Python API, sometimes in a
"filename">python/recoll</code>.</p> package separate from the main one (maybe named something
<p>The <code class="filename">python/recoll/</code> like python-recoll). Else refer to the <a class="link"
directory contains the usual <code class= href="#RCL.INSTALL.BUILDING" title=
"filename">setup.py</code>. After configuring the main "6.3.&nbsp;Building from source">Building from source
<span class="application">Recoll</span> code, you can use chapter</a>.</p>
the script to build and install the Python module:</p>
<pre class="screen">
<strong class=
"userinput"><code>cd recoll-xxx/python/recoll</code></strong>
<strong class=
"userinput"><code>python setup.py build</code></strong>
<strong class=
"userinput"><code>python setup.py install</code></strong>
</pre>
<p>As of <span class="application">Recoll</span> 1.19,
the module can be compiled for Python3.</p>
<p>The normal <span class="application">Recoll</span>
installer installs the Python2 API along with the main
code. The Python3 version must be explicitely built and
installed.</p>
<p>When installing from a repository, and depending on
the distribution, the Python API can sometimes be found
in a separate package.</p>
<p>As an introduction, the following small sample will <p>As an introduction, the following small sample will
run a query and list the title and url for each of the run a query and list the title and url for each of the
results. It would work with <span class= results. It would work with <span class=
@ -6216,6 +6204,13 @@ recollindex -c "$confdir"
for doc in results: for doc in results:
print(doc.url, doc.title) print(doc.url, doc.title)
</pre> </pre>
<p>You can also take a look at the source for the
<a class="ulink" href=
"https://github.com/koniu/recoll-webui" target=
"_top">Recoll WebUI</a>, or the <a class="ulink" href=
"https://opensourceprojects.eu/p/upmpdcli/code/ci/c8c8e75bd181ad9db2df14da05934e53ca867a06/tree/src/mediaserver/cdplugins/uprcl/uprclfolders.py"
target="_top">upmpdcli local media server</a>, which are
both based on the Python API.</p>
</div> </div>
<div class="sect2"> <div class="sect2">
<div class="titlepage"> <div class="titlepage">
@ -7575,8 +7570,8 @@ for i in range(nres):
<div> <div>
<div> <div>
<h3 class="title"><a name= <h3 class="title"><a name=
"RCL.INSTALL.BUILDING.BUILD" id= "RCL.INSTALL.BUILDING.BUILDING" id=
"RCL.INSTALL.BUILDING.BUILD"></a>6.3.2.&nbsp;Building</h3> "RCL.INSTALL.BUILDING.BUILDING"></a>6.3.2.&nbsp;Building</h3>
</div> </div>
</div> </div>
</div> </div>
@ -7718,7 +7713,7 @@ for i in range(nres):
<strong class= <strong class=
"userinput"><code>(practices usual hardship-repelling invocations)</code></strong> "userinput"><code>(practices usual hardship-repelling invocations)</code></strong>
</pre> </pre>
<p>When building from source cloned from the BitBucket <p>When building from source cloned from the git
repository, you also need to install <span class= repository, you also need to install <span class=
"application">autoconf</span>, <span class= "application">autoconf</span>, <span class=
"application">automake</span>, and <span class= "application">automake</span>, and <span class=
@ -7726,29 +7721,6 @@ for i in range(nres):
<code class="literal">sh autogen.sh</code> in the top <code class="literal">sh autogen.sh</code> in the top
source directory before running <code class= source directory before running <code class=
"literal">configure</code>.</p> "literal">configure</code>.</p>
<div class="sect3">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a name=
"RCL.INSTALL.BUILDING.BUILD.SOLARIS" id=
"RCL.INSTALL.BUILDING.BUILD.SOLARIS"></a>6.3.2.1.&nbsp;Building
on Solaris</h4>
</div>
</div>
</div>
<p>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 <a class="ulink" href=
"http://www.recoll.org/download-1.14.html" target=
"_top">an old web site page</a>, they may still be
valid.</p>
<p>Someone did test the 1.19 indexer and Python module
build, they do work, with a few minor glitches. Be sure
to use GNU <span class=
"command"><strong>make</strong></span> and <span class=
"command"><strong>install</strong></span>.</p>
</div>
</div> </div>
<div class="sect2"> <div class="sect2">
<div class="titlepage"> <div class="titlepage">
@ -7756,7 +7728,7 @@ for i in range(nres):
<div> <div>
<h3 class="title"><a name= <h3 class="title"><a name=
"RCL.INSTALL.BUILDING.INSTALL" id= "RCL.INSTALL.BUILDING.INSTALL" id=
"RCL.INSTALL.BUILDING.INSTALL"></a>6.3.3.&nbsp;Installation</h3> "RCL.INSTALL.BUILDING.INSTALL"></a>6.3.3.&nbsp;Installing</h3>
</div> </div>
</div> </div>
</div> </div>
@ -7769,6 +7741,66 @@ for i in range(nres):
to <code class="filename"><em class= to <code class="filename"><em class=
"replaceable"><code>prefix</code></em>/share/recoll</code>.</p> "replaceable"><code>prefix</code></em>/share/recoll</code>.</p>
</div> </div>
<div class="sect2">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a name=
"RCL.INSTALL.BUILDING.PYTHON" id=
"RCL.INSTALL.BUILDING.PYTHON"></a>6.3.4.&nbsp;Python
API package</h3>
</div>
</div>
</div>
<p>The Python interface can be found in the source tree,
under the <code class="filename">python/recoll</code>
directory.</p>
<p>As of <span class="application">Recoll</span> 1.19,
the module can be compiled for Python3.</p>
<p>The normal <span class="application">Recoll</span>
build procedure (see above) installs the API package for
the default system version (python) along with the main
code. The package for other Python versions (e.g. python3
if the system default is python2) must be explicitely
built and installed.</p>
<p>The <code class="filename">python/recoll/</code>
directory contains the usual <code class=
"filename">setup.py</code>. After configuring and
building the main <span class="application">Recoll</span>
code, you can use the script to build and install the
Python module:</p>
<pre class="screen">
<strong class=
"userinput"><code>cd recoll-xxx/python/recoll</code></strong>
<strong class=
"userinput"><code>pythonX setup.py build</code></strong>
<strong class=
"userinput"><code>sudo pythonX setup.py install</code></strong>
</pre>
</div>
<div class="sect2">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a name=
"RCL.INSTALL.BUILDING.SOLARIS" id=
"RCL.INSTALL.BUILDING.SOLARIS"></a>6.3.5.&nbsp;Building
on Solaris</h3>
</div>
</div>
</div>
<p>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 <a class="ulink" href=
"http://www.recoll.org/download-1.14.html" target=
"_top">an old web site page</a>, they may still be
valid.</p>
<p>Someone did test the 1.19 indexer and Python module
build, they do work, with a few minor glitches. Be sure
to use GNU <span class=
"command"><strong>make</strong></span> and <span class=
"command"><strong>install</strong></span>.</p>
</div>
</div> </div>
<div class="sect1"> <div class="sect1">
<div class="titlepage"> <div class="titlepage">

100
src/doc/user/usermanual.xml
View File

@ -5,7 +5,7 @@
<!ENTITY RCL "<application>Recoll</application>"> <!ENTITY RCL "<application>Recoll</application>">
<!ENTITY RCLAPPS "<ulink url='http://www.recoll.org/features.html#doctypes'>http://www.recoll.org/features.html</ulink>"> <!ENTITY RCLAPPS "<ulink url='http://www.recoll.org/features.html#doctypes'>http://www.recoll.org/features.html</ulink>">
<!ENTITY RCLVERSION "1.23"> <!ENTITY RCLVERSION "1.24">
<!ENTITY XAP "<application>Xapian</application>"> <!ENTITY XAP "<application>Xapian</application>">
<!ENTITY WIN "<application>Windows</application>"> <!ENTITY WIN "<application>Windows</application>">
<!ENTITY FAQS "https://www.lesbonscomptes.com/recoll/faqsandhowtos/"> <!ENTITY FAQS "https://www.lesbonscomptes.com/recoll/faqsandhowtos/">
@ -1470,7 +1470,7 @@
<para>When building &RCL;, the real time indexing support can be <para>When building &RCL;, the real time indexing support can be
customised during package <link customised during package <link
linkend="RCL.INSTALL.BUILDING.BUILD">configuration</link> with linkend="RCL.INSTALL.BUILDING">configuration</link> with
the <option>--with[out]-fam</option> or the <option>--with[out]-fam</option> or
<option>--with[out]-inotify</option> options. The default is <option>--with[out]-inotify</option> options. The default is
currently to include <application>inotify</application> currently to include <application>inotify</application>
@ -4817,30 +4817,11 @@ recollindex -c "$confdir"
paragraph at the end of this section will explain a few differences paragraph at the end of this section will explain a few differences
and ways to write code compatible with both versions.</para> and ways to write code compatible with both versions.</para>
<para>The Python interface can be found in the source package, <para>There is a good chance that your system repository has
under <filename>python/recoll</filename>.</para> packages for the Recoll Python API, sometimes in a package separate
from the main one (maybe named something like python-recoll). Else
<para>The <filename>python/recoll/</filename> directory refer to the <link linkend="RCL.INSTALL.BUILDING">Building from
contains the usual <filename>setup.py</filename>. After source chapter</link>.</para>
configuring the main &RCL; code, you can use the script to
build and install the Python module:
<screen>
<userinput>cd recoll-xxx/python/recoll</userinput>
<userinput>python setup.py build</userinput>
<userinput>python setup.py install</userinput>
</screen>
</para>
<para>As of &RCL; 1.19, the module can be compiled for
Python3.</para>
<para>The normal &RCL; installer installs the Python2
API along with the main code. The Python3 version must be
explicitely built and installed.</para>
<para>When installing from a repository, and depending on the
distribution, the Python API can sometimes be found in a
separate package.</para>
<para>As an introduction, the following small sample will run a <para>As an introduction, the following small sample will run a
query and list the title and url for each of the results. It would query and list the title and url for each of the results. It would
@ -4863,6 +4844,11 @@ recollindex -c "$confdir"
print(doc.url, doc.title) print(doc.url, doc.title)
]]></programlisting> ]]></programlisting>
<para>You can also take a look at the source for the <ulink
url="https://github.com/koniu/recoll-webui">Recoll
WebUI</ulink>, or the <ulink url="https://opensourceprojects.eu/p/upmpdcli/code/ci/c8c8e75bd181ad9db2df14da05934e53ca867a06/tree/src/mediaserver/cdplugins/uprcl/uprclfolders.py">upmpdcli local media server</ulink>, which are both
based on the Python API.</para>
</sect2> </sect2>
<sect2 id="RCL.PROGRAM.PYTHONAPI.ELEMENTS"> <sect2 id="RCL.PROGRAM.PYTHONAPI.ELEMENTS">
@ -5894,7 +5880,7 @@ for i in range(nres):
</sect2> </sect2>
<sect2 id="RCL.INSTALL.BUILDING.BUILD"> <sect2 id="RCL.INSTALL.BUILDING.BUILDING">
<title>Building</title> <title>Building</title>
<para>&RCL; has been built on Linux, FreeBSD, Mac OS X, and Solaris, <para>&RCL; has been built on Linux, FreeBSD, Mac OS X, and Solaris,
@ -6010,30 +5996,16 @@ for i in range(nres):
<userinput>(practices usual hardship-repelling invocations)</userinput> <userinput>(practices usual hardship-repelling invocations)</userinput>
</screen> </screen>
<para>When building from source cloned from the BitBucket repository, <para>When building from source cloned from the git repository,
you also need to install <application>autoconf</application>, you also need to install <application>autoconf</application>,
<application>automake</application>, and <application>automake</application>, and
<application>libtool</application> and you must execute <literal>sh <application>libtool</application> and you must execute <literal>sh
autogen.sh</literal> in the top source directory before running autogen.sh</literal> in the top source directory before running
<literal>configure</literal>.</para> <literal>configure</literal>.</para>
<sect3 id="RCL.INSTALL.BUILDING.BUILD.SOLARIS">
<title>Building on Solaris</title>
<para>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 <ulink url="http://www.recoll.org/download-1.14.html">an old
web site page</ulink>, they may still be valid.</para>
<para>Someone did test the 1.19 indexer and Python module build,
they do work, with a few minor glitches. Be sure to use
GNU <command>make</command> and <command>install</command>.</para>
</sect3>
</sect2> </sect2>
<sect2 id="RCL.INSTALL.BUILDING.INSTALL"> <sect2 id="RCL.INSTALL.BUILDING.INSTALL">
<title>Installation</title> <title>Installing</title>
<para>Use <userinput>make install</userinput> <para>Use <userinput>make install</userinput>
in the root in the root
@ -6045,6 +6017,48 @@ for i in range(nres):
</para> </para>
</sect2> </sect2>
<sect2 id="RCL.INSTALL.BUILDING.PYTHON">
<title>Python API package</title>
<para>The Python interface can be found in the source tree,
under the <filename>python/recoll</filename> directory.</para>
<para>As of &RCL; 1.19, the module can be compiled for
Python3.</para>
<para>The normal &RCL; build procedure (see above) installs the API
package for the default system version (python) along with the main
code. The package for other Python versions (e.g. python3 if the
system default is python2) must be explicitely built and
installed.</para>
<para>The <filename>python/recoll/</filename> directory contains
the usual <filename>setup.py</filename>. After configuring and
building the main &RCL; code, you can use the script to build and
install the Python module:
<screen>
<userinput>cd recoll-xxx/python/recoll</userinput>
<userinput>pythonX setup.py build</userinput>
<userinput>sudo pythonX setup.py install</userinput>
</screen>
</para>
</sect2>
<sect2 id="RCL.INSTALL.BUILDING.SOLARIS">
<title>Building on Solaris</title>
<para>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 <ulink url="http://www.recoll.org/download-1.14.html">an old
web site page</ulink>, they may still be valid.</para>
<para>Someone did test the 1.19 indexer and Python module build,
they do work, with a few minor glitches. Be sure to use
GNU <command>make</command> and <command>install</command>.</para>
</sect2>
</sect1> </sect1>
<sect1 id="RCL.INSTALL.CONFIG"> <sect1 id="RCL.INSTALL.CONFIG">