We are now almost ready to land! Here is the last part of this long suit of blog posts about Quickly.
Packaging your project
It's the last, but not the least issue when you are writing your software: once your application is functional, you surely want to enable other users to install it. Well, you can give it into a tar.gz and run from a trunk, but what about creating a nice package, containing all dependency information for you? Let's see how to achieve this automagically.
Build your project locally
First good idea (even if it's not compulsory) is to try to build it locally. Just issue this command for that:
$ quickly package
It will creates a debian binary package (deb) from your project. The first time, quickly package creates the packaging too. Before running the package command you can edit the Icon and Category entry of your <project_name>*.desktop.in file.
Note that if you didn't run quickly release, quickly share or quickly change-lp-project you may miss the name, email and some other entries in setup.py file. So, you won't have those metada in your package. You can edit them if you don't want to use any of these commands afterwards. Those changes are not mandatory at all for testing purpose.
Quickly package will retrieve all dependencies on your project for you and then build the package locally. You will get a .deb file in the upper folder of your project directory and can install it for testing purpose.
In addition to giving a lot of hints to setup.py, default ubuntu-project enables you to have some automation to specify a data directory that works both from trunk or specified location. If you know a little about python packaging, you can build and install your own local version with python setup.py build -homedir </usr/local/...> (or -rootdir) and this (and any other path) is taken into account at build time.
Debian package description is taken from setup.py where you can change them by editing
description='UI for managing …', long_description='Here a longer description',
Stop! Before packaging and making it available to whole world, you really should license your project
Hum, I know what you think "licensing is boring, I never know what I must do and ship in my package" (how many upstreams never shipped the GPL vanilla file in their tarballs). That's an old story with Quickly. Just launch
$ quickly license
to create a GPL-3 project, shipping all desirable headers to all files as well as the right LICENSE and AUTHORS file.
It will warn you that you should modify "# Copyright (C) YYYY <Your Name> <Your E-mail>" in Copyright file if you "$ launch quickly license" the first time before launching "$ quickly share" or "$ quickly release" (in the other case, all files are licensed automatically with GPL-3 and name/email are taken from Launchpad). So, edit it manually in the former case.
But well, you are going to tell me that you don't want to license under GPL-V3? Shell-completion will reveal your all supported licenses by Quickly:
$ quickly license [Tab][Tab] BSD GPL-2 GPL-3 LGPL-2 LGPL-3
Quickly always ship the right files and put the header in an according form. Be aware that you can relicensed your project with another license once if you have already licensed it. It will just override your previous license and clean all files accordingly.
If you want to put your own Quickly unsupported License, put your own license text in Copyright file between the tags ### BEGIN AUTOMATIC LICENCE GENERATION and ### END AUTOMATIC LICENCE GENERATION. Then "$ quickly license" does the trick and will add your personal license to every files.
Adding new licenses is really easy, if you think that another license ought to be included in ubuntu-project, do not hesitate to open a bug against Quickly.
So, no more mess when licensing your project. It also updates setup.py and next "$ quickly package" (or "$ quickly release/share) will update the Debian packaging too.
I guess that your are now ready to enable the world to discover an early beta of your application without publishing this version (or intermediate release) as stable one?
Launchpad ppa are great for that and avoid releasing an official version. It's as easy as:
$ quickly share
It updates your PPA with the the latest saved project changes.
So, before running "$ quickly release", you should: create your account on http://launchpad.net and add a PPA to your launchpad account. Quickly will check that you have an ssh and gpg key. We hope to be able to add advanced support to that in later release.
The first time the command is issued (and that "$ quickly release" was not issued before), it will ask to open a webpage for identifying your Launchpad account so that you can bind Quickly with Launchpad. This is done once by machine (that is to say, all projects on a host share the same launchpad account).
Then name, email and version setup.py will be automatically changed. Version will be <current_release~publicX> where X is incremented at each "$ quickly share" execution before a new release is done.
If "$ Quickly package" was not issued before, it will run it. Same for licensing, updating name, email, license to every part of your project. No more unlicensed file.
Then, it pushes a source package to your ppa. Just wait for Soyuz (in Launchpad) builds your package and you can make your friend discover your project!
Well well well, when you have tested throughly your package, it's time to release it, isn't?
$ quickly release <release_number> notes about changes
<version> and <description of the release> are optional. Let's see first without them:
$ quickly release
This command first ask for a Launchpad account if you didn't run "$ quickly share" before in any other project. Then, it will propose you to bind your project with an existing Launchpad project, search it with some keywords and then enter the number corresponding to your project. That will be done once per project and finally, if you didn't packaged it previously (neither with quickly package, nor with quickly share), it will do it (same with license issue).
If you didn't put any release version, Quickly will then release it with current number in setup.py (0.1 when you create your project and then, incremented by +0.1 each time the command is issued). If you previously used "$ quickly shared" publicX will be dropped to release <current_release> version (as <current_release>~publicX is less than <current_release> in packaging world).
If you feel the current version is an "0.8" release (without respecting the +0.1 order), your can launch:
$ quickly release 0.8
to enforce this value.
Then, Quickly will save the current state (with the optional notes about changes commit message), add a tag to it and bind your bzr branch with the corresponding project in Launchpad (pull and push). Finally, it will create the source package and upload it to your ppa before bumping the revision (+0.1), ready for next changes.
Of course, some setup.py values are updated too like setting project url, pushing it to debian/control, and so on.
And that's it, you have now a new rocking release, updated with all licensing and packaging issues done for you. Enjoy!
Change Launchpad project
If you want to unbind and bind again your project with another Launchpad one, you can issue this simple command:
$ quickly change-lp-project
It enables you to set or change the Launchpad project binded with the current ubuntu project.
Ok, that's it for the tour, I hope you enjoyed it and it gave you some desire to use Quickly for your own project, develop new templates, and give new ideas!
In a nutshell, in two commands:
$ quickly create ubuntu-project myproject $ quickly release
you can have a release of your project, licensed, packaged, under proper revision control. Easy and quick isn't?
Get Things Done Right and... Quickly!
More info on Quickly:
- project page: https://launchpad.net/quickly
- Quickly wiki page (will be updated soon with this tour content): https://wiki.ubuntu.com/Quickly
- Karmic Blueprint for Quickly: https://blueprints.launchpad.net/ubuntu/+spec/desktop-karmic-quickly
- Quickly IRC talk: https://wiki.ubuntu.com/MeetingLogs/devweek0909/QuicklyFun
- Previous part of the tour:
- Part 1: introduction
- Part 2: general concepts, core and templates
- Part 3: getting help
- Part 4: shell-completion
- Part 5: miscellaneous core stuff
- Part 6: creating templates
- Part 7: ubuntu-project template presentation
- Part 8: ubuntu-project template code editing