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

From Apertium
Jump to navigation Jump to search
(First bit about how to install Apertium's D-Bus bindings)
Line 19: Line 19:
 
* [[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:
 
* [[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>.
 
::<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. 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.'''):
+
: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>
 
::<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:
 
: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>
 
::<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>
+
: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>
   
  +
If you have gotten to this point, 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>
  +
This should return an array of strings of all the Apertium modes installed on your system. It should look something like
  +
<pre>user@somewhere:~/home/user$ 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"
  +
]
  +
</pre>
  +
  +
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>
  +
[D-BUS Service]
  +
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
  +
:<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 on the [http://sourceforge.net/tracker/?group_id=143781&atid=756475 Sourceforge site for Apertium]. If the service starts up without errors, try executing
  +
:<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
  +
:<code>dbus-monitor</code>.
  +
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.
   
 
==D-Bus bus names==
 
==D-Bus bus names==

Revision as of 18:49, 14 December 2007

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 debugging tools, such as Apertium-view.

Installing the D-Bus bindings for Apertium

You will need:

  • D-Bus for Python - almost every modern UNIX will have a package for this. You can install this in Debian/Ubuntu Linux by issuing:
sudo apt-get install 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:
svn co http://apertium.svn.sourceforge.net/svnroot/apertium/apertium-tools/apertium-py.
Installation is a breeze thanks to Python's distutils. In checkout directory (probably apertium-py) there should be a file called setup.py. Simply execute:
python setup.py install.
If you are using your system's stock Python interpreter, you'll probably have to execute that as root (sudo python setup.py install).
  • 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:
svn co http://apertium.svn.sourceforge.net/svnroot/apertium/apertium-tools/apertium-dbus.
After checkout, you need to execute the install_services.sh 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 /usr/share/dbus-1/services. If you don't know what I'm talking about, then you are probably safe, since this is the default for D-Bus.):
./install_services.sh <path to info.py and mode.py> <path to apertium>
The first parameter is the path to the files info.py and mode.py which are in the same directory as install_services.sh after checkout. Feel free to move them. The second parameter is the prefix to your Apertium installation. If your Apertium binaries are under /usr/local/bin (you can check this by running which apertium on the command line), then the prefix is /usr/local. On my machine, I invoked the script as follows:
./install_services.sh /home/wynand/apertium-git/apertium-tools/apertium-dbus /usr/local
since I keep info.py and mode.py in my development tree. You can also see that my Apertium installation is in /usr/local

If you have gotten to this point, 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

user@somewhere:~/home/user$ 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"
   ]

If D-Bus complains, then you should first check whether the activation files installed correctly. Go to /usr/share/dbus-1/services and look for org.apertium.info.service and org.apertium.mode.service. If these files are missing, then ./install_services.sh wasn't successful; make sure that you have the rights to copy the files to /usr/share/dbus-1/services. If they are there, it might be the case that you mis-specified the path to info.py and mode.py 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:

[D-BUS Service]
Name=org.apertium.info
Exec=/home/wynand/apertium-git/apertium-tools/apertium-dbus/info.py -p /usr/local/

As you will recall, I keep the service executables under /home/wynand/apertium-git/apertium-tools/apertium-dbus/. The flag -p tells info.py that the prefix to my Apertium installation is /usr/local.

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

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 on the Sourceforge site for Apertium. 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.

D-Bus bus names

D-Bus allows services to be registered under Java style package names (e.g. org.apertium.my_service).

We envision two services:

  • org.apertium.info - this will expose objects to query various aspects of the installed apertium system.
  • org.apertium.translate - this will exposes translation functions.

Multiple objects can be registered with each service. Objects are given UNIX path names. For example, suppose we have English-Polish (en-pl) and English-Catalan (en-ca) translation modes installed in our system, then org.apertium.translate will expose at least four translation objects:

  • English->Catalan translation object,
  • Catalan->English translation object,
  • English->Polish translation object,
  • Polish->English translation object.

Given that one invokes these modes from the command line with "apertium en-ca", "apertium ca-en", "apertium en-pl" and "apertium pl-en", a good naming scheme for the objects would be:

  • /en-ca for the English->Catalan translation object
  • /ca-en for the Catalan->English translation object
  • /en-pl for the English->Polish translation object
  • /pl-en for the Polish->English translation object

These objects will have the full names org.apertium.translate/en-ca, org.apertium.translate/ca-en, org.apertium.translate/en-pl and org.apertium.translate/pl-en.

Alternative

Something that just creates the pipeline from the modes.xml file would be good, and then exposes each mode. If people want to change it they can edit the modes file, e.g.:

org.apertium.info

Would list information about what modes are installed, and what they correspond to (e.g. human readable language names, metadata that stuff... this could be in a separate "directory" xml file that is updated with each package installed.)

org.apertium.mode/<name>

Would be an interface to exectute a particular mode on a piece of text. Of course you still have the problem of the other command line options (-u, -f, etc...)