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 not only give you the latest improvements and fixes, but will let you build the protocol files against a different version than is available through pip (the version of Wayland the protocol is compiled against is listed on the top of the PyPI page).
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.
Generating the Wayland Protocol¶
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.
If the Wayland protocol file is in the default location
(/usr/share/wayland/wayland.xml
) or can be found with pkg-config
, you
should be able to build the protocol files without any problems:
$ python -m pywayland.scanner
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.
Running PyWayland inplace¶
Once the protocol files are created, you can generate the cffi module. Note: this is only required if you want to run from the source in place. If the libwayland header files are correctly installed, you will just need to run:
$ python pywaland/ffi_build.py
At this point, you should be able to use the PyWayland library. You can check
that you have everything installed correctly by running the associated
test-suite (note that you will also need pytest
to run the tests). Simply
run:
$ pytest
from the root directory.
Installing PyWayland¶
The package can be installed from source using typical setup.py
mechanisms:
$ python setup.py install
Additional arguments can be used to automatically generate the Wayland protocols for the standard Wayland package (which will fail if it cannot run) and the wayland-protocols package (which will be attempted by default, but will not raise an error if it fails).
If you have any problems or have any feedback, please report back to the issue tracker, contribution is always welcome, see Contributing.