docs/getting_started.rst

   1 .. include:: icons.rst
   2
   3 .. _gettingstarted:
   4
   5 ===============
   6 Getting Started
   7 ===============
   8
   9 To get things started we will try to run a very simple `GTK+
  10 <https://www.gtk.org/>`_ based GUI application using the :doc:`PyGObject <index>` provided
  11 Python bindings. First create a small Python script called ``hello.py`` with
  12 the following content and save it somewhere:
  13
  14 .. code:: python
  15
  16     import gi
  17     gi.require_version("Gtk", "3.0")
  18     from gi.repository import Gtk
  19
  20     window = Gtk.Window(title="Hello World")
  21     window.show()
  22     window.connect("destroy", Gtk.main_quit)
  23     Gtk.main()
  24
  25 Before we can run the example application we need to install PyGObject, GTK+
  26 and their dependencies. Follow the instructions for your platform below.
  27
  28 ======================================================= ==================================================== ==================================================== ==========================================================
  29 |ubuntu-logo| :ref:`Ubuntu <ubuntu-getting-started>`    |fedora-logo| :ref:`Fedora <fedora-getting-started>` |arch-logo| :ref:`Arch Linux <arch-getting-started>` |opensuse-logo| :ref:`openSUSE <opensuse-getting-started>`
  30 |windows-logo| :ref:`Windows <windows-getting-started>` |macosx-logo| :ref:`macOS <macosx-getting-started>`  |python-logo| :ref:`PyPI <pypi-getting-started>`
  31 ======================================================= ==================================================== ==================================================== ==========================================================
  32
  33
  34 .. _windows-getting-started:
  35
  36 |windows-logo| Windows
  37 ----------------------
  38
  39 #) Go to http://www.msys2.org/ and download the x86_64 installer
  40 #) Follow the instructions on the page for setting up the basic environment
  41 #) Run ``C:\msys64\mingw32.exe`` - a terminal window should pop up
  42 #) Execute ``pacman -Suy``
  43 #) Execute ``pacman -S mingw-w64-i686-gtk3 mingw-w64-i686-python2-gobject mingw-w64-i686-python3-gobject``
  44 #) To test that GTK+3 is working you can run ``gtk3-demo``
  45 #) Copy the ``hello.py`` script you created to ``C:\msys64\home\<username>``
  46 #) In the mingw32 terminal execute ``python3 hello.py`` - a window should appear.
  47
  48 .. figure:: images/start_windows.png
  49     :scale: 60%
  50
  51
  52 .. _ubuntu-getting-started:
  53
  54 |ubuntu-logo| Ubuntu / |debian-logo| Debian
  55 -------------------------------------------
  56
  57 1) Open a terminal
  58 2) Execute ``sudo apt install python-gi python-gi-cairo python3-gi python3-gi-cairo gir1.2-gtk-3.0``
  59 3) Change the directory to where your ``hello.py`` script can be found (e.g. ``cd Desktop``)
  60 4) Run ``python3 hello.py``
  61
  62 .. figure:: images/start_linux.png
  63     :scale: 60%
  64
  65
  66 .. _fedora-getting-started:
  67
  68 |fedora-logo| Fedora
  69 --------------------
  70
  71 1) Open a terminal
  72 2) Execute ``sudo dnf install pygobject3 python3-gobject gtk3``
  73 3) Change the directory to where your ``hello.py`` script can be found (e.g. ``cd Desktop``)
  74 4) Run ``python3 hello.py``
  75
  76
  77 .. _arch-getting-started:
  78
  79 |arch-logo| Arch Linux
  80 ----------------------
  81
  82 1) Open a terminal
  83 2) Execute ``sudo pacman -S python-gobject python2-gobject gtk3``
  84 3) Change the directory to where your ``hello.py`` script can be found (e.g. ``cd Desktop``)
  85 4) Run ``python3 hello.py``
  86
  87
  88 .. _opensuse-getting-started:
  89
  90 |opensuse-logo| openSUSE
  91 ------------------------
  92
  93 1) Open a terminal
  94 2) Execute ``sudo zypper install python-gobject python3-gobject gtk3``
  95 3) Change the directory to where your ``hello.py`` script can be found (e.g. ``cd Desktop``)
  96 4) Run ``python3 hello.py``
  97
  98
  99 .. _macosx-getting-started:
 100
 101 |macosx-logo| macOS
 102 -------------------
 103
 104 1) Go to https://brew.sh/ and install homebrew
 105 2) Open a terminal
 106 3) Execute ``brew install pygobject3 --with-python@2 gtk+3`` to install for both python2 and python3
 107 4) Change the directory to where your ``hello.py`` script can be found (e.g. ``cd Desktop``)
 108 5) Run ``python3 hello.py``
 109
 110 .. figure:: images/start_macos.png
 111     :scale: 70%
 112
 113
 114 .. _pypi-getting-started:
 115
 116 |python-logo| From PyPI
 117 -----------------------
 118
 119 PyGObject is also available on PyPI: https://pypi.org/project/PyGObject
 120
 121 For this approach you have to make sure that all runtime and build
 122 dependencies are present yourself as pip will only take care of pycairo.
 123
 124 .. code::
 125
 126     virtualenv --python=python3 myvenv
 127     source myvenv/bin/activate
 128     pip install pygobject
 129     python hello.py
 130
 131
 132 For more details on how to use a virtualenv with PyGObject, see the
 133 ":ref:`devenv`" page.