From ac12eb06f3d4c610f3261badfbbad874b71addb5 Mon Sep 17 00:00:00 2001 From: Max Hilbrunner Date: Tue, 25 Jul 2023 02:05:30 +0200 Subject: [PATCH] Merge pull request #7720 from Calinou/uwp-non-functional --- .../compiling/compiling_for_uwp.rst | 152 +----------------- tutorials/export/exporting_for_uwp.rst | 121 +------------- 2 files changed, 10 insertions(+), 263 deletions(-) diff --git a/contributing/development/compiling/compiling_for_uwp.rst b/contributing/development/compiling/compiling_for_uwp.rst index 8d6a8618b..f07e86a9c 100644 --- a/contributing/development/compiling/compiling_for_uwp.rst +++ b/contributing/development/compiling/compiling_for_uwp.rst @@ -3,152 +3,10 @@ Compiling for Universal Windows Platform ======================================== -.. highlight:: shell +.. important:: -.. seealso:: + Compiling UWP export templates is not implemented in Godot 4. + Godot 3 has limited UWP support, but there are many + `known issues `__. - This page describes how to compile UWP export template binaries from source. - If you're looking to export your project to UWP instead, read :ref:`doc_exporting_for_uwp`. - -Requirements ------------- - -- `Python 3.6+ `_. - **Make sure to enable the option to add Python to the ``PATH`` in the installer.** -- `SCons 3.0+ `_ build system. Using the - latest release is recommended, especially for proper support of recent Visual - Studio releases. -- Windows 10 SDK (can be selected in Visual Studio installation). -- `ANGLE source `__. Use the - ``ms_master`` (default) branch. Keep it in a path without spaces to - avoid problems. - -.. note:: The ANGLE repo by Microsoft has been discontinued and the - ``ms_master`` branch has been cleared out. - - As a temporary workaround however, it is still possible to - download an older state of the source code via commit - `c61d048 `__. - - This page will eventually be updated in the future to reflect - the new build instructions. - -.. seealso:: To get the Godot source code for compiling, see - :ref:`doc_getting_source`. - - For a general overview of SCons usage for Godot, see - :ref:`doc_introduction_to_the_buildsystem`. - -Compiling ---------- - -You need to open a proper Visual Studio prompt for the target architecture -you want to build. Check :ref:`doc_compiling_for_windows` to see how these -prompts work. - -There are three target architectures for UWP: x86 (32-bits), x64 (64-bits) -and ARM (32-bits). For the latter, you can run ``vcvarsall.bat`` with -``x86_arm`` or ``amd64_arm`` as argument to set the environment. - -Set the ``ANGLE_SRC_PATH`` to the directory where you downloaded the ANGLE -source code. The build process will also build ANGLE to produce the -required DLLs for the selected architecture. - -Once you're set, run the SCons command similarly to the other platforms:: - - C:\godot>scons platform=uwp - -Creating UWP export templates ------------------------------ - -To export using the editor you need to properly build package the templates. -You need all three architectures with ``debug`` and ``release`` templates to -be able to export. - -Open the command prompt for one architecture and run SCons twice (once for -each target):: - - C:\godot>scons platform=uwp target=template_debug - C:\godot>scons platform=uwp target=template_release - -Repeat for the other architectures. - -In the end your ``bin`` folder will have the ``.exe`` binaries with a name -like ``godot.uwp.opt.debug.32.x86.exe`` (with variations for each -target/arch). - -Copy one of these to ``misc/dist/uwp_template`` inside the Godot source -folder and rename the binary to ``godot.uwp.exe``. From the ANGLE source, -under ``winrt/10/src/Release_%arch%`` (where ``%arch%`` can be ``Win32``, -``x64`` or ``ARM``), get the ``libEGL.dll`` and the ``libGLESv2.dll``, -putting them along with the executable. - -Add the files in the ``uwp_template`` folder to a ZIP. Rename the resulting -Zip according to the target/architecture of the template:: - - uwp_x86_debug.zip - uwp_x86_release.zip - uwp_x64_debug.zip - uwp_x64_release.zip - uwp_arm_debug.zip - uwp_arm_release.zip - -Move those templates to the ``[versionstring]\templates`` folder in Godot -settings path, where `versionstring` is the version of Godot you have compiled -the export templates for - e.g. `3.0.alpha` for the alpha version of Godot 3. -If you don't want to replace the templates, you can set the "Custom Package" -property in the export window. - -Running UWP apps with Visual Studio ------------------------------------ - -If you want to debug the UWP port or simply run your apps without packaging -and signing, you can deploy and launch them using Visual Studio. It might be -the easiest way if you are testing on a device such as a Windows Phone or an -Xbox One. - -Within the ANGLE source folder, open ``templates`` and double-click the -``install.bat`` script file. This will install the Visual Studio project -templates for ANGLE apps. - -If you have not built Godot yet, open the ``winrt/10/src/angle.sln`` solution -from the ANGLE source and build it to Release/Win32 target. You may also need -to build it for ARM if you plan to run on a device. You can also use MSBuild if -you're comfortable with the command line. - -Create a new Windows App project using the "App for OpenGL ES -(Windows Universal)" project template, which can be found under the -``Visual C++/Windows/Universal`` category. - -This is a base project with the ANGLE dependencies already set up. However, by -default it picks the debug version of the DLLs which usually have poor -performance. So in the "Binaries" filter, click in each of the DLLs there -and in the "Properties" window and change the relative path from -``Debug_Win32`` to ``Release_Win32`` (or ``Release_ARM`` for devices). - -In the same "Binaries" filter, select "Add > Existing Item" and point to the -Godot executable for UWP you have. In the "Properties" window, set "Content" -to ``True`` so it's included in the project. - -Right-click the ``Package.appxmanifest`` file and select "Open With... > XML -(Text) Editor". In the ``Package/Applications/Application`` element, replace -the ``Executable`` attribute from ``$targetnametoken$.exe`` to -``godot.uwp.exe`` (or whatever your Godot executable is called). Also change -the ``EntryPoint`` attribute to ``GodotUWP.App``. This will ensure that -the Godot executable is correctly called when the app starts. - -Create a folder (*not* a filter) called ``game`` in your Visual Studio project -folder and there you can put either a ``data.pck`` file or your Godot project -files. After that, make sure to include it all with the "Add > Existing Item" -command and set their "Content" property to ``True`` so they're copied to the -app. - -To ease the workflow, you can open the "Solution Properties" and in the -"Configuration" section untick the "Build" option for the app. You still have -to build it at least once to generate some needed files, you can do so by -right-clicking the project (*not* the solution) in the "Solution Explorer" and -selecting "Build". - -Now you can just run the project and your app should open. You can also use -the "Start Without Debugging" option from the "Debug" menu (or press :kbd:`Ctrl + F5`) to make it -launch faster. + We recommend you use the :ref:`Win32 export ` instead. diff --git a/tutorials/export/exporting_for_uwp.rst b/tutorials/export/exporting_for_uwp.rst index 39cbc8540..c7c766504 100644 --- a/tutorials/export/exporting_for_uwp.rst +++ b/tutorials/export/exporting_for_uwp.rst @@ -1,123 +1,12 @@ -:article_outdated: True - .. _doc_exporting_for_uwp: Exporting for Universal Windows Platform ======================================== -.. seealso:: +.. important:: - This page describes how to export a Godot project to UWP. - If you're looking to compile export template binaries from source instead, - read :ref:`doc_compiling_for_uwp`. + Exporting projects to UWP is not implemented in Godot 4. + Godot 3 has limited UWP support, but there are many + `known issues `__. -There's no extra requirement to export an ``.appx`` package that can be -installed as a Windows App or submitted to the Windows Store. Exporting UWP -packages also works from any platform, not only from Windows. - -However, if you want to install and run the app, you need to sign it with a -trusted signature. Godot supports automatic signing of packages with -external tools. - -Also, make sure the Publisher Name you set when exporting the package matches -the name used on the certificate. - -Limitations on Xbox One ------------------------ - -As described in the `UWP documentation `__: - -- Submitted as an "App" - - available memory is 1GB - - share of 2-4 CPU cores - - shared access of GPU power (45%) - -- Submitted as a "Game" (through `Xbox Live Creators Program `__) - - available memory is 5GB - - 4 exclusive CPU cores and 2 shared CPU cores - - exclusive access to GPU power (100%) - -- Exceeding these memory limitations will cause allocation failures and the application will crash. - -Creating a signing certificate ------------------------------- - -This requires the ``MakeCert.exe`` and ``Pvk2Pfx.exe`` tools, which come with -the Windows SDK. If you use Visual Studio, you can open one of its Developer -Prompts, since it comes with these tools and they can be located in the path. - -You can get more detailed instructions from `Microsoft's documentation -`__. - -First, run ``MakeCert`` to create a private key:: - - MakeCert /n publisherName /r /h 0 /eku "1.3.6.1.5.5.7.3.3,1.3.6.1.4.1.311.10.3.13" /e expirationDate /sv MyKey.pvk MyKey.cer - -Where ``publisherName`` matches the Publisher Name of your package and -``expirationDate`` is in the ``mm/dd/yyyy`` format. - -Next, create a Personal Information Exchange (.pfx) file using ``Pvk2Pfx.exe``:: - - Pvk2Pfx /pvk MyKey.pvk /pi pvkPassword /spc MyKey.cer /pfx MyKey.pfx [/po pfxPassword] - -If you don't specify a password with ``/po`` argument, the PFX will have the -same password as the private key. - -You will also need to trust this certificate in order to be able to install your -app. Open the Command Prompt as Administrator and run the following command:: - - Certutil -addStore TrustedPeople MyKey.cer - -Setting up automatic signing ----------------------------- - -To setup automatic signing on export you need to go to Editor Settings > Export > Uwp. -From there you need to click on the folder for ``Signtool``, and navigate to -the ``SignTool.exe`` file on your computer. - -.. image:: img/UWP_sign_tool.png - -After setting that up close the editor settings, go to Project > Export, -and select the UWP preset. Under the ``Signing`` options click on the folder -next to ``Certificate`` and go to the certificate file. Then enter the -pfxPassword in the password field. - -.. image:: img/UWP_export_signing.png - -Your project will now be automatically signed on export. - -If you want to sign an exported app manually run ``SignTool.exe`` and use the -following command. - - SignTool sign /fd SHA256 /a /f MyKey.pfx /p pfxPassword package.appx - -Installing the package ----------------------- - -As of the Windows 10 Anniversary Update, you are able to install packages simply by -double clicking the ``.appx`` file from Windows Explorer. - -It's also possible to install by using the ``Add-AppxPackage`` PowerShell cmdlet. - -.. note:: If you want to update your already installed app, you must - update the version number on the new package or first uninstall - the previous package. - -Environment variables ---------------------- - -You can use the following environment variables to set export options outside of -the editor. During the export process, these override the values that you set in -the export menu. - -.. list-table:: UWP export environment variables - :header-rows: 1 - - * - Export option - - Environment variable - * - Encryption / Encryption Key - - GODOT_SCRIPT_ENCRYPTION_KEY - * - Options / Signing / Certificate - - GODOT_UWP_SIGNING_CERTIFICATE - * - Options / Signing / Password - - GODOT_UWP_SIGNING_PASSWORD + We recommend you use the :ref:`Win32 export ` instead.