FAQ for xpra
============

This is the original README file, please refer to the website:
http://xpra.org/
For more up to date information.

What is xpra?
-------------

Xpra is 'screen for X' -- it allows you to run X programs, usually on
a remote host, direct their display to your local machine, and then to
disconnect from these programs and reconnect from the same or another
machine, without losing any state.


Wait, isn't that what VNC does?
-------------------------------

VNC is another system for using apps remotely.  The main difference
between xpra and VNC is that xpra is "rootless" -- i.e., programs you
run under it show up on your desktop as regular programs, managed by
your regular window manager, instead of being trapped inside a box.
It gives you "remote applications", not a "remote desktop".  (Hence
the name -- "X Persistent Remote Applications".)

What about NX?
--------------

NX is the name for a protocol, rootless X server, mass of management
scripts, etc., produced by NoMachine Inc.  There's some very nice tech
in NX, and in principle it can do everything that xpra does and more.
In practice, they offer either a super-slick, complete thin client
solution with some questionable (IMO) engineering decisions and a
proprietary license, or, a minimally-documented code dump of GPLed
software with a build system straight from the 1980s, an included fork
of the old X.org monolithic (!) tree, and if you somehow get it built
then it has all sorts of weird quirks to work around.  Xpra, by
comparison, is <1000 source lines of code for the core, was written in
a weekend, and just works.

NX seems aimed at large enterprise thin client deployments, and I just
want a way to run data visualization jobs that won't die when my
wireless does -- xpra is great for the latter.


And what about xmove?
---------------------

xmove is a tool designed to do exactly the same thing as xpra.  The
main differences are that xmove uses a very different implementation
strategy (it implements a "pseudo" X server, while xpra takes
advantage of the standard X.org server), and that xmove has been
unmaintained since ~1997.

I have not personally used xmove, and X clients tend to be very
conservative -- it's entirely possible that all modern X apps will
still work just fine against a 10+ year old server like xmove.
However, X *has* changed since then; for example, xmove does not
support the Render extension, which is essentially required if you
want anti-aliased fonts.  Between the somewhat cumbersome design and
the lack of existing maintainers, this will almost certainly never get
fixed; nor will any other flaws that xmove may have.  (For instance,
xpra looks easier to set up without writing custom shell scripts.)

The other major issue with xmove's design is its sensitivity to
latency.  Usually, if you're using a tool like xmove or xpra, it's
because you want to run an app on a remote computer.  Usually you
don't have a local ethernet connection to that remote computer, but
rather something with a much higher ping time.  Standard X forwarding
becomes notoriously slow and unusable in such situations -- and xmove
uses the same mechanisms as standard X.  Xpra, on the other hand, uses
a protocol with no round trips, and applications forwarded by xpra
should remain snappy and responsive over connections that make X or
xmove crawl away to die.

Still, like I said, I haven't actually used xmove, and would be
interested to hear from those who do.


Okay, so how do I try xpra?
---------------------------

Download the latest version from
  http://xpra.org/

Make sure you have the dependencies, at least:
  development packages for python-gtk, and all dependencies
  Xvfb
  cython (version 0.14 at least, 0.16 to support video encoding
  check with 'cython --version')
  there are many optional packages, for details see:
  http://xpra.org/trac/wiki/Dependencies
On Debian-based OSes, I think it's:
  # aptitude install libx11-dev libxtst-dev libxcomposite-dev \
    libxkbfile-dev libxdamage-dev \
    python-gobject-dev python-gtk2-dev xvfb cython
  To support video encoding, you also need:
    libx264-dev libswscale-dev libavcodec-dev libvpx-dev
For Fedora:
  # yum install xorg-x11-server-Xvfb Cython libX11-devel \
    libXtst-devel libXcomposite-devel libXdamage-devel libxkbfile-devel \
    pygobject2-devel pygtk2-devel gtk2-devel libvpx-devel
