教程 1 - 您的第一个应用程序¶

我们准备好创建我们的第一个应用程序了。

安装 BeeWare 工具¶

首先，我们需要安装 Briefcase。Briefcase 是一款 BeeWare 工具，可用于打包应用程序，以便分发给最终用户；但它也可用于引导新项目。确保您在教程0 中创建的 beeware-tutorial 目录中，并已激活 beeware-venv 虚拟环境，然后运行：

macOSLinuxWindows

(beeware-venv) $ python -m pip install briefcase

(beeware-venv) $ python -m pip install briefcase

安装过程中可能出现的错误

如果在安装过程中出现错误，几乎可以肯定是因为某些系统要求尚未安装。请确保已安装所有平台先决条件。

(beeware-venv) C:\...>python -m pip install briefcase

安装过程中可能出现的错误

请务必使用 python -m pip，而不是简单的 pip。Briefcase 需要确保它拥有最新版本的 pip 和 setuptools ，而裸调用的 pip 无法自我更新。如果您想了解更多，Brett Cannon 有一篇关于这个问题的详细博文。

引导新项目¶

让我们开始第一个 BeeWare 项目！我们将使用 Briefcase new 命令创建一个名为 Hello World 的应用程序。在命令提示符下运行以下命令

macOSLinuxWindows

(beeware-venv) $ briefcase new

(beeware-venv) $ briefcase new

(beeware-venv) C:\...>briefcase new

Briefcase会要求我们提供新应用程序的一些详细信息。在本教程中，请使用以下内容：

Formal Name - 接受默认值：Hello World。
App Name - 接受默认值：helloworld。
Bundle Identifier（捆绑标识符） - 如果您拥有自己的域名，请按相反顺序输入该域名。(例如，如果您拥有域名 "cupcakes.com"，则输入 com.cupcakes 作为捆绑标识符）。如果您没有自己的域名，请接受默认值（com.example）。
Project Name - 接受默认值：Hello World。
描述 - 接受默认值（或者，如果您想发挥自己的创造力，也可以提出自己的描述！）
Author - 在此处输入您自己的名字。
Author's Email - 输入您自己的电子邮件地址。这将用于配置文件、帮助文本以及向应用程序商店提交应用程序时需要电子邮件的任何地方。
URL - 应用程序登陆页面的 URL。同样，如果您拥有自己的域名，请输入该域名的 URL（包括 https://）。否则，接受默认 URL (https://example.com/helloworld) 即可。此 URL（暂时）不需要实际存在；只有在您将应用程序发布到应用程序商店时才会使用。
Project License (项目许可证) - 接受默认许可证（BSD）。这不会影响本教程的任何操作，因此，如果您对许可证选择有特别强烈的意见，请随意选择其他许可证。
GUI Framework - 接受默认选项 Toga（BeeWare 自己的图形用户界面工具包）。

接下来，Briefcase 会生成一个项目骨架供你使用。如果你到目前为止都已经跟着这个教程走的话，并接受了所述的默认设置，那么你的文件系统应该是这样的:

beeware-tutorial/
├── beeware-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

该骨架实际上是一个功能完备的应用程序，无需添加任何其他内容。src 文件夹包含应用程序的所有代码，tests 文件夹包含初始测试套件，pyproject.toml 文件描述了如何打包发布应用程序。如果您用编辑器打开 pyproject.toml，就会看到刚才提供给 Briefcase 的配置详细信息。

现在我们有了一个包含占位代码的应用程序，可以使用 Briefcase 来运行它。

在开发者模式下运行应用程序¶

移动到 helloworld 项目目录，告诉 Briefcase 以开发者（或 dev）模式启动项目：

macOSLinuxWindows

(beeware-venv) $ cd helloworld
(beeware-venv) $ briefcase dev

[helloworld] Activating dev environment...
...
Creating virtual environment (dev.cpython-313-darwin)... done

[hello-world] Installing requirements...
...

[helloworld] Starting in dev mode...
===========================================================================

(beeware-venv) $ cd helloworld
(beeware-venv) $ briefcase dev

[helloworld] Activating dev environment...
...
Creating virtual environment (dev.cpython-313-x86_64-linux-gnu)... done

[hello-world] Installing requirements...
...

[helloworld] Starting in dev mode...
===========================================================================

(beeware-venv) C:\...>cd helloworld
(beeware-venv) C:\...>briefcase dev

[helloworld] Activating dev environment...
...
Creating virtual environment (dev.cp313-win_amd64)... done

[hello-world] Installing requirements...
...

[helloworld] Starting in dev mode...
===========================================================================

这将打开一个图形用户界面 (GUI) 窗口：

macOSLinuxWindows

Hello World 教程 1 窗口，在 macOS 上](../images/macOS/tutorial-1.png)。

运行 briefcase dev 时可能出现的错误

若运行briefcase dev时出现错误，几乎可以确定是某些系统要求尚未安装。请确保已安装所有平台预置条件；您收到的错误信息应会指出缺失的具体软件包。

无效要求或 pip 无法连接

如果您遇到错误：

Unable to install requirements. This may be because one of your
requirements is invalid, or because pip was unable to connect
to the PyPI server.

确认运行的是本教程支持的 python 版本。

如果您的 Python 版本不被支持，则需重新开始本教程。

关闭应用程序 – 可以使用应用程序窗口上的关闭按钮、从应用程序的菜单栏选择关闭/退出、或在您运行 briefcase dev 的命令行窗口中按 Ctrl+C – 就完成了！恭喜您，您刚刚使用 Python 编写了一个独立、原生的应用程序！

下一步¶

现在，我们有了一个在开发者模式下运行的应用程序。现在我们可以添加一些自己的逻辑，让应用程序做更有趣一些的事情。在\ :doc:教程 2<tutorial-2> 中，我们将为应用程序添加一个更有用的用户界面。