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

… code signing info.
godotengine · Jul 26, 2021 · d3f7bac · d3f7bac
1 parent 8471a34
commit d3f7bac
Show file tree

Hide file tree

Showing 15 changed files with 299 additions and 12 deletions.
diff --git a/development/compiling/compiling_for_osx.rst b/development/compiling/compiling_for_osx.rst
@@ -184,3 +184,32 @@ Now you can compile with SCons like you normally would::
 If you have an OSXCross SDK version different from the one expected by the SCons buildsystem, you can specify a custom one with the ``osxcross_sdk`` argument::
 
     scons platform=osx osxcross_sdk=darwin15
+
+Debugging Godot editor on the macOS
+-----------------------------------
+
+Attaching debugger to the signed macOS process require "com.apple.security.get-task-allow" entitlements, which is not enabled by default, since it's impossible to notarize app if it is.
+If you want to debug custom of official build of the editor it should be re-signed with the proper entitlements.
+
+Create "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>
+
+And use the following command to re-sign the editor::
+
+    codesign -s - --deep --force --options=runtime --entitlements ./editor.entitlements ./path/to/Godot.app
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 executables
+(``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 → tutorials/export/exporting_for_windows.rst b/tutorials/export/exporting_for_pc.rst → tutorials/export/exporting_for_windows.rst
@@ -1,17 +1,21 @@
-.. _doc_exporting_for_pc:
+.. _doc_exporting_for_windows:
 
-Exporting for PC
-================
+Exporting for Windows
+=====================
 
 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.
+(``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.
+
+Code signing
+------------
+
+TODO: osscs, signtool install, key conversion
 
 .. warning::
 

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,101 @@
+.. _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
+------------------------------------------------------
+
+The app should run out of the box, without extra user interaction required.
+
+App is signed, notarized and distributed outside App Store
+----------------------------------------------------------
+
+App developer have joined Apple Developer Program, and configurated siging and notarization options during export.
+
+When you try to run the app, 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
+-------------------------------------------------------------
+
+App developer used self-signed certificate or ad-hoc signing (default Godot behavior when exporting app form the macOS).
+
+When you try to run the app, 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
+----------------------------------------------
+
+App is built using official export templates, but is not signed (default Godot behavior when exporting from Windows and Linux).
+
+When you try to run the app, the following dialog is displayed:
+
+.. image:: img/linker_signed_1.png
+
+To run this app, you can remove "quarantine" file attribute manually:
+
+* Open "Terminal.app" (press ``Cmd + Space```, and enter "Terminal").
+
+* Navigate to the folder containing the target application.
+
+  Use ``cd path_to_the_app_folder`` command, e.g. ``cd ~/Downloads/`` if it's in the "Downloads" folder.
+
+* Run following 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)
+---------------------------------------------------------------------------
+
+App is built using custom export templates, and it is not signed at all.
+
+When you try to run the app, 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 ``cd path_to_the_app_folder`` command, e.g. ``cd ~/Downloads/`` if it's in the "Downloads" folder.
+
+* Run 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).