BRIEFCASE(1)

NAME
briefcase - Tool for converting Python projects into standalone native
applications for distribution.

SYNOPSIS
briefcase [command] [platform] [format] [options]

DESCRIPTION
briefcase is a tool that allows you to convert a Python project into a
standalone native application, ready for distribution. It supports multiple
platforms and formats, making it easy to create, build, and publish applications.

USAGE
briefcase [-h] <command> [<platform>] [<format>] [...]

ENVIRONMENT SETUP
Before using Briefcase, you need to prepare your environment. This involves
ensuring Python is installed and setting up a virtual environment.

  1. Install Python
Briefcase requires Python to be installed on your system. You can use the
system's default Python or manage multiple Python versions using pyenv.

Option 1: Use the system Python
Most Linux distributions and macOS come with Python pre-installed. To check
if Python is installed, run: python3 --version

If Python is not installed, you can install it using your system's package
manager. For example:
   - On Debian/Ubuntu: sudo apt install python3
   - On macOS (using Homebrew): brew install python

Option 2: Use pyenv to manage Python versions
If you need to use a specific version of Python or manage multiple versions,
you can use pyenv. To install pyenv, follow the instructions at:
https://github.com/pyenv/pyenv

After installing pyenv, you can install a specific Python version,
for example:
   pyenv install 3.9.7
And set it as the global version:
   pyenv global 3.9.7

  2. Create a Virtual Environment
It is recommended to use a virtual environment to isolate your project's
dependencies. To create and activate a virtual environment, follow these steps:

1. Create a virtual environment:
   python3 -m venv venv

2. Activate the virtual environment:
   - On Linux/macOS: source venv/bin/activate
   - On Windows: venv\Scripts\activate

Once activated, your terminal prompt will change to indicate the virtual
environment is active. You can now install Briefcase and other dependencies
within this environment.

COMMANDS
     new      Create a new Briefcase project.

     dev      Run a Briefcase project in the dev environment.

     convert  Set up an existing project for Briefcase.

     create   Create a new app for a target platform.

     open     Open an app in the build tool for the target platform.

     build    Build an app for a target platform.

     update   Update the source, dependencies, and resources for an app.

     run      Run an app.

     package  Package an app for distribution.

     publish  Publish an app to a distribution channel.

     upgrade  Upgrade Briefcase-managed tools.

PLATFORMS

      android, iOS, linux, macOS, web, windows

OPTIONS

      -h, --help
               Show this help message and exit.

      -V, --version
               Show the program's version number and exit.

EXAMPLES

  briefcase new
The `briefcase new` command requests basic information to create a
new application. The following details are required:

      Formal Name: Full name of the application (default: "Hello World").
      App Name: Technical name of the application, without spaces (default: "helloworld").
      Bundle: Unique app identifier. If you own a domain, enter it in reverse
         order (e.g., com.example). Otherwise, use the default (com.example).
      Project Name: Name of the project directory (default: "Hello World").
      Description: Brief description of the application (accept the default or customize).
      Author: Your name as the author of the project.
      Author's Email: Your email, used for settings and publishing.
      URL: Application home page (use your own domain or the default https://example.com/helloworld).
      License: Choose the project license (default: BSD).
      GUI Framework: Choose the GUI framework (default: Toga, BeeWare's GUI toolkit).

├── venv-venv/
│   └── ...
└── helloworld/
    ├── CHANGELOG
    ├── LICENSE
    ├── pyproject.toml
    ├── README.rst
    ├── src/
    │   └── helloworld/
    │       ├── app.py
    │       ├── __init__.py
    │       ├── __main__.py
    │       └── resources/
    │           └── README
    └── tests/
        ├── helloworld.py
        ├── __init__.py
        └── test_app.py

  briefcase create
This command installs the dependencies specified in the  pyproject.toml
file, creating the project structure for the native operating system
and configuring the necessary files for packaging and distributing the application:

(venv-venv)$ briefcase create
              [helloworld] Finalizing application configuration...
        Targeting ubuntu:jammy (Vendor base debian)
        Determining glibc version... done
        Targeting glibc 2.35
        Targeting Python3.10
        [helloworld] Generating application template...
        Using app template: https://github.com/beeware/briefcase-linux-AppImage-template.git, branch v0.3.18
        ...

`briefcase create android` This command configures the project structure for
packaging on the Android system.

  briefcase build
The command compiles and prepares a Briefcase project for
distribution on the specified platform. It generates the binaries, packages and
configurations required to run the application

(venv-venv)$ briefcase build
              [helloworld] Finalizing application configuration...
        Targeting ubuntu:jammy (Vendor base debian)
        Determining glibc version... done
        Targeting glibc 2.35
        Targeting Python3.10
        [helloworld] Building application...
        Build bootstrap binary...
        make: Entering directory '/home/brutus/beeware-tutorial/helloworld/build/linux/ubuntu/jammy/bootstrap'
        ...
        make: Leaving directory '/home/brutus/beeware-tutorial/helloworld/build/linux/ubuntu/jammy/bootstrap'
        Building bootstrap binary... done
        Installing license... done
        Installing changelog... done
        Installing man page... done
        Updating file permissions... done
        Stripping binary... done

  briefcase run
This command executes the generated application within the
environment prepared  by Briefcase, ensuring that all dependencies and configurations
are correctly applied:

(venv-venv)$ briefcase run
              [helloworld] Finalizing application configuration...
        Targeting ubuntu:jammy (Vendor base debian)
        Determining glibc version... done
        Targeting glibc 2.35
        Targeting Python3.10

        [helloworld] Starting app...
        ===========================================================================
        Install path: /home/brutus/beeware-tutorial/helloworld/build/helloworld/linux/ubuntu/jammy/helloworld-0.0.1/usr
        Pre-initializing Python runtime...
        PYTHONPATH:
        /usr/lib/python3.10
        /usr/lib/python3.10/lib-dynload
        /home/brutus/beeware-tutorial/helloworld/build/helloworld/linux/ubuntu/jammy/helloworld-0.0.1/usr/lib/helloworld/app
        /home/brutus/beeware-tutorial/helloworld/build/helloworld/linux/ubuntu/jammy/helloworld-0.0.1/usr/lib/helloworld/app_packages
        Configure argc/argv...
        Initializing Python runtime...
        Running app module: helloworld

  briefcase package
This command generates the final files needed to distribute the application,
such as target platform-specific installers and packages.

(venv-venv)$ briefcase packahe
              [helloworld] Finalizing application configuration...
        Targeting ubuntu:jammy (Vendor base debian)
        Determining glibc version... done
        Targeting glibc 2.35
        Targeting Python3.10
        [helloworld] Building .deb package...
        Write Debian package control file... done
        dpkg-deb: building package 'helloworld' in 'helloworld-0.0.1.deb'.
        Building Debian package... done
        [helloworld] Packaged dist/helloworld_0.0.1-1~ubuntu-jammy_amd64.deb

SEE ALSO
Check the official documentation at https://briefcase.readthedocs.io/ for more details.

AUTHOR
Briefcase Project https://github.com/beeware/briefcase/ or https://briefcase.readthedocs.io/en/stable/

Josenilson Ferreira da Silva <nilsonfsilva@hotmail.com> authored this manual.