~ubuntu-branches/ubuntu/natty/quickly/natty

« back to all changes in this revision

Viewing changes to data/templates/ubuntu-project/help/quickly-package.html

  • Committer: Bazaar Package Importer
  • Author(s): Didier Roche
  • Date: 2010-03-29 19:00:48 UTC
  • mfrom: (8.1.1 upstream)
  • Revision ID: james.westby@ubuntu.com-20100329190048-olhobq492x3xnztz
Tags: 0.3.90-0ubuntu1
* New release:
  Quickly core:
  - check now that --template has one argument
  - -- enables to give options to templates (unknown options and arguments
    are still given to templates but -- specify explicity what to give to
    templates commands like -h, --version...)
  - check and enable recreation of the credential if user deletes it on
    Launchpad
  - Use realpath so that we can symlink to the binary in trunk.
    (Jonathan Lange)
  - project_path_not_found is raised when data_path_not_found should be
    (originated from Philip Peitsch's patch). (LP: #497688)
  - importing command in one template from another template is now possible
    support as well "all" keyword to import all commands from a template
    into another one (take care of overridden commands too)
    (LP: #452306, #487301)
  - add an apport hook to get installed templates (LP: #411127)
  - enable option completion for templates
  - handle now version upgrade, launching script for templates and handling
    versionning on them
  - change getstarted wording (LP: #486180) - Grant
  - Quickly ship now "version" tag instead of "format" tag
  - add some templatetools to check X display
  - if a commands exit with 4, do not show "ERROR:" (case of wrong command
    usage, for instance)
  - Rewrote importing module in both bin/quickly and ubuntu-project binary
  - Add get_camel_case_name() and get_sentence_name() to templatetools
  - Refactor some code in pre_create hook()
  - Now dashes and spaces support in project name! Dealing with python and
    packaging issues for you. (LP: #493130)
  - Provide Quickly API (LP: #426480)
  - Fix some issues in the man page
  ubuntu-application Template:
  - Enabling upload to team or user ppa, as well as any ppa.
    Use --ppa ppaname or --ppa team/ppaname
    .quickly file can be used as well with ppa = ppaname or
    ppa = team/ppaname (LP: #470192)
    ppa completion is also available
  - Change BSD header by full license
  - Add MIT license
  - Fixes an error when launchpad display name contains unicode character
    (Petar Vasić)
  - Fix typo in quickly help save (Petar Vasić)
  - Adds logo.png as logo property in about dialog (LP: #478389)
    (Petar Vasić)
  - Remove lp-project-change command and add configure command.
    configure lp-project [project_name] to set/reset lp project binded to
    your Quickly project
    ppa <ppa name> to set a default ppa with your project
  - Fix ~/.selected-editor being ignored (LP: #484730)
  - Fix wrong shell completion when in a template (it wrongly proposed
    all commands followed by templates)
  - Check if we have a X display available before running "run" or launching
    GUI in "create" command.
  - add -- support in quickly run to pass options like --help, --version so
    that Quickly core don't take them.
  - enable preferences save call being called multiple times (Philip Peitsch)
  - Use realpath so that we can symlink to the binary in trunk.
  - Fixed some errors in the tutorial (Brian) (LP: #499356)
  - Fix missing import sys in setup.py (Philip Peitsch) (LP: #499712)
  - rename ubuntu-project to ubuntu-application
  - enhance quickly license (no more Copyright file, only one AUTHORS file)
    personal license needs COPYING file now (and the header will be copied in
    every files). No more # needed in those files too. Some other little
    refactoring too (LP: #469330)
  - autolicence by default on first share/release (with LP info and on GPL-3)
  - change versionning support in ubuntu application: (LP: #476814)
   + quickly share just adds -publicX to current version where X is bumped
     at each "quicky share" execution
   + quickly release remove -publicX (if any) and release with current YY.MM.
     If there is already a release with that version, it will be YY.MM.1, 
     then YY.MM.2
  - add accelerators to menu items (jens persson)
  - set correctly title dialog (Philip Peitsch) (LP: #501999)
  - about dialog box is now fully automated: (LP: #478414)
   + update copyright, authors, license (when licensing)
   + version (when sharing and releasing)
   + homepage (when changing launchpad project: release and configure)
  - add an 'add' command. $ quickly dialog … is now $ quickly add dialog …
    (LP: #438320)
  - enable automatic release and milestone built in LP, releasing and pushing
    upstream tarball (LP: #470344)
  - automatic collect and publish changelog message from commits and save
    messages used during devlopment. (LP: #476572)
  - add i18n to boiler plate (LP: #423529)
  - enable adding manual depdencies to quickly project (LP: #474639)
  - enable configure its own bzr branch and resetting parent branch even once
    already configured (quickly configure bzr <branch-path>)
  - now recommends seahorse-plugins to have a graphical prompt for signing
    package
  - rename quickly glade to quickly design (LP: #528664)
  - create command is now more flexible and enable people to inherit from
    other template more easily
  - add translation domain to gtkbuilder and fix some items that shouldn't
    been translatable (Łukasz Jernaś)
  - add apport and launchpadintegration to new and existing project once
    bounded to LP (Philip Peitsch)
  - fix spelling mistake "connexion" (Łukasz Jernaś) (LP: #532667)
  - the ubuntu-application tutorial is now internationalized and use docbook
    format. Translators, it's yours! (Shane Fagan) (LP: #525168)
  - package/share/release are now more quiet and only print something on error
    warning as a summary as with unfound packages, and so on (LP: #482915)
  - new algorithm to select good email automatically. Try to get the preferred
    email and update the AUTHOR file with it.
  - test GPG key and create one automatically if none is available. The
    corresponding public key availabity in launchpad is also checked.
    (LP: #427730, #408993)
  - add devscripts as a dependency (bug #465833), will fix all the depends
    mess later
  - bump python-distutils-extra (>= 2.18bzr1)
  ubuntu-cli Template:
  - first release using import command feature (no command written into the
    template itself). This is a basic ubuntu CLI application
  ubuntu-pygame Template:
  - first release using import command feature. python-pygame added as a
    depends
* debian/control:
  - renamed and separate in multiple packages to get a -common used with
    Quickly widgets (LP: #519633)
  - suggests python-quickly-widgets

Show diffs side-by-side

added added

removed removed

Lines of Context:
1
 
<HTML>
2
 
<HEAD>
3
 
<TITLE>Quickly Tutorial Part 3</TITLE>
4
 
<STYLE>
5
 
img
6
 
{
7
 
    display: block;
8
 
    width:668px;
9
 
    padding-top:10px;
10
 
}
11
 
p
12
 
{
13
 
    width: 800px;
14
 
}
15
 
 
16
 
</STYLE>
17
 
</HEAD>
18
 
<BODY>
19
 
<H1>Introduction to Part 3</H1>
20
 
<P>In parts 1 and 2, we showed how to create a simple Ubuntu application using Quickly. This section will cover how to package an application so that it is easy for you to share, and easy for other people to install.</P>
21
 
<H1>License your Project</H1>
22
 
<P>It's important to license your code so users and other programmers know their rights in terms of redistributing or modifying it. To quickly grant a GPL license to your  code, simply:</P>
23
 
<OL>
24
 
<LI>Specify your name and email address in the Copyright file.</LI>
25
 
<LI>Run the "license" command.</LI>
26
 
</OL>
27
 
<H2>Specify your name and email</H2>
28
 
<P>When Quickly created your Ubuntu project, it added a file named Copyright in the top level of the directory. Open this file in your text editor, and modify the top line so it has your name and email included. Be sure not to modify other lines as it will interfere with the next step. For example, I would change the entire file to look like this:</P>
29
 
<DIV class="code"><TEXTAREA rows="3" cols="80">
30
 
# Copyright (C) 2009 Rick Spencer rick.spencer@canonical.com
31
 
### BEGIN AUTOMATIC LICENSE GENERATION
32
 
### END AUTOMATIC LICENSE GENERATION
33
 
</TEXTAREA></DIV>
34
 
<H2>Run the "License" Command</H2>
35
 
<P>By default, Quickly will use a GPL 3 license for your project. To use this license, use this command:</P>
36
 
<DIV class="terminal"><TEXTAREA rows="1" cols="80">
37
 
$quickly license
38
 
</TEXTAREA></DIV>
39
 
This will add the GPL 3 license to all of your code files that you've added to your project using Quickly. 
40
 
 
41
 
<P>Keep in mind a couple of things:<P>
42
 
<UL>
43
 
<LI>This is a one way trip. Once you license the project, changes to the license must be done manually.</LI>
44
 
<LI>If you prefer a GPL 2 license, you can specify that when you issue the license command:
45
 
<DIV class="terminal"><TEXTAREA rows="1" cols="80">
46
 
$quickly license GPL-2
47
 
</TEXTAREA></DIV>
48
 
</LI>
49
 
<LI>Quickly doesn't care what license you use, but only knows natively what files and headers to include for BSD, GPL-2, GPL-3, LGPL-2 and LGPL-3. If you prefer another license, you can simply add whatever you license you like by adding your own license in the Copyright file:
50
 
<DIV class="code"><TEXTAREA rows="3" cols="80">
51
 
### BEGIN AUTOMATIC LICENSE GENERATION
52
 
# My personal license here
53
 
### END AUTOMATIC LICENSE GENERATION
54
 
</TEXTAREA></DIV>
55
 
and then run:
56
 
<DIV class="code"><TEXTAREA rows="1" cols="80">
57
 
quickly license
58
 
</TEXTAREA></DIV>
59
 
to license every files.
60
 
</LI>
61
 
<LI>If you've added code files or other files to your project manually, you will need to add the license to those files manually or add those tags at the beginning of the file:
62
 
<DIV class="code"><TEXTAREA rows="2" cols="80">
63
 
### BEGIN LICENSE
64
 
### END LICENSE
65
 
</TEXTAREA></DIV>
66
 
</LI>
67
 
</UL>
68
 
<H1>Specify Application Settings</H1>
69
 
<P>
70
 
You should personalize your application a little before creating the archive. This is very easy to do, as all of the files that you need have already been created, and only need a few lines changed to make them your own. To do this you should:
71
 
</P>
72
 
<OL>
73
 
<LI>Personalize the Application Icon</LI>
74
 
<LI>Edit the Desktop File</LI>
75
 
<LI>Edit the setup.py File</LI>
76
 
</OL>
77
 
<H2>Personalize your Application Icon</H2>
78
 
<P>
79
 
When users install your application, Ubuntu will display an icon next to it in the menus. You can create your own icon or edit the file called "icon.png" in the media directory (jotty/data/media). Ubuntu comes with a great image editing program called "Gimp." So you can go:</P>
80
 
<DIV class="terminal"><TEXTAREA rows="1" cols="80">
81
 
$gimp data/media/icon.png
82
 
</TEXTAREA></DIV>
83
 
<IMG SRC="./images/package0.png" ALT="customized jotty icon" />
84
 
</P>
85
 
<P>
86
 
If you don't personalize the icon, it's ok, your app will just have the default icon, such as in the image below.
87
 
</P>
88
 
<H2>Edit the Desktop File</H2>
89
 
<P>
90
 
By default, Quickly Ubuntu-Project applications are classified as "utilities", so they show up under the Accessories menu in Ubuntu. If we wanted to make Jotty show up in another category, we can do this by editing the desktop file. A desktop file is a file that describes your application to a Linux desktop. The file "jottydesktop.in" was automatically created in the jotty project directory. To change Jotty from a Utility to an Office application, edit jotty.desktop.in and change this:
91
 
</P>
92
 
<DIV class="code"><TEXTAREA rows="8" cols="80">
93
 
[Desktop Entry]
94
 
Name=Jotty
95
 
Comment=Jotty application
96
 
Categories=GNOME;Utility;
97
 
Exec=jotty
98
 
Icon=jotty
99
 
Terminal=false
100
 
Type=Application
101
 
</TEXTAREA></DIV>
102
 
 
103
 
<P>
104
 
to this:
105
 
</P>
106
 
<DIV class="code"><TEXTAREA rows="8" cols="80">
107
 
[Desktop Entry]
108
 
Name=Jotty
109
 
Comment=Jotty application
110
 
Categories=GNOME;Office;
111
 
Exec=jotty
112
 
Icon=jotty
113
 
Terminal=false
114
 
Type=Application
115
 
</TEXTAREA></DIV>
116
 
<P>
117
 
There are lots more categories that you can use, all defined by the FreeDesktop spec. You can see the complete list in the <A HREF="http://standards.freedesktop.org/menu-spec/latest/apa.html">menu spec</A>.
118
 
</P>
119
 
<H2>Edit Setup.py</H2>
120
 
<P>
121
 
Finally, you should include some informatoin in the setup.py file to tell your users a little about yourself. The setup.py file was created for you, just like the desktop file. Most of of the setup.py file shouldn't be modified, as it is just boiler plate that makes your application work properly after it has been installed. However, there is a section at the bottom of the setup.py file that you should edit to describe yourself and the application.
122
 
</P>
123
 
<P>
124
 
So I would change this section:
125
 
</P>
126
 
<DIV class="code"><TEXTAREA rows="8" cols="80">
127
 
DistUtilsExtra.auto.setup(
128
 
    name='jotty',
129
 
    version='0.1',
130
 
    license='GPL v3',
131
 
    #author='Your Name',
132
 
    #author_email='email@ubuntu.com',
133
 
    #description='UI for managing …',
134
 
    #long_description='Here a longer description',
135
 
    #url='https://launchpad.net/jotty',
136
 
    cmdclass={'install': InstallAndUpdateDataDirectory}
137
 
    )
138
 
</TEXTAREA></DIV>
139
 
<P>
140
 
To look like this:
141
 
</P>
142
 
<DIV class="code"><TEXTAREA rows="8" cols="80">
143
 
DistUtilsExtra.auto.setup(
144
 
    name='jotty',
145
 
    version='0.1',
146
 
    license='GPL v3',
147
 
    author='Rick Spencer',
148
 
    author_email='rick.spencer@canonical.com',
149
 
    description='Note taking application',
150
 
    long_description='Note taking application that uses CouchDB as the backend to support easy replication across users and computers.',
151
 
    #url='https://launchpad.net/jotty',
152
 
    cmdclass={'install': InstallAndUpdateDataDirectory}
153
 
    )
154
 
</TEXTAREA></DIV>
155
 
<P>Note that the license has already been set up for you. author and author_email are updated each time you connect to Launchpad (with quickly release or quickly share) with your Launchpad real name and preferred email adress.</P>
156
 
<P>
157
 
Notice that Jotty doesn't have a web page yet, so I just left that line commented out. Also, you don't have to increment version number as quickly share and quickly release commands will make it for you..
158
 
</P>
159
 
 
160
 
</TEXTAREA></DIV>
161
 
<H1>Create and Test the Debian Archive</H1>
162
 
<P>
163
 
After personalizing the project, we are now ready to create the package. This is easily done by issuing the package command:
164
 
</P>
165
 
<DIV class="terminal"><TEXTAREA rows="1" cols="80">
166
 
$quickly package
167
 
</TEXTAREA></DIV>
168
 
<P>This command will take a little while to discover dependencies and create all the required archives, etc... It will also report some errors as we haven't created a PGP key, for instance. None the less, when it is done, the package will be created. Using the file browser, you can see the created package next to the project directory:</P>
169
 
<IMG SRC="./images/package1.png" ALT="package command creates .deb archive" />
170
 
<P>Right now, the specific file we are interested in is "jotty_0.1_all.deb". To test it out, double click on it, to open it in Ubuntu's graphical installer program:</P>
171
 
<IMG SRC="./images/package2.png" ALT="deb opened in gdebi" />
172
 
<P>Click "Install Package" to see how it  installs onto your desktop. After chugging for a bit, you'll see that it is installed in the Applications->Office menu. If you customized your icon, you'll see that the menu uses your custom icon as well.</p>
173
 
<IMG SRC="./images/package3.png" ALT="jotty installed" />
174
 
<H1>Now that you have a package</H1>
175
 
<P>Now that you've packaged your application, you can share the .deb file. However, if your users install their application this way, and you update the application, your users will have to find this out and resinstall. This hassle can be avoided in Ubuntu by using Personal Package Archives (or PPAs). Distrubuting your applications in this manner is covered in section 4 (not yet available).</P>
176
 
</BODY>