Linux OS package instructions are not obvious enough

[Resonanz]

When installing Toga on Ubuntu (and Raspberri Pi) I had the same issue regarding pycairo (details pasted below)

Environment:

• Operating System: Ubuntu
• Python version: 3.10.6
• Software versions: toga_demo-0.3.0.dev39-py3-none-any.whl

UBUNTU: python3 -m pip install --pre toga-demo

Installing build dependencies ... error
  error: subprocess-exited-with-error
  
  × pip subprocess to install build dependencies did not run successfully.
  │ exit code: 1
  ╰─> [38 lines of output]
      Collecting setuptools
        Using cached setuptools-65.5.1-py3-none-any.whl (1.2 MB)
      Collecting wheel
        Using cached wheel-0.38.4-py3-none-any.whl (36 kB)
      Collecting pycairo
        Using cached pycairo-1.21.0.tar.gz (340 kB)
        Installing build dependencies: started
        Installing build dependencies: finished with status 'done'
        Getting requirements to build wheel: started
        Getting requirements to build wheel: finished with status 'done'
        Preparing metadata (pyproject.toml): started
        Preparing metadata (pyproject.toml): finished with status 'done'
      Building wheels for collected packages: pycairo
        Building wheel for pycairo (pyproject.toml): started
        Building wheel for pycairo (pyproject.toml): finished with status 'error'
        error: subprocess-exited-with-error
      
        × Building wheel for pycairo (pyproject.toml) did not run successfully.
        │ exit code: 1
        ╰─> [12 lines of output]
            running bdist_wheel
            running build
            running build_py
            creating build
            creating build/lib.linux-x86_64-cpython-310
            creating build/lib.linux-x86_64-cpython-310/cairo
            copying cairo/__init__.py -> build/lib.linux-x86_64-cpython-310/cairo
            copying cairo/__init__.pyi -> build/lib.linux-x86_64-cpython-310/cairo
            copying cairo/py.typed -> build/lib.linux-x86_64-cpython-310/cairo
            running build_ext
            'pkg-config' not found.
            Command ['pkg-config', '--print-errors', '--exists', 'cairo >= 1.15.10']
            [end of output]
      
        note: This error originates from a subprocess, and is likely not a problem with pip.
        ERROR: Failed building wheel for pycairo
      Failed to build pycairo
      ERROR: Could not build wheels for pycairo, which is required to install pyproject.toml-based projects
      [end of output]
  
  note: This error originates from a subprocess, and is likely not a problem with pip.
error: subprocess-exited-with-error

× pip subprocess to install build dependencies did not run successfully.
│ exit code: 1
╰─> See above for output.

Suggestions for installing pycairo to get around this issue:

https://stackoverflow.com/questions/70508775/error-could-not-build-wheels-for-pycairo-which-is-required-to-install-pyprojec

sudo apt-get install libcairo2

libcairo2 is already the newest version (1.16.0-5ubuntu2).

apt-get install libcairo2-dev

Lots of libraries installed following this command. Now try Toga again:

UBUNTU: python3 -m pip install --pre toga-demo

Package gobject-introspection-1.0 was not found in the pkg-config search path.
      Perhaps you should add the directory containing `gobject-introspection-1.0.pc'
      to the PKG_CONFIG_PATH environment variable
      No package 'gobject-introspection-1.0' found
      Command '('pkg-config', '--print-errors', '--exists', 'gobject-introspection-1.0 >= 1.56.0')' returned non-zero exit status 1.
      
      Try installing it with: 'sudo apt install libgirepository1.0-dev'

sudo apt install libgirepository1.0-dev

Installed fine, try Toga again:

Successfully installed gbulb-0.6.3 pycairo-1.21.0 pygobject-3.42.2 toga-0.3.0.dev39 toga-core-0.3.0.dev39 toga-demo-0.3.0.dev39 toga-gtk-0.3.0.dev39 travertino-0.1.3

Toga now working beautifully !!!

[mhsmith]

These OS packages are already mentioned in the first page of the tutorial, in the "Linux" tab of "install Toga into your virtual environment". However, if I was reading that, I wouldn't bother clicking on the Linux tab because I already know that the pip install command is the same on all platforms, so I would probably have missed it too.

Instead, it would be better for the OS dependencies to be a separate section, as it is on the "How to contribute code" page. Or even better, create a separate page for the whole process of installing Python, creating the virtual environment and installing OS packages, and reference it from both locations.

[TGMaker]

Fyi I had the same issue for Ubuntu. I copy pasted the line from Ubuntu 18.04+ / Debian 10+. Installing python3-cairo-dev fixed it for me.