Latest Threat Research:SANDWORM_MODE: Shai-Hulud-Style npm Worm Hijacks CI Workflows and Poisons AI Toolchains.Details →
beeware
Artifacts are distributable versions of a package. It typically includes the source code and metadata
Advanced tools
beeware - npm Package Compare versions
Sorry, the diff of this file is not supported yet
Sorry, the diff of this file is too big to display
Sorry, the diff of this file is too big to display
Sorry, the diff of this file is not supported yet
| ====================================== | ||
| Tutorial 4 - Updating your application | ||
| ====================================== | ||
| In the last tutorial, we packaged our application as a native application. If | ||
| you're dealing with a real-world app, that isn't going to be the end of the | ||
| story - you'll likely do some testing, discover problems, and need to make some | ||
| changes. Even if your application is perfect, you'll eventually want to publish | ||
| version 2 of your application with improvements. | ||
| So - how do you update your installed app when you make code changes? | ||
| Updating application code | ||
| ========================= | ||
| Our application current prints to the console when you press the button. | ||
| However, GUI applications shouldn't really use the console for output. They | ||
| need to use dialogs to communicate with users. | ||
| Let's add a dialog box to say hello, instead of writing to the console. | ||
| Modify the `say_hello` callback so it looks like this:: | ||
| def say_hello(self, widget): | ||
| self.main_window.info_dialog( | ||
| 'Hi there!', | ||
| "Hello, {}".format(self.name_input.value) | ||
| ) | ||
| This directs Toga to open a modal dialog box when the button is pressed. | ||
| If you run ``briefcase dev`` and press the button, you'll see the new dialog | ||
| box. However, if you run ``briefcase run``, the dialog box won't appear. | ||
| Why is this? Well, ``briefcase dev`` operates by running your code in place - | ||
| it tries to produce as realistic runtime environment for your code as possible, | ||
| but it doesn't provide or use any of the platform infrastructure for wrapping | ||
| your code as an application. Part of the process of packaging your app involves | ||
| copying your code *into* the application bundle - and at the moment, your | ||
| application still has the old code in it. | ||
| So - we need to tell briefcase to copy over the new version of the code. We | ||
| *could* do this by deleting the old platform directory and starting from | ||
| scratch. However, Briefcase provides an easier way - you can update the code | ||
| for your existing bundled application: | ||
| .. tabs:: | ||
| .. group-tab:: macOS | ||
| .. code-block:: bash | ||
| (beeware-venv) $ briefcase update | ||
| [helloworld] Updating application code... | ||
| Installing src/helloworld... | ||
| [helloworld] Application updated. | ||
| .. group-tab:: Linux | ||
| .. code-block:: bash | ||
| (beeware-venv) $ briefcase update | ||
| [helloworld] Updating application code... | ||
| Installing src/helloworld... | ||
| [helloworld] Application updated. | ||
| .. group-tab:: Windows | ||
| .. code-block:: doscon | ||
| (beeware-venv) C:\...>briefcase update | ||
| [helloworld] Updating application code... | ||
| Installing src/helloworld... | ||
| [helloworld] Application updated. | ||
| If Briefcase can't find the scaffolded template, it will automatically invoke | ||
| `create` to generate a fresh scaffold. | ||
| Now that we've updated the installer code, We can then run ``briefcase build`` | ||
| to re-compiled app, ``briefcase run`` to run the updated app, and ``briefcase | ||
| publish`` to repackage the application for distribution. | ||
| Updating dependencies and icons | ||
| =============================== | ||
| This only updates the application code, though - what if your dependencies have | ||
| changed, or you have new application resources, like a new splash screen or | ||
| application icon)? In this situation, the ``update`` command has some options | ||
| you can use: | ||
| * ``briefcase update -d`` (or ``briefcase update --update_dependencies``) | ||
| will re-install your the application dependecies. | ||
| * ``briefcase update -r`` (or ``briefcase update --update_resources``) | ||
| will re-install your application resources. | ||
| Update and run in one step | ||
| ========================== | ||
| If you're rapidly iterating code changes, you'll likely want to make a code | ||
| change, update the application, and immediately re-run your application. | ||
| Briefcase has a shortcut to support this usage pattern - the ``-u`` (or | ||
| ``--update``) option on the ``run`` command. | ||
| Let's try making another change. You may have noticed that if you don't type | ||
| a name in the text input box, the dialog will say "Hello, ". Let's modify the | ||
| ``say_hello`` function again to handle this edge case:: | ||
| def say_hello(self, widget): | ||
| if self.name_input.value: | ||
| name = self.name_input.value | ||
| else: | ||
| name = 'stranger' | ||
| self.main_window.info_dialog( | ||
| 'Hi there!', | ||
| "Hello, {}".format(name) | ||
| ) | ||
| Run your app in development mode (with ``briefcase dev``) to confirm that the | ||
| new logic works; then update, build and run the app with one command: | ||
| .. tabs:: | ||
| .. group-tab:: macOS | ||
| .. code-block:: bash | ||
| (beeware-venv) $ briefcase run -u | ||
| [helloworld] Updating application code... | ||
| Installing src/helloworld... | ||
| [helloworld] Application updated. | ||
| [helloworld] Starting app... | ||
| .. group-tab:: Linux | ||
| .. code-block:: bash | ||
| (beeware-venv) $ briefcase run -u | ||
| [helloworld] Updating application code... | ||
| Installing src/helloworld... | ||
| [helloworld] Application updated. | ||
| [helloworld] Building AppImage... | ||
| ... | ||
| [helloworld] Created linux/Hello World-x86_64-0.0.1.AppImage. | ||
| [helloworld] Starting app... | ||
| .. group-tab:: Windows | ||
| .. code-block:: doscon | ||
| (beeware-venv) C:\...>briefcase update | ||
| [helloworld] Updating application code... | ||
| Installing src/helloworld... | ||
| [helloworld] Application updated. | ||
| [helloworld] Starting app... | ||
| This should only be required if you're testing something about how your | ||
| application runs as a native binary, or hunting a bug that only manifests when | ||
| your application is in packaged form. For most day-to-day development, | ||
| ``briefcase dev`` will be a lot faster. | ||
| The package command also accepts the ``-u`` argument, so if you make a change | ||
| to your application code and want to repackage immediately, you can run | ||
| ``briefcase package -u``. | ||
| Next steps | ||
| ========== | ||
| We now have our application packaged for distribution on desktop platforms, | ||
| and we've been able to update the code in our application. | ||
| But what about mobile? In :doc:`Tutorial 5 <tutorial-5/index>`, we'll convert | ||
| out application into a mobile application, and deploy it onto a device | ||
| simulator, and onto a phone. |
| ====================================== | ||
| Tutorial 5 - Taking it mobile: Android | ||
| ====================================== | ||
| To deploy our applicaton to Android... | ||
| Next steps | ||
| ========== | ||
| We've now got an application on our phone! Is there anywhere other way to | ||
| deploy a BeeWare app? Turn to :doc:`Tutorial 6 <../tutorial-6>` to find | ||
| out... |
| .. raw:: html | ||
| <style> | ||
| .row {clear: both} | ||
| .column img {border: 1px solid black;} | ||
| @media only screen and (min-width: 1000px), | ||
| only screen and (min-width: 500px) and (max-width: 768px){ | ||
| .column { | ||
| padding-left: 5px; | ||
| padding-right: 5px; | ||
| float: left; | ||
| } | ||
| .column3 { | ||
| width: 33.3%; | ||
| } | ||
| .column2 { | ||
| width: 50%; | ||
| } | ||
| } | ||
| </style> | ||
| ============================= | ||
| Tutorial 5 - Taking it Mobile | ||
| ============================= | ||
| So far, we've been running and testing our application on the desktop. However, | ||
| BeeWare also supports mobile platforms - and the application we've written | ||
| can be deployed to your mobile device, too! | ||
| .. admonition:: iOS only... for now. | ||
| The BeeWare project *has* tooling for Android. Unfortunately, due to some | ||
| recent changes in the Android ecosystem, combined with some changes in Toga | ||
| itself, means that our Android tooling is currently broken. We're working | ||
| on it, and hope to have a solution in the very near future. | ||
| In the meantime, this tutorial only works on iOS. | ||
| .. rst-class:: clearfix row | ||
| .. rst-class:: column column2 | ||
| :doc:`iOS <iOS>` | ||
| ---------------- | ||
| iOS applications can only be compiled on macOS. You'll need `Xcode | ||
| <https://apps.apple.com/au/app/xcode/id497799835?mt=12>`__, which you should | ||
| have installed in :doc:`Tutorial 0 <../tutorial-0>`. | ||
| .. rst-class:: column column2 | ||
| :doc:`Android <android>` | ||
| ------------------------ | ||
| Android applications be compiled on macOS, Windows or Linux. You'll need to | ||
| download and install `Android Studio <https://developer.android.com/studio>`__. | ||
| .. toctree:: | ||
| :maxdepth: 1 | ||
| :hidden: | ||
| iOS | ||
| android |
| ================================== | ||
| Tutorial 5 - Taking it mobile: iOS | ||
| ================================== | ||
| Now, we're going to take our application, and deploy it as an iOS application. | ||
| The process of deploying an application to iOS is very similar to the process | ||
| for deploying as a desktop application. First, you run the ``create`` command - | ||
| but this time, we specify that we want to create an iOS application: | ||
| .. code-block:: bash | ||
| (beeware-venv) $ briefcase create iOS | ||
| [helloworld] Generating application template... | ||
| Using app template: https://github.com/beeware/briefcase-iOS-app-template.git | ||
| ... | ||
| [helloworld] Installing support package... | ||
| ... | ||
| [helloworld] Installing dependencies... | ||
| ... | ||
| [helloworld] Installing application code... | ||
| ... | ||
| [helloworld] Installing application resources... | ||
| ... | ||
| [helloworld] Application created. | ||
| Once this completes, we'll now have an ``iOS`` directory in your project. | ||
| This directory will contain a ``Hello World`` folder, which will contain | ||
| an Xcode project, as well as the support libraries and the application code | ||
| needed for the application. | ||
| You can then use Briefcase to compile the application compile your app, using | ||
| the ``build`` command. You'll be prompted to select a device to compile for; if | ||
| you've got simulators for multiple iOS versions installed, you may also be | ||
| asked which iOS version you want to target. The options you are shown may | ||
| differ from the options show in this output; for our purposes, it doesn't | ||
| matter which simulator you pick. | ||
| .. code-block:: bash | ||
| (beeware-venv) $ briefcase build iOS | ||
| Select iOS version: | ||
| 1) 10.3 | ||
| 2) 13.3 | ||
| > 2 | ||
| Select simulator device: | ||
| 1) iPad (7th generation) | ||
| 2) iPad Air (3rd generation) | ||
| 3) iPad Pro (11-inch) | ||
| 4) iPad Pro (12.9-inch) (3rd generation) | ||
| 5) iPad Pro (9.7-inch) | ||
| 6) iPhone 11 | ||
| 7) iPhone 11 Pro | ||
| 8) iPhone 11 Pro Max | ||
| 9) iPhone 8 | ||
| 10) iPhone 8 Plus | ||
| > 6 | ||
| Targeting an iPhone 11 running iOS 13.3 (device UDID 4768AA69-497B-4B37-BD0C-3961756C38AC) | ||
| [hello-world] Building XCode project... | ||
| ... | ||
| Build succeeded. | ||
| [hello-world] Built iOS/Hello World/build/Debug-iphonesimulator/Hello World.app | ||
| We're now ready to run our application. You could do this by running | ||
| ``briefcase run iOS``. If you run briefcase in that way, you'll be asked again | ||
| for the device you want to target. If you already know the devices that are | ||
| available, you can tell briefcase to use that simulator by providing a ``-d`` | ||
| (or ``--device``) option. Using the name of the device you selected when | ||
| you built your application, run:: | ||
| $ briefcase run iOS -d "iPhone 11" | ||
| If you have multiple iPhone 11 simulators, briefcase will pick the highest | ||
| iOS version; if you want to pick a particular iOS version, you tell it to use | ||
| that specific version:: | ||
| $ briefcase run iOS -d "iPhone 11::13.3" | ||
| Or, you can name a specific device UDID:: | ||
| $ briefcase run iOS -d 4768AA69-497B-4B37-BD0C-3961756C38AC | ||
| This will start the iOS simulator, install your app, and start it. You should | ||
| see the simulator start, and eventually open your iOS application: | ||
| .. image:: ../images/iOS/tutorial-5.png | ||
| :alt: Hello World Tutorial 5 window, on iOS | ||
| Next steps | ||
| ========== | ||
| We've now got an application on our phone! Is there anywhere other way to | ||
| deploy a BeeWare app? Turn to :doc:`Tutorial 6 <../tutorial-6>` to find | ||
| out... |
| ================================= | ||
| Tutorial 7 - Publishing your app! | ||
| ================================= | ||
| Once you've built an installer for your application, you're going to want to | ||
| share it with the world. Briefcase provides a command - ``publish`` to manage | ||
| this process, with a range of options for how to publish your application. | ||
| **Coming soon** | ||
| Next steps | ||
| ========== | ||
| This has been a taster for what you can do with the tools provided by the | ||
| BeeWare project. What you do from here is up to you! | ||
| Some places to go from here: | ||
| * Tutorials demonstrating `features of the Toga widget toolkit | ||
| <https://toga.readthedocs.io/en/latest/tutorial/index.html>`__. | ||
| * Details on the `options available when configuring your Briefcase project | ||
| <https://briefcase.readthedocs.io/en/latest/reference/index.html>`__. |
| Metadata-Version: 2.1 | ||
| Name: beeware | ||
| Version: 0.3.0.dev1 | ||
| Version: 0.3.0.dev2 | ||
| Summary: A metapackage to install the full BeeWare suite of tools. | ||
@@ -72,3 +72,3 @@ Home-page: http://beeware.org/ | ||
| .. _BeeWare suite: https://beeware.org | ||
| .. _BeeWare Tutorial: https://beeware.readthedocs.io/en/latest/tutorial/ | ||
| .. _BeeWare Tutorial: https://beeware.readthedocs.io/en/latest/ | ||
| .. _@pybeeware on Twitter: https://twitter.com/pybeeware | ||
@@ -75,0 +75,0 @@ .. _beeware/general: https://gitter.im/beeware/general |
@@ -1,2 +0,2 @@ | ||
| briefcase>=0.3.0.dev1 | ||
| toga>=0.3.0.dev15 | ||
| briefcase>=0.3.0.dev2 | ||
| toga>=0.3.0.dev16 |
@@ -25,10 +25,15 @@ AUTHORS | ||
| docs/tutorial/tutorial-3.rst | ||
| docs/tutorial/tutorial-5.rst | ||
| docs/tutorial/tutorial-4.rst | ||
| docs/tutorial/tutorial-6.rst | ||
| docs/tutorial/tutorial-7.rst | ||
| docs/tutorial/images/iOS/tutorial-5.png | ||
| docs/tutorial/images/linux/tutorial-1.png | ||
| docs/tutorial/images/linux/tutorial-2.png | ||
| docs/tutorial/images/macOS/tutorial-1.png | ||
| docs/tutorial/images/macOS/tutorial-2.png | ||
| docs/tutorial/images/windows/Thumbs.db | ||
| docs/tutorial/images/windows/tutorial-1.png | ||
| docs/tutorial/tutorial-4/android.rst | ||
| docs/tutorial/tutorial-4/iOS.rst | ||
| docs/tutorial/tutorial-4/index.rst | ||
| docs/tutorial/images/windows/tutorial-2.png | ||
| docs/tutorial/tutorial-5/android.rst | ||
| docs/tutorial/tutorial-5/iOS.rst | ||
| docs/tutorial/tutorial-5/index.rst |
+3
-2
@@ -50,4 +50,5 @@ ======= | ||
| tutorial/tutorial-3 | ||
| tutorial/tutorial-4/index | ||
| tutorial/tutorial-5 | ||
| tutorial/tutorial-4 | ||
| tutorial/tutorial-5/index | ||
| tutorial/tutorial-6 | ||
| tutorial/tutorial-7 |
@@ -74,2 +74,7 @@ =========================== | ||
| * **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``). | ||
| * **Project Name** - Accept the default value: ``Hello World``. | ||
@@ -82,9 +87,6 @@ | ||
| * **Author email** - Enter your own email address. This wil only appear in the | ||
| * **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. | ||
| * **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``). | ||
| * **URL** - The URL of the landing page for your application. Again, if you own | ||
@@ -182,3 +184,3 @@ your own domain, enter a URL at that domain (including the ``https://``). | ||
| .. image:: images/macOS/tutorial-1.png | ||
| :alt: Hello World Tutorial 1 window, on macOS | ||
| :alt: Hello World Tutorial 1 window, on macOS | ||
@@ -188,3 +190,3 @@ .. group-tab:: Linux | ||
| .. image:: images/linux/tutorial-1.png | ||
| :alt: Hello World Tutorial 1 window, on Linux | ||
| :alt: Hello World Tutorial 1 window, on Linux | ||
@@ -194,3 +196,3 @@ .. group-tab:: Windows | ||
| .. image:: images/windows/tutorial-1.png | ||
| :alt: Hello World Tutorial 1 window, on Windows | ||
| :alt: Hello World Tutorial 1 window, on Windows | ||
@@ -197,0 +199,0 @@ Press the close button (or select Quit from the application's menu), and you're |
@@ -16,7 +16,7 @@ ================================== | ||
| ``__init__.py`` marks the ``helloworld`` directory as an importable Python | ||
| package. It is an empty file; the very fact it exists tells the Python | ||
| interpreter that ``helloworld`` is a package. | ||
| module. It is an empty file; the very fact it exists tells the Python | ||
| interpreter that the ``helloworld`` directory defines a module. | ||
| ``__main__.py`` marks the ``helloworld`` package as a special kind of package - | ||
| an executable module. If you try to run the ``helloworld`` module, using | ||
| ``__main__.py`` marks the ``helloworld`` module as a special kind of module - | ||
| an executable module. If you try to run the ``helloworld`` module using | ||
| ``python -m helloworld``, the ``__main__.py`` file is where Python will start | ||
@@ -111,7 +111,117 @@ executing. The contents of ``__main__.py`` is relatively simple:: | ||
| That's the simplest possible Toga application. Let's put some of our own | ||
| content into the application, and make the app do something interesting. | ||
| Adding some content of our own | ||
| ============================== | ||
| **TODO** | ||
| Modify your ``HelloWorld`` class so it looks like this:: | ||
| class HelloWorld(toga.App): | ||
| def startup(self): | ||
| main_box = toga.Box(style=Pack(direction=COLUMN)) | ||
| name_label = toga.Label( | ||
| 'Your name: ', | ||
| style=Pack(padding=(0, 5)) | ||
| ) | ||
| self.name_input = toga.TextInput(style=Pack(flex=1)) | ||
| name_box = toga.Box(style=Pack(direction=ROW, padding=5)) | ||
| name_box.add(name_label) | ||
| name_box.add(self.name_input) | ||
| button = toga.Button( | ||
| 'Say Hello!', | ||
| on_press=self.say_hello, | ||
| style=Pack(padding=5) | ||
| ) | ||
| main_box.add(name_box) | ||
| main_box.add(button) | ||
| self.main_window = toga.MainWindow(title=self.name) | ||
| self.main_window.content = main_box | ||
| self.main_window.show() | ||
| def say_hello(self, widget): | ||
| print("Hello", self.name_input.value) | ||
| Let's look in detail at what has changed. | ||
| We're still creating a main box; however, we are now applying a style:: | ||
| main_box = toga.Box(style=Pack(direction=COLUMN)) | ||
| Toga's builtin layout system is called "Pack". It behaves a lot like CSS. You | ||
| define objects in a heirarchy - in HTML, the objects are ``<div>``, ``<span>``, | ||
| and other DOM elements; in Toga, they're widgets and boxes. You can then assign | ||
| styles to the individual elements. In this case, we're indicating that this is | ||
| a ``COLUMN`` box - that is, it is a box that will consume all the available | ||
| width, and will expand it's height as content is added, but it will try to be | ||
| as short as possible. | ||
| Next, we define a couple of widgets:: | ||
| name_label = toga.Label( | ||
| 'Your name: ', | ||
| style=Pack(padding=(0, 5)) | ||
| ) | ||
| self.name_input = toga.TextInput(style=Pack(flex=1)) | ||
| Here, we define a Label and a TextInput. Both widgets have styles associated | ||
| with them; the label will have 5px of padding on it's left and right, and no | ||
| padding on the top and bottom. The TextInput is marked as being flexible - that | ||
| is, it will absorb all available space in it's layout axis. | ||
| The TextInput is assigned as an instance variable of class. This gives us | ||
| easy access to the widget instance - something that we'll use in a moment. | ||
| Next, we define a box to hold these two widgets:: | ||
| name_box = toga.Box(style=Pack(direction=ROW, padding=5)) | ||
| name_box.add(name_label) | ||
| name_box.add(self.name_input) | ||
| The ``name_box`` is a box just like the main box; however, this time, it's a | ||
| ``ROW`` box. That means content will be added horizontally, and it will try | ||
| to make it's width as narrow as possible. The box also has some padding - 5px | ||
| on all sides. | ||
| Now we define a button:: | ||
| button = toga.Button( | ||
| 'Say Hello!', | ||
| on_press=self.say_hello, | ||
| style=Pack(padding=5) | ||
| ) | ||
| The button also has 5px of padding on all sides. We also define a *handler* - | ||
| a method to invoke when the button is pressed. | ||
| Then, we add the name box and the button to the main box:: | ||
| main_box.add(name_box) | ||
| main_box.add(button) | ||
| This completes our layout; the rest of the startup method is as it was | ||
| previously - defining a MainWindow, and assigning the main box as the window's | ||
| content:: | ||
| self.main_window = toga.MainWindow(title=self.name) | ||
| self.main_window.content = main_box | ||
| self.main_window.show() | ||
| The last thing we need to do is define the handler for the button. A handler | ||
| can be any method, generator or asynchronous co-routine; it accepts the widget | ||
| that generated the event as an argument, and will be invoked whenever the | ||
| button is pressed:: | ||
| def say_hello(self, widget): | ||
| print("Hello, ", self.name_input.value) | ||
| The body of the method is a simple print statement - however, it will | ||
| interrogate the current value of the name input, and use that content as the | ||
| text that is printed. | ||
| Now that we've made these changes we can see what they look like by starting | ||
@@ -159,3 +269,3 @@ the application again. As before, we'll use Developer mode: | ||
| .. image:: images/macOS/tutorial-2.png | ||
| :alt: Hello World Tutorial 2 window, on macOS | ||
| :alt: Hello World Tutorial 2 window, on macOS | ||
@@ -165,3 +275,3 @@ .. group-tab:: Linux | ||
| .. image:: images/linux/tutorial-2.png | ||
| :alt: Hello World Tutorial 2 window, on Linux | ||
| :alt: Hello World Tutorial 2 window, on Linux | ||
@@ -171,4 +281,7 @@ .. group-tab:: Windows | ||
| .. image:: images/windows/tutorial-2.png | ||
| :alt: Hello World Tutorial 2 window, on Windows | ||
| :alt: Hello World Tutorial 2 window, on Windows | ||
| If you enter a name in the text box, and press the GUI button, you should see | ||
| output appear in the console where you started the application. | ||
| Next steps | ||
@@ -175,0 +288,0 @@ ========== |
+194
-31
@@ -16,7 +16,9 @@ ======================================= | ||
| You can now use briefcase to build your application. Since this is the first | ||
| time we're packaging our application, we need to create some confguration files | ||
| and other scaffolding to support the packaging process. From the ``helloworld`` | ||
| directory, run: | ||
| Creating your application scaffold | ||
| ================================== | ||
| Since this is the first time we're packaging our application, we need to create | ||
| some confguration files and other scaffolding to support the packaging process. | ||
| From the ``helloworld`` directory, run: | ||
| .. tabs:: | ||
@@ -41,4 +43,12 @@ | ||
| ... | ||
| [helloworld] Application created. | ||
| [helloworld] Created macOS/Hello World | ||
| Once this step completes, the ``macOS`` folder will contain a ``Hello | ||
| World`` folder. That folder fill contain another folder named ``Hello | ||
| World.app``. This ``.app`` folder is a self contained macOS executable. If | ||
| you open the Finder, you can double click on the icon for thi folder to | ||
| start your application. If you send ``Hello World.app`` to a friend, they | ||
| will be able to do the same - double click on the app, and see your app | ||
| running. | ||
| .. group-tab:: Linux | ||
@@ -80,3 +90,3 @@ | ||
| $ apt-get update | ||
| $ apt-get install python3-dev python3-venv libgirepository1.0-dev libcairo2-dev libpango1.0-dev libwebkitgtk-3.0-0 gir1.2-webkit-3.0 | ||
| $ apt-get install python3-dev libgirepository1.0-dev libcairo2-dev libpango1.0-dev libwebkitgtk-3.0-0 gir1.2-webkit-3.0 | ||
| $ pip install beeware | ||
@@ -114,3 +124,3 @@ | ||
| ... | ||
| [helloworld] Application created. | ||
| [helloworld] Created linux/Hello World | ||
@@ -134,4 +144,54 @@ .. group-tab:: Windows | ||
| ... | ||
| [helloworld] Application created. | ||
| [helloworld] Created windows\Hello World | ||
| You've probably just seen pages of content go past in your terminal... so what | ||
| just happened? Briefcase has done the following: | ||
| 1. It **generated an application template**. There's a lot of files and | ||
| configurations required to build a native installer, above and beyond the | ||
| code of your actual application. This extra scaffolding is almost the same | ||
| for every application on the same platform, except for the name of the | ||
| actual application being constructed - so Briefcase provides an application | ||
| template for each platform it supports. This step rolls out the template, | ||
| subsituting the name of your application, bundle ID, and other properties of | ||
| your configuration file as required to support the platform you're building | ||
| on. | ||
| If you're not happy with the template provided by Briefcase, you can | ||
| provide your own. However, you probably don't want to do this until you've | ||
| got a bit more experience using Briefcase's default template. | ||
| 2. It **downloaded and installed a support package**. The packaging approach | ||
| taken by briefcase is best described as "the simplest thing that could | ||
| possibly work" - it ships a complete, isolated Python interpreter as part of | ||
| every application it builds. This is slightly space innefficient - if you | ||
| have 5 applications packaged with Briefcase, you'll have 5 copies of the | ||
| Python interpreter. However, this approach guarantees that every application | ||
| is completely independent, using a specific version of Python that is known | ||
| to work with the application. | ||
| Again, Briefcase provides a default support package for each platform; if | ||
| you want, you can provide your own support package, and have that package | ||
| included as part of the build process. You may want to do this if you have | ||
| particular options in the Python interpreter that you need to have enabled, | ||
| or if you want to strip modules out of the standard library that you don't | ||
| need at runtime. | ||
| Briefcase maintains a local cache of support packages, so once you've | ||
| downloaded a specific support package, that cached copy will be used on | ||
| future builds. | ||
| 3. It **installed application dependencies**. Your application can specify any | ||
| third-party modules that are required at runtime. These will be installed | ||
| using `pip` into your application's installer. | ||
| 4. It **Installed your application code**. Your application will have it's own | ||
| code and resources (e.g., images that are needed at runtime); these files | ||
| are copied into the installer. | ||
| 5. It **installed your resources needed by your application.** Lastly, it | ||
| adds any additional resources that are needed by the installer itself. | ||
| This includes things like icons that need to be attached to the final | ||
| application and splash screen images. | ||
| Once this completes, if you look in the project directory, you should now see a | ||
@@ -142,4 +202,9 @@ directory corresponding to your platform (``macOS``, ``linux``, or ``windows``) | ||
| You can then compile an installer, using the `build` command: | ||
| Building your application | ||
| ========================= | ||
| You can now compile your your application. This step performs any binary | ||
| compilation that is necessary for your application to be executable on your | ||
| target platform. | ||
| .. tabs:: | ||
@@ -153,12 +218,102 @@ | ||
| [helloworld] Built macOS/Hello World/Hello World.app | ||
| On ``macOS``, the ``build`` command doesn't need to do anything. A ``.app`` | ||
| folder is a layout convention of ``macOS`` itself; as long as the folder | ||
| has a ``.app`` extension, and adheres to some internal layout rules, and | ||
| provides some metadata in a known location, the folder will appear to the | ||
| operating system as an application. | ||
| .. group-tab:: Linux | ||
| .. code-block:: bash | ||
| (beeware-venv) $ briefcase build | ||
| [helloworld] Building AppImage... | ||
| ... | ||
| [helloworld] Built linux/Hello World-x86_64-0.0.1.AppImage | ||
| Once this step completes, the ``linux`` folder will contain a file named | ||
| ``Hello World-x86_64-0.0.1.AppImage``. This AppImage is an executable; | ||
| you can run it from the shell, or double click on it in your file explorer. | ||
| You can also give it to any other Linux user, and as long as they've got | ||
| a recent version of Linux, they should be able to run it in the same way. | ||
| .. group-tab:: Windows | ||
| .. code-block:: doscon | ||
| (beeware-venv) C:\...>briefcase build | ||
| [helloworld] Built windows\Hello World | ||
| On Windows, this step does nothing. The distributed "binary" on windows is | ||
| a folder with a known entry point; the installer (when it is eventually | ||
| created) will encode details on how to start the application, and install | ||
| a Start Menu item to invoke the application. | ||
| Running your app | ||
| ================ | ||
| You can now use Briefcase to run your application: | ||
| .. tabs:: | ||
| .. group-tab:: macOS | ||
| .. code-block:: bash | ||
| (beeware-venv) $ briefcase run | ||
| [helloworld] Starting app... | ||
| .. group-tab:: Linux | ||
| .. code-block:: bash | ||
| (beeware-venv) $ briefcase run | ||
| [helloworld] Starting app... | ||
| .. group-tab:: Windows | ||
| .. code-block:: doscon | ||
| (beeware-venv) C:\...>briefcase run | ||
| [helloworld] Starting app... | ||
| This will start your run your native application, using the output of the | ||
| `build` command. You may notice some small differences in the way your | ||
| application looks when it's running - for example, icons, and the name | ||
| displayed by the operating system, may be slightly different to those you saw | ||
| when running under developer mode. This is because you're using the actual | ||
| packaged application, not just running Python code. From the operating system's | ||
| perspective, you're now running "an app", not "a Python program", and that is | ||
| reflected in how the application appears. | ||
| Building your installer | ||
| ======================= | ||
| You can now package your application for distribution, using the `package` | ||
| command. The package command does any compilation that is required to convert | ||
| the scaffolded project into a final, distributable product. Depending on the | ||
| platform, this may involve compiling an installer, performing code signing, | ||
| or doing other pre-distribution tasks. | ||
| .. tabs:: | ||
| .. group-tab:: macOS | ||
| .. code-block:: bash | ||
| (beeware-venv) $ briefcase package --no-sign | ||
| [helloworld] Signing app... | ||
| ... | ||
| [helloworld] Building DMG... | ||
| ... | ||
| [helloworld] Created Hello World-0.0.1.dmg. | ||
| [helloworld] Created macOS/Hello World-0.0.1.dmg | ||
| Once this step completes, the ``macOS`` folder will contain an ``Hello | ||
| World.app``. This file is a self contained macOS executable. If you open | ||
| the Finder, you can double click on the icon to start the application. If | ||
| you send ``Hello World.app`` to a friend, they will be able to do the same | ||
| - double click on the app, and see your app running. | ||
| The ``macOS`` folder will contain a file named ``Hello World-0.0.1.dmg``. | ||
@@ -171,2 +326,13 @@ If you locate this file in the Finder, and double click on it's icon, | ||
| In this example, we've used the ``--no-sign`` option - that is, we've | ||
| decided to *not* sign our application. We've done this to keep the tutorial | ||
| simple. Setting up code signing identities is a little fiddly, and they're | ||
| only *absolutely* required if you're intending to distribute your | ||
| application to others. If we were publishing a real application, you would | ||
| leave off the ``--no-sign`` flag. | ||
| When you're ready to publish a real application, check out the Briefcase | ||
| How-To guide on `Setting up a macOS code signing identity | ||
| <https://briefcase.readthedocs.io/en/latest/how-to/code-signing/macOS.html>`__ | ||
| .. group-tab:: Linux | ||
@@ -176,13 +342,10 @@ | ||
| (beeware-venv) $ briefcase build | ||
| (beeware-venv) $ briefcase package | ||
| [helloworld] Building AppImage... | ||
| ... | ||
| [helloworld] Created Hello World-x86_64-0.0.1.AppImage. | ||
| [helloworld] Created linux/Hello World-x86_64-0.0.1.AppImage. | ||
| Once this step completes, the ``linux`` folder will contain a file named | ||
| ``Hello World-x86_64-0.0.1.AppImage``. This AppImage is an executable; | ||
| you can run it from the shell, or double click on it in your file explorer. | ||
| You can also give it to any other Linux user, and as long as they've got | ||
| a recent version of Linux, they should be able to run it in the same way. | ||
| On Linux, this step does nothing. The AppImage created by the build command | ||
| is a complete executable, requiring no additional processing. | ||
@@ -193,11 +356,11 @@ .. group-tab:: Windows | ||
| (beeware-venv) C:\...>briefcase build | ||
| (beeware-venv) C:\...>briefcase package | ||
| [helloworld] Building MSI... | ||
| ... | ||
| [helloworld] Created Hello_World-0.0.1.msi. | ||
| [helloworld] Created windows\Hello_World-0.0.1.msi | ||
| Once this step completes, the ``windows`` folder will contain a file named | ||
| ``Hello_World-0.0.1.msi``. If you double click on this installer, you | ||
| should go through a familiar Windows installation process. Once this | ||
| ``Hello_World-0.0.1.msi``. If you double click on this installer to run it, | ||
| you should go through a familiar Windows installation process. Once this | ||
| installation completes, there will be a "Hello World" entry in your start | ||
@@ -209,5 +372,5 @@ menu. | ||
| We now have our application packaged for distribution on desktop platforms. But | ||
| what about mobile? In :doc:`Tutorial 4 <tutorial-4/index>`, we'll convert | ||
| out application into a mobile application, and deploy it onto a device | ||
| simulator, and onto a phone. | ||
| We now have our application packaged for distribution on desktop platforms. | ||
| But what happens when we need to update the code in our application? How do | ||
| we get those updates into our packaged application? Turn to | ||
| :doc:`Tutorial 4 <./tutorial-4>` to find out... |
@@ -1,8 +0,7 @@ | ||
| ================================= | ||
| Tutorial 6 - Publishing your app! | ||
| ================================= | ||
| =============================== | ||
| Tutorial 6 - Put it on the web! | ||
| =============================== | ||
| Once you've built an installer for your application, you're going to want to | ||
| share it with the world. Briefcase provides a command - ``publish`` to manage | ||
| this process, with a range of options for how to publish your application. | ||
| In addition to supporting mobile platforms, the Toga widget toolkit supports | ||
| the web! Using the same API, you can deploy your application as a web site. | ||
@@ -14,10 +13,4 @@ **Coming soon** | ||
| This has been a taster for what you can do with the tools provided by the | ||
| BeeWare project. What you do from here is up to you! | ||
| Some places to go from here: | ||
| * Tutorials demonstrating `features of the Toga widget toolkit | ||
| <https://toga.readthedocs.io/en/latest/tutorial/index.html>`__. | ||
| * Details on the `options available when configuring your Briefcase project | ||
| <https://briefcase.readthedocs.io/en/latest/reference/index.html>`__. | ||
| We've now deployed our application on the web! We're now ready to share our | ||
| application with the rest of the world. In :doc:`Tutorial 7 <./tutorial-7>`, | ||
| we'll use Briefcase to publish our application so others can download it. |
+2
-2
| Metadata-Version: 2.1 | ||
| Name: beeware | ||
| Version: 0.3.0.dev1 | ||
| Version: 0.3.0.dev2 | ||
| Summary: A metapackage to install the full BeeWare suite of tools. | ||
@@ -72,3 +72,3 @@ Home-page: http://beeware.org/ | ||
| .. _BeeWare suite: https://beeware.org | ||
| .. _BeeWare Tutorial: https://beeware.readthedocs.io/en/latest/tutorial/ | ||
| .. _BeeWare Tutorial: https://beeware.readthedocs.io/en/latest/ | ||
| .. _@pybeeware on Twitter: https://twitter.com/pybeeware | ||
@@ -75,0 +75,0 @@ .. _beeware/general: https://gitter.im/beeware/general |
+1
-1
@@ -58,3 +58,3 @@ .. image:: https://beeware.org/static/images/brutus-270.png | ||
| .. _BeeWare suite: https://beeware.org | ||
| .. _BeeWare Tutorial: https://beeware.readthedocs.io/en/latest/tutorial/ | ||
| .. _BeeWare Tutorial: https://beeware.readthedocs.io/en/latest/ | ||
| .. _@pybeeware on Twitter: https://twitter.com/pybeeware | ||
@@ -61,0 +61,0 @@ .. _beeware/general: https://gitter.im/beeware/general |
+3
-3
| [metadata] | ||
| name = beeware | ||
| version = 0.3.0.dev1 | ||
| version = 0.3.0.dev2 | ||
| url = http://beeware.org/ | ||
@@ -38,4 +38,4 @@ project_urls = | ||
| install_requires = | ||
| briefcase >= 0.3.0.dev1 | ||
| toga >= 0.3.0.dev15 | ||
| briefcase >= 0.3.0.dev2 | ||
| toga >= 0.3.0.dev16 | ||
@@ -42,0 +42,0 @@ [bdist_wheel] |
| ====================================== | ||
| Tutorial 4 - Taking it mobile: Android | ||
| ====================================== | ||
| To deploy our applicaton to Android... | ||
| Next steps | ||
| ========== | ||
| We've now got an application on our phone! Is there anywhere other way to | ||
| deploy a BeeWare app? Turn to :doc:`Tutorial 5 <../tutorial-5>` to find | ||
| out... |
| .. raw:: html | ||
| <style> | ||
| .row {clear: both} | ||
| .column img {border: 1px solid black;} | ||
| @media only screen and (min-width: 1000px), | ||
| only screen and (min-width: 500px) and (max-width: 768px){ | ||
| .column { | ||
| padding-left: 5px; | ||
| padding-right: 5px; | ||
| float: left; | ||
| } | ||
| .column3 { | ||
| width: 33.3%; | ||
| } | ||
| .column2 { | ||
| width: 50%; | ||
| } | ||
| } | ||
| </style> | ||
| ============================= | ||
| Tutorial 4 - Taking it Mobile | ||
| ============================= | ||
| So far, we've been running and testing our application on the desktop. However, | ||
| BeeWare also supports mobile platforms - and the application we've written | ||
| can be deployed to your mobile device, too! | ||
| .. admonition:: iOS only... for now. | ||
| The BeeWare project *has* tooling for Android. Unfortunately, due to some | ||
| recent changes in the Android ecosystem, combined with some changes in Toga | ||
| itself, means that our Android tooling is currently broken. We're working | ||
| on it, and hope to have a solution in the very near future. | ||
| In the meantime, this tutorial only works on iOS. | ||
| .. rst-class:: clearfix row | ||
| .. rst-class:: column column2 | ||
| :doc:`iOS <iOS>` | ||
| ---------------- | ||
| iOS applications can only be compiled on macOS. You'll need `Xcode | ||
| <https://apps.apple.com/au/app/xcode/id497799835?mt=12>`__, which you should | ||
| have installed in :doc:`Tutorial 0 <../tutorial-0>`. | ||
| .. rst-class:: column column2 | ||
| :doc:`Android <android>` | ||
| ------------------------ | ||
| Android applications be compiled on macOS, Windows or Linux. You'll need to | ||
| download and install `Android Studio <https://developer.android.com/studio>`__. | ||
| .. toctree:: | ||
| :maxdepth: 1 | ||
| :hidden: | ||
| iOS | ||
| android |
| ================================== | ||
| Tutorial 4 - Taking it mobile: iOS | ||
| ================================== | ||
| Now, we're going to take our application, and deploy it as an iOS application. | ||
| The process of deploying an application to iOS is very similar to the process | ||
| for deploying as a desktop application. First, you run the ``create`` command - | ||
| but this time, we specify that we want to create an iOS application: | ||
| .. code-block:: bash | ||
| (beeware-venv) $ briefcase create iOS | ||
| [helloworld] Generating application template... | ||
| Using app template: https://github.com/beeware/briefcase-iOS-app-template.git | ||
| ... | ||
| [helloworld] Installing support package... | ||
| ... | ||
| [helloworld] Installing dependencies... | ||
| ... | ||
| [helloworld] Installing application code... | ||
| ... | ||
| [helloworld] Installing application resources... | ||
| ... | ||
| [helloworld] Application created. | ||
| Once this completes, we'll now have an ``iOS`` directory in your project. | ||
| This directory will contain a ``Hello World`` folder, which will contain | ||
| an Xcode project, as well as the support libraries and the application code | ||
| needed for the application. | ||
| You can then use briefcase to compile the application compile an installer, | ||
| using the ``build`` command: | ||
| .. code-block:: bash | ||
| (beeware-venv) $ briefcase build iOS | ||
| [hello-world] Generating application template... | ||
| Using app template: https://github.com/beeware/briefcase-iOS-Xcode-template.git | ||
| [helloworld] Building DMG... | ||
| ... | ||
| [helloworld] Created Hello World-0.0.1.dmg. | ||
| Once this step completes, the ``macOS`` folder will contain an ``Hello | ||
| World.app``. This file is a self contained macOS executable. If you open | ||
| the Finder, you can double click on the icon to start the application. If | ||
| you send ``Hello World.app`` to a friend, they will be able to do the same | ||
| - double click on the app, and see your app running. | ||
| The ``macOS`` folder will contain a file named ``Hello World-0.0.1.dmg``. | ||
| If you locate this file in the Finder, and double click on it's icon, | ||
| you'll mount the DMG, giving you a copy of the Hello World app, and a | ||
| link to your Applications folder for easy installation. Drag the app file | ||
| into Application, and you've installed your application. Send the DMG file | ||
| to a friend, and they should be able to do the same. | ||
| Next steps | ||
| ========== | ||
| We've now got an application on our phone! Is there anywhere other way to | ||
| deploy a BeeWare app? Turn to :doc:`Tutorial 5 <../tutorial-5>` to find | ||
| out... |
| =============================== | ||
| Tutorial 5 - Put it on the web! | ||
| =============================== | ||
| In addition to supporting mobile platforms, the Toga widget toolkit supports | ||
| the web! Using the same API, you can deploy your application as a web site. | ||
| **Coming soon** | ||
| Next steps | ||
| ========== | ||
| We've now deployed our application on the web! We're now ready to share our | ||
| application with the rest of the world. In :doc:`Tutorial 6 <./tutorial-6>`, | ||
| we'll use Briefcase to publish our application so others can download it. |
Alert delta unavailable
Currently unable to show alert delta for PyPI packages.
Improved metrics
- Total package byte prevSize
911385
102.07%- Number of package files
39
14.71%