Installation
************

To install PyWayland, you will need to have a base set of dependencies
installed.  This should be all the configuration that is required to
run the packaged version on PyPI.  The additional steps to build and
install from source are outlined below.

If you have any problems with anything outlined here, feedback is
greatly appreciated.


External Dependencies
=====================

In order to run PyWayland, you will need to have installed the Wayland
libraries and headers such that they can be found by CFFI.  This can
be done with the "libwayland-dev" apt package; however, note that it
is probably best to use the most recent version of Wayland available
from the Wayland releases site, and the pip package will try to track
the most recent version.

You will also need to have the Python headers installed and a version
of GCC to compile the cffi library.  The headers are typically
available through the "python-dev" package.

Optionally, you can have installed the "wayland-protocols" package,
also available from the Wayland releases page.  The package uploaded
to PyPI will already have these protocols included, so this is only
needed if you plan on installing from source.


Installing with pip
===================

Once the external dependencies are in place you should just be able to
run:

   $ pip install pywayland

Any additional unfulfilled dependencies should be downloaded.


Installing from Source
======================

You can download and run PyWayland from source, which will let you
build the protocol files against a different version than is available
through pip.


Getting the Source
------------------

You can download the most recent version of PyWayland from the git
repository, or clone the repository as:

   $ git clone https://github.com/flacjacket/pywayland.git


Python Dependencies
-------------------

PyWayland depends on a minimal set of dependencies.  All Python
version require cffi (to perform Wayland library calls), which can be
pip installed for non-PyPy installations.  Note that PyPy platforms
ship with cffi.


Wayland Protocols
-----------------

At this point, you have the base PyWayland module, which contains some
core objects and objects specific to client and server
implementations.  The client and server exchange messages defined in
the Wayland protocol, which is an XML file that ships with Wayland.
The scanner parses this XML file and generates the relevant objects.


Running PyWayland inplace
-------------------------

If the libwayland header files are correctly installed and if the
Wayland protocol file is in the default location
("/usr/share/wayland/wayland.xml") or can be found with "pkg-config",
you can build the cffi module and then generate the protocol files
without any problems:

   $ python pywayland/ffi_build.py
   $ python -m pywayland.scanner --with-protocols

This will output the protocol files to the directory
"./pywayland/protocol/". The input file and the output directory can
be set from the command line options, see "python -m pywayland.scanner
-h" for more information.

You can check that you have everything installed correctly by running
the associated test-suite .  Simply run "pytest" from the root
directory.


Installing PyWayland
--------------------

The package can be installed from source using typical pip mechanisms:

   $ pip install .

This uses the custom build backend, which runs protocol generation and
cffi binding generation automatically. Manual pre-compilation is not
required for regular pip builds.

If you have any problems or have any feedback, please report back to
the issue tracker, contribution is always welcome, see Contributing.
