Convert README to Markdown

README.md

@@ -0,0 +1,125 @@
+# Briefcase Windows Visual Studio Template
+
+A [Cookiecutter](https://github.com/cookiecutter/cookiecutter/) template for
+building Python apps from a Visual Studio project, that can then be packaged
+with an MSI installer.
+
+## Using this template
+
+The easiest way to use this project is to not use it at all - at least, not
+directly. [Briefcase](https://github.com/beeware/briefcase/) is a tool that
+uses this template, rolling it out using data extracted from a `pyproject.toml`
+configuration file.
+
+However, if you *do* want use this template directly...
+
+1. Install [cookiecutter](https://github.com/cookiecutter/cookiecutter). This
+   is a tool used to bootstrap complex project templates:
+
+   ```console
+   $ pip install cookiecutter
+   ```
+
+2. Run `cookiecutter` on the template:
+
+   ```console
+   $ cookiecutter https://github.com/beeware/briefcase-windows-visualstudio-template
+   ```
+
+   This will ask you for a number of details of your application, including the
+   `name` of your application (which should be a valid PyPI identifier), and
+   the `Formal Name` of your application (the full name you use to describe
+   your app). The remainder of these instructions will assume a `name` of
+   `my-project`, and a formal name of `My Project`.
+
+3. Build the project. You can do this by opening the solution file in Visual
+   Studio and building the Release configuration, or by using MSBuild:
+
+   ```console
+   $ MSBuild.exe "My Project.sln" -target:restore -property:RestorePackagesConfig=true -target:"My Project" -property:Configuration=Release
+   ```
+
+   In order to build the project, you will need to configure Visual Studio to
+   include the following modules:
+
+   * **.NET Desktop development** - default options
+   * **Deskop Development with C++** - default options, plus the "C++/CLI
+     Support for v143 build tools".
+
+4. [Obtain a Python Windows Embeddable package](https://www.python.org/downloads/windows/),
+   and extract it into the `My Project/x64/Release` directory generated by the
+   template (`My Project/ARM64/Release` if you're on ARM64). This will give you
+   a `python3.dll` (amongst other artefacts) in the
+   `My Project/x64/Release` folder.
+
+5. Add your code to the template, into the `My Project/x64/Release/app`
+   directory. At the very minimum, you need to have an
+   `app/<app name>/__main__.py` file that defines an entry point that will start
+   your application.
+
+   If your code has any dependencies, they should be installed under the
+   `My Project/x64/Release/app_packages` directory.
+
+If you've done this correctly, a project with a formal name of `My Project`,
+with an app name of `my-project` should have a directory structure that looks
+something like:
+
+```text
+My Project/
+    x64/
+        Release/
+            app/
+                my_project/
+                    __init__.py
+                    __main__.py
+                    app.py
+            app_packages/
+                ...
+            python3.dll
+            ...
+            My Project.exe
+            My Project.exe.metagen
+            My Project.pdb
+    My Project/
+        My Project.vcxproj
+        My Project.vcxproj.filters
+        ...
+    My Project.sln
+    briefcase.toml
+    my-project.wxs
+    unicode.wxl
+```
+
+The executable in `x64/Release` will start your application.
+
+This project can now be compiled with [WiX](https://wixtoolset.org) to produce
+an MSI file. Open a command prompt, and change into the `My Project` directory.
+Then:
+
+```console
+C:\...>wix build -ext WixToolset.UI.wixext -arch x64 my-project.wxs -loc unicode.wxl -o "My Project.msi"
+```
+
+Use `-arch arm64` if you're on ARM64.
+
+The MSI file can then be used to install your application. When installed, your
+application will have an entry in your Start menu.
+
+## Next steps
+
+Of course, running Python code isn't very interesting by itself - you won't be
+able to do any console input or output, because a Windows app doesn't display a
+console.
+
+To do something interesting, you'll need to work with the native Windows system
+libraries to draw widgets and respond to screen taps. The
+[Python for .NET](http://pythonnet.github.io/) bridging library can be used to
+interface with the Windows system libraries. Alternatively, you could use a
+cross-platform widget toolkit that supports Windows (such as
+[Toga](https://beeware.org/project/projects/libraries/toga)) to provide a GUI
+for your application.
+
+If you have any external library dependencies (like Toga, or anything other
+third-party library), you should install the library code into the
+`app_packages` directory. This directory is the same as a `site_packages`
+directory on a desktop Python install.