Merge pull request #240 from vnen/winrt-compile

Update instructions to build for UWP

reference/_compiling.rst

@@ -12,7 +12,7 @@ Compiling
    compiling_for_android
    compiling_for_ios
    cross-compiling_for_ios_on_linux
-   compiling_for_universal_windows_apps
+   compiling_for_uwp
    compiling_for_web
    batch_building_templates
    configuring_an_ide

reference/compiling_for_universal_windows_apps.rst

@@ -1,139 +0,0 @@
-.. _doc_compiling_for_universal_windows_apps:
-
-Compiling for Universal Windows Apps
-====================================
-
-.. highlight:: shell
-
-This page documents the current state of the "winrt" platform, used to
-support "Windows Store Apps" for Windows 8.1, and Windows Phone 8.1 apps
-using Microsoft's new "Universal" APIs.
-
-Requirements
-------------
-
--  Windows 8
--  SCons (see :ref:`doc_compiling_for_windows` for more details)
--  Visual Studio 2013 for Windows (but *not* "for Windows Desktop").
-   Tested on "Microsoft Visual Studio Express 2013 for Windows Version
-   12.0.31101.00 Update 4".
-
-Compiling
----------
-
-The platform can compile binaries for both Windows 8.1 and Windows Phone
-8.1. The architecture is decided by the environment variable "PLATFORM".
-
-Windows 8.1
-~~~~~~~~~~~
-
--  Open a "VS 2013 x64 Cross Tools Command Prompt"
--  The value of environment variable "PLATFORM" should be "x64"
--  Run scons with ``platform=winrt`` from the root of the source tree::
-
-    C:\godot_source> scons platform=winrt
-
--  You should get an executable file inside bin/ named according to your
-   build options, for the architecture "x64", for example
-   "godot.winrt.tools.x64.exe".
-
-Windows Phone 8.1
-~~~~~~~~~~~~~~~~~
-
--  Open a "Visual Studio 2012 ARM Phone Tools Command Prompt"
--  The value of environment variable "PLATFORM" should be "arm"
--  Run scons with ``platform=winrt`` from the root of the source tree::
-
-    C:\godot_source> scons platform=winrt
-
--  You should get an executable file inside bin/ named according to your
-   build options, for the architecture "arm", for example
-   "godot.winrt.tools.arm.exe".
-
-Running
--------
-
-On Visual studio, create a new project using any of the "Universal App"
-templates found under Visual C++ -> Store Apps -> Universal Apps. "Blank
-App" should be fine.
-
-On the "Solution Explorer" box, you should have 3 sections, "App.Windows
-(Windows 8.1)", "App.WindowsPhone (Windows Phone 8.1)" and "App.Shared".
-You need to add files to each section:
-
-App.Shared
-~~~~~~~~~~
-
-Add a folder named "game" containing your game content (can be individual
-files or your data.pck). Remember to set the "Content" property of each
-file to "True", otherwise your files won't get included in the package.
-
-App.Windows
-~~~~~~~~~~~
-
--  Add your windows executable, and all the .dll files found on
-   platform/winrt/x64/bin on the godot source. Remember to also set the
-   "Content" property.
--  Find the file "Package.appxmanifest". Right click on it and select
-   "Open with..." then "XML (Text) Editor" from the list.
--  Find the "Application" section, and add (or modify) the "Executable"
-   property with the name of your .exe. Example:
-
-::
-
-    <Application Id="App" Executable="godot.winrt.tools.x64.exe" EntryPoint="App_Windows.App">
-
-App.WindowsPhone
-~~~~~~~~~~~~~~~~
-
-Repeat all the steps from App.Windows, using your arm executable and
-the dlls found in platform/winrt/arm/bin. Remember to set the
-"Content" property for all the files.
-
-Use the green "Play" button on the top to run. The drop down menu next
-to it should let you choose the project (App.Windows or
-App.WindowsPhone) and the device ("Local Machine", "Device" for an
-attached phone, etc).
-
-Angle
------
-
-ANGLE precompiled binaries are provided on platform/winrt/x64 and
-platform/winrt/arm. They are built from MSOpenTech's "future-dev"
-branch, found here: https://github.com/MSOpenTech/angle. The visual
-studio 'solutions' used are found on ``projects/winrt/windows/angle.sln``
-and ``projects/winrt/windowsphone/angle.sln``.
-
-What's missing
---------------
-
--  Audio
--  Semaphores
--  Keyboard input
--  Proper handling of screen rotation
--  Proper handling of other events such as focus lost, back button, etc.
--  Packaging and deploying to devices from the editor.
--  Adding Angle to our tree and compiling it from there. The same source
-   could also be used to build for Windows (and use Angle instead of
-   native GL, which will be more compatible with graphics hardware)
-
-Packages
---------
-
-This is what we know:
-
--  App packages are documented here:
-   http://msdn.microsoft.com/en-us/library/windows/apps/xaml/hh464929.aspx
--  There are 2 command line tools that might be useful, `App Packager
-   <http://msdn.microsoft.com/en-us/library/windows/apps/xaml/hh446767.aspx>`__
-   and `SignTool
-   <http://msdn.microsoft.com/en-us/library/windows/apps/xaml/ff551778.aspx>`__.
--  There are a bunch of tools on "powershell" that deal with packages
-   that might be relevant:
-   http://technet.microsoft.com/library/dn448373.aspx
--  When running a Windows 8.1 app on "Local Machine" from Visual studio,
-   the app seems to run from an uncompressed directory on the filesystem
-   in an arbitrary location (ie. outside of the proper directory where
-   Apps are installed), but there is some special registry entry made
-   for it, so we know it's possible to skip the packaging step to run
-   locally (in the case of very big games this can be useful).