And for Mac OSX, CentOS, BSD, and many other platforms, see:
	http://xpra.org/trac/wiki/Building

Build it:
  tar xvzf xpra-<whatever>.tar.gz
  cd xpra-<whatever>
  ./setup.py install --home=install
  export PYTHONPATH=$PWD/install/lib/python:$PYTHONPATH
Note 1: If running and displaying apps on two different machines, then
  you'll need to do this on both of them, obviously.
Note 2: If you're on a 64-bit Redhat-ish distro (one with multilib
  support), then you may need to replace 'lib' with 'lib64' above.

On the machine where you will run the apps (usually, a remote machine):
  install/bin/xpra start :13

On the machine where you want the apps to display (usually, your local machine):
  install/bin/xpra attach ssh:<remote box>:13
or if displaying on the same machine for testing, then just:
  install/bin/xpra attach :13
(But make sure that you haven't set DISPLAY= in the terminal where you
run 'xpra attach', because then xpra will try to display your apps
inside itself!)

Then on the machine where you ran 'xpra start' (usually, the remote
machine), start some apps:
  export DISPLAY=:13
  emacs


So how does it work?
--------------------

Very well, thank you.

Oh, you mean... right.

Okay.  So you may have heard about these fancy newfangled "compositing
window managers".  Here's how they work.  Normally, when you run an
app under X, the app is responsible for drawing stuff into the windows
it owns, and then the X server combines those windows on the screen to
produce the final desktop view that you interact with.  Compositing
managers change this.  If you are running a compositing manager, then
each app still decides what goes in each of its own windows, but the X
server stops putting those windows on the screen.  Instead, the job of
reading those images for each window and creating a display on the
screen falls to the compositing manager.

Xpra works by connecting to an ordinary X server as a compositing
manager -- but instead of combining the window images to present on
the screen, it takes the window images and stuffs them into a network
connection to the xpra client, which then displays them onto the
*remote* screen.  It also acts as a window manager for the X server it
is running against, but it doesn't actually have any window manager
policy built into it.  Instead, it takes all the window management
requests from the applications, sends them over the wire to the
client, who then issues those same requests on the real display, waits
to see what answer your real window manager gives, and then forwards
that answer back to the xpra server.

(So note that there are actually *two* X servers here -- one on your
remote host that your apps actually run against, and then the local
one that you're sitting at, where the apps end up being displayed.)

Now, unless you're debugging xpra's guts, you never want to actually
see the X server that xpra is connected to, especially since it's
generally on some far away host that doesn't have a monitor, and if it
did the screen would just be black anyway (because we don't composite
properly, y'see).  So 'xpra start' will silently spawn 'Xvfb', which
is a special X server with all its video drivers ripped out, and then
connect to it, so now that you've finished reading this section you
can forget all about it again and just use xpra and be happy.

Maybe a picture with boxes in will help:

 +-----+     +--------+                                                  
 |     |     |  your  |     +---------+                                  
 | you | <-> |   X    | <-> |'xpra    |                                  
 |     |     | server |     |  attach'|                                  
 +-----+     +--------+     +---------+                                  
                                 ^                                       
                                 |                                       
                              INTERNET!                                  
                                 |                                       
                                 v                                       
                            +---------+                                  
                            |'xpra    |     +------+     +-------------+
                            |   start'| <-> |      | <-> | firefox     |
                            +---------+     | Xvfb |     | or whatever |
                                            |      |     +-------------+
                                            +------+                     


No, actually, I really did mean how *well* does it work?
--------------------------------------------------------

Oh.  Sorry.  Heh.

As a first release, some lower priority features aren't included -- it
doesn't support transient hints, shaped windows, input grabs, etc.
These are all straightforward to add, however, and in practice xpra
seems to already be very usable without them.

In principle, it should be dramatically less latency-sensitive than raw X,
and might use more or less bandwidth depending on task.

Warning: the X keyboard model makes it hard to get keypresses right.