Overview
========

Installing
----------

Installing Pango, GLib, FFI
______________________________

pangocffi depends on Pango_, GLib_, and libffi_ being installed.

.. _Pango: https://www.pango.org/Download
.. _GLib: https://wiki.gnome.org/Projects/GLib
.. _libffi: https://sourceware.org/libffi/

Feel free to contribute a guide for how to install these dependencies on other
systems.

Linux
^^^^^

These packages are usually installed as part of the base OS.

macOS
^^^^^

The default installation of Python that Apple bundles with macOS does not support loading dynamic libraries used by pangocffi.
Instead, it is recommended that python3 be installed via homebrew::

    brew install python3

To check if python3 has been installed by homebrew, run ``which python3``, and confirm the path is ``/opt/homebrew/bin/python3``.

Use `homebrew`_ to install the packages::

    brew install pkg-config
    brew install libffi
    brew install pango
    brew install glib

Windows
^^^^^^^

If you are using a 64-bit Python, you can use `this binary installer`_ to install GTK 3.
Use ``python --version --version`` to check whether you're running 32-bit or 64-bit Python.

.. _homebrew: https://brew.sh
.. _`this binary installer`: https://github.com/tschoonj/GTK-for-Windows-Runtime-Environment-Installer

Installing pangocffi
____________________

Install with pip_::

    pip install pangocffi

.. _pip: https://pip.pypa.io/

Note: Python versions < 3.10 are not supported.

Importing pangocffi
-------------------

The module to import is named ``pangocffi``, however you are welcome to alias
the module as ``pango``::

    import pangocffi as pango

pangocffi will dynamically load Pango, GLib, and GObject as a shared library
upon importing. If it fails to find it, you will see an exception like this::

    OSError: dlopen() failed to load pango: pango / pango-1 / ...

If Pango, GLib, or GObject are not installed as a shared library, pangocffi
supports specifying a path via environment variables respectively:
``PANGO_LOCATION``, ``GLIB_LOCATION``, ``GOBJECT_LOCATION``.

Basic usage
-----------

.. include:: rendering-pango.rst