Difference between revisions of "D-Bus service for Apertium"

From Apertium
Jump to navigation Jump to search
m (svn link updated)
 
(22 intermediate revisions by 8 users not shown)
Line 1: Line 1:
 
{{TOCD}}
 
{{TOCD}}
 
[http://dbus.freedesktop.org/ D-Bus] is a simple inter-process communication system. We are in the process of developing D-Bus services for Apertium which will make programmatic access to the Apertium tools easier.
 
[http://dbus.freedesktop.org/ D-Bus] is a simple inter-process communication system. We are in the process of developing D-Bus services for Apertium which will make programmatic access to the Apertium tools easier.
 
 
We have started developing simple D-Bus bindings for Apertium which allow for:
 
We have started developing simple D-Bus bindings for Apertium which allow for:
 
* discovery of details of the current Apertium installation and,
 
* discovery of details of the current Apertium installation and,
 
* translations via a programmatic interface.
 
* translations via a programmatic interface.
   
The D-Bus bindings are needed for some of the debugging tools, such as [[Apertium-view]].
+
The D-Bus bindings are needed for some of the tools, such as [[Apertium-view]] and [[Apertium-tolk]].
   
  +
==Prerequisites==
==Installing the D-Bus bindings for Apertium==
 
   
  +
* apertium (>= 3.0.0)
You will need:
 
  +
* python
* [http://www.freedesktop.org/wiki/Software/dbus D-Bus for Python] - almost every modern UNIX will have a package for this. You can install this in Debian/Ubuntu Linux by issuing:
 
  +
* dbus
::<code>sudo apt-get install python-dbus</code>.
 
  +
* python-dbus
* [[apertium-py]], which is a collection of Python routines that might be useful to people writing tools for Apertium. You can check it out using SVN:
 
::<code>svn co http://apertium.svn.sourceforge.net/svnroot/apertium/apertium-tools/apertium-py</code>.
 
:Installation is a breeze thanks to Python's distutils. In checkout directory (probably <code>apertium-py</code>) there should be a file called <code>setup.py</code>. Simply execute:
 
::<code>python setup.py install</code>.
 
:If you are using your system's stock Python interpreter, you'll probably have to execute that as root (<code>sudo python setup.py install</code>).
 
* [[apertium-dbus]], which contains the actual D-Bus bindings. This is quite rough around the edges at the moment. To get the code, check out the code from SVN using:
 
::<code>svn co http://apertium.svn.sourceforge.net/svnroot/apertium/apertium-tools/apertium-dbus</code>.
 
:After checkout, you need to execute the <code>install_services.sh</code> script in the checked out directory. This script installs the D-Bus activation files which tell D-Bus how to start up the Apertium D-Bus services if a user wants to use them. The command line format is ('''NB: This script assumes that your D-Bus activation directory is at <code>/usr/share/dbus-1/services</code>. If you don't know what I'm talking about, then you are probably safe, since this is the default for D-Bus.'''):
 
::<code>./install_services.sh &lt;path to info.py and mode.py&gt; &lt;path to apertium&gt;</code>
 
:The first parameter is the path to the files <code>info.py</code> and <code>mode.py</code> which are in the same directory as <code>install_services.sh</code> after checkout. Feel free to move them. The second parameter is the ''prefix'' to your Apertium installation. If your Apertium binaries are under <code>/usr/local/bin</code> (you can check this by running <code>which apertium</code> on the command line), then the prefix is <code>/usr/local</code>. On my machine, I invoked the script as follows:
 
::<code>./install_services.sh /home/wynand/apertium-git/apertium-tools/apertium-dbus /usr/local</code>
 
:since I keep <code>info.py</code> and <code>mode.py</code> in my development tree. You can also see that my Apertium installation is in <code>/usr/local</code>
 
   
  +
==Installing==
If you have gotten to this point, you can check that the bindings work by issuing the command:
 
  +
  +
'''Note:''' After Apertium's migration to GitHub, this tool is '''read-only''' on the SourceForge repository and does not exist on GitHub. If you are interested in migrating this tool to GitHub, see [[Migrating tools to GitHub]].
  +
  +
The package is available from [[SVN]] in the <code>apertium-dbus</code> module. The process for installation is the standard:
  +
 
<pre>
 
$ svn co https://svn.code.sf.net/p/apertium/svn/trunk/apertium-dbus
 
</pre>
  +
 
<pre>
  +
$ ./autogen.sh
  +
$ make
  +
$ make install
  +
</pre>
  +
  +
The current package is in the process of being ported to Python3, but should work. Do "svn up -r25849" if you want to get the last working Python2 version instead.
  +
  +
===Check that it works===
 
You can check that the bindings work by issuing the command:
 
:<code>dbus-send --print-reply --dest=org.apertium.info / org.apertium.Info.modes</code>
 
:<code>dbus-send --print-reply --dest=org.apertium.info / org.apertium.Info.modes</code>
 
This should return an array of strings of all the Apertium modes installed on your system. It should look something like
 
This should return an array of strings of all the Apertium modes installed on your system. It should look something like
  +
<pre>
<pre>user@somewhere:~/home/user$ dbus-send --print-reply --dest=org.apertium.info / org.apertium.Info.modes
+
$ dbus-send --print-reply --dest=org.apertium.info / org.apertium.Info.modes
 
method return sender=:1.567 -> dest=:1.599 reply_serial=2
 
method return sender=:1.567 -> dest=:1.599 reply_serial=2
 
array [
 
array [
Line 39: Line 47:
 
</pre>
 
</pre>
   
  +
To translate from the command line (assuming apertium-en-ca is installed), try e.g.
If D-Bus complains, then you should first check whether the activation files installed correctly. Go to <code>/usr/share/dbus-1/services</code> and look for <code>org.apertium.info.service</code> and <code>org.apertium.mode.service</code>. If these files are missing, then <code>./install_services.sh</code> wasn't successful; make sure that you have the rights to copy the files to <code>/usr/share/dbus-1/services</code>. If they are there, it might be the case that you mis-specified the path to <code>info.py</code> and <code>mode.py</code> and/or the prefix to your Apertium installation. You can verify if by opening the files. The format is very simple. On my machine, the contents of org.apertium.info.service are:
 
 
<pre>
 
<pre>
  +
$ dbus-send --print-reply --dest=org.apertium.mode / org.apertium.Translate.translate string:en-ca dict:string:string:"mark_unknown","true" string:'My hoovercraft is full of eels'
[D-BUS Service]
 
  +
</pre>
Name=org.apertium.info
 
Exec=/home/wynand/apertium-git/apertium-tools/apertium-dbus/info.py -p /usr/local/
 
</pre>
 
As you will recall, I keep the service executables under <code>/home/wynand/apertium-git/apertium-tools/apertium-dbus/</code>. The flag <code>-p</code> tells <code>info.py</code> that the prefix to my Apertium installation is <code>/usr/local</code>.
 
   
If you still have no luck, then it's quite possible that a Python error from our side snuck in. Try running info.py directly; that is
+
If the above two commannds don't work, then it's quite possible that a Python error from our side snuck in. Try running info.py directly; that is
 
:<code>python info.py -p /usr/local</code>
 
:<code>python info.py -p /usr/local</code>
where the prefix for Apertium in the above example is <code>/usr/local</code>. If you get a Python error, please post the error on this page or post a bug report in [http://xixona.dlsi.ua.es/bugzilla/ our bug tracker]. If the service starts up without errors, try executing
+
where the prefix for Apertium in the above example is <code>/usr/local</code>. If you get a Python error, please post the error on this page or post a bug report in [http://bugs.apertium.org/cgi-bin/bugzilla/index.cgi our bug tracker]. If the service starts up without errors, try executing
 
:<code>dbus-send --print-reply --dest=org.apertium.info / org.apertium.Info.modes</code>
 
:<code>dbus-send --print-reply --dest=org.apertium.info / org.apertium.Info.modes</code>
 
again. If there is no output, then open a new terminal and run
 
again. If there is no output, then open a new terminal and run
Line 55: Line 60:
 
This neat utility shows you the activity on the D-Bus. Now try executing <code>dbus-send --print-reply --dest=org.apertium.info / org.apertium.Info.modes</code> again.
 
This neat utility shows you the activity on the D-Bus. Now try executing <code>dbus-send --print-reply --dest=org.apertium.info / org.apertium.Info.modes</code> again.
   
If you have no luck, come and talk to us in #apertium at irc.freenode.net.
+
If you have no luck, come and talk to us in <code>#apertium</code> at <code>irc.freenode.net</code>
   
 
==Installing into a prefix==
 
==Installing into a prefix==
  +
:''This is unfinished''
   
* Installing apertium-py into a prefix
 
* Installing dbus into a prefix.
 
**::<code>./install_services.sh &lt;path to info.py and mode.py&gt; &lt;path to apertium&gt;</code>
 
 
<pre>
 
$ ./install_services.sh ./ /home/spectre/local
 
./install_services.sh: line 15: /usr/share/dbus-1/services/org.apertium.info.service: Permission denied
 
./install_services.sh: line 15: /usr/share/dbus-1/services/org.apertium.mode.service: Permission denied
 
</pre>
 
 
*Do: mkdir -p <prefix>/share/lib/apertium
 
** Then copy mode.py and info.py into there
 
 
*Do: mkdir -p <prefix>/share/dbus-1/services/
 
*Do: mkdir -p <prefix>/share/dbus-1/services/
  +
*Copy the <code>.service</code> files into <prefix>/share/dbus-1/services/
 
*Edit the files and change the @servdir@ to where you put the info.py and mode.py and change the prefix to your prefix
 
 
*Make a session-local.conf file like it says [http://www.linuxfromscratch.org/blfs/view/svn/general/dbus.html here] under "" Configuration Information"".
 
*Make a session-local.conf file like it says [http://www.linuxfromscratch.org/blfs/view/svn/general/dbus.html here] under "" Configuration Information"".
 
**Change the <servicedir> element value to <prefix>/share/dbus-1/services/
 
**Change the <servicedir> element value to <prefix>/share/dbus-1/services/
 
* Restart dbus. /etc/init.d/dbus restart
 
* Restart dbus. /etc/init.d/dbus restart
  +
* Log out and log back in again
   
  +
==Interfaces==
==Apertium D-Bus interfaces==
 
 
Currently, Apertium offers two D-Bus services:
 
Currently, Apertium offers two D-Bus services:
 
* <code>org.apertium.info</code> has a single object <code>/</code>, which offers rudimentary information about the Apertium installation.
 
* <code>org.apertium.info</code> has a single object <code>/</code>, which offers rudimentary information about the Apertium installation.
 
* <code>org.apertium.translate</code> contains an object for each Apertium mode installed in the system.
 
* <code>org.apertium.translate</code> contains an object for each Apertium mode installed in the system.
   
==D-Bus issues==
+
==Issues==
 
If you make a change to any of the D-Bus configuration files, you will need to restart both the system-wide and session D-Bus daemons. The system-wide daemon can be restarted on a Debian/Ubuntu system with:
 
If you make a change to any of the D-Bus configuration files, you will need to restart both the system-wide and session D-Bus daemons. The system-wide daemon can be restarted on a Debian/Ubuntu system with:
 
*<code>/etc/init.d/dbus restart</code>
 
*<code>/etc/init.d/dbus restart</code>
 
The only real way to restart your session deamon is to logout and log back in again. You will likely run into strange problems if you attempt to kill the session D-Bus daemon.
 
The only real way to restart your session deamon is to logout and log back in again. You will likely run into strange problems if you attempt to kill the session D-Bus daemon.
  +
  +
==Filesystem layout==
  +
  +
* <code>/usr/share/dbus-1/services/</code> &mdash; DBUS <code>.service</code> files.
  +
* <code>/usr/share/apertium/dbus-1/</code> &mdash; Python code that actually does the service (<code>info.py</code> and <code>mode.py</code>)
  +
  +
==Examples==
  +
  +
There are some simple examples in various languages on the page [[D-Bus examples]].
  +
  +
==External links==
  +
  +
* [http://www.pygtk.org/articles/applets_arturogf/x207.html Autotoolising python]
   
 
[[Category:Development]]
 
[[Category:Development]]
  +
[[Category:Services]]
  +
[[Category:Documentation in English]]

Latest revision as of 19:36, 13 April 2018

D-Bus is a simple inter-process communication system. We are in the process of developing D-Bus services for Apertium which will make programmatic access to the Apertium tools easier. We have started developing simple D-Bus bindings for Apertium which allow for:

  • discovery of details of the current Apertium installation and,
  • translations via a programmatic interface.

The D-Bus bindings are needed for some of the tools, such as Apertium-view and Apertium-tolk.

Prerequisites[edit]

  • apertium (>= 3.0.0)
  • python
  • dbus
  • python-dbus

Installing[edit]

Note: After Apertium's migration to GitHub, this tool is read-only on the SourceForge repository and does not exist on GitHub. If you are interested in migrating this tool to GitHub, see Migrating tools to GitHub.

The package is available from SVN in the apertium-dbus module. The process for installation is the standard:

$ svn co https://svn.code.sf.net/p/apertium/svn/trunk/apertium-dbus
$ ./autogen.sh
$ make 
$ make install

The current package is in the process of being ported to Python3, but should work. Do "svn up -r25849" if you want to get the last working Python2 version instead.

Check that it works[edit]

You can check that the bindings work by issuing the command:

dbus-send --print-reply --dest=org.apertium.info / org.apertium.Info.modes

This should return an array of strings of all the Apertium modes installed on your system. It should look something like

$ dbus-send --print-reply --dest=org.apertium.info / org.apertium.Info.modes 
method return sender=:1.567 -> dest=:1.599 reply_serial=2
   array [
      string "en-ca"
      string "ca-en"
      string "en-af"
      string "af-en"
   ]

To translate from the command line (assuming apertium-en-ca is installed), try e.g.

$ dbus-send --print-reply --dest=org.apertium.mode / org.apertium.Translate.translate string:en-ca dict:string:string:"mark_unknown","true" string:'My hoovercraft is full of eels'

If the above two commannds don't work, then it's quite possible that a Python error from our side snuck in. Try running info.py directly; that is

python info.py -p /usr/local

where the prefix for Apertium in the above example is /usr/local. If you get a Python error, please post the error on this page or post a bug report in our bug tracker. If the service starts up without errors, try executing

dbus-send --print-reply --dest=org.apertium.info / org.apertium.Info.modes

again. If there is no output, then open a new terminal and run

dbus-monitor.

This neat utility shows you the activity on the D-Bus. Now try executing dbus-send --print-reply --dest=org.apertium.info / org.apertium.Info.modes again.

If you have no luck, come and talk to us in #apertium at irc.freenode.net

Installing into a prefix[edit]

This is unfinished
  • Do: mkdir -p <prefix>/share/dbus-1/services/
  • Make a session-local.conf file like it says here under "" Configuration Information"".
    • Change the <servicedir> element value to <prefix>/share/dbus-1/services/
  • Restart dbus. /etc/init.d/dbus restart
  • Log out and log back in again

Interfaces[edit]

Currently, Apertium offers two D-Bus services:

  • org.apertium.info has a single object /, which offers rudimentary information about the Apertium installation.
  • org.apertium.translate contains an object for each Apertium mode installed in the system.

Issues[edit]

If you make a change to any of the D-Bus configuration files, you will need to restart both the system-wide and session D-Bus daemons. The system-wide daemon can be restarted on a Debian/Ubuntu system with:

  • /etc/init.d/dbus restart

The only real way to restart your session deamon is to logout and log back in again. You will likely run into strange problems if you attempt to kill the session D-Bus daemon.

Filesystem layout[edit]

  • /usr/share/dbus-1/services/ — DBUS .service files.
  • /usr/share/apertium/dbus-1/ — Python code that actually does the service (info.py and mode.py)

Examples[edit]

There are some simple examples in various languages on the page D-Bus examples.

External links[edit]