Add macOS exporting and running non App Store apps pages. Add Windows…

… code signing info.
godotengine · Nov 3, 2021 · 17be494 · 17be494
1 parent a006f1c
commit 17be494
Show file tree

Hide file tree

Showing 17 changed files with 361 additions and 25 deletions.
diff --git a/development/cpp/index.rst b/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
diff --git a/development/cpp/macos_debug.rst b/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.
diff --git a/tutorials/export/exporting_for_linux.rst b/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.
diff --git a/tutorials/export/exporting_for_mac.rst b/tutorials/export/exporting_for_mac.rst
diff --git a/tutorials/export/exporting_for_pc.rst b/tutorials/export/exporting_for_pc.rst
diff --git a/tutorials/export/exporting_for_windows.rst b/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.
diff --git a/tutorials/export/img/linker_signed_1.png b/tutorials/export/img/linker_signed_1.png
diff --git a/tutorials/export/img/signed_0.png b/tutorials/export/img/signed_0.png
diff --git a/tutorials/export/img/signed_1.png b/tutorials/export/img/signed_1.png
diff --git a/tutorials/export/img/signed_2.png b/tutorials/export/img/signed_2.png
diff --git a/tutorials/export/img/signed_and_notarized_0.png b/tutorials/export/img/signed_and_notarized_0.png
diff --git a/tutorials/export/img/signed_and_notarized_1.png b/tutorials/export/img/signed_and_notarized_1.png
diff --git a/tutorials/export/img/sys_pref_0.png b/tutorials/export/img/sys_pref_0.png
diff --git a/tutorials/export/img/sys_pref_1.png b/tutorials/export/img/sys_pref_1.png
diff --git a/tutorials/export/img/unsigned_1.png b/tutorials/export/img/unsigned_1.png
diff --git a/tutorials/export/index.rst b/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

diff --git a/tutorials/export/running_on_mac.rst b/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).