From ea39a905ecc28864ae5c010992e06876700f3020 Mon Sep 17 00:00:00 2001
From: minikids <96962258+minikids@users.noreply.github.com>
Date: Thu, 28 Aug 2025 21:08:24 -0600
Subject: [PATCH] Update setup-building.rst

---
 getting-started/setup-building.rst | 19 +++++++++++++++++++
 1 file changed, 19 insertions(+)

diff --git a/getting-started/setup-building.rst b/getting-started/setup-building.rst
index f6a6f6a94..2102448cd 100644
--- a/getting-started/setup-building.rst
+++ b/getting-started/setup-building.rst
@@ -699,6 +699,25 @@ wrap the invocation of the Xcode :program:`xcrun` tool, removing user- and
 version-specific paths from the values encoded in the :py:mod:`sysconfig`
 module. Copies of these scripts are included in the final build products.
 
+
+.. note::
+
+   The ``--enable-framework`` option installs Python as a macOS Framework.
+   This changes the install location to
+   ``/Library/Frameworks/Python.framework/Versions/X.Y/`` and integrates
+   Python with macOS’s native framework system.
+
+   Framework builds are required for some GUI libraries (such as ``tkinter`` or
+   ``PyObjC``) and allow Python to be embedded in Cocoa applications via
+   ``NSBundle``.
+
+   Without ``--enable-framework``, you still get a working command-line
+   ``python3``, but certain macOS-specific integrations (GUI event loops,
+   app embedding, etc.) will not work.
+
+
+
+
 Once this build completes, the ``iOS/Frameworks`` folder will contain a
 ``Python.framework`` that can be used for testing.