Tutorial 0 - Hello, world!

In this tutorial, you’ll take a really simple “Hello, world!” program written in Python, convert it into a working project.


This tutorial assumes you’ve read and followed the instructions in Getting Started. If you’ve done this, you should have:

  • A tutorial directory,
  • A activated Python 3.5 virtual environment,
  • Briefcase installed in that virtual environment,
  • Any platform-specific dependencies installed.

Start a new project

Let’s get started by using the handy template briefcase-template:

$ pip install cookiecutter briefcase
$ cookiecutter https://github.com/pybee/briefcase-template

This will ask a bunch of questions of you. We’ll use an app_name of “helloworld”, a formal_name of “Hello World”, using the Toga GUI toolkit. You can use the default values for the other questions (or update them to reflect your own name if you want).

You’ll now have a few files in this folder, including a helloworld directory.

Check out what the provided helloworld/app.py file contains:

$ cd helloworld
$ cat helloworld/app.py
def main():
    # This needs to return an object that has a main_loop() method.
    return None

This won’t do much as it is, but we can make it useful.

Add this into the app.py:

import toga

def main():
    return toga.App('Hello World', 'org.pybee.helloworld')

Put it in a briefcase

Your project is now ready to using briefcase.


To create and run the application, run:

$ python setup.py windows -s

This will produce a windows subdirectory that will contain a HelloWorld-0.0.1.msi installer.


To create and run the application, run:

$ python setup.py macos -s

This will produce a macOS subdirectory that contains a Hello World.app application bundle. This bundle can be dragged into your Applications folder, or zipped and distributed to anyone else.


To create and run the application, run:

$ python setup.py linux -s

This will produce a linux subdirectory that contains a Hello World script that will start the application.


To create and run the application, run:

$ python setup.py ios -s

This will start the iOS simulator (you may be asked to select an API and a simulator device on which to run the app) and run your app.

It will also produce an ios subdirectory that contains an XCode project called Hello World.xcodeproj. You can open this project in XCode to run your application.


To create and run the application, run:

$ python setup.py android -s

This will produce an android subdirectory that contains a Gradle project. It will also launch the app on the first Android device or simulator that can be found running on (or attached to) your computer.

What should happen

When the application runs, you should see a window with a title of “Hello World” appear. The window won’t contain any content - but it will be a native application, with a native icon in your task bar (or wherever icons appear on your platform).

You’ve just packaged your first app with Briefcase! Now, let’s make the app actually do something interesting.