From 04862bce4834c3935438f44c03f4d9f4c4eee73f Mon Sep 17 00:00:00 2001
From: thePR0M3TH3AN <53631862+PR0M3TH3AN@users.noreply.github.com>
Date: Sat, 19 Jul 2025 13:43:49 -0400
Subject: [PATCH] install: ensure cairo installed

---
 README.md                                         |  4 ++++
 .../content/01-getting-started/06-gui_adapter.md  |  3 +++
 scripts/install.sh                                | 15 ++++++++++-----
 3 files changed, 17 insertions(+), 5 deletions(-)

diff --git a/README.md b/README.md
index f80cf8a..2e0983b 100644
--- a/README.md
+++ b/README.md
@@ -251,6 +251,10 @@ for your platform:
 # Linux
 pip install toga-gtk
 
+# If you see build errors about "cairo" on Linux, install the cairo
+# development headers using your package manager, e.g.:
+sudo apt-get install libcairo2 libcairo2-dev
+
 # Windows
 pip install toga-winforms
 
diff --git a/docs/docs/content/01-getting-started/06-gui_adapter.md b/docs/docs/content/01-getting-started/06-gui_adapter.md
index fe77b86..dcb2dac 100644
--- a/docs/docs/content/01-getting-started/06-gui_adapter.md
+++ b/docs/docs/content/01-getting-started/06-gui_adapter.md
@@ -23,6 +23,9 @@ backend for your platform:
 # Linux
 pip install toga-gtk
 
+# If installation fails with cairo errors, install libcairo2-dev or the
+# cairo development package using your distro's package manager.
+
 # Windows
 pip install toga-winforms
 
diff --git a/scripts/install.sh b/scripts/install.sh
index 1fa2de1..95bc6a4 100755
--- a/scripts/install.sh
+++ b/scripts/install.sh
@@ -86,13 +86,18 @@ main() {
     # 3. Install OS-specific dependencies
     print_info "Checking for build dependencies..."
     if [ "$OS_NAME" = "Linux" ]; then
-        if command -v apt-get &> /dev/null; then sudo apt-get update && sudo apt-get install -y build-essential pkg-config xclip;
-        elif command -v dnf &> /dev/null; then sudo dnf groupinstall -y "Development Tools" && sudo dnf install -y pkg-config xclip;
-        elif command -v pacman &> /dev/null; then sudo pacman -Syu --noconfirm base-devel pkg-config xclip;
-        else print_warning "Could not detect package manager. Ensure build tools and pkg-config are installed."; fi
+        if command -v apt-get &> /dev/null; then
+            sudo apt-get update && sudo apt-get install -y build-essential pkg-config xclip libcairo2 libcairo2-dev
+        elif command -v dnf &> /dev/null; then
+            sudo dnf groupinstall -y "Development Tools" && sudo dnf install -y pkg-config cairo cairo-devel xclip
+        elif command -v pacman &> /dev/null; then
+            sudo pacman -Syu --noconfirm base-devel pkg-config cairo xclip
+        else
+            print_warning "Could not detect package manager. Ensure build tools, cairo, and pkg-config are installed."
+        fi
     elif [ "$OS_NAME" = "Darwin" ]; then
         if ! command -v brew &> /dev/null; then print_error "Homebrew not installed. See https://brew.sh/"; fi
-        brew install pkg-config
+        brew install pkg-config cairo
     fi
 
     # 4. Clone or update the repository