Merge pull request #7720 from Calinou/uwp-non-functional

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 <https://github.com/godotengine/godot/issues?q=is%3Aopen+is%3Aissue+label%3Aplatform%3Auwp>`__.
 
-    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+ <https://www.python.org/downloads/windows/>`_.
-  **Make sure to enable the option to add Python to the ``PATH`` in the installer.**
-- `SCons 3.0+ <https://scons.org/pages/download.html>`_ 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 <https://github.com/Microsoft/angle>`__. 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 <https://github.com/microsoft/angle/tree/c61d0488abd9663e0d4d2450db7345baa2c0dfb6>`__.
-
-          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 <doc_exporting_for_windows>` instead.

tutorials/export/exporting_for_uwp.rst

@@ -1,123 +1,12 @@
-:article_outdated: True
-
 .. _doc_exporting_for_uwp:
 
 Exporting for Universal Windows Platform
 ========================================
 
-.. seealso::
-
-    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`.
-
-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 <https://docs.microsoft.com/en-us/windows/uwp/xbox-apps/system-resource-allocation>`__:
-
-- 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 <https://www.xbox.com/en-US/developers/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
-<https://msdn.microsoft.com/en-us/library/windows/desktop/jj835832(v=vs.85).aspx>`__.
-
-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.
+.. important::
 
-.. list-table:: UWP export environment variables
-   :header-rows: 1
+    Exporting projects to UWP is not implemented in Godot 4.
+    Godot 3 has limited UWP support, but there are many
+    `known issues <https://github.com/godotengine/godot/issues?q=is%3Aopen+is%3Aissue+label%3Aplatform%3Auwp>`__.
 
-   * - 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 <doc_exporting_for_windows>` instead.