Merge pull request #11762 from Calinou/creating-applications-single-exe-portable

Document creating single-executable/portable apps in Creating applications

Author: mhilbrunner

tutorials/export/exporting_for_windows.rst

@@ -32,15 +32,15 @@ The default is x86_64, this is the most common architecture of PC processors
 today. All modern Intel and AMD processors as of writing this are x86_64.
 
 x86_32 will give you a 32bit executable that can run on 32bit-only versions of
-Windows as well as modern versions which are 64bit. It is NOT recommended to use
+Windows as well as modern versions which are 64bit. It is **not** recommended to use
 this option unless you are trying to get your project to run on an old 32bit version
 of Windows. And it should be noted that no 32bit versions of Windows receive
 Microsoft support anymore.
 
 arm64 processors are modern but less common than x86_64, and run Windows on ARM.
 Snapdragon X Elite is an example of a modern Windows ARM processor. Using this
 export option will allow your project to run natively on arm processors without
-Microsoft's Prism emulator. Executables made using this option will NOT run on
+Microsoft's Prism emulator. Executables made using this option will **not** run on
 regular Windows with an x86_64 processor. If you're uploading your project to a
 platform that allows multiple executables, such as itch.io, and are confident a
 Snapdragon X Elite processor is powerful enough to run it, we would recommend
@@ -55,6 +55,14 @@ settings, and convert it to an ICO file for the exported project. If you want to
 manually create an ICO file for greater control over how the icon looks at different
 resolutions then see the :ref:`doc_changing_application_icon_for_windows` page.
 
+PCK embedding
+-------------
+
+PCK embedding is only supported on executables up to ~3.89 GB in size. This
+metric includes both the executable and embedded PCK size, so in practice,
+the PCK file may only weigh up to ~3.75 GB. This can also vary depending on
+build options when using a custom export template.
+
 .. _doc_exporting_for_windows_code_signing:
 
 Code signing
@@ -65,16 +73,6 @@ Godot is capable of automatic code signing on export. To do this you must have t
 (on any other OS) installed. You will also need a package signing certificate,
 information on creating one can be found `here <https://learn.microsoft.com/en-us/windows/msix/package/create-certificate-package-signing>`__.
 
-.. 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.
-
 Setup
 ~~~~~
 

tutorials/ui/creating_applications.rst

@@ -796,6 +796,56 @@ The size reduction is often significant (relative to the project's size),
 since applications contain fewer large assets compared to games.
 See :ref:`doc_optimizing_for_size` for more information on how to do this.
 
+Creating a single-executable distribution
+-----------------------------------------
+
+By default, Godot creates a PCK file containing the project data next to the
+executable. This means that if the executable is moved without moving the PCK
+file at the same time, the application will not run. This is not ideal for
+applications, which are increasingly being distributed as a single executable
+file.
+
+To make the application entirely self-contained to a single executable, you can
+enable **Embed PCK** in the export preset options. This will embed the PCK data
+within the executable, so that the application can be moved around without
+breaking. This also makes it possible to run the application directly from a ZIP
+archive without having to extract it first.
+
+.. note::
+
+    PCK embedding has a size limitation depending on the platform. Very large
+    applications (several GBs) may not be able to use this feature on all platforms.
+    Check the export documentation for the target platform for more details.
+
+Creating portable applications
+------------------------------
+
+An application is called *portable* when it can be run without installation, and
+when its configuration is entirely self-contained to the folder it was extracted
+to. This allows placing the application files on an USB drive or similar, and
+running it on different machines without having to go through an installation
+process.
+
+The Godot editor's own :ref:`self-contained mode <doc_data_paths_self_contained_mode>`
+currently can't be used within projects. However, you can still choose to save
+your own configuration files to the folder containing the executable as follows:
+
+::
+
+    var config_path = OS.get_executable_path().get_base_dir().path_join("config.ini")
+    # Then use `config_path` to save/load configuration files using ConfigFile or similar.
+
+You may want to make portable mode optional as it's not always desired.
+Typically, this is performed by detecting the presence of a specific file in the
+executable's folder (e.g. a file named ``portable.txt``), and only using the
+executable's folder for configuration if that file is present.
+
+.. warning::
+
+    Remember that this will only work if the application is extracted to a
+    writable location. This will result in permission errors if the executable
+    is run from a read-only location, such as ``C:\Program Files`` on Windows.
+
 Creating installers
 -------------------