Docs: Add Building a CLI Application Tutorial #1958
Conversation
john0isaac
changed the title
There was a problem hiding this comment.
Thanks - this is a good first draft. The underlying example is a good target, and you've covered most of the major points that we need to hit.
The major issue that needs to be resolved is whether this should be a tutorial or a HOWTO. I suspect that you've landed on writing this as a HOWTO because of the existing language in the tutorials section leading to the HOWTO page - but that should be read more of an indication that we need to lay a path to somewhere, and in the absence of more tutorial pages, HOWTOs are the next step.
We use diataxis as a guide for how we structure our docs. In that framework, a tutorial is a complete step-by-step guide, coming from a clean starting point (or at least a known starting point). It's a learning guide, aiding knowledge acquisition. A HOWTO guide, on the other hand, is focused on achieving a specific task. It can assume some background knowledge about how the tool works. It's a more practical guide to completing a specific task. Generally, a HOWTO will be a lot shorter, as it will point out the major steps and landmarks, but won't hold your hand the whole way.
A HOWTO for building a CLI would be really short. It wouldn't need to be much more than a bunch of bullet points highlighting the major differences between a GUI and CLI app built with Briefcase.
Therefore, I think I'd lean towards the tutorial in this case. If you've already got a good handle on how Briefcase works, then the process of building a CLI tool shouldn't be that unexpected. The only thing that you might not already know about is the handling of command line arguments, and how the app will appear on the command line.
However, even in a tutorial, we can lean heavily on assuming the user has done the existing BeeWare tutorial. I'd suggest structuring this document as the first of a collection of "additional tutorial topics" - similar to how the end of the BeeWare tutorial is structured. Those tutorials assume you've already done the main tutorial (and explicitly say as much), but build on that knowledge with a new example.
In that context, you don't need to be explicit about all the initial setup steps - you should definitely summarise the main steps (create a fresh venv, install Briefcase, create an app with a name of hello-cli, select Console as the GUI framework); but that's more by way of refreshing the user's memory about the steps required, not explicit handholding. You can defer to "as you did in step X of the beeware tutorial"-style instructions, rather than giving full explicit console output of every step. You only need to be explicit when something new is happening - for example, in the packaging step, showing how the installed app would be executed.
I've left a few other comments inline; if you need any clarification on any of this, I'm happy to fill in the gaps.
|
Just to confirm - is this ready for another review, or are you expecting to make more updates? |
|
Not yet, the packaging steps are still not done, when it's done I will re-request your review. |
john0isaac
force-pushed
the
docs-how-to-cli
branch
3 times, most recently
from
fc20e15 to
a0b6819
Compare
john0isaac
force-pushed
the
docs-how-to-cli
branch
from
a0b6819 to
4af5222
Compare
|
@freakboy3742 Sorry for the delay I finally was able to test this on Linux and Windows. I have a question thought why is the size of the application on macOS +200MB this is huge for a program that only says Hello + Your Name 😆 I think it would be great if we had a way to make it slimmer. Thank you for your patience! |
There was a problem hiding this comment.
Thanks for these updates; however, I think we've had a miscommunication over my previous review notes. In my last review I said:
In that context, you don't need to be explicit about all the initial setup steps - you should definitely summarise the main steps (create a fresh venv, install Briefcase, create an app with a name of hello-cli, select Console as the GUI framework); but that's more by way of refreshing the user's memory about the steps required, not explicit handholding. You can defer to "as you did in step X of the beeware tutorial"-style instructions, rather than giving full explicit console output of every step. You only need to be explicit when something new is happening - for example, in the packaging step, showing how the installed app would be executed.
The bulk of what you've got here is essentially a duplicate of what is contained in the initial BeeWare tutorial. The first ~180 lines of this content could essentially be replaced with "Start a new app as you did in the Beeware tutorial, but select 'console app' rather than 'Toga' as your GUI framework". Similarly for L293 onwards - that can be replace with "You can now build and publish your app as you did in the Beeware tutorial" (ok - maybe a few more words than that.. but not that many).
The thing this tutorial can offer is:
- Explicitly pointing out what is different when you pick "console app";
- Pointing out the
console_appflag in pyproject.toml as the major thing that is different - Highlighting how command line arguments are handled by
briefcase devandbriefcase run - Pointing out notable differences in how console apps operate (e.g., outputting to console, rather than to the system log as GUI apps do)
- Pointing out notable differences in packaging - for example, that console apps need to be distributed as
.pkgbundles on macOS.
It should probably also point out that although you're using argparse in the example code, that's not required by Briefcase. You could use bare sys.argv handling, click, or any other library you wanted - argparse is just a convenient library that is built into the standard library.
I have a question thought why is the size of the application on macOS +200MB this is huge for a program that only says Hello + Your Name 😆 I think it would be great if we had a way to make it slimmer.
AFAICT, the app isn't 200MB - it's "only" (cough) 89MB. The full build folder is 200MB, but that includes a second copy of the Python framework.
However, that's still 89MB. So where is that space being used?
About 10MB is libPython; you can't avoid that. A bare bones app with no dependencies adds around 500K - most of which is the app's icon. You can't avoid that either.
The rest is almost all in the standard library. There's 20MB in the Python test folder, including things such as decimal and compression module test data - but there are also some useful utilities in that folder. There's 21MB in the lib-dynload folder, providing binary modules for the full standard library. There's also all the binary libraries to support Tkinter, OpenSSL, and NCurses.
However, there's no way for Briefcase to know for sure what your app uses. So - we have to include everything by default.
The good news is that if you know you're not using part of the standard library - you can delete it. Briefcase provides a cleanup_paths property that allows you to specify file patterns that you want to be deleted from your packaged app - so if you know you're not going to be using anything in the tests folder or bz2 compression, you can purge those from your app as part of the app release process:
cleanup_paths = [
"My App.app/Contents/Frameworks/Python.framework/Versions/*/lib/python3.*/test",
"My App.app/Contents/Frameworks/Python.framework/Versions/*/lib/python3.*/lib-dynload/_bz2.*",
]
And your app is now 66MB instead of 89MB. Rinse and repeat for anything else you don't need, and you should be able to get a bare bones app down to ~15MB.
FWIW - this would also be worth an explanatory document - either a HOWTO or a tutorial.
|
I knew you wanted to highlight some points in this one but didn't know what, that's why I went through and completed it with all the steps based on your other tutorial. Thanks for the explanation I will try to work on it this weekend it's on of my new year's goals :D Re size |
I'm not sure what you're saying here - the current Briefcase installer is less than 100MB - it's 89MB. As I said, the 200MB number you're seeing is the full build directory, which includes things that aren't in the distributed final product. |
|
I don't know where did i get this Sorry for that. To clarify this for anyone seeing this in the future. The current size for the console application installers are:
It's really cool! |
No worries.
To be clear, the 74MB can be made substantially smaller if you know what parts of the Python standard library you're not using. The Linux installer doesn't include any of Python - it's relying on the DEB system package. The Windows installer is also missing a lot of pieces - for example, it doesn't have any support for Tkinter, whereas the macOS installer does. |
fix #1947
PR Checklist: