Add macOS exporting and running non App Store apps pages. Add Windows code signing info.

development/cpp/index.rst

@@ -53,5 +53,6 @@ This section is about finding spots to optimize in the engine code when you need
    :maxdepth: 1
    :name: toc-devel-cpp-debug-profiling
 
+   macos_debug
    using_cpp_profilers
    vulkan/index

development/cpp/macos_debug.rst

@@ -0,0 +1,36 @@
+Debugging on macOS
+==================
+
+Debugging Godot editor
+----------------------
+
+Attaching a debugger to the signed macOS process requires the "com.apple.security.get-task-allow" entitlement, which is not enabled by default, since apps can't be notarized as long as it is enabled.
+If you want to debug an official build of the editor it should be re-signed with the proper entitlements.
+
+Create a ``editor.entitlements`` text file with the following contents:
+
+.. code-block:: xml
+
+    <?xml version="1.0" encoding="UTF-8"?>
+    <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+    <plist version="1.0">
+        <dict>
+            <key>com.apple.security.device.audio-input</key>
+            <true/>
+            <key>com.apple.security.device.camera</key>
+            <true/>
+            <key>com.apple.security.cs.disable-library-validation</key>
+            <true/>
+            <key>com.apple.security.get-task-allow</key>
+            <true/>
+        </dict>
+    </plist>
+
+Then use the following command to re-sign the editor::
+
+    codesign -s - --deep --force --options=runtime --entitlements ./editor.entitlements ./path/to/Godot.app
+
+Debugging exported project
+--------------------------
+
+To allow debugging, select the ``codesign\debugging`` (``com.apple.security.get-task-allow``) entitlement during the export. When it is selected, notarization is not supported and should be disabled.

tutorials/export/exporting_for_linux.rst

@@ -0,0 +1,13 @@
+.. _doc_exporting_for_linux:
+
+Exporting for Linux
+===================
+
+The simplest way to distribute a game for PC is to copy the executable
+(``godot``), compress the folder and send it to someone else. However, this is
+often not desired.
+
+Godot offers a more elegant approach for PC distribution when using the export
+system. When exporting for Linux, the exporter takes all the project files and
+creates a ``data.pck`` file. This file is bundled with a specially optimized
+binary that is smaller, faster and does not contain the editor and debugger.

tutorials/export/exporting_for_mac.rst

