ClassNotes

Install Quickly

Let's start with installing.

While it's installing, I can provide some background

Quickly works with Karmic only.

Note that this may take a while to download everything if you don't have it installed already, as it brings in lots of developer tools, like Glade, and dpkg-dev.

Open a terminal and type:
sudo apt-get install quickly python-desktopcouch-records

After Quickly is installed, close the terminal and open a new one so that statement completion works.

What is Quicky?

Quickly has two parts:

  1. A command line parser that parses user input and directs commands to "templates".
  2. Templates are sets of commands and code generators that are designed to work together in an end to end fashion to help developers write a certain kind of application.

  3. There is only on Quickly template so far, and it's for a Ubuntu project.
  4. Quickly is in on version 0.2 in Karmic universe repository.
  5. Quickly templates should make programming easy and fun.

Who Developed Quickly?

The lead developer is didrocks

I did a lot of the ubuntu application that gets built and got some of the commands started

eeejay helped a lot with the ubuntu applications

ken-vandine put a lot into quickly, as did lool and others

join as on #quickly to ask questions, etc...

What's in the Ubuntu Project Template?

The Ubuntu Project template is designed to make it easy and fun to write an application intended to run on Ubuntu. It uses the following components:

  1. Python for the language
  2. pygtk for the UI framework
  3. Glade for the UI editor
  4. Gedit for the code editor
  5. bzr for version control
  6. Launchpad for code hosting
  7. desktopcouch for storage/database
  8. A terminal for the interface ... yes Quickly is a CL tool

The application can be extended to run on other systems, and use different tools, etc... There is nothing stopping you from doing that. However, if you stray off the chosen path, some of the commands may no longer work for you.

Also note, there is no quickly runtime or base class library. Using the Ubuntu Project won't bring in any dependencies on Quickly itself.

Quickly End To End

Probably the best way to see what Quickly is all about is to follow along as I build and release an app. We'll use the following commands to build the app:

  • $quickly create ubuntu-project searchy
  • $quickly glade
  • $quickly edit
  • $quickly run
  • $quickly package
  • $quickly release

We'll build an app that directs a search to http://linuxsearch.org (kirkland's custom search page). If we have time we'll create some preferences, and perhaps dive a bit into desktopcouch by saving history as well.

Create an app

Get started by creating an application from the ubuntu-project template.

I'm calling it "searchy".

Note that I've already claimed "searchy" on launchpad, so you'll need to choose a different name if you want to try to release your code.

So when I say "searchy" or "Searchy" later, just replace that with the name that you choose.

Also note that there is currently a limitation in Quickly that means that your application has to have only a one word name. We hope to fix this in a future release.

Here's the command to create the application: $quickly create ubuntu-project searchy

This causes a bunch of info to be dumped to the command line, but ends with the application being run.

Note that it's called "Searchy", but otherwise, it's just a stock application.

If you've closed the application and want to run it again, change to the searchy directory, and use:

$quickly run

Edit the Glade file

The UI I am envisioning is just a text box, and when I hit enter, it does the search. So I need to edit the default UI.

Glade is the program that I use to edit the UI.

If I just run Glade from the Applicatons menu IT WON'T WORK.

Quickly needs to pass in some command line args for Glade to work. So:

First, go to the directory that quickly created for the app: $cd searchy

then: $quickly glade

This will make Glade open.

Edit the UI

Under the Projects window, switch to SearchyWindow. This is the main window for your application.

Delete the image and the label (image1 and label1) to clear out space in the UI.

In the pallette, under Control and Display, click on the Text Entry control. Then click on the space where the label used to be.

Also, turn off the size request for the window.

Do this by selecting searchy_window in the inspector.

Then click on the Common tab, and unselect Width Request and Height Request checkboxes.

Edit a Signal Handler

We want a search to kick off when the user hits enter in the text entry field. To make this happen, we'll tell the edit field to send the do_search signal.

In Glade, click on the text entry (entry1) to select it.

Switch to the Signals tab.

Click in the Hanlder column in the activate row, and type "do_search". Hit Enter.

Make sure that you save, or your changes won't show up when you run the app!

Write some code

Now we just need to write a little code to make the search happen.

Go back to the terminal and type: $quickly edit

This will open your editor (most likey Gedit) with all of the python files for your project.

Set up Gedit

Before you start, make sure your editor is set up for Python programming.

Python uses spaces and tabs very differently, and it can cause your program not to run, and can be very confusing if you don't set up Gedit properly.

Go to Edit -> Preferences

Go to Editor tab

Turn on Use spaces instead of tabs

Set Tab width to 4

This will set up Gedit to follow Python standards while coding

Edit the Python File

Click on the tab for "searchy".

Hit Cntrl-S to make the syntax coloring work.

"searchy" is the main python file for your application. It runs the code for the main window, and is the first file that gets run when you start your app.

All we need to do is to add a function in the SearchyWindow class.

The function will just read what is in the text entry field, construct a url string, and use webbrowser to do a web search. Searchy will then close itself.

Add urllib by adding "import urllib" at line 10.

Add urllib by adding "import webbrowser" at line 11.

Then at line 82, hit enter a couple of times to add a new function at line 84.

I put the edited file into pastebin here: http://paste.ubuntu.com/262082/

Look it over, and copy and paste from it if you want. I'll get you all some time to check it out.

Let's look at something important in the do_search function.

Notice around line 86, the code uses "self.builder" to get a reference to the text entry that was added in Glade.

Where does self.builder come from?

Well, the ubuntu-project template sets up a relationship between .ui files generated by Glade, and Python *classes* that use those files.

In order for this to work, the generated Python files have special functions that get generated that set up the objects for you.

