--- name: "briefcase" section: "1" platform: "linux" package: "python3-briefcase" version: "0.3.22-2" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/briefcase" --- # 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 \ authored this manual.