From 730bf1bfee413a5738053bf0609aeb0efaa92c46 Mon Sep 17 00:00:00 2001 From: John Aziz Date: Wed, 14 Aug 2024 00:39:06 +0300 Subject: [PATCH 1/7] docs: initial pass --- docs/how-to/cli-apps.rst | 551 +++++++++++++++++++++++++++++++++++++++ docs/how-to/index.rst | 1 + 2 files changed, 552 insertions(+) create mode 100644 docs/how-to/cli-apps.rst diff --git a/docs/how-to/cli-apps.rst b/docs/how-to/cli-apps.rst new file mode 100644 index 000000000..4115ddb8d --- /dev/null +++ b/docs/how-to/cli-apps.rst @@ -0,0 +1,551 @@ +========================================== +Building a CLI application with Briefcase +========================================== + +Overview +--------- + +In this tutorial, you'll learn how to build and package a Command Line Interface (CLI) application for distribution on Windows, macOS, and Linux using Briefcase. + +Prerequisites +------------- + +Before you start, you'll need to have the following installed on your computer: + +* Python 3.8 or later +* Briefcase +* A code editor + +For more information on installing Briefcase, see the `BeeWare Tutorial `_. + +Bootstrap a new project +------------------------ + +Let's start our first Briefcase CLI project! +We're going to use the Briefcase ``new`` command to create an application called **Hello World**. +The only thing that we need to change is the GUI framework. +Since we're building a CLI application, we'll select the **Console** GUI framework. +Run the following from your command prompt: + +.. tabs:: + + .. group-tab:: macOS + + .. code-block:: console + + $ briefcase new + Let's build a new Briefcase app! + -- Formal Name --------------------------------------------------------------- + + First, we need a formal name for your application. + + This is the name that will be displayed to humans whenever the name of the + application is displayed. It can have spaces and punctuation if you like, and + any capitalization will be used as you type it. + + Formal Name [Hello World]: Hello World + + + -- App Name ------------------------------------------------------------------ + + Next, we need a name that can serve as a machine-readable Python package name + for your application. + + This name must be PEP508-compliant - that means the name may only contain + letters, numbers, hyphens and underscores; it can't contain spaces or + punctuation, and it can't start with a hyphen or underscore. + + Based on your formal name, we suggest an app name of 'helloworld', but you can + use another name if you want. + + App Name [helloworld]: helloworld + + + -- Bundle Identifier --------------------------------------------------------- + + Now we need a bundle identifier for your application. + + App stores need to protect against having multiple applications with the same + name; the bundle identifier is the namespace they use to identify applications + that come from you. The bundle identifier is usually the domain name of your + company or project, in reverse order. + + For example, if you are writing an application for Example Corp, whose website + is example.com, your bundle would be 'com.example'. The bundle will be + combined with your application's machine readable name to form a complete + application identifier (e.g., com.example.helloworld). + + Bundle Identifier [com.example]: com.example + + + -- Project Name -------------------------------------------------------------- + + Briefcase can manage projects that contain multiple applications, so we need a + Project name. + + If you're only planning to have one application in this project, you can use + the formal name as the project name. + + Project Name [Hello World]: Hello World + + + -- Description --------------------------------------------------------------- + + Now, we need a one line description for your application. + + Description [My first application]: My first application + + + -- Author -------------------------------------------------------------------- + + Who do you want to be credited as the author of this application? + + This could be your own name, or the name of your company you work for. + + Author [Jane Developer]: Jane Developer + + + -- Author's Email ------------------------------------------------------------ + + What email address should people use to contact the developers of this + application? + + This might be your own email address, or a generic contact address you set up + specifically for this application. + + Author's Email [jane@example.com]: jane@example.com + + + -- Application URL ----------------------------------------------------------- + + What is the website URL for this application? + + If you don't have a website set up yet, you can put in a dummy URL. + + Application URL [https://example.com/helloworld]: https://example.com/helloworld + + + -- Project License ----------------------------------------------------------- + + What license do you want to use for this project's code? + + 1) BSD license + 2) MIT license + 3) Apache Software License + 4) GNU General Public License v2 (GPLv2) + 5) GNU General Public License v2 or later (GPLv2+) + 6) GNU General Public License v3 (GPLv3) + 7) GNU General Public License v3 or later (GPLv3+) + 8) Proprietary + 9) Other + + Project License [1]: 1 + + + -- GUI Framework ------------------------------------------------------------- + + What GUI toolkit do you want to use for this project? + + Additional GUI bootstraps are available; visit + https://beeware.org/bee/briefcase-bootstraps for a full list of known GUI + bootstraps. + + 1) Toga + 2) PySide6 (does not support iOS/Android/Web deployment) + 3) Pygame (does not support iOS/Android/Web deployment) + 4) Console (does not support iOS/Android/Web deployment) + 5) None + + GUI Framework [1]: 4 + + + ------------------------------------------------------------------------------ + + [helloworld] Generating a new application 'Hello World' + Using app template: https://github.com/beeware/briefcase-template, branch v0.1 + Template branch v0.1 not found; falling back to development template + Using existing template (sha b7a98f8ef56dce6dc4ec0afb211b475c71caea26, updated Mon Aug 12 07:18:17 2024) + + [helloworld] Generated new application 'Hello World' + + To run your application, type: + + $ cd helloworld + $ briefcase dev + + + .. group-tab:: Linux + + .. code-block:: console + + $ briefcase new + Let's build a new Briefcase app! + -- Formal Name --------------------------------------------------------------- + + First, we need a formal name for your application. + + This is the name that will be displayed to humans whenever the name of the + application is displayed. It can have spaces and punctuation if you like, and + any capitalization will be used as you type it. + + Formal Name [Hello World]: Hello World + + + -- App Name ------------------------------------------------------------------ + + Next, we need a name that can serve as a machine-readable Python package name + for your application. + + This name must be PEP508-compliant - that means the name may only contain + letters, numbers, hyphens and underscores; it can't contain spaces or + punctuation, and it can't start with a hyphen or underscore. + + Based on your formal name, we suggest an app name of 'helloworld', but you can + use another name if you want. + + App Name [helloworld]: helloworld + + + -- Bundle Identifier --------------------------------------------------------- + + Now we need a bundle identifier for your application. + + App stores need to protect against having multiple applications with the same + name; the bundle identifier is the namespace they use to identify applications + that come from you. The bundle identifier is usually the domain name of your + company or project, in reverse order. + + For example, if you are writing an application for Example Corp, whose website + is example.com, your bundle would be 'com.example'. The bundle will be + combined with your application's machine readable name to form a complete + application identifier (e.g., com.example.helloworld). + + Bundle Identifier [com.example]: com.example + + + -- Project Name -------------------------------------------------------------- + + Briefcase can manage projects that contain multiple applications, so we need a + Project name. + + If you're only planning to have one application in this project, you can use + the formal name as the project name. + + Project Name [Hello World]: Hello World + + + -- Description --------------------------------------------------------------- + + Now, we need a one line description for your application. + + Description [My first application]: My first application + + + -- Author -------------------------------------------------------------------- + + Who do you want to be credited as the author of this application? + + This could be your own name, or the name of your company you work for. + + Author [Jane Developer]: Jane Developer + + + -- Author's Email ------------------------------------------------------------ + + What email address should people use to contact the developers of this + application? + + This might be your own email address, or a generic contact address you set up + specifically for this application. + + Author's Email [jane@example.com]: jane@example.com + + + -- Application URL ----------------------------------------------------------- + + What is the website URL for this application? + + If you don't have a website set up yet, you can put in a dummy URL. + + Application URL [https://example.com/helloworld]: https://example.com/helloworld + + + -- Project License ----------------------------------------------------------- + + What license do you want to use for this project's code? + + 1) BSD license + 2) MIT license + 3) Apache Software License + 4) GNU General Public License v2 (GPLv2) + 5) GNU General Public License v2 or later (GPLv2+) + 6) GNU General Public License v3 (GPLv3) + 7) GNU General Public License v3 or later (GPLv3+) + 8) Proprietary + 9) Other + + Project License [1]: 1 + + + -- GUI Framework ------------------------------------------------------------- + + What GUI toolkit do you want to use for this project? + + Additional GUI bootstraps are available; visit + https://beeware.org/bee/briefcase-bootstraps for a full list of known GUI + bootstraps. + + 1) Toga + 2) PySide6 (does not support iOS/Android/Web deployment) + 3) Pygame (does not support iOS/Android/Web deployment) + 4) Console (does not support iOS/Android/Web deployment) + 5) None + + GUI Framework [1]: 4 + + + ------------------------------------------------------------------------------ + + [helloworld] Generating a new application 'Hello World' + Using app template: https://github.com/beeware/briefcase-template, branch v0.1 + Template branch v0.1 not found; falling back to development template + Using existing template (sha b7a98f8ef56dce6dc4ec0afb211b475c71caea26, updated Mon Aug 12 07:18:17 2024) + + [helloworld] Generated new application 'Hello World' + + To run your application, type: + + $ cd helloworld + $ briefcase dev + + .. group-tab:: Windows + + .. code-block:: doscon + + C:\...>briefcase new + Let's build a new Briefcase app! + -- Formal Name --------------------------------------------------------------- + + First, we need a formal name for your application. + + This is the name that will be displayed to humans whenever the name of the + application is displayed. It can have spaces and punctuation if you like, and + any capitalization will be used as you type it. + + Formal Name [Hello World]: Hello World + + + -- App Name ------------------------------------------------------------------ + + Next, we need a name that can serve as a machine-readable Python package name + for your application. + + This name must be PEP508-compliant - that means the name may only contain + letters, numbers, hyphens and underscores; it can't contain spaces or + punctuation, and it can't start with a hyphen or underscore. + + Based on your formal name, we suggest an app name of 'helloworld', but you can + use another name if you want. + + App Name [helloworld]: helloworld + + + -- Bundle Identifier --------------------------------------------------------- + + Now we need a bundle identifier for your application. + + App stores need to protect against having multiple applications with the same + name; the bundle identifier is the namespace they use to identify applications + that come from you. The bundle identifier is usually the domain name of your + company or project, in reverse order. + + For example, if you are writing an application for Example Corp, whose website + is example.com, your bundle would be 'com.example'. The bundle will be + combined with your application's machine readable name to form a complete + application identifier (e.g., com.example.helloworld). + + Bundle Identifier [com.example]: com.example + + + -- Project Name -------------------------------------------------------------- + + Briefcase can manage projects that contain multiple applications, so we need a + Project name. + + If you're only planning to have one application in this project, you can use + the formal name as the project name. + + Project Name [Hello World]: Hello World + + + -- Description --------------------------------------------------------------- + + Now, we need a one line description for your application. + + Description [My first application]: My first application + + + -- Author -------------------------------------------------------------------- + + Who do you want to be credited as the author of this application? + + This could be your own name, or the name of your company you work for. + + Author [Jane Developer]: Jane Developer + + + -- Author's Email ------------------------------------------------------------ + + What email address should people use to contact the developers of this + application? + + This might be your own email address, or a generic contact address you set up + specifically for this application. + + Author's Email [jane@example.com]: jane@example.com + + + -- Application URL ----------------------------------------------------------- + + What is the website URL for this application? + + If you don't have a website set up yet, you can put in a dummy URL. + + Application URL [https://example.com/helloworld]: https://example.com/helloworld + + + -- Project License ----------------------------------------------------------- + + What license do you want to use for this project's code? + + 1) BSD license + 2) MIT license + 3) Apache Software License + 4) GNU General Public License v2 (GPLv2) + 5) GNU General Public License v2 or later (GPLv2+) + 6) GNU General Public License v3 (GPLv3) + 7) GNU General Public License v3 or later (GPLv3+) + 8) Proprietary + 9) Other + + Project License [1]: 1 + + + -- GUI Framework ------------------------------------------------------------- + + What GUI toolkit do you want to use for this project? + + Additional GUI bootstraps are available; visit + https://beeware.org/bee/briefcase-bootstraps for a full list of known GUI + bootstraps. + + 1) Toga + 2) PySide6 (does not support iOS/Android/Web deployment) + 3) Pygame (does not support iOS/Android/Web deployment) + 4) Console (does not support iOS/Android/Web deployment) + 5) None + + GUI Framework [1]: 4 + + + ------------------------------------------------------------------------------ + + [helloworld] Generating a new application 'Hello World' + Using app template: https://github.com/beeware/briefcase-template, branch v0.1 + Template branch v0.1 not found; falling back to development template + Using existing template (sha b7a98f8ef56dce6dc4ec0afb211b475c71caea26, updated Mon Aug 12 07:18:17 2024) + + [helloworld] Generated new application 'Hello World' + + To run your application, type: + + $ cd helloworld + $ briefcase dev + +Briefcase will then generate a project skeleton for you to use. +If you've followed this tutorial so far, and accepted the defaults as described, +your file system should look something like:: + + 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 + +This skeleton is actually a fully functioning application without adding +anything else. The ``src`` folder contains all the code for the application, the +``tests`` folder contains an initial test suite, and the ``pyproject.toml`` file +describes how to package the application for distribution. If you open +``pyproject.toml`` in an editor, you'll see the configuration details you just +provided to Briefcase. + +Now that we have a stub application, we can use Briefcase to run the +application. + + +Running the application in developer mode +------------------------------------------ + +To run the application in developer (or ``dev``) mode, navigate to the project directory ``helloworld``` and +run the following command: + +.. tabs:: + + .. group-tab:: macOS + + .. code-block:: console + + (beeware-venv) $ cd helloworld + (beeware-venv) $ briefcase dev + + [hello-world] Installing requirements... + ... + + [helloworld] Starting in dev mode... + =========================================================================== + + .. group-tab:: Linux + + .. code-block:: console + + (beeware-venv) $ cd helloworld + (beeware-venv) $ briefcase dev + + [hello-world] Installing requirements... + ... + + [helloworld] Starting in dev mode... + =========================================================================== + + .. group-tab:: Windows + + .. code-block:: doscon + + (beeware-venv) C:\...>cd helloworld + (beeware-venv) C:\...>briefcase dev + + [hello-world] Installing requirements... + ... + + [helloworld] Starting in dev mode... + =========================================================================== + +The application will start in a new terminal window. You should see a message +that says "Hello, world!". + + +Now you are ready to start building and packaging CLI apps! Have fun! diff --git a/docs/how-to/index.rst b/docs/how-to/index.rst index a59af3298..ab6196323 100644 --- a/docs/how-to/index.rst +++ b/docs/how-to/index.rst @@ -20,3 +20,4 @@ stand alone. contribute-docs internal/index publishing/index + cli-apps From abd480138294d293eb2af71e7c9b6cd6d75c59e0 Mon Sep 17 00:00:00 2001 From: John Aziz Date: Wed, 14 Aug 2024 00:44:20 +0300 Subject: [PATCH 2/7] add towncrier changes --- changes/1947.docs.rst | 1 + 1 file changed, 1 insertion(+) create mode 100644 changes/1947.docs.rst diff --git a/changes/1947.docs.rst b/changes/1947.docs.rst new file mode 100644 index 000000000..a2e600f99 --- /dev/null +++ b/changes/1947.docs.rst @@ -0,0 +1 @@ +Tutorial for building and packaging a Command Line Interface (CLI) application using Briefcase. From 93a7c67d274f236f0ee58e656c6493c4ec77188c Mon Sep 17 00:00:00 2001 From: John Aziz Date: Wed, 14 Aug 2024 00:45:59 +0300 Subject: [PATCH 3/7] fix typo --- changes/{1947.docs.rst => 1947.doc.rst} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename changes/{1947.docs.rst => 1947.doc.rst} (100%) diff --git a/changes/1947.docs.rst b/changes/1947.doc.rst similarity index 100% rename from changes/1947.docs.rst rename to changes/1947.doc.rst From 07346c0141d7c35c7b080e36858edfa6d9e78231 Mon Sep 17 00:00:00 2001 From: John Aziz Date: Wed, 14 Aug 2024 19:47:54 +0300 Subject: [PATCH 4/7] docs: tutorial building a cli app part 2 --- docs/how-to/cli-apps.rst | 147 +++++++++++++++++++++++++++++++++++---- 1 file changed, 132 insertions(+), 15 deletions(-) diff --git a/docs/how-to/cli-apps.rst b/docs/how-to/cli-apps.rst index 4115ddb8d..d040bce28 100644 --- a/docs/how-to/cli-apps.rst +++ b/docs/how-to/cli-apps.rst @@ -33,7 +33,7 @@ Run the following from your command prompt: .. code-block:: console - $ briefcase new + (venv) $ briefcase new Let's build a new Briefcase app! -- Formal Name --------------------------------------------------------------- @@ -178,7 +178,7 @@ Run the following from your command prompt: .. code-block:: console - $ briefcase new + (venv) $ briefcase new Let's build a new Briefcase app! -- Formal Name --------------------------------------------------------------- @@ -322,7 +322,7 @@ Run the following from your command prompt: .. code-block:: doscon - C:\...>briefcase new + (venv) C:\...>briefcase new Let's build a new Briefcase app! -- Formal Name --------------------------------------------------------------- @@ -486,8 +486,7 @@ your file system should look something like:: ├── __init__.py └── test_app.py -This skeleton is actually a fully functioning application without adding -anything else. The ``src`` folder contains all the code for the application, the +The ``src`` folder contains all the code for the application, the ``tests`` folder contains an initial test suite, and the ``pyproject.toml`` file describes how to package the application for distribution. If you open ``pyproject.toml`` in an editor, you'll see the configuration details you just @@ -500,7 +499,7 @@ application. Running the application in developer mode ------------------------------------------ -To run the application in developer (or ``dev``) mode, navigate to the project directory ``helloworld``` and +To run the application in developer (or ``dev``) mode, navigate to the project directory ``helloworld`` and run the following command: .. tabs:: @@ -509,43 +508,161 @@ run the following command: .. code-block:: console - (beeware-venv) $ cd helloworld - (beeware-venv) $ briefcase dev + (venv) $ cd helloworld + (venv) $ briefcase dev [hello-world] Installing requirements... ... [helloworld] Starting in dev mode... =========================================================================== + Hello, World. + =========================================================================== .. group-tab:: Linux .. code-block:: console - (beeware-venv) $ cd helloworld - (beeware-venv) $ briefcase dev + (venv) $ cd helloworld + (venv) $ briefcase dev [hello-world] Installing requirements... ... [helloworld] Starting in dev mode... =========================================================================== + Hello, World. + =========================================================================== .. group-tab:: Windows .. code-block:: doscon - (beeware-venv) C:\...>cd helloworld - (beeware-venv) C:\...>briefcase dev + (venv) C:\...>cd helloworld + (venv) C:\...>briefcase dev [hello-world] Installing requirements... ... [helloworld] Starting in dev mode... =========================================================================== + Hello, World. + =========================================================================== + +The application will start in the terminal window. You should see a message +that says "Hello, World.". + + +Now you are ready to start building your CLI application! + + +Making it interesting +---------------------- + +Right now the ``app.py`` file contains a simple ``print`` statement that prints "Hello, World.". +Let's use ``argparse`` to make it more interesting. + +Replace the contents of ``src/helloworld/app.py`` with the following code: + +.. code-block:: python + + import argparse + + def main(): + parser = argparse.ArgumentParser( + prog="helloworld", + usage="%(prog)s [options] name", + description="A simple command line application.", + add_help=True + ) + parser.add_argument("name", help="Your name") + parser.add_argument("-v", "--version", action="version", version="%(prog)s 1.0") + args = parser.parse_args() + print(f'Hello, {args.name}!') + +Let’s look in detail at what has changed. + +1. We import the ``argparse`` module. +2. We define a new function called ``main`` that will contain the logic for our application. +3. We create an instance of ``argparse.ArgumentParser`` and pass in some arguments: + * ``prog``: The name of the program (in this case, ``helloworld``). + * ``usage``: The usage message that will be displayed when the user runs the program with the ``-h`` or ``--help`` flag. + * ``description``: A description of the program. + * ``add_help``: Whether to add a ``-h`` or ``--help`` flag to the program. +4. We add two arguments to the parser: + * ``name``: A positional argument that takes the user's name. + * ``version``: An optional argument that prints the version of the program. +5. We parse the arguments using ``parser.parse_args()``. +6. We print a message that greets the user by name. + + +Now that we've made these changes we can see what they look like by starting the application again. +As before, we'll use developer mode: + +.. tabs:: + + .. group-tab:: macOS + + .. code-block:: console + + (venv) $ briefcase dev + + .. group-tab:: Linux + + .. code-block:: console + + (venv) $ briefcase dev + + .. group-tab:: Windows + + .. code-block:: doscon + + (venv) C:\...>briefcase dev + +When you run the application, you should see the following output: + +.. code-block:: console + + [helloworld] Starting in dev mode... + =========================================================================== + usage: helloworld [options] name + helloworld: error: the following arguments are required: name + +To pass arguments to the application, we will use the the following briefcase command ``-- ARGS ...`` +Let's run the application again, this time with a name: + +.. tabs:: + + .. group-tab:: macOS + + .. code-block:: console + + (venv) $ briefcase dev -- John + + .. group-tab:: Linux + + .. code-block:: console + + (venv) $ briefcase dev -- John + + .. group-tab:: Windows + + .. code-block:: doscon + + (venv) C:\...>briefcase dev -- John + +Now you should see the following output: + +.. code-block:: console + + [helloworld] Starting in dev mode... + =========================================================================== + Hello, John! -The application will start in a new terminal window. You should see a message -that says "Hello, world!". +Congratulations! You've just built a simple command line application using Briefcase. +Next steps +---------- -Now you are ready to start building and packaging CLI apps! Have fun! +So far we have been running the application in developer mode. To distribute the application, you will need to package it for distribution. +For more information, see the `Tutorial 3 - Packaging for distribution documentation `_. From b3062042232a28789b2cb4c42893557a9f06a353 Mon Sep 17 00:00:00 2001 From: John Aziz Date: Thu, 15 Aug 2024 21:02:22 +0300 Subject: [PATCH 5/7] Update changes/1947.doc.rst Co-authored-by: Russell Keith-Magee --- changes/1947.doc.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/changes/1947.doc.rst b/changes/1947.doc.rst index a2e600f99..7a4b50b92 100644 --- a/changes/1947.doc.rst +++ b/changes/1947.doc.rst @@ -1 +1 @@ -Tutorial for building and packaging a Command Line Interface (CLI) application using Briefcase. +A tutorial for writing command-line apps was added. From 9c10ac31c27f6ac8cbca2d9c2bdc016875b8054d Mon Sep 17 00:00:00 2001 From: John Aziz Date: Thu, 15 Aug 2024 21:30:47 +0300 Subject: [PATCH 6/7] apply PR feedback --- docs/how-to/cli-apps.rst | 497 +++++---------------------------------- 1 file changed, 57 insertions(+), 440 deletions(-) diff --git a/docs/how-to/cli-apps.rst b/docs/how-to/cli-apps.rst index d040bce28..675c9f4a3 100644 --- a/docs/how-to/cli-apps.rst +++ b/docs/how-to/cli-apps.rst @@ -7,24 +7,14 @@ Overview In this tutorial, you'll learn how to build and package a Command Line Interface (CLI) application for distribution on Windows, macOS, and Linux using Briefcase. -Prerequisites -------------- +We're going to assume you've got an environment set up like you did in the `Hello, World! tutorial `_. -Before you start, you'll need to have the following installed on your computer: - -* Python 3.8 or later -* Briefcase -* A code editor - -For more information on installing Briefcase, see the `BeeWare Tutorial `_. Bootstrap a new project ------------------------ Let's start our first Briefcase CLI project! -We're going to use the Briefcase ``new`` command to create an application called **Hello World**. -The only thing that we need to change is the GUI framework. -Since we're building a CLI application, we'll select the **Console** GUI framework. +We're going to use the Briefcase ``new`` command to create an application called **Hello CLI**. Run the following from your command prompt: .. tabs:: @@ -35,144 +25,7 @@ Run the following from your command prompt: (venv) $ briefcase new Let's build a new Briefcase app! - -- Formal Name --------------------------------------------------------------- - - First, we need a formal name for your application. - - This is the name that will be displayed to humans whenever the name of the - application is displayed. It can have spaces and punctuation if you like, and - any capitalization will be used as you type it. - - Formal Name [Hello World]: Hello World - - - -- App Name ------------------------------------------------------------------ - - Next, we need a name that can serve as a machine-readable Python package name - for your application. - - This name must be PEP508-compliant - that means the name may only contain - letters, numbers, hyphens and underscores; it can't contain spaces or - punctuation, and it can't start with a hyphen or underscore. - - Based on your formal name, we suggest an app name of 'helloworld', but you can - use another name if you want. - - App Name [helloworld]: helloworld - - - -- Bundle Identifier --------------------------------------------------------- - - Now we need a bundle identifier for your application. - - App stores need to protect against having multiple applications with the same - name; the bundle identifier is the namespace they use to identify applications - that come from you. The bundle identifier is usually the domain name of your - company or project, in reverse order. - - For example, if you are writing an application for Example Corp, whose website - is example.com, your bundle would be 'com.example'. The bundle will be - combined with your application's machine readable name to form a complete - application identifier (e.g., com.example.helloworld). - - Bundle Identifier [com.example]: com.example - - - -- Project Name -------------------------------------------------------------- - - Briefcase can manage projects that contain multiple applications, so we need a - Project name. - - If you're only planning to have one application in this project, you can use - the formal name as the project name. - - Project Name [Hello World]: Hello World - - - -- Description --------------------------------------------------------------- - - Now, we need a one line description for your application. - - Description [My first application]: My first application - - - -- Author -------------------------------------------------------------------- - - Who do you want to be credited as the author of this application? - - This could be your own name, or the name of your company you work for. - - Author [Jane Developer]: Jane Developer - - - -- Author's Email ------------------------------------------------------------ - - What email address should people use to contact the developers of this - application? - - This might be your own email address, or a generic contact address you set up - specifically for this application. - - Author's Email [jane@example.com]: jane@example.com - - - -- Application URL ----------------------------------------------------------- - - What is the website URL for this application? - - If you don't have a website set up yet, you can put in a dummy URL. - - Application URL [https://example.com/helloworld]: https://example.com/helloworld - - - -- Project License ----------------------------------------------------------- - - What license do you want to use for this project's code? - - 1) BSD license - 2) MIT license - 3) Apache Software License - 4) GNU General Public License v2 (GPLv2) - 5) GNU General Public License v2 or later (GPLv2+) - 6) GNU General Public License v3 (GPLv3) - 7) GNU General Public License v3 or later (GPLv3+) - 8) Proprietary - 9) Other - - Project License [1]: 1 - - - -- GUI Framework ------------------------------------------------------------- - - What GUI toolkit do you want to use for this project? - - Additional GUI bootstraps are available; visit - https://beeware.org/bee/briefcase-bootstraps for a full list of known GUI - bootstraps. - - 1) Toga - 2) PySide6 (does not support iOS/Android/Web deployment) - 3) Pygame (does not support iOS/Android/Web deployment) - 4) Console (does not support iOS/Android/Web deployment) - 5) None - - GUI Framework [1]: 4 - - - ------------------------------------------------------------------------------ - - [helloworld] Generating a new application 'Hello World' - Using app template: https://github.com/beeware/briefcase-template, branch v0.1 - Template branch v0.1 not found; falling back to development template - Using existing template (sha b7a98f8ef56dce6dc4ec0afb211b475c71caea26, updated Mon Aug 12 07:18:17 2024) - - [helloworld] Generated new application 'Hello World' - - To run your application, type: - - $ cd helloworld - $ briefcase dev - + ... .. group-tab:: Linux @@ -180,143 +33,7 @@ Run the following from your command prompt: (venv) $ briefcase new Let's build a new Briefcase app! - -- Formal Name --------------------------------------------------------------- - - First, we need a formal name for your application. - - This is the name that will be displayed to humans whenever the name of the - application is displayed. It can have spaces and punctuation if you like, and - any capitalization will be used as you type it. - - Formal Name [Hello World]: Hello World - - - -- App Name ------------------------------------------------------------------ - - Next, we need a name that can serve as a machine-readable Python package name - for your application. - - This name must be PEP508-compliant - that means the name may only contain - letters, numbers, hyphens and underscores; it can't contain spaces or - punctuation, and it can't start with a hyphen or underscore. - - Based on your formal name, we suggest an app name of 'helloworld', but you can - use another name if you want. - - App Name [helloworld]: helloworld - - - -- Bundle Identifier --------------------------------------------------------- - - Now we need a bundle identifier for your application. - - App stores need to protect against having multiple applications with the same - name; the bundle identifier is the namespace they use to identify applications - that come from you. The bundle identifier is usually the domain name of your - company or project, in reverse order. - - For example, if you are writing an application for Example Corp, whose website - is example.com, your bundle would be 'com.example'. The bundle will be - combined with your application's machine readable name to form a complete - application identifier (e.g., com.example.helloworld). - - Bundle Identifier [com.example]: com.example - - - -- Project Name -------------------------------------------------------------- - - Briefcase can manage projects that contain multiple applications, so we need a - Project name. - - If you're only planning to have one application in this project, you can use - the formal name as the project name. - - Project Name [Hello World]: Hello World - - - -- Description --------------------------------------------------------------- - - Now, we need a one line description for your application. - - Description [My first application]: My first application - - - -- Author -------------------------------------------------------------------- - - Who do you want to be credited as the author of this application? - - This could be your own name, or the name of your company you work for. - - Author [Jane Developer]: Jane Developer - - - -- Author's Email ------------------------------------------------------------ - - What email address should people use to contact the developers of this - application? - - This might be your own email address, or a generic contact address you set up - specifically for this application. - - Author's Email [jane@example.com]: jane@example.com - - - -- Application URL ----------------------------------------------------------- - - What is the website URL for this application? - - If you don't have a website set up yet, you can put in a dummy URL. - - Application URL [https://example.com/helloworld]: https://example.com/helloworld - - - -- Project License ----------------------------------------------------------- - - What license do you want to use for this project's code? - - 1) BSD license - 2) MIT license - 3) Apache Software License - 4) GNU General Public License v2 (GPLv2) - 5) GNU General Public License v2 or later (GPLv2+) - 6) GNU General Public License v3 (GPLv3) - 7) GNU General Public License v3 or later (GPLv3+) - 8) Proprietary - 9) Other - - Project License [1]: 1 - - - -- GUI Framework ------------------------------------------------------------- - - What GUI toolkit do you want to use for this project? - - Additional GUI bootstraps are available; visit - https://beeware.org/bee/briefcase-bootstraps for a full list of known GUI - bootstraps. - - 1) Toga - 2) PySide6 (does not support iOS/Android/Web deployment) - 3) Pygame (does not support iOS/Android/Web deployment) - 4) Console (does not support iOS/Android/Web deployment) - 5) None - - GUI Framework [1]: 4 - - - ------------------------------------------------------------------------------ - - [helloworld] Generating a new application 'Hello World' - Using app template: https://github.com/beeware/briefcase-template, branch v0.1 - Template branch v0.1 not found; falling back to development template - Using existing template (sha b7a98f8ef56dce6dc4ec0afb211b475c71caea26, updated Mon Aug 12 07:18:17 2024) - - [helloworld] Generated new application 'Hello World' - - To run your application, type: - - $ cd helloworld - $ briefcase dev + ... .. group-tab:: Windows @@ -324,165 +41,66 @@ Run the following from your command prompt: (venv) C:\...>briefcase new Let's build a new Briefcase app! - -- Formal Name --------------------------------------------------------------- - - First, we need a formal name for your application. - - This is the name that will be displayed to humans whenever the name of the - application is displayed. It can have spaces and punctuation if you like, and - any capitalization will be used as you type it. - - Formal Name [Hello World]: Hello World - - - -- App Name ------------------------------------------------------------------ - - Next, we need a name that can serve as a machine-readable Python package name - for your application. - - This name must be PEP508-compliant - that means the name may only contain - letters, numbers, hyphens and underscores; it can't contain spaces or - punctuation, and it can't start with a hyphen or underscore. - - Based on your formal name, we suggest an app name of 'helloworld', but you can - use another name if you want. - - App Name [helloworld]: helloworld - - - -- Bundle Identifier --------------------------------------------------------- - - Now we need a bundle identifier for your application. - - App stores need to protect against having multiple applications with the same - name; the bundle identifier is the namespace they use to identify applications - that come from you. The bundle identifier is usually the domain name of your - company or project, in reverse order. - - For example, if you are writing an application for Example Corp, whose website - is example.com, your bundle would be 'com.example'. The bundle will be - combined with your application's machine readable name to form a complete - application identifier (e.g., com.example.helloworld). - - Bundle Identifier [com.example]: com.example - - - -- Project Name -------------------------------------------------------------- - - Briefcase can manage projects that contain multiple applications, so we need a - Project name. - - If you're only planning to have one application in this project, you can use - the formal name as the project name. - - Project Name [Hello World]: Hello World - - - -- Description --------------------------------------------------------------- - - Now, we need a one line description for your application. - - Description [My first application]: My first application - - - -- Author -------------------------------------------------------------------- - - Who do you want to be credited as the author of this application? - - This could be your own name, or the name of your company you work for. - - Author [Jane Developer]: Jane Developer - - - -- Author's Email ------------------------------------------------------------ - - What email address should people use to contact the developers of this - application? - - This might be your own email address, or a generic contact address you set up - specifically for this application. - - Author's Email [jane@example.com]: jane@example.com - - - -- Application URL ----------------------------------------------------------- - - What is the website URL for this application? - - If you don't have a website set up yet, you can put in a dummy URL. - - Application URL [https://example.com/helloworld]: https://example.com/helloworld - - - -- Project License ----------------------------------------------------------- - - What license do you want to use for this project's code? - - 1) BSD license - 2) MIT license - 3) Apache Software License - 4) GNU General Public License v2 (GPLv2) - 5) GNU General Public License v2 or later (GPLv2+) - 6) GNU General Public License v3 (GPLv3) - 7) GNU General Public License v3 or later (GPLv3+) - 8) Proprietary - 9) Other - - Project License [1]: 1 - + ... - -- GUI Framework ------------------------------------------------------------- +Briefcase will ask us for some details of our new application. For the +purposes of this tutorial, use the following: - What GUI toolkit do you want to use for this project? +* **Formal Name** - Accept the default value: ``Hello CLI``. - Additional GUI bootstraps are available; visit - https://beeware.org/bee/briefcase-bootstraps for a full list of known GUI - bootstraps. +* **App Name** - Accept the default value: ``hello-cli``. - 1) Toga - 2) PySide6 (does not support iOS/Android/Web deployment) - 3) Pygame (does not support iOS/Android/Web deployment) - 4) Console (does not support iOS/Android/Web deployment) - 5) None +* **Bundle** - If you own your own domain, enter that domain in reversed order. + (For example, if you own the domain "cupcakes.com", enter ``com.cupcakes`` + as the bundle). If you don't own your own domain, accept the default bundle + (``com.example``). - GUI Framework [1]: 4 +* **Project Name** - Accept the default value: ``Hello CLI``. +* **Description** - Accept the default value (or, if you want to be really + creative, come up with your own description!) - ------------------------------------------------------------------------------ +* **Author** - Enter your own name here. - [helloworld] Generating a new application 'Hello World' - Using app template: https://github.com/beeware/briefcase-template, branch v0.1 - Template branch v0.1 not found; falling back to development template - Using existing template (sha b7a98f8ef56dce6dc4ec0afb211b475c71caea26, updated Mon Aug 12 07:18:17 2024) +* **Author's email** - Enter your own email address. This will be used in the + configuration file, in help text, and anywhere that an email is required + when submitting the app to an app store. - [helloworld] Generated new application 'Hello World' +* **URL** - The URL of the landing page for your application. Again, if you own + your own domain, enter a URL at that domain (including the ``https://``). + Otherwise, just accept the default URL (``https://example.com/hello-cli``). + This URL doesn't need to actually exist (for now); it will only be used if + you publish your application to an app store. - To run your application, type: +* **License** - Accept the default license (BSD). This won't affect + anything about the operation of the tutorial, though - so if you have + particularly strong feelings about license choice, feel free to choose + another license. - $ cd helloworld - $ briefcase dev +* **GUI framework** - Enter ``4`` to select the **Console** GUI framework. This + will create a project that is designed to run in a terminal window. Briefcase will then generate a project skeleton for you to use. If you've followed this tutorial so far, and accepted the defaults as described, your file system should look something like:: - beeware-tutorial/ - ├── beeware-venv/ + tutorial/ + ├── venv/ │ └── ... - └── helloworld/ + └── hello-cli/ ├── CHANGELOG ├── LICENSE ├── pyproject.toml ├── README.rst ├── src/ - │ └── helloworld/ + │ └── hello_cli/ │ ├── app.py │ ├── __init__.py │ ├── __main__.py │ └── resources/ │ └── README └── tests/ - ├── helloworld.py + ├── hello_cli.py ├── __init__.py └── test_app.py @@ -499,7 +117,7 @@ application. Running the application in developer mode ------------------------------------------ -To run the application in developer (or ``dev``) mode, navigate to the project directory ``helloworld`` and +To run the application in developer (or ``dev``) mode, navigate to the project directory ``hello-cli`` and run the following command: .. tabs:: @@ -508,13 +126,13 @@ run the following command: .. code-block:: console - (venv) $ cd helloworld + (venv) $ cd hello-cli (venv) $ briefcase dev - [hello-world] Installing requirements... + [hello-cli] Installing requirements... ... - [helloworld] Starting in dev mode... + [hello-cli] Starting in dev mode... =========================================================================== Hello, World. =========================================================================== @@ -523,13 +141,13 @@ run the following command: .. code-block:: console - (venv) $ cd helloworld + (venv) $ cd hello-cli (venv) $ briefcase dev - [hello-world] Installing requirements... + [hello-cli] Installing requirements... ... - [helloworld] Starting in dev mode... + [hello-cli] Starting in dev mode... =========================================================================== Hello, World. =========================================================================== @@ -538,13 +156,13 @@ run the following command: .. code-block:: doscon - (venv) C:\...>cd helloworld + (venv) C:\...>cd hello-cli (venv) C:\...>briefcase dev - [hello-world] Installing requirements... + [hello-cli] Installing requirements... ... - [helloworld] Starting in dev mode... + [hello-cli] Starting in dev mode... =========================================================================== Hello, World. =========================================================================== @@ -552,7 +170,6 @@ run the following command: The application will start in the terminal window. You should see a message that says "Hello, World.". - Now you are ready to start building your CLI application! @@ -560,9 +177,9 @@ Making it interesting ---------------------- Right now the ``app.py`` file contains a simple ``print`` statement that prints "Hello, World.". -Let's use ``argparse`` to make it more interesting. +Let's use :any:`argparse` to make it more interesting. -Replace the contents of ``src/helloworld/app.py`` with the following code: +Replace the contents of ``src/hello_cli/app.py`` with the following code: .. code-block:: python @@ -570,7 +187,7 @@ Replace the contents of ``src/helloworld/app.py`` with the following code: def main(): parser = argparse.ArgumentParser( - prog="helloworld", + prog="hello-cli", usage="%(prog)s [options] name", description="A simple command line application.", add_help=True @@ -580,12 +197,12 @@ Replace the contents of ``src/helloworld/app.py`` with the following code: args = parser.parse_args() print(f'Hello, {args.name}!') -Let’s look in detail at what has changed. +Let's look in detail at what has changed. -1. We import the ``argparse`` module. +1. We import the :any:`argparse` module. 2. We define a new function called ``main`` that will contain the logic for our application. -3. We create an instance of ``argparse.ArgumentParser`` and pass in some arguments: - * ``prog``: The name of the program (in this case, ``helloworld``). +3. We create an instance of :any:`argparse.ArgumentParser` and pass in some arguments: + * ``prog``: The name of the program (in this case, ``hello-cli``). * ``usage``: The usage message that will be displayed when the user runs the program with the ``-h`` or ``--help`` flag. * ``description``: A description of the program. * ``add_help``: Whether to add a ``-h`` or ``--help`` flag to the program. @@ -623,10 +240,10 @@ When you run the application, you should see the following output: .. code-block:: console - [helloworld] Starting in dev mode... + [hello-cli] Starting in dev mode... =========================================================================== - usage: helloworld [options] name - helloworld: error: the following arguments are required: name + usage: hello-cli [options] name + hello-cli: error: the following arguments are required: name To pass arguments to the application, we will use the the following briefcase command ``-- ARGS ...`` Let's run the application again, this time with a name: @@ -655,7 +272,7 @@ Now you should see the following output: .. code-block:: console - [helloworld] Starting in dev mode... + [hello-cli] Starting in dev mode... =========================================================================== Hello, John! From 3f774252d1a97e552ef2c1a054fc8eb296443f85 Mon Sep 17 00:00:00 2001 From: John Aziz Date: Thu, 15 Aug 2024 22:14:57 +0300 Subject: [PATCH 7/7] wrap lines and move to tutorials --- docs/how-to/index.rst | 1 - docs/{how-to => tutorial}/cli-apps.rst | 43 +++++++++++++++----------- docs/tutorial/index.rst | 12 +++++++ 3 files changed, 37 insertions(+), 19 deletions(-) rename docs/{how-to => tutorial}/cli-apps.rst (87%) diff --git a/docs/how-to/index.rst b/docs/how-to/index.rst index ab6196323..a59af3298 100644 --- a/docs/how-to/index.rst +++ b/docs/how-to/index.rst @@ -20,4 +20,3 @@ stand alone. contribute-docs internal/index publishing/index - cli-apps diff --git a/docs/how-to/cli-apps.rst b/docs/tutorial/cli-apps.rst similarity index 87% rename from docs/how-to/cli-apps.rst rename to docs/tutorial/cli-apps.rst index 675c9f4a3..8fcfcddd0 100644 --- a/docs/how-to/cli-apps.rst +++ b/docs/tutorial/cli-apps.rst @@ -5,16 +5,18 @@ Building a CLI application with Briefcase Overview --------- -In this tutorial, you'll learn how to build and package a Command Line Interface (CLI) application for distribution on Windows, macOS, and Linux using Briefcase. +In this tutorial, you'll learn how to build and package a Command Line Interface +(CLI) application for distribution on Windows, macOS, and Linux using Briefcase. -We're going to assume you've got an environment set up like you did in the `Hello, World! tutorial `_. +We're going to assume you've got an environment set up like you did in the +`Hello, World! tutorial `_. Bootstrap a new project ------------------------ -Let's start our first Briefcase CLI project! -We're going to use the Briefcase ``new`` command to create an application called **Hello CLI**. +Let's start our first Briefcase CLI project! We're going to use the Briefcase +``new`` command to create an application called **Hello CLI**. Run the following from your command prompt: .. tabs:: @@ -117,8 +119,8 @@ application. Running the application in developer mode ------------------------------------------ -To run the application in developer (or ``dev``) mode, navigate to the project directory ``hello-cli`` and -run the following command: +To run the application in developer (or ``dev``) mode, navigate to the project +directory ``hello-cli`` and run the following command: .. tabs:: @@ -176,8 +178,8 @@ Now you are ready to start building your CLI application! Making it interesting ---------------------- -Right now the ``app.py`` file contains a simple ``print`` statement that prints "Hello, World.". -Let's use :any:`argparse` to make it more interesting. +Right now the ``app.py`` file contains a simple ``print`` statement that +prints "Hello, World.". Let's use :any:`argparse` to make it more interesting. Replace the contents of ``src/hello_cli/app.py`` with the following code: @@ -200,10 +202,12 @@ Replace the contents of ``src/hello_cli/app.py`` with the following code: Let's look in detail at what has changed. 1. We import the :any:`argparse` module. -2. We define a new function called ``main`` that will contain the logic for our application. -3. We create an instance of :any:`argparse.ArgumentParser` and pass in some arguments: +2. We define a new function called ``main`` that will contain the logic for + our application. +3. We create an instance of :any:`argparse.ArgumentParser` and pass in some arguments: * ``prog``: The name of the program (in this case, ``hello-cli``). - * ``usage``: The usage message that will be displayed when the user runs the program with the ``-h`` or ``--help`` flag. + * ``usage``: The usage message that will be displayed when the user runs + the program with the ``-h`` or ``--help`` flag. * ``description``: A description of the program. * ``add_help``: Whether to add a ``-h`` or ``--help`` flag to the program. 4. We add two arguments to the parser: @@ -213,8 +217,8 @@ Let's look in detail at what has changed. 6. We print a message that greets the user by name. -Now that we've made these changes we can see what they look like by starting the application again. -As before, we'll use developer mode: +Now that we've made these changes we can see what they look like by starting +the application again. As before, we'll use developer mode: .. tabs:: @@ -245,8 +249,8 @@ When you run the application, you should see the following output: usage: hello-cli [options] name hello-cli: error: the following arguments are required: name -To pass arguments to the application, we will use the the following briefcase command ``-- ARGS ...`` -Let's run the application again, this time with a name: +To pass arguments to the application, we will use the the following briefcase +command ``-- ARGS ...``. Let's run the application again, this time with a name: .. tabs:: @@ -276,10 +280,13 @@ Now you should see the following output: =========================================================================== Hello, John! -Congratulations! You've just built a simple command line application using Briefcase. +Congratulations! You've just built a simple command line application using +Briefcase. Next steps ---------- -So far we have been running the application in developer mode. To distribute the application, you will need to package it for distribution. -For more information, see the `Tutorial 3 - Packaging for distribution documentation `_. +So far we have been running the application in developer mode. +To distribute the application, you will need to package it for distribution. +For more information, see the +`Tutorial 3 - Packaging for distribution documentation `_. diff --git a/docs/tutorial/index.rst b/docs/tutorial/index.rst index c2dc9c86e..bc1fea4af 100644 --- a/docs/tutorial/index.rst +++ b/docs/tutorial/index.rst @@ -13,3 +13,15 @@ through the process of building a native Python application from scratch. Once you've done that tutorial, the :doc:`Briefcase How-To Guides <../how-to/index>` provide details on performing specific tasks with Briefcase. + +Additional Topics +----------------- + +If you're looking for a more advanced tutorials, +you might be interested in these topics: + +.. toctree:: + :maxdepth: 1 + :includehidden: + + cli-apps