Convert README.rst to README.md (1) (#86)

Co-authored-by: Arnold Hanser <arnold.hanser@igtplc.onmicrosoft.com>

Author: igt-ahanser

README.md

@@ -0,0 +1,93 @@
+# Briefcase macOS Xcode Template
+
+A [Cookiecutter](https://github.com/cookiecutter/cookiecutter/) template for
+building Python apps that will run under macOS.
+
+## 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:
+
+    ```text
+    pip install cookiecutter
+    ```
+
+2. Run `cookiecutter` on the template:
+
+    ```text
+    cookiecutter https://github.com/beeware/briefcase-macOS-Xcode-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. [Obtain a Python Apple support package for macOS](https://github.com/beeware/Python-Apple-support),
+   and extract it into the `My Project/Support` directory generated by the template.
+
+4. Add your code to the template, into the `My Project/My Project/app`.
+   directory. At the very minimum, you need to have an
+   `app/<app name>/__main__.py` file that will be run on startup.
+
+   If your code has any dependencies, they should be installed into the
+   `My Project/My Project/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/
+    My Project/
+        app/
+            my_project/
+                __init__.py
+                app.py
+        app_packages/
+            ...
+        ...
+    My Project.xcodeproj/
+        ...
+    Support/
+        ...
+        VERSIONS
+    briefcase.toml
+```
+
+You're now ready to open the XCode project file, build and run your project!
+
+## Next steps
+
+Of course, running Python code isn't very interesting by itself - you'll be
+able to output to the console, and see that output in XCode, but if you tap the
+app icon on your phone, you won't see anything - because there isn't a visible
+console on an iPhone.
+
+To do something interesting, you'll need to work with the native macOS system
+libraries to draw widgets and respond to screen taps. The
+[Rubicon](https://github.com/beeware/rubicon-objc) Objective
+C bridging library can be used to interface with the macOS system libraries.
+Alternatively, you could use a cross-platform widget toolkit that supports macOS
+(such as [Toga](https://beeware.org/project/projects/libraries/toga))
+to provide a GUI for your application.
+
+Regardless of whether you use Toga, or you write an application natively, the
+template project will try to start a Python module matching the name of the
+`MainModule` property in the `Info.plist` file associated with the project.
+If that module can't be started, any error raised will be logged, and the
+Python interpreter will be shut down. All console output and errors are
+automatically redirected to the macOS system console.
+
+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.