@@ -0,0 +1,165 @@
+.. _doc_exporting_for_mac:
+
+Exporting for macOS
+===================
+
+macOS apps are exported as an ``.app`` bundle, a folder with a specific structure which stores the executable, libraries and all the project files.
+This bundle is packed in a ZIP archive or DMG disk image (only supported when exporting for macOS).
+
+Requirements
+------------
+
+-  To enable code signing and notarization, you must export from a computer running macOS with Xcode command line tools installed.
+-  Download the Godot export templates. Use the Godot menu: ``Editor > Manage Export Templates``.
+
+.. warning::
+
+    Projects exported without code signing and notarization will be blocked by Gatekeeper if they are downloaded from unknown sources, see the :ref:`Running Godot apps on macOS <doc_running_on_mac>` page for more info.
+
+Code signing and notarization
+-----------------------------
+
+By default, macOS will run only applications that are signed and notarized, if you use any other signing configuration see :ref:`Running Godot apps on macOS <doc_running_on_mac>` for workarounds.
+
+To notarize an app you mast have a valid `Apple Developer ID Certificate <https://developer.apple.com/>`__.
+
+If you have an Apple Developer ID Certificate
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+- Enable ``Code Signing``, ``Notarization``, ``Hardened Runtime`` and ``Timestamp`` and disable the ``Debug`` entitlement.
+- Provide valid Apple ID credentials and certificate identity.
+
+If ``Notarization`` is enabled, Godot will automatically upload the exported project for notarization.
+
+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.
+
+If you encounter notarization issues, see `Resolving common notarization issues <https://developer.apple.com/documentation/security/notarizing_macos_software_before_distribution/resolving_common_notarization_issues>`__ for more info.
+
+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 do not have an Apple Developer ID Certificate
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Keep ``Code Signing`` enabled and leave the ``Identity`` option empty, in this case Godot will use a ad-hoc signature, which will make running an exported app easier for the end users.
+
+Signing Options
+~~~~~~~~~~~~~~~
+
++------------------------------+---------------------------------------------------------------------------------------------------+
+| Option                       | Description                                                                                       |
++==============================+===================================================================================================+
+| Enable                       | Enables code signing.                                                                             |
++------------------------------+---------------------------------------------------------------------------------------------------+
+| Identity                     | The "Full Name" or "Common Name" of the signing identity, store in the macOS key chain. [1]_      |
++------------------------------+---------------------------------------------------------------------------------------------------+
+| Timestamp                    | Requests a timestamp server to authenticate the time of signing. Required for notarization.       |
++------------------------------+---------------------------------------------------------------------------------------------------+
+| Hardened Runtime             | Enables "Hardened Runtime". Required for notarization.                                            |
++------------------------------+---------------------------------------------------------------------------------------------------+
+| Replace Existing Signature   | Replaces existing signatures of the GDNative libraries and embedded helper executables.           |
++------------------------------+---------------------------------------------------------------------------------------------------+
+
+.. note::
+
+    To notarize an app, you must enable the ``Hardened Runtime`` and ``Timestamp``.
+
+.. [1] Leave ``Identity`` option empty to use ad-hoc signature.
+
+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.
+
+Entitlements
+------------
+
+Hardened Runtime Entitlements
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Hardened Runtime entitlements manage security options and resource access policy.
+See `Hardened Runtime <https://developer.apple.com/documentation/security/hardened_runtime?language=objc>`__ for more info.
+
++---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| Entitlement                           | Description                                                                                                                                                                                      |
++=======================================+==================================================================================================================================================================================================+
+| Allow JIT Code Execution [2]_         | 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 [2]_ | 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 [2]_ | 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.                     |
++---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| Audio Input                           | Enable if you need to use the microphone or other audio input sources, if it's enabled you should also provide usage message in the `privacy/microphone_usage_description` option.               |
++---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| Camera                                | Enable if you need to use the camera, if it's enabled you should also provide usage message in the `privacy/camera_usage_description` option.                                                    |
++---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| 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                          | [3]_ 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                             | [3]_ 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                         | [3]_ 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                          | [3]_ Enable to allow app to send Apple events to other apps.                                                                                                                                     |
++---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| Debugging                             | [4]_ You can temporarily enable this entitlement to use native debugger (GDB, LLDB) with the exported app. This entitlement should be disabled for production export.                            |
++---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+
+.. [2] 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.
+.. [3] These features aren't supported by Godot out of the box, enable them only if you are using add-ons which require them.
+.. [4] To notarize an app, you must disable the ``Debugging`` entitlement.
+
+App Sandbox Entitlement
+~~~~~~~~~~~~~~~~~~~~~~~
+
+The App Sandbox restricts access to user data, networking and devices.
+Sandboxed apps can't access most of the file system, can't use custom file dialogs and execute binaries (using ``OS.execute`` and ``OS.create_process``) outside the ``.app`` bundle.
+See `App Sandbox <https://developer.apple.com/documentation/security/app_sandbox?language=objc>`__ for more info.
+
+.. note::
+
+    To distribute an app through the App Store, you must enable the App Sandbox.
+
++-----------------------------------+--------------------------------------------------------------------------------------------------------------------------------------+
+| Entitlement                       | Description                                                                                                                          |
++===================================+======================================================================================================================================+
+| Enabled                           | Enables App Sandbox.                                                                                                                 |
++-----------------------------------+--------------------------------------------------------------------------------------------------------------------------------------+
+| Network Server                    | Enable to allow app to listen for incoming network connections.                                                                      |
++-----------------------------------+--------------------------------------------------------------------------------------------------------------------------------------+
+| Network Client                    | Enable to allow app to establish outgoing network connections.                                                                       |
++-----------------------------------+--------------------------------------------------------------------------------------------------------------------------------------+
+| Device USB                        | Enable to allow app to interact with USB devices. This entitlement is required to use wired controllers.                             |
++-----------------------------------+--------------------------------------------------------------------------------------------------------------------------------------+
+| Device Bluetooth                  | Enable to allow app to interact with Bluetooth devices. This entitlement is required to use wireless controllers.                    |
++-----------------------------------+--------------------------------------------------------------------------------------------------------------------------------------+
+| Files Downloads [5]_              | Allows read or write access to the user's "Downloads" folder.                                                                        |
++-----------------------------------+--------------------------------------------------------------------------------------------------------------------------------------+
+| Files Pictures [5]_               | Allows read or write access to the user's "Pictures" folder.                                                                         |
++-----------------------------------+--------------------------------------------------------------------------------------------------------------------------------------+
+| Files Music [5]_                  | Allows read or write access to the user's "Music" folder.                                                                            |
++-----------------------------------+--------------------------------------------------------------------------------------------------------------------------------------+
+| Files Movies [5]_                 | Allows read or write access to the user's "Movies" folder.                                                                           |
++-----------------------------------+--------------------------------------------------------------------------------------------------------------------------------------+
+| Files User Selected [5]_          | 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.                |
++-----------------------------------+--------------------------------------------------------------------------------------------------------------------------------------+
+
+.. [5] 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.

tutorials/export/exporting_for_pc.rst

@@ -1,24 +0,0 @@
-.. _doc_exporting_for_pc:
-
-Exporting for PC
-================
-
-The simplest way to distribute a game for PC is to copy the executables
-(``godot.exe`` on Windows, ``godot`` on the rest), compress the folder
-and send it to someone else. However, this is often not desired.
-
-Godot offers a more elegant approach for PC distribution when using the
-export system. When exporting for PC (Linux, Windows, macOS), the exporter
-takes all the project files and creates a ``data.pck`` file. This file is
-bundled with a specially optimized binary that is smaller, faster and
-does not contain the editor and debugger.
-
-.. warning::
-
-    If you export for Windows with embedded PCK files, you will not be able to
-    sign the program as it will break.
-
-    On Windows, PCK embedding is also known to cause false positives in
-    antivirus programs. Therefore, it's recommended to avoid using it unless
-    you're distributing your project via Steam as it bypasses code signing and
-    antivirus checks.

tutorials/export/exporting_for_windows.rst

@@ -0,0 +1,29 @@
+.. _doc_exporting_for_windows:
+
+Exporting for Windows
+=====================
+
+The simplest way to distribute a game for PC is to copy the executable
+(``godot.exe``), compress the folder and send it to someone else. However, this
+is often not desired.
+
+Godot offers a more elegant approach for PC distribution when using the export
+system. When exporting for Windows, the exporter takes all the project files and
+creates a ``data.pck`` file. This file is bundled with a specially optimized
+binary that is smaller, faster and does not contain the editor and debugger.
+
+Requirements
+------------
+
+-  To enable code signing, you must have the ``Windows 10 SDK`` (on Windows) or `osslsigncode <https://github.com/mtrojnar/osslsigncode>`__ (on any other OS) installed.
+-  Download the Godot export templates. Use the Godot menu: ``Editor > Manage Export Templates``.
+
+.. warning::
+
+    If you export for Windows with embedded PCK files, you will not be able to
+    sign the program as it will break.
+
+    On Windows, PCK embedding is also known to cause false positives in
+    antivirus programs. Therefore, it's recommended to avoid using it unless
+    you're distributing your project via Steam as it bypasses code signing and
+    antivirus checks.

tutorials/export/index.rst

@@ -8,7 +8,10 @@ Export
    exporting_projects
    exporting_pcks
    feature_tags
-   exporting_for_pc
+   exporting_for_linux
+   exporting_for_mac
+   running_on_mac
+   exporting_for_windows
    changing_application_icon_for_windows
    exporting_for_uwp
    exporting_for_ios