reference/compiling_for_uwp.rst

@@ -0,0 +1,76 @@
+.. _doc_compiling_for_uwp:
+
+Compiling for Universal Windows Platform
+========================================
+
+.. highlight:: shell
+
+Requirements
+------------
+
+-  SCons (see :ref:`doc_compiling_for_windows` for more details).
+-  Visual Studio 2015 Update 2. It may work with earlier versions. See
+   :ref:`doc_compiling_for_windows` about the caveats of installing it
+   and the various prompts.
+-  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.
+
+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). You can run ``vcvarsall.bat`` with ``arm`` as argument to
+set the environment for this target architecture.
+
+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=winrt
+
+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=winrt target=release_debug
+    C:\godot>scons platform=winrt target=release
+
+Repeat for the other architectures.
+
+In the end your ``bin`` folder will have the ``.exe`` binaries with a name
+like ``godot.winrt.opt.debug.32.x86.exe`` (with variations for each
+target/arch).
+
+Copy one of these to ``tools/dist/uwp_template`` inside the Godot source
+folder and rename the binary to ``godot.winrt.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::
+
+    winrt_x86_debug.zip
+    winrt_x86_release.zip
+    winrt_x64_debug.zip
+    winrt_x64_release.zip
+    winrt_arm_debug.zip
+    winrt_arm_release.zip
+
+Move those templates to the ``templates`` folder in Godot settings path. If
+you don't want to replacet the templates, you can set the "Custom Package"
+property in the export window.

tutorials/asset_pipeline/_export.rst

@@ -11,6 +11,7 @@ Export
    exporting_for_pc
    exporting_for_android
    exporting_for_ios
+   exporting_for_uwp
 .. exporting_for_bb10
 .. exporting_for_nacl
 .. exporting_for_html5

tutorials/asset_pipeline/exporting_for_uwp.rst

@@ -0,0 +1,57 @@
+.. _doc_exporting_for_uwp:
+
+Exporting for Universal Windows Platform
+========================================
+
+There's no extra requirement to export an ``.appx`` package that can be
+installed as a Windows App or submited to the Windows Store. Exporting
+packages also works from any platform, not only on Windows.
+
+However, if you want to install an run the app, you need to sign it with a
+trusted signature. Currently, Godot supports no signing of packages and you
+need to use externals to tools to do so.
+
+Also, make sure the Publisher name you set when export the package matches
+the name on the certificate.
+
+Creating a signing certificate
+------------------------------
+
+This requires the tools ``MakeCert.exe`` and ``Pvk2Pfx.exe`` which comes
+with the Windows SDK. If you use Visual Studio, open one of its Developer
+Prompts since they come with those tools available and in the path.
+
+You can get more detailed instructions from `Microsof 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.
+
+Signing the package
+-------------------
+
+Using the ``SignTool.exe`` this requires a single command:;
+
+    SignTool sign /fd SHA256 /a /f MyKey.pfx /p pfxPassword package.appx
+
+Installing the package
+----------------------
+
+After Windows 10 Anniversary Update you can install packages by just double
+clicking the ``.appx`` file from the Windows Explorer.
+
+It's also possible to install using the ``Add-AppxPackage`` PowerShell cmdlet.
+
+Note that if you don't update the version number, you'll have to uninstall the
+previous installed package before reinstalling it.