1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
|
.TH BRIEFCASE "1" "JAN 2024" "BRIEFCASE 1.0.0" "Tool for converting Python projects into native applications"
.SH NAME
.nf
.fam C
\fBbriefcase\fP \- Tool for converting Python projects into standalone native
applications for distribution.
.SH SYNOPSIS
\fBbriefcase\fP [\fIcommand\fP] [\fIplatform\fP] [\fIformat\fP] [\fIoptions\fP]
.fam T
.fi
.SH DESCRIPTION
.nf
.fam C
\fBbriefcase\fP 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.
.fam T
.fi
.SH USAGE
\fBbriefcase\fP [\fB\-h\fP] <\fIcommand\fP> [<\fIplatform\fP>] [<\fIformat\fP>] [...]
.SH ENVIRONMENT SETUP
.nf
.fam C
Before using Briefcase, you need to prepare your environment. This involves
ensuring Python is installed and setting up a virtual environment.
.fam T
.fi
.SS 1. Install Python
.nf
.fam C
Briefcase requires Python to be installed on your system. You can use the
system's default Python or manage multiple Python versions using \fBpyenv\fP.
\fBOption 1: Use the system Python\fP
Most Linux distributions and macOS come with Python pre-installed. To check
if Python is installed, run: \fBpython3 --version\fP
If Python is not installed, you can install it using your system's package
manager. For example:
- On Debian/Ubuntu: \fBsudo apt install python3\fP
- On macOS (using Homebrew): \fBbrew install python\fP
\fBOption 2: Use pyenv to manage Python versions\fP
If you need to use a specific version of Python or manage multiple versions,
you can use \fBpyenv\fP. To install pyenv, follow the instructions at:
\fBhttps://github.com/pyenv/pyenv\fP
After installing pyenv, you can install a specific Python version,
for example:
\fBpyenv install 3.9.7\fP
And set it as the global version:
\fBpyenv global 3.9.7\fP
.fam T
.fi
.SS 2. Create a Virtual Environment
.nf
.fam C
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:
\fBpython3 -m venv venv\fP
2. Activate the virtual environment:
- On Linux/macOS: \fBsource venv/bin/activate\fP
- On Windows: \fBvenv\\Scripts\\activate\fP
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.
.fam T
.fi
.SH COMMANDS
.nf
.fam C
\fBnew\fP Create a new Briefcase project.
\fBdev\fP Run a Briefcase project in the dev environment.
\fBconvert\fP Set up an existing project for Briefcase.
\fBcreate\fP Create a new app for a target platform.
\fBopen\fP Open an app in the build tool for the target platform.
\fBbuild\fP Build an app for a target platform.
\fBupdate\fP Update the source, dependencies, and resources for an app.
\fBrun\fP Run an app.
\fBpackage\fP Package an app for distribution.
\fBpublish\fP Publish an app to a distribution channel.
\fBupgrade\fP Upgrade Briefcase-managed tools.
.fam T
.fi
.SH PLATFORMS
.nf
.fam C
android, iOS, linux, macOS, web, windows
.fam T
.fi
.SH OPTIONS
.nf
.fam C
\-h, \-\-help
Show this help message and exit.
\-V, \-\-version
Show the program's version number and exit.
.fam T
.fi
.SH EXAMPLES
.SS briefcase new
.nf
.fam C
The \fB`briefcase new`\fP command requests basic information to create a
new application. The following details are required:
\fBFormal Name\fP: Full name of the application (default: "Hello World").
\fBApp Name\fP: Technical name of the application, without spaces (default: "helloworld").
\fBBundle\fP: Unique app identifier. If you own a domain, enter it in reverse
order (e.g., \fBcom.example\fP). Otherwise, use the default (\fBcom.example\fP).
\fBProject Name\fP: Name of the project directory (default: "Hello World").
\fBDescription\fP: Brief description of the application (accept the default or customize).
\fBAuthor\fP: Your name as the author of the project.
\fBAuthor's Email\fP: Your email, used for settings and publishing.
\fBURL\fP: Application home page (use your own domain or the default \fBhttps://example.com/helloworld\fP).
\fBLicense\fP: Choose the project license (default: BSD).
\fBGUI Framework\fP: 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
.fam T
.fi
.SS briefcase create
.nf
.fam C
This command installs the dependencies specified in the \fB pyproject.toml\fP
file, creating the project structure for the native operating system
and configuring the necessary files for packaging and distributing the application:
\fB(venv-venv)$ briefcase create\fP
[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
...
\fB`briefcase create android`\fP This command configures the project structure for
packaging on the Android system.
.fam T
.fi
.SS briefcase build
.nf
.fam C
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
\fB(venv-venv)$ briefcase build\fP
[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
.fam T
.fi
.SS briefcase run
.nf
.fam C
This command executes the generated application within the
environment prepared by Briefcase, ensuring that all dependencies and configurations
are correctly applied:
\fB(venv-venv)$ briefcase run\fP
[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
.fam T
.fi
.SS briefcase package
.nf
.fam C
This command generates the final files needed to distribute the application,
such as target platform-specific installers and packages.
\fB(venv-venv)$ briefcase packahe\fP
[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
.fam T
.fi
.SH SEE ALSO
Check the official documentation at https://briefcase.readthedocs.io/ for more details.
.SH AUTHOR
Briefcase Project https://github.com/\fBbeeware\fP/briefcase/ or https://briefcase.readthedocs.io/en/stable/
.PP
Josenilson Ferreira da Silva <nilsonfsilva@hotmail.com> authored this manual.
.PP
|
