summaryrefslogtreecommitdiff
path: root/docs/getting_started.rst
blob: a2f53dd32477c37f7081dfe619e98549d813a8b1 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
.. include:: icons.rst

.. _gettingstarted:

===============
Getting Started
===============

To get things started we will try to run a very simple `GTK
<https://www.gtk.org/>`_ based GUI application using the :doc:`PyGObject <index>` provided
Python bindings. First create a small Python script called ``hello.py`` with
the following content and save it somewhere:

.. code:: python

    import gi
    gi.require_version("Gtk", "3.0")
    from gi.repository import Gtk

    window = Gtk.Window(title="Hello World")
    window.show()
    window.connect("destroy", Gtk.main_quit)
    Gtk.main()

Before we can run the example application we need to install PyGObject, GTK
and their dependencies. Follow the instructions for your platform below.

======================================================= ==================================================== ==========================================================
|ubuntu-logo| :ref:`Ubuntu <ubuntu-getting-started>`    |fedora-logo| :ref:`Fedora <fedora-getting-started>` |arch-logo| :ref:`Arch Linux <arch-getting-started>`
|windows-logo| :ref:`Windows <windows-getting-started>` |macosx-logo| :ref:`macOS <macosx-getting-started>`  |opensuse-logo| :ref:`openSUSE <opensuse-getting-started>`
======================================================= ==================================================== ==========================================================

After running the example application have a look at the "`Python GTK 3
Tutorial <https://python-gtk-3-tutorial.readthedocs.io>`__" for more examples
on how to create GTK apps and the "`PyGObject API Reference
<https://lazka.github.io/pgi-docs>`__" for API documentation for all supported
libraries.

.. _windows-getting-started:

|windows-logo| Windows
----------------------

#) Go to http://www.msys2.org/ and download the x86_64 installer
#) Follow the instructions on the page for setting up the basic environment
#) Run ``C:\msys64\mingw64.exe`` - a terminal window should pop up
#) Execute ``pacman -Suy``
#) Execute ``pacman -S mingw-w64-x86_64-gtk3 mingw-w64-x86_64-python3 mingw-w64-x86_64-python3-gobject``
#) To test that GTK 3 is working you can run ``gtk3-demo``
#) Copy the ``hello.py`` script you created to ``C:\msys64\home\<username>``
#) In the mingw32 terminal execute ``python3 hello.py`` - a window should appear.

.. figure:: images/start_windows.png
    :scale: 60%


.. _ubuntu-getting-started:

|ubuntu-logo| Ubuntu / |debian-logo| Debian
-------------------------------------------

Installing the system provided PyGObject:
  #) Open a terminal
  #) Execute ``sudo apt install python3-gi python3-gi-cairo gir1.2-gtk-3.0``
  #) Change the directory to where your ``hello.py`` script can be found (e.g. ``cd Desktop``)
  #) Run ``python3 hello.py``

Installing from PyPI with pip:
  #) Open a terminal and enter your virtual environment
  #) Execute ``sudo apt install libgirepository1.0-dev gcc libcairo2-dev pkg-config python3-dev gir1.2-gtk-3.0``
     to install the build dependencies and GTK
  #) Execute ``pip3 install pycairo`` to build and install Pycairo
  #) Execute ``pip3 install PyGObject`` to build and install PyGObject
  #) Change the working directory to where your ``hello.py`` script can be found
  #) Run ``python3 hello.py``

.. figure:: images/start_linux.png
    :scale: 60%


.. _fedora-getting-started:

|fedora-logo| Fedora
--------------------

Installing the system provided PyGObject:
  #) Open a terminal
  #) Execute ``sudo dnf install python3-gobject gtk3``
  #) Change the working directory to where your ``hello.py`` script can be found
  #) Run ``python3 hello.py``

Installing from PyPI with pip:
  #) Open a terminal and enter your virtual environment
  #) Execute ``sudo dnf install gcc gobject-introspection-devel cairo-devel pkg-config python3-devel gtk3``
     to install the build dependencies and GTK
  #) Execute ``pip3 install pycairo`` to build and install Pycairo
  #) Execute ``pip3 install PyGObject`` to build and install PyGObject
  #) Change the working directory to where your ``hello.py`` script can be found
  #) Run ``python3 hello.py``


.. _arch-getting-started:

|arch-logo| Arch Linux
----------------------

Installing the system provided PyGObject:
  #) Open a terminal
  #) Execute ``sudo pacman -S python-gobject gtk3``
  #) Change the working directory to where your ``hello.py`` script can be found
  #) Run ``python3 hello.py``

Installing from PyPI with pip:
  #) Open a terminal and enter your virtual environment
  #) Execute ``sudo pacman -S python cairo pkgconf gobject-introspection gtk3``
     to install the build dependencies and GTK
  #) Execute ``pip3 install pycairo`` to build and install Pycairo
  #) Execute ``pip3 install PyGObject`` to build and install PyGObject
  #) Change the working directory to where your ``hello.py`` script can be found
  #) Run ``python3 hello.py``


.. _opensuse-getting-started:

|opensuse-logo| openSUSE
------------------------

Installing the system provided PyGObject:
  #) Open a terminal
  #) Execute ``sudo zypper install python3-gobject python3-gobject-Gdk typelib-1_0-Gtk-3_0 libgtk-3-0``
  #) Change the directory to where your ``hello.py`` script can be found
  #) Run ``python3 hello.py``

Installing from PyPI with pip:
  #) Open a terminal and enter your virtual environment
  #) Execute ``sudo zypper install cairo-devel pkg-config python3-devel gcc gobject-introspection-devel``
     to install the build dependencies and GTK
  #) Execute ``pip3 install pycairo`` to build and install Pycairo
  #) Execute ``pip3 install PyGObject`` to build and install PyGObject
  #) Change the working directory to where your ``hello.py`` script can be found
  #) Run ``python3 hello.py``


.. _macosx-getting-started:

|macosx-logo| macOS
-------------------

#) Go to https://brew.sh/ and install homebrew
#) Open a terminal
#) Execute ``brew install pygobject3 gtk+3``
#) Change the working directory to where your ``hello.py`` script can be found
#) Run ``python3 hello.py``

.. figure:: images/start_macos.png
    :scale: 70%


----

For more details on how to use a virtualenv with PyGObject, see the
":ref:`devenv`" page.