From 46e6b271f720a67fa72dc0f460ca69fb7601443e Mon Sep 17 00:00:00 2001
From: bruvzg <7645683+bruvzg@users.noreply.github.com>
Date: Sun, 18 Sep 2022 22:19:40 +0300
Subject: [PATCH] Update macOS export page to reflect rcodesign support.

---
 tutorials/export/exporting_for_macos.rst | 141 ++++++++++++++---------
 1 file changed, 87 insertions(+), 54 deletions(-)

diff --git a/tutorials/export/exporting_for_macos.rst b/tutorials/export/exporting_for_macos.rst
index 13f0c7cdb..e8394689d 100644
--- a/tutorials/export/exporting_for_macos.rst
+++ b/tutorials/export/exporting_for_macos.rst
@@ -15,8 +15,6 @@ This bundle can be exported as is, packed in a ZIP archive or DMG disk image (on
 Requirements
 ------------
 
--  To enable code signing with Apple Developer ID and notarization, you must export from a computer running macOS with Xcode command line tools installed.
--  Ad-hoc code signing is supported on all platforms, without additional tools.
 -  Download the Godot export templates. Use the Godot menu: ``Editor > Manage Export Templates``.
 -  A valid and unique ``Bundle identifier`` should be set in the ``Application`` section of the export options.
 
@@ -31,14 +29,23 @@ By default, macOS will run only applications that are signed and notarized. If y
 
 To notarize an app, you **must** have a valid `Apple Developer ID Certificate <https://developer.apple.com/>`__.
 
-If you have an Apple Developer ID Certificate
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+If you have an Apple Developer ID Certificate and exporting from macOS
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-- Export your project from a computer running macOS with Xcode command line tools installed.
-- Enable ``Code Signing``, ``Notarization``, ``Hardened Runtime`` and ``Timestamp`` and disable the ``Debug`` entitlement.
-- Provide valid Apple ID credentials and certificate identity.
+Install `Xcode <https://developer.apple.com/xcode/>`__ command line tools and open Xcode at least once or run the ``sudo xcodebuild -license accept`` command to accept license agreement.
 
-If ``Notarization`` is enabled, Godot will automatically upload the exported project for notarization.
+To sign exported app
+^^^^^^^^^^^^^^^^^^^^
+
+- Select ``Xcode codesign`` in the ``Code Signing > Codesign`` option.
+- Set valid Apple ID certificate identity (certificate "Common Name") in the ``Code Signing > Identity`` section.
+
+To notarize exported app
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+- Select ``Xcode altool`` in the ``Notarization > Notarization`` option.
+- Disable the ``Debugging`` entitlement.
+- Set valid Apple ID login / app. specific password or `App Store Connect <https://developer.apple.com/documentation/appstoreconnectapi>`__ API UUID / Key in the ``Notarization`` section.
 
 You can use the ``xcrun notarytool history`` command to check notarization status and use the ``xcrun notarytool log {ID}`` command to download the notarization log.
 
@@ -46,10 +53,34 @@ If you encounter notarization issues, see `Resolving common notarization issues
 
 After notarization is completed, `staple the ticket <https://developer.apple.com/documentation/security/notarizing_macos_software_before_distribution/customizing_the_notarization_workflow>`__ to the exported project.
 
+If you have an Apple Developer ID Certificate and exporting from Linux or Windows
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Install `PyOxidizer rcodesign <https://github.com/indygreg/PyOxidizer/tree/main/apple-codesign>`__, and configure the path to ``rcodesign`` in the ``Editor Settings > Export > macOS > rcodesign``.
+
+To sign exported app
+^^^^^^^^^^^^^^^^^^^^
+
+- Select ``PyOxidizer rcodesign`` in the ``Code Signing > Codesign`` option.
+- Set valid Apple ID PKCS #12 certificate file and password in the ``Code Signing`` section.
+
+To notarize exported app
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+- Select ``PyOxidizer rcodesign`` in the ``Notarization > Notarization`` option.
+- Disable the ``Debugging`` entitlement.
+- Set valid `App Store Connect <https://developer.apple.com/documentation/appstoreconnectapi>`__ API UUID / Key in the ``Notarization`` section.
+
+You can use the ``rcodesign notary-log`` command to check notarization status.
+
+After notarization is completed, use the ``rcodesign staple`` command to staple the ticket to the exported project.
+
 If you do not have an Apple Developer ID Certificate
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Keep ``Code Signing`` enabled and leave the ``Identity`` option empty (when exporting from a computer running macOS, on other platforms this option is hidden).
+- Select ``Built-in (ad-hoc only)`` in the ``Code Signing > Codesign`` option.
+- Select ``Disabled`` in the ``Notarization > Notarization`` option.
+
 In this case Godot will use a ad-hoc signature, which will make running an exported app easier for the end users, see the :ref:`Running Godot apps on macOS <doc_running_on_macos>` page for more information.
 
 Signing Options
@@ -58,46 +89,46 @@ Signing Options
 +------------------------------+---------------------------------------------------------------------------------------------------+
 | Option                       | Description                                                                                       |
 +==============================+===================================================================================================+
-| Enable                       | Enables code signing.                                                                             |
+| Codesign                     | Tool to use for code signing.                                                                     |
 +------------------------------+---------------------------------------------------------------------------------------------------+
-| Identity                     | The "Full Name" or "Common Name" of the signing identity, store in the macOS keychain. [1]_ [2]_  |
+| Identity                     | The "Full Name" or "Common Name" of the signing identity, store in the macOS keychain. [1]_       |
 +------------------------------+---------------------------------------------------------------------------------------------------+
-| Timestamp                    | Requests a timestamp server to authenticate the time of signing. Required for notarization. [2]_  |
+| Certificate File             | The PKCS #12 certificate file. [2]_                                                               |
 +------------------------------+---------------------------------------------------------------------------------------------------+
-| Hardened Runtime             | Enables "Hardened Runtime". Required for notarization. [2]_                                       |
+| Certificate Password         | Password for the certificate file. [2]_                                                           |
 +------------------------------+---------------------------------------------------------------------------------------------------+
-| Replace Existing Signature   | Replaces existing signatures of the GDNative libraries and embedded helper executables.           |
+| Custom Options               | Array of command line arguments passed to the code signing tool.                                  |
 +------------------------------+---------------------------------------------------------------------------------------------------+
 
-.. note::
-
-    To notarize an app, you must enable the ``Hardened Runtime`` and ``Timestamp``.
-
-    The ``Hardened Runtime`` and ``Timestamp`` options are incompatible with ad-hoc signing and will be ignored.
-
-.. [1] Leave ``Identity`` option empty to use ad-hoc signature.
-.. [2] This option is visible only when exporting from a computer running macOS.
+.. [1] This option is visible only when signing with Xcode codesign.
+.. [2] These options are visible only when signing with PyOxidizer rcodesign.
 
 Notarization Options
 ~~~~~~~~~~~~~~~~~~~~
 
-+--------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| Option             | Description                                                                                                                                                                  |
-+====================+==============================================================================================================================================================================+
-| Enable             | Enables automatic upload for notarization.                                                                                                                                   |
-+--------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| Apple ID Name      | Apple ID account name (email address)                                                                                                                                        |
-+--------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| Apple ID Password  | Apple ID app-specific password. See `Using app-specific passwords <https://support.apple.com/en-us/HT204397>`__ to enable two-factor authentication and create app password. |
-+--------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| Apple Team ID      | Team ID, if your Apple ID belongs to multiple teams                                                                                                                          |
-+--------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-
-See `Notarizing macOS Software Before Distribution <https://developer.apple.com/documentation/security/notarizing_macos_software_before_distribution?language=objc>`__ for more info.
++--------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| Option             | Description                                                                                                                                                                       |
++====================+===================================================================================================================================================================================+
+| Notarization       | Tool to use for notarization.                                                                                                                                                     |
++--------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| Apple ID Name      | Apple ID account name (email address). [3]_                                                                                                                                       |
++--------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| Apple ID Password  | Apple ID app-specific password. See `Using app-specific passwords <https://support.apple.com/en-us/HT204397>`__ to enable two-factor authentication and create app password. [3]_ |
++--------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| Apple Team ID      | Team ID ("Organization Unit"), if your Apple ID belongs to multiple teams (optional). [3]_                                                                                        |
++--------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| API UUID           | Apple `App Store Connect <https://developer.apple.com/documentation/appstoreconnectapi>`__ API issuer UUID.                                                                       |
++--------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| API Key            | Apple `App Store Connect <https://developer.apple.com/documentation/appstoreconnectapi>`__ API key.                                                                               |
++--------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
 
 .. note::
 
-    Notarization is supported when exporting from a computer running macOS, these options are hidden on other platforms.
+    You should set either Apple ID Name/Password or App Store Connect API UUID/Key.
+
+.. [3] These options are visible only when notarizing with Xcode altool.
+
+See `Notarizing macOS Software Before Distribution <https://developer.apple.com/documentation/security/notarizing_macos_software_before_distribution?language=objc>`__ for more info.
 
 Entitlements
 ------------
@@ -111,11 +142,11 @@ See `Hardened Runtime <https://developer.apple.com/documentation/security/harden
 +---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
 | Entitlement                           | Description                                                                                                                                                                                      |
 +=======================================+==================================================================================================================================================================================================+
-| Allow JIT Code Execution [3]_         | Allows creating writable and executable memory for JIT code. If you are using add-ons with dynamic or self-modifying native code, enable them according to the add-on documentation.             |
+| Allow JIT Code Execution [4]_         | Allows creating writable and executable memory for JIT code. If you are using add-ons with dynamic or self-modifying native code, enable them according to the add-on documentation.             |
 +---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| Allow Unsigned Executable Memory [3]_ | Allows creating writable and executable memory without JIT restrictions. If you are using add-ons with dynamic or self-modifying native code, enable them according to the add-on documentation. |
+| Allow Unsigned Executable Memory [4]_ | Allows creating writable and executable memory without JIT restrictions. If you are using add-ons with dynamic or self-modifying native code, enable them according to the add-on documentation. |
 +---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| Allow DYLD Environment Variables [3]_ | Allows app to uss dynamic linker environment variables to inject code.  f you are using add-ons with dynamic or self-modifying native code, enable them according to the add-on documentation.   |
+| Allow DYLD Environment Variables [4]_ | Allows app to uss dynamic linker environment variables to inject code.  f you are using add-ons with dynamic or self-modifying native code, enable them according to the add-on documentation.   |
 +---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
 | Disable Library Validation            | Allows app to load arbitrary libraries and frameworks. Enabled it if you are using GDNative add-ons and ad-hoc signature, or want to support user-provided external add-ons.                     |
 +---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
@@ -125,20 +156,20 @@ See `Hardened Runtime <https://developer.apple.com/documentation/security/harden
 +---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
 | Location                              | Enable if you need to use location information from Location Services, if it's enabled you should also provide usage message in the `privacy/location_usage_description` option.                 |
 +---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| Address Book                          | [4]_ Enable to allow access contacts in the user's address book, if it's enabled you should also provide usage message in the `privacy/address_book_usage_description` option.                   |
+| Address Book                          | [5]_ Enable to allow access contacts in the user's address book, if it's enabled you should also provide usage message in the `privacy/address_book_usage_description` option.                   |
 +---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| Calendars                             | [4]_ Enable to allow access to the user's calendar, if it's enabled you should also provide usage message in the `privacy/calendar_usage_description` option.                                    |
+| Calendars                             | [5]_ Enable to allow access to the user's calendar, if it's enabled you should also provide usage message in the `privacy/calendar_usage_description` option.                                    |
 +---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| Photo Library                         | [4]_ Enable to allow access to the user's Photos library, if it's enabled you should also provide usage message in the `privacy/photos_library_usage_description` option.                        |
+| Photo Library                         | [5]_ Enable to allow access to the user's Photos library, if it's enabled you should also provide usage message in the `privacy/photos_library_usage_description` option.                        |
 +---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| Apple Events                          | [4]_ Enable to allow app to send Apple events to other apps.                                                                                                                                     |
+| Apple Events                          | [5]_ Enable to allow app to send Apple events to other apps.                                                                                                                                     |
 +---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| Debugging                             | [5]_ You can temporarily enable this entitlement to use native debugger (GDB, LLDB) with the exported app. This entitlement should be disabled for production export.                            |
+| Debugging                             | [6]_ You can temporarily enable this entitlement to use native debugger (GDB, LLDB) with the exported app. This entitlement should be disabled for production export.                            |
 +---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
 
-.. [3] The ``Allow JIT Code Execution``, ``Allow Unsigned Executable Memory`` and ``Allow DYLD Environment Variables`` entitlements are always enabled for the Godot Mono exports, and are not visible in the export options.
-.. [4] These features aren't supported by Godot out of the box, enable them only if you are using add-ons which require them.
-.. [5] To notarize an app, you must disable the ``Debugging`` entitlement.
+.. [4] The ``Allow JIT Code Execution``, ``Allow Unsigned Executable Memory`` and ``Allow DYLD Environment Variables`` entitlements are always enabled for the Godot Mono exports, and are not visible in the export options.
+.. [5] These features aren't supported by Godot out of the box, enable them only if you are using add-ons which require them.
+.. [6] To notarize an app, you must disable the ``Debugging`` entitlement.
 
 App Sandbox Entitlement
 ~~~~~~~~~~~~~~~~~~~~~~~
@@ -164,19 +195,21 @@ See `App Sandbox <https://developer.apple.com/documentation/security/app_sandbox
 +-----------------------------------+--------------------------------------------------------------------------------------------------------------------------------------+
 | Device Bluetooth                  | Enable to allow app to interact with Bluetooth devices. This entitlement is required to use wireless controllers.                    |
 +-----------------------------------+--------------------------------------------------------------------------------------------------------------------------------------+
-| Files Downloads [6]_              | Allows read or write access to the user's "Downloads" folder.                                                                        |
+| Files Downloads [7]_              | Allows read or write access to the user's "Downloads" folder.                                                                        |
 +-----------------------------------+--------------------------------------------------------------------------------------------------------------------------------------+
-| Files Pictures [6]_               | Allows read or write access to the user's "Pictures" folder.                                                                         |
+| Files Pictures [7]_               | Allows read or write access to the user's "Pictures" folder.                                                                         |
 +-----------------------------------+--------------------------------------------------------------------------------------------------------------------------------------+
-| Files Music [6]_                  | Allows read or write access to the user's "Music" folder.                                                                            |
+| Files Music [7]_                  | Allows read or write access to the user's "Music" folder.                                                                            |
 +-----------------------------------+--------------------------------------------------------------------------------------------------------------------------------------+
-| Files Movies [6]_                 | Allows read or write access to the user's "Movies" folder.                                                                           |
+| Files Movies [7]_                 | Allows read or write access to the user's "Movies" folder.                                                                           |
 +-----------------------------------+--------------------------------------------------------------------------------------------------------------------------------------+
-| Files User Selected [6]_          | Allows read or write access to arbitrary folder. To gain access, a folder must be selected from the native file dialog by the user.  |
+| Files User Selected [7]_          | Allows read or write access to arbitrary folder. To gain access, a folder must be selected from the native file dialog by the user.  |
 +-----------------------------------+--------------------------------------------------------------------------------------------------------------------------------------+
 | Helper Executable                 | List of helper executables to embedded to the app bundle. Sandboxed app are limited to execute only these executable.                |
 +-----------------------------------+--------------------------------------------------------------------------------------------------------------------------------------+
 
-.. [6] You can optionally provide usage messages for various folders in the `privacy/*_folder_usage_description` options.
+.. [7] You can optionally provide usage messages for various folders in the `privacy/*_folder_usage_description` options.
 
-You can override default entitlements by selecting custom entitlements file, in this case all other entitlement are ignored.
+.. note::
+
+    You can override default entitlements by selecting custom entitlements file, in this case all other entitlement are ignored.