You can see this around line 94 of the searchy file. A function called NewSearchWindow.

This special function knows how to set up SearchyWindow object. And then calls "finish_initializing" on the newly created object.

This means a few things:

1. never try to create a searchy window in code like this:

wind = SearchyWindow()

because then the ui file won't be set up correctly, and "finish_initializing" won't be called.

2. Use "finish_initializing" to add any set up code, as that will be called *after* the UI is loaded.

3. Do this to create a new window:

wind = NewSearchyWindow()

and all will be well.

Otherwise, you can see that this function pulls out the text from text entry on line 86.

Uses urllib to create a url parameter in line 87

line 88 - 90 build a url string

line 91 opens the web browser

and line 92 closes the SearchyWidow

Run the app

So if you've added code, you probably want to know how to run the app. Use this: $quickly run

This is the easiest way to test it out.

Package It

If we have time, we can dig a bit more into the Ubuntu project, and into some CouchDB coding.

But for now, let's move on to packaging.

In Quickly, packaging is an easy way to create an installer for your app.

Typically, you'll want to share your software in a PPA, but we'll cover that next.

Licensing

To make a package with quickly, you'll want to start by licensing your software.

To do this, start by editing the generated file called "Copyright".

Change the top line to have the current year and your name and your email.

So I would make the top line look like this:

# Copyright (C) 2009 Rick Spencer rick.spencer@canonical.com

I use the command $quickly license to kick that off.

The ubuntu-project template is going to use this to apply the GPL V3 (as no license is given in the command arg) to Searchy python files.

You can use other well-known license with $quickly license <LICENSE> (shell completion is your friend) or use your personal license.

Now if I reload the file, I can see that the license has been added to the top.

Note that if you didn't license before building the package on LP, it will be automatically licensed to GPL V3 with your LP user name for copyright.

Setup.py

Now I need to provide just a little info to quickly so that it knows enough about my project to make a good package.

This info is provided in the setup.py file.

Open setup.py.

Scroll down to the part that says:

Obviously, you only want to edit what is below that.

You can see how I set that up here:

http://paste.ubuntu.com/262183/

You can also change the info in the desktop file to change the category and other stuff.

For Searchy, it's called searchy.desktop.in

Everything in that is fine for searchy, so I won't change it.

Another good thing to do is to change the icon to your own.

You can do that by editing the file "logo.svg" and the file "icon.png"

package it

Once you've licensed it and personalized it, to create a package, just use the command:

$quickly package

This will do a few things for you.

First, it will search through your project for dependencies.

It does this using dist-utils-auto-extra.

Then quickly package does a bunch of deb magic.

This spits out a zipped up version of your project

But more importantly, a .deb file

You can find these files at the peer level of your project directory.

If you double click on the .deb file, you can install it using gebi.

You can send around the deb file, etc...

Release it

Using deb files to release your software has some significant drawbacks.

The mote significant is that it is hard to update it once a user has installed it.

This is where PPAs and $quickly release comes in.

Before you can use quickly release, though, you need to set up launchpad.

You need to do a few things.

First, you need a launchpad account.

To do that, go here: https://launchpad.net/

and then click "register" in the upper right

after seeing up your account, you need to set up a ssh key.

The ssh key is used by bzr to establish a secure connection between you computer and your launchpad account.

Carefully follow the instructions here: https://help.launchpad.net/YourAccount/CreatingAnSSHKeyPair

In your launchpad account, you will need a "personal package archive", or PPA

When your release your code, it will land in your PPA, and your users can get it from there.

But first, you'll need a pgp key for your ppa.

Follow the instructions here: https://help.launchpad.net/YourAccount/ImportingYourPGPKey

when you make you pgp key, don't add a comment to it!

If there is a comment in it, quickly won't be able to find it.

Now you can click "Create a New PPA" on your launchpad account page.

Phew! It takes some effort to set up a ppa.

It's not easy and fun yet, so we'll keep working on that.

Before you can use quickly to release your software to your PPA, you need to do one more thing ...

You should create a launchpad project page: https://launchpad.net/projects/+new

Here's the searchy project page: https://launchpad.net/searchy

Once you have a PPA and a project page, you can "release" your project.

Use the command:

$quickly release

You will have to interact a little with command to make it work

first, you will be prompted to grant quickly rights to modify your launchpad account.

Then you will need to search for, and choose your project page.

When this is all done, quickly will churn for a while building and signing packages

Then it will upload the package to your ppa.

Once it's in your ppa, you can share that link with your users

they can install by adding the deb line to their sofware sources

and after that, if you update the software, they will get the changes.

Miscellaneous

NOTE: if you only want to share your deb and not release the application (that is to say, not bumping your version), you can use $quickly share which as approximately the same behavior.

You have others commands for even more fun:

$quickly tutorial

$quickly help <command>

$quickly quickly ...

More info on them, soon

What's Next for Quickly

New Templates

ubuntu-project is the first template, but we hope people add more

There are two that I would like to do at some point

First, a ubuntu-game template, that uses pygame

Second, a gedit-plugin that makes it easy to add functions to gedit

If anyone wants to make templates for other platforms, we would gladly merge those into our project

Ideally, each template will have a certain number of functions that are the same

Like create, edit, package, release

Also, if we identify common code, we should work together to refactor it into the core quickly library (it's already the case for launchpad and bzr binding)

GUI?

Quickly is designed as CL tool, not a GUI

It should be easy to integrate with existing GUIs

It should also be easy to use quickly to create a quickly GUI

Questions?

MeetingLogs/devweek0909/QuicklyFun/ClassNotes (last edited 2009-08-31 17:04:50 by rick-rickspencer3)