# Setting up the Telepathy components for Ytstenut

Skip to 

* [[XMPP Account Setup|http://freedesktop.org/wiki/Software/YtstenutAccounts]] 
* [[Source Code Change Management|http://freedesktop.org/wiki/Software/YtstenutChangeManagement]] 

## Salut

1. Make sure you have Mission Control at least version 5.7.7 installed. 
1. Check out the repositories, for example into ~/src/:  

[[!format txt """
 cd ~/src/
 git clone git://anongit.freedesktop.org/telepathy/telepathy-salut
 git clone git://anongit.freedesktop.org/ytstenut/telepathy-ytstenut
 git clone git://anongit.freedesktop.org/ytstenut/ytstenut-plugins
 git clone git://anongit.freedesktop.org/ytstenut/ytstenut-glib
"""]]
1. Build Salut.  

[[!format txt """
cd ~/src/telepathy-salut
./autogen.sh
make
# don't bother installing; it's not necessary
"""]]
1. Build telepathy-ytstenut.  

[[!format txt """
cd ~/src/telepathy-ytstenut
./autogen.sh --disable-qt4
make
# again, doesn't need an install
"""]]
1. Build ytstenut-plugins.  

[[!format txt """
cd ~/src/ytsenut-plugins
# we will need to point to the salut and tp-ytstenut we just built.
./autogen.sh PKG_CONFIG_PATH=$HOME/src/telepathy-ytstenut/telepathy-ytstenut-glib:$HOME/src/telepathy-salut/salut
make
"""]]
1. Test to see the tests still pass.  

[[!format txt """
cd ~/src/ytstenut-plugins
make check
"""]]
1. Build ytstenut-glib. This is the library that applications will build against. 

[[!format txt """
cd ~/src/ytsenut-glib
# we will need to point to the salut and tp-ytstenut we just built.
./autogen.sh --enable-gtk-doc --enable-docs PKG_CONFIG_PATH=$HOME/src/telepathy-ytstenut/telepathy-ytstenut-glib:$HOME/src/telepathy-salut/salut
make
"""]]
1. If everything is working, then you can run salut with Ytstenut not in the test suite:  

[[!format txt """
cd ~/src/telepathy-salut
SALUT_PERSIST=1 SALUT_DEBUG=all WOCKY_DEBUG=all SALUT_PLUGIN_DIR=$HOME/src/ytstenut-plugins/salut/.libs src/telepathy-salut
"""]]
Here's what the above Salut environment variables mean:  
[[!table header="no" class="mointable" data="""
 **Variable**  |  **Meaning**  |  **Typical or allowed values** 
 SALUT_PERSIST   |   If set then Salut won't timeout due to no connections after five seconds   |   set to anything, but we typically use  SALUT_PERSIST=1 
 SALUT_DEBUG   |   Whether Salut should log stuff to stdout   |   any log flag will work, but all is recommended  
 WOCKY_DEBUG   |   Whether Wocky should log stuff to stdout   |   same as above, use all 
 SALUT_PLUGIN_DIR   |   The directory for Salut to look in for plugins (like the Ytstenut one) if not /usr/lib/telepathy/salut-0   |   we will want to set it to the directory the Ytstenut plugin is in. If you've not installed anything, like above, then the plugin source is in ~/src/ytstenut-plugins/salut/ but the actual .so file is in the /.libs subdirectory due to libtool, hence the setting in the above example  
"""]]


## Mission Control

1. First make sure you don't have a salut.manager file in /usr/share/telepathy/.  If you do this will trigger [[#22 (fixed by now)|https://trac.shamdeh.collabora.co.uk/ticket/22]]. Systems using Ytstenut should not distribute a manager file. A manager file just contains information about a connection manager and what it does so that it can be read by Mission Control. However, because we have a Ytstenut Salut plugin and so a Ytstenut protocol the manager file is wrong. Not having this file simply means that Mission Control will start the connection manager (Salut in our case) and introspect it manually. This is good. This is what we want.  
1. Start Mission Control pointing to the Ytstenut plugin:  

[[!format txt """
MC_FILTER_PLUGIN_DIR=$HOME/src/ytstenut-plugins/mission-control/.libs/ MC_DEBUG=all TP_MC_DEBUG=all /usr/lib/telepathy/mission-control-5
"""]]
* The environment variables mean roughly the same things as for Salut. 
* Ensure the automatic account has been recognised successfully. {mc-tool show ...} should give the following:  

[[!format txt """
% mc-tool show salut/local_ytstenut/automatic_account
     Account: salut/local_ytstenut/automatic_account
Display Name: Last Name
     Enabled: enabled
        Icon: im-local-ytstenut
     Service: local-ytstenut
   Automatic: available (2) ""
     Current:  (1) ""
   Requested: offline (1) ""

      (string) last-name = Last Name
      (string) first-name = First Name
"""]]
1. Try out the telepathy-ytstenut-glib tests:  

[[!format txt """
cd $HOME/src/telepathy-ytstenut/
telepathy-ytstenut-glib/tests/nosey-status
"""]]
* You should get updates to the services and statuses on the bus on the command line from this program. It should look like this when you first start it: 

[[!format txt """
% telepathy-ytstenut-glib/tests/nosey-status
Trying to prepare account, this will only continue if the account is connected...
Got status sidecar.
ServiceAdded:
 - contact ID: user@host
 - service name: nosey.status
"""]]
* Here is a list of the telepathy-ytstenut-glib tests and what they do:  [[!table header="no" class="mointable" data="""
  **Test name**   |   **What it does**  
  diddle-account-manager   |   Tests [[TpYtsAccountManager|TpYtsAccountManager]] by calling Hold(), getting the automatic account from the Mission Control plugin, and finally calling Release().  
  client-ping   |   Tests sending an arbitrary message to another service. The first argument is the local service name and the second is the remote service name. The remote service should be running on the same machine. This has only been tested with the client-pong test. Waits for a reply and prints the reply and quits.  
  client-pong   |   Returns the arbitrary message from client-ping with some more rubbish. Waits for a message, prints it, replies, and quits. The first argument is the local service name which you pass as the second argument to client-ping.  
  nosey-status   |   A bit like dbus-monitor, but for Ytstenut services. Every time [[ServiceAdded|ServiceAdded]], [[ServiceRemoved|ServiceRemoved]] or [[StatusChanged|StatusChanged]] is emitted by the Status sidecar in the Salut plugin, this test will print out details. Bear in mind that [[StatusChanged|StatusChanged]] is only emitted on non-local services where it shows an interest. This test advertises only one interest: urn:ytstenut:capabilities:yts-caps-cats, so if you want this to print [[StatusChanged|StatusChanged]] for you from a non-local service, your capability either has to be that or you have to change the test to add another interest.  
  passing-service   |   A simple test to pop up a new service, and then disappear after a few seconds and quits. The first argument is the local service name. You can see the service appearing and then disappearing if you run nosey-status beforehand.  
  passing-status   |   Similar to passing-service but it pops up a service, advertises a status, waits a few seconds, clears the status, waits a few more seconds, then quits. The service name is currently hard-coded. The status which is advertised uses the urn:ytstenut:capabilities:yts-caps-cats capability so it needs no changes when nosey-status is being used.  
"""]]

1. Run ytstenut-glib tests and inspect the example(s) 

[[!format txt """
cd $HOME/src/telepathy-glib
make check

cd examples
# browse around here
"""]]

### A note about capabilities, interests and StatusChanged

* If a service registers an interest in a capability, for example:  

[[!format txt """
tp_yts_client_add_interest (client, "urn:ytstenut:capabilities:yts-cats-falling-on-their-feet");
"""]]
* then this means that any service on the network which advertise statuses with the same capability will notify said interested service.  Please note, however, that this only applies to non-local services. When one advertises a status, a PEP node is published and Salut goes through its contacts looking at their capabilities to see who to send the node to -- this is the reason for the adding interest. However, the PEP XEP also states that the message must be sent to the local user from where it originated.  As a result, **any** status you advertise will **also** appear in the local [[TpYtsStatus|TpYtsStatus]]. Just something to keep in mind, so filtering of [[StatusChanged|StatusChanged]] signals must always be done.  

## Gabble

1. Check out the repositories, for example into ~/src/:  

[[!format txt """
 cd ~/src/
 git clone git://anongit.freedesktop.org/telepathy/telepathy-gabble
 git clone git://anongit.freedesktop.org/ytstenut/telepathy-ytstenut
 git clone git://anongit.freedesktop.org/ytstenut/ytstenut-plugins
 git clone git://anongit.freedesktop.org/ytstenut/ytstenut-glib
"""]]
1. Build Gabble. 

[[!format txt """
cd ~/src/telepathy-gabble
./autogen.sh
make
# don't bother installing; it's not necessary
"""]]
1. Build telepathy-ytstenut.  

[[!format txt """
cd ~/src/telepathy-ytstenut
./autogen.sh --disable-qt4
make
# again, doesn't need an install
"""]]
1. Build ytstenut-plugins.  

[[!format txt """
cd ~/src/ytsenut-plugins
# we will need to point to the gabble and tp-ytstenut we just built.
./autogen.sh PKG_CONFIG_PATH=$HOME/src/telepathy-ytstenut/telepathy-ytstenut-glib:$HOME/src/telepathy-gabble/gabble
make
"""]]
1. Test to see the tests still pass.  

[[!format txt """
cd ~/src/ytstenut-plugins
make check
"""]]
1. Build ytstenut-glib. This is the library that applications will build against. 

[[!format txt """
cd ~/src/ytsenut-glib
# we will need to point to the gabble and tp-ytstenut we just built.
./autogen.sh --enable-gtk-doc --enable-docs PKG_CONFIG_PATH=$HOME/src/telepathy-ytstenut/telepathy-ytstenut-glib:$HOME/src/telepathy-gabble/gabble
make
"""]]
1. If everything is working, then you can run gabble with Ytstenut not in the test suite:  

[[!format txt """
cd ~/src/telepathy-gabble
GABBLE_PERSIST=1 GABBLE_DEBUG=all WOCKY_DEBUG=all GABBLE_PLUGIN_DIR=$HOME/src/ytstenut-plugins/gabble/.libs src/telepathy-gabble
"""]]
Here's what the above Gabble environment variables mean:  
[[!table header="no" class="mointable" data="""
 **Variable**  |  **Meaning**  |  **Typical or allowed values** 
 GABBLE_PERSIST   |   If set then Gabble won't timeout due to no connections after five seconds   |   set to anything, but we typically use  GABBLE_PERSIST=1 
 GABBLE_DEBUG   |   Whether Gabble should log stuff to stdout   |   any log flag will work, but all is recommended (easiest) 
 WOCKY_DEBUG   |   Whether Wocky should log stuff to stdout   |   same as above, use all 
 GABBLE_PLUGIN_DIR   |   The directory for Gabble to look in for plugins (like the Ytstenut one) if not /usr/lib/telepathy/gabble-0   |   we will want to set it to the directory the Ytstenut plugin is in. If you've not installed anything, like above, then the plugin source is in ~/src/ytstenut-plugins/gabble/ but the actual .so file is in the /.libs subdirectory due to libtool, hence the setting in the above example  
"""]]

There are some telepathy-ytstenut-glib tests for gabble. These are exactly the same as the ones for salut but the binaries start with "server-" and they take an account triple as the first argument. For example, instead of: 


[[!format txt """
% telepathy-ytstenut-glib/tests/nosey-status
"""]]
you should use: 


[[!format txt """
% mc-tool list
gabble/jabber/test_40gmail_2ecom0
...

% telepathy-ytstenut-glib/tests/server-nosey-status gabble/jabber/test_40gmail_2ecom0
...
"""]]
where `gabble/jabber/test_40gmail_2ecom0` is a gabble jabber account (with jid [[test@gmail.com|mailto:test@gmail.com]]) which is already configured.