From d10cdd3db7c25b8d6ef5703d467f43e28cbf0d55 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Ren=C3=A9=20Canna=C3=B2?= <rene.cannao@gmail.com>
Date: Tue, 20 Jan 2026 22:41:56 +0100
Subject: [PATCH] Updated macOS build instructions in INSTALL.md and added
 doc/BUILD-MACOS.md

---
 INSTALL.md         | 11 ++++++++++-
 doc/BUILD-MACOS.md | 49 ++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 59 insertions(+), 1 deletion(-)
 create mode 100644 doc/BUILD-MACOS.md

diff --git a/INSTALL.md b/INSTALL.md
index 8d9b17970..33e727340 100644
--- a/INSTALL.md
+++ b/INSTALL.md
@@ -188,7 +188,16 @@ zypper install -y automake bzip2 cmake make gcc-c++ gcc git openssl openssl-deve
 
 ### macOS (using Homebrew):
 ```bash
-brew install automake bzip2 cmake make git gpatch gnutls ossp-uuid
+brew install automake bzip2 cmake make git gpatch gnutls openssl@3 icu4c pkg-config libiconv zlib
+```
+
+To compile on macOS, you must set the following environment variables to ensure the build system can find OpenSSL and Homebrew dependencies:
+
+```bash
+export PATH="/opt/homebrew/bin:$PATH"
+export PKG_CONFIG_PATH="/opt/homebrew/opt/openssl@3/lib/pkgconfig:$PKG_CONFIG_PATH"
+export OPENSSL_ROOT_DIR="/opt/homebrew/opt/openssl@3"
+make # or make debug
 ```
 
 For more details, inspect the docker build images:
diff --git a/doc/BUILD-MACOS.md b/doc/BUILD-MACOS.md
new file mode 100644
index 000000000..3196c57bb
--- /dev/null
+++ b/doc/BUILD-MACOS.md
@@ -0,0 +1,49 @@
+# Compiling ProxySQL on macOS
+
+This guide provides step-by-step instructions for compiling ProxySQL from source on macOS (Intel or Apple Silicon) using Homebrew.
+
+## Prerequisites
+
+Ensure you have [Homebrew](https://brew.sh/) installed.
+
+### Install Dependencies
+
+Run the following command to install the required build tools and libraries:
+
+```bash
+brew install automake bzip2 cmake make git gpatch gnutls openssl@3 icu4c pkg-config libiconv zlib
+```
+
+## Compilation Steps
+
+To compile ProxySQL, you must set the following environment variables so the build system can locate OpenSSL and other Homebrew-provided libraries.
+
+### 1. Set Environment Variables
+
+```bash
+export PATH="/opt/homebrew/bin:$PATH"
+export PKG_CONFIG_PATH="/opt/homebrew/opt/openssl@3/lib/pkgconfig:$PKG_CONFIG_PATH"
+export OPENSSL_ROOT_DIR="/opt/homebrew/opt/openssl@3"
+```
+
+### 2. Run the Build
+
+You can now run the standard build command:
+
+```bash
+make
+```
+
+Or for a debug build:
+
+```bash
+make debug
+```
+
+## Troubleshooting
+
+### Linking Issues
+If the linker fails to find `libssl` or `libcrypto`, ensure that `OPENSSL_ROOT_DIR` and `PKG_CONFIG_PATH` are correctly set to point to your Homebrew OpenSSL installation.
+
+### Missing ICU Headers
+The build system is configured to find `icu4c` via Homebrew. If you encounter errors related to ICU, ensure `icu4c` is installed and the Homebrew prefix is correct.