Linuxbrew causing issues with Toga installs

[freakboy3742]

Describe the bug

Initially reported as #3745.

It appears that having Linuxbrew installed can cause issues with the operation of Toga.

Steps to reproduce

1. On a Unix machine, install Linuxbrew
2. Install GTK (or an app with GTK as a dependency) using Linuxbrew
3. Run toga-demo
4. See error

Traceback (most recent call last):
  File "/tmp/toga-tutorial/.venv/lib/python3.13/site-packages/gi/importer.py", line 139, in create_module
    introspection_module = get_introspection_module(namespace)
  File "/tmp/toga-tutorial/.venv/lib/python3.13/site-packages/gi/module.py", line 243, in get_introspection_module
    module = IntrospectionModule(namespace, version)
  File "/tmp/toga-tutorial/.venv/lib/python3.13/site-packages/gi/module.py", line 111, in __init__
    repository.require(namespace, version)
    ~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^
gi.RepositoryError: Typelib file for namespace 'cairo', version '1.0' not found

The above exception was the direct cause of the following exception:

Traceback (most recent call last):
  File "/tmp/toga-tutorial/./.venv/bin/toga-demo", line 7, in <module>
    sys.exit(run())
             ~~~^^
  File "/tmp/toga-tutorial/.venv/lib/python3.13/site-packages/toga_demo/__main__.py", line 6, in run
    main().main_loop()
    ~~~~^^
  File "/tmp/toga-tutorial/.venv/lib/python3.13/site-packages/toga_demo/app.py", line 106, in main
    return TogaDemo("Toga Demo", "org.beeware.toga-demo")
  File "/tmp/toga-tutorial/.venv/lib/python3.13/site-packages/toga/app.py", line 285, in __init__
    self.factory = get_platform_factory()
                   ~~~~~~~~~~~~~~~~~~~~^^
  File "/tmp/toga-tutorial/.venv/lib/python3.13/site-packages/toga/platform.py", line 120, in get_platform_factory
    factory = importlib.import_module(f"{backend.value}.factory")
  File "/home/linuxbrew/.linuxbrew/opt/python@3.13/lib/python3.13/importlib/__init__.py", line 88, in import_module
    return _bootstrap._gcd_import(name[level:], package, level)
           ~~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "<frozen importlib._bootstrap>", line 1387, in _gcd_import
  File "<frozen importlib._bootstrap>", line 1360, in _find_and_load
  File "<frozen importlib._bootstrap>", line 1331, in _find_and_load_unlocked
  File "<frozen importlib._bootstrap>", line 935, in _load_unlocked
  File "<frozen importlib._bootstrap_external>", line 1026, in exec_module
  File "<frozen importlib._bootstrap>", line 488, in _call_with_frames_removed
  File "/tmp/toga-tutorial/.venv/lib/python3.13/site-packages/toga_gtk/factory.py", line 3, in <module>
    from . import dialogs
  File "/tmp/toga-tutorial/.venv/lib/python3.13/site-packages/toga_gtk/dialogs.py", line 5, in <module>
    from .libs import GTK_VERSION, Gtk
  File "/tmp/toga-tutorial/.venv/lib/python3.13/site-packages/toga_gtk/libs/__init__.py", line 2, in <module>
    from .gtk import *  # noqa: F401, F403
    ^^^^^^^^^^^^^^^^^^
  File "/tmp/toga-tutorial/.venv/lib/python3.13/site-packages/toga_gtk/libs/gtk.py", line 10, in <module>
    from gi.repository import (  # noqa: E402, F401
    ...<7 lines>...
    )
  File "/tmp/toga-tutorial/.venv/lib/python3.13/site-packages/gi/importer.py", line 141, in create_module
    raise ImportError(e) from e
ImportError: Typelib file for namespace 'cairo', version '1.0' not found

Expected behavior

Having installed GTK with Linuxbrew shouldn't prevent toga-demo (or any other Toga app) from starting.

Screenshots

No response

Environment

• Operating System: Fedora 42 (but likely any Linux)
• Python version: Any
• Software versions:
  • Toga: 0.5.2

Logs

Additional context

There's a number of possible responses to this issue.

At the very least, we should document the potential conflict on the Linux platform page in the docs.

A more permanent fix will depend on what is possible with Linuxbrew.

It may be possible to Toga under Linuxbrew if the right Linuxbrew dependencies are installed. If this is the case, we should document those dependencies.

However, even if we can configure Linuxbrew appropriately, we also need to confirm that if a user builds a system package of their app with Briefcase, that package works:

1. If the developer has Linuxbrew installed but the end-user doesn't
2. If the developer doesn't have Linuxbrew installed, but the end user does.

If these two scenarios cause issues, it's not clear if that problem would represent a Toga issue or a Briefcase packaging issue.