tutorials/export/running_on_mac.rst

@@ -0,0 +1,113 @@
+.. _doc_running_on_mac:
+
+Running Godot apps on macOS
+===========================
+
+By default, macOS will run only applications that are signed and notarized.
+
+Depending on the way a macOS app is signed and distributed, the following scenarios are possible:
+
+App is signed, notarized and distributed via App Store
+------------------------------------------------------
+
+.. note::
+
+    App developers need to join the Apple Developer Program, and configure signing and notarization options during export, then upload the app to the App Store.
+
+The app should run out of the box, without extra user interaction required.
+
+App is signed, notarized and distributed outside App Store
+----------------------------------------------------------
+
+.. note::
+
+    App developers need to join the Apple Developer Program, and configure signing and notarization options during export, then distribute the app as ".DMG" or ".ZIP" archive.
+
+When you run the app for the first time, the following dialog is displayed:
+
+.. image:: img/signed_and_notarized_0.png
+
+Click ``Open`` to start the app.
+
+If you see the following warning dialog, your Mac is set up to allow apps only from the App Store.
+
+.. image:: img/signed_and_notarized_1.png
+
+To allow third-party apps, open ``System Preferences``, click ``Security & Privacy``, then click ``General``, unlock settings, and select ``App Store and identified developers``.
+
+.. image:: img/sys_pref_0.png
+
+App is signed (including ad-hoc signatures) but not notarized
+-------------------------------------------------------------
+
+.. note::
+
+    App developer used self-signed certificate or ad-hoc signing (default Godot behavior for exported project).
+
+When you run the app for the first time, the following dialog is displayed:
+
+.. image:: img/signed_0.png
+
+To run this app, you can temporarily override Gatekeeper:
+
+* Either open ``System Preferences``, click ``Security & Privacy``, then click ``General``, and click ``Open Anyway``.
+
+  .. image:: img/sys_pref_1.png
+
+* Or, right-click (Control-click) on the app icon in the Finder window and select ``Open`` from the menu.
+
+  .. image:: img/signed_1.png
+
+* Then click ``Open`` in the confirmation dialog.
+
+  .. image:: img/signed_2.png
+
+* Enter your password if you're prompted.
+
+App is not-signed, executable is linker-signed
+----------------------------------------------
+
+.. note::
+
+    App is built using official export templates, but it is not signed.
+
+When you run the app for the first time, the following dialog is displayed:
+
+.. image:: img/linker_signed_1.png
+
+To run this app, you should remove the quarantine extended file attribute manually:
+
+* Open ``Terminal.app`` (press ``Cmd + Space``, and enter ``Terminal``).
+
+* Navigate to the folder containing the target application.
+
+  Use the ``cd path_to_the_app_folder`` command, e.g. ``cd ~/Downloads/`` if it's in the ``Downloads`` folder.
+
+* Run the command ``xattr -dr com.apple.quarantine "Unsigned Game.app"`` (including quotation marks and ``.app`` extension).
+
+Neither app not executable is signed (relevant for Apple Silicon macs only)
+---------------------------------------------------------------------------
+
+.. note::
+
+    App is built using custom export templates, compiled using OSXCross, and it is not signed at all.
+
+When you run the app for the first time, the following dialog is displayed:
+
+.. image:: img/unsigned_1.png
+
+To run this app, you can ad-hoc sign it yourself:
+
+* Install ``Xcode`` for the App Store, start it and confirm command line tools installation.
+
+* Open ``Terminal.app`` (press ``Cmd + Space``, and enter ``Terminal``).
+
+* Navigate to the folder containing the target application.
+
+  Use the ``cd path_to_the_app_folder`` command, e.g. ``cd ~/Downloads/`` if it's in the ``Downloads`` folder.
+
+* Run the following commands:
+
+  ``xattr -dr com.apple.quarantine "Unsigned Game.app"`` (including quotation marks and ".app" extension).
+
+  ``codesign -s - --force --deep "Unsigned Game.app"`` (including quotation marks and ".app" extension).