Merge pull request #63 from beeware/readme-update

Update details about template in README.

README.rst

@@ -14,8 +14,8 @@ uses this template, rolling it out using data extracted from a
 
 However, if you *do* want use this template directly...
 
-1. Install `cookiecutter`_. This is a tool used to bootstrap complex project
-   templates::
+1. Install `Cookiecutter <https://github.com/cookiecutter/cookiecutter>`__. This
+   is a tool used to bootstrap complex project templates::
 
     $ pip install cookiecutter
 
@@ -29,11 +29,21 @@ However, if you *do* want use this template directly...
    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`_, and extract it into
-   the ``My Project/My Project.app/Contents/Resources/Suppoort`` directory
-   generated by the template.
-
-4. Add your code to the template, into the
+3. `Obtain a Python Apple support package for macOS
+   <https://github.com/beeware/Python-Apple-support>`__, and extract it into the
+   ``My Project/My Project.app/Contents/Resources/Suppoort`` directory generated
+   by the template.
+
+4. Obtain a stub binary, and add it as a file named ``My Project`` in the ``My
+   Project/My Project.app/Contents/MacOS/`` directory generated by the template.
+   The `stub project
+   <https://github.com/beeware/briefcase-macOS-Xcode-template/tree/main/stub>`__
+   in the `Briefcase macOS Xcode template
+   <https://github.com/beeware/briefcase-macOS-Xcode-template>`__ generates
+   two stub binaries - one for GUI apps, and one for console apps; copy the
+   appropriate executable from that project into your app template.
+
+5. Add your code to the template, into the
    ``My Project/My Project.app/Contents/Resources/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.
@@ -64,13 +74,24 @@ looks something like::
                         VERSIONS
                     my-project.icns
                 Info.plist
+        installer/
+            resources/
+                welcome.html
+            scripts/
+                postinstall
+            Distribution.xml
         Entitlements.plist
         briefcase.toml
 
 The ``My Project.app`` directory should identify as an macOS application that
 can be started by clicking on the application icon in Finder. It can also be
 distributed as a standalone package.
 
+Before you can run the app, you will need to sign any binary files, frameworks
+and embedded apps in the ``My Project.app`` folder, as well as the ``My
+Project.app`` folder itself. The ``Entitlements.plist`` file should be a good
+starting point for the entitlements required to sign the app.
+
 Next steps
 ----------
 
@@ -79,52 +100,13 @@ be able to do any console input or output, because a macOS app doesn't display
 a console.
 
 To do something interesting, you'll need to work with the native macOS system
-libraries to draw widgets and respond to user input. The `Rubicon`_ 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`_) to provide a GUI for your application.
+libraries to draw widgets and respond to user input. The `Rubicon Objective C
+<https://github.com/beeware/rubicon-objc>`__ 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://github.com/beeware/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.
-
-Debugging
----------
-
-If, when you run your application, you get an error of::
-
-    LSOpenURLsWithRole() failed with error -10810 for the file /Users/.../My Project.app.
-
-then your application is crashing during startup. This might indicate a problem
-with the Briefcase template; however, it's more likely a problem with your
-code - probably a syntax error, or a missing dependency.
-
-To get more helpful debugging information, you can run the application directly
-from the command line. Although it presents as a single icon in Finder,
-internally a macOS application is a folder with a specific structure, and an
-entry point matching the name of the application. We can use this entry point
-to manually start the application directly from the command line.
-
-If your application is called ``My Project``, you can start the application by
-running::
-
-    $ My\ Project/My\ Project.app/Contents/MacOS/My\ Project
-
-This starts the application the same way as Finder, but outputs any Python
-errors to the console.
-
-If the problem is a syntax error, you can fix your code.
-
-If it's a dependency problem, ensure that any required dependencies have been
-installed into the ``Contents/Resources/app_packages`` directory.
-
-If it's a problem with the execution environment, you can modify the entry
-point script. ``My\ Project/My\ Project.app/Contents/MacOS/My\ Project`` is a
-simple Bash script that starts the python interpreter after setting some
-environment variables. If necessary, you can modify this script.
-
-.. _cookiecutter: https://github.com/cookiecutter/cookiecutter
-.. _Obtain a Python Apple support package for macOS: https://github.com/beeware/Python-Apple-support
-.. _Rubicon: https://github.com/beeware/rubicon-objc
-.. _Toga: https://beeware.org/project/projects/libraries/toga