Pro-reason
September 25th, 2008, 02:12 AM
This tutorial necessarily assumes that you have a PPA (Personal Package Archive) on Launchpad. This involves:
creating a Launchpad account (https://launchpad.net/ubuntu/+ppas/+login)
setting up a GPG key (https://help.launchpad.net/YourAccount/ImportingYourPGPKey)
signing the code of conduct (https://help.launchpad.net/BecomingAnUbuntero)
The official documentation is at https://help.launchpad.net/Packaging/PPA and https://wiki.ubuntu.com/PackagingGuide/Complete.
The first thing that newbie packagers will notice is that a lot of the documentation assumes that you already have a basic understanding of compiling code, writing makefiles, and the packaging process. It also assumes that you want to package quite complex stuff. All this may be true, but what if you're just trying to package a picture or a bash script?
This tutoral walks you through every step of doing that basic packaging work.
---------------------
Let's say that you have written a script with the following content:
#!/bin/bash
echo "Hello, world!"
You could just save it as /usr/local/bin/helloworld.sh. However, you want to share your fabulous code with the world. This is how you do it.
First, make a directory for your code. It needs to end in the version number of the software. We will be creating files both inside this directory and also one step above it.
mkdir -p ~/PPA/helloworld/helloworld-1.0/
cd ~/PPA/helloworld/helloworld-1.0/
Put your script in that directory.
Put any documentation you have written in there too.
If you just wanted to distribute source code, you could at this stage just archive this directory as helloworld-1.0.tgz and send it to people, but we want to go further than that.
The key to Debian/Ubuntu packaging is the “debian” directory. So let's create it.
mkdir debian
cd debian
There are a few files that we need to put into this directory. Let's create them all:
touch changelog compat control copyright install rules
gedit * &
All the files will now be open in gedit, in various tabs.
Go to the changelog tab, and put something like this:
helloworld (1.0-0ubuntu1~ppa1) hardy; urgency=low
* Initial release
-- Joe Bloggs <j.bloggs@example.com> Sun, 01 Jan 2000 01:01:01 +0000
The version number should be constructed like this:
First, you have the version of the actual software. If it's your own, then you get to decide what version it is at. Let's say it is “1.0”.
Then, we put a hyphen and the Debian version number. Since this is your own stuff, you know that it is not in Debian, so we put a zero.
The, we write “ubuntu1”, because this is the first version of it available for Ubuntu.
Then, we put “~ppa1”, to say that this is the first PPA version.
Put the same e-mail address that you gave when you created your Launchpad account. It must have a GPG fingerprint associated with it.
To get the correct date, type “date -R” on the command line. Copy and paste it into the file. In must be in that format exactly.
Go to the compat tab, and put this:
5
Go to the control tab, and put this:
Source: helloworld
Section: utils
Priority: extra
Maintainer: Joe Bloggs <j.bloggs@example.com>
Build-Depends: debhelper (>= 5), cdbs (>= 0.2)
Standards-Version: 3.8.0
Package: helloworld
Architecture: all
Depends: ${shlibs:Depends}, ${misc:Depends}, bash (>= 2)
Description: Prints a pointless message
This is a long description of the package and most of
the stuff it does. I don't want each line to be more
than about 50 or 60 characters. Each line starts with
a space.
.
If I need to make a new paragraph, I have to put a dot
as you can see above.
Depending on what you are packaging, you may need to change the section to something other than ”utils”.
I have added “bash” to the dependencies, because this is a bash script. Specify a recent version of bash if your script uses some new feature of bash. Also specify any other programs which are called by your script. For example, if your script compresses something with bzip2, then you would add “bzip2” as a dependency.
Go to the copyright tab, and put something like this:
This package was debianised by Joe Bloggs <j.bloggs@example.com> on
Sun, 01 Jan 2000 01:01:01 +0000
It can be downloaded from https://launchpad.net/~joebloggs/+archive
Upstream Author:
Joe Bloggs <j.bloggs@example.com>
Copyright:
This software (including its Debian packaging)
is under the copyright of the above author.
Licence:
This software (including its Debian packaging)
is available to you under the terms
of the GPL-3, see "/usr/share/common-licenses/GPL-3".
You can also use it under the terms of any other GPL version.
Put the name and e-mail exactly as in the changelog file. Also enter the date in the same way. Include the actual copyright and licence of the software. It must be under a Free licence.
If you are not packaging your own work, then you have to be slightly more careful, making sure that everything in the package is properly licensed.
For the “downloaded from” address, you normally put the address that you found the source code at. If it is your own, then you give your website (where people can download the source code). If you have created the code just to upload it to Launchpad, then your full Launchpad URL is probably the most sensible website to give.
Go to the install tab, and put something like this:
helloworld.sh /usr/bin/
As you can see, this is a file that consists of lines which consist of: a file in your package directory, some spaces or tabs, and then the location that they will be installed to. There can be as many lines as you need.
The proper place for most executable files is /usr/bin/. Do your research to find out where other files ought to go. A GRUB background picture would go in /boot/grub/splashimages/, for example. Make sure that the files installed by your package do not clash with those installed by those in any other commonly used package.
Go to the rules tab, and put something like this:
#!/usr/bin/make -f
include /usr/share/cdbs/1/rules/debhelper.mk
binary-install/helloworld::
dh_icons
binary-fixup/helloworld::
dh_gconf --priority=16
With most packages, this is a bit complicated. However, since we have nothing to compile, we can use a nice simple rules file like this.
Save all, and close.
Return to your terminal, and exit the debian directory:
cd ..
Into this directory you can now put a file called “README” with any basic notes about the package; a file called “THANKS” with any people who really helped with the software; a file called “COPYING” with the full text of the licence under which the software is released; and a file called “AUTHORS” with the names and e-mail addresses of the people who wrote the software (you, in this case). These are files that are expected to be in any tarball of source code anyway. They aren't specifically to do with Debian packaging. That's why they aren't in the debian directory.
Now make sure that you have the software needed to work with Launchpad:
sudo apt-get install devscripts dput
Now let's prepare this stuff for Launchpad:
debuild -S
That will take a while to complete, and spit out a load of info. If there is an error, then you messed something up. Go to the top of this guide and check that you did each step properly.
At the end, debuild will ask your for your GPG password so that it can sign the package with your name. This is for security. Launchpad won't accept unsigned stuff.
If all goes well, debuild will have created several files in the parent of the current directory. In our case, this is ~/PPA/helloworld.
You can now do “ls ..” or “cd .. && ls” to check that the files are indeed there.
Let's make sure that your computer knows where to upload the stuff. Do this:
gedit ~/.dput.cf
In the window that comes up, paste the following:
[my-ppa]
fqdn = ppa.launchpad.net
method = ftp
incoming = ~joebloggs/ubuntu/
login = anonymous
allow_unsigned_uploads = 0
[DEFAULT]
default_host_main = my-ppa
Change “joebloggs” to your actual Launchpad ID. Save and close.
Now upload your work to Launchpad:
dput my-ppa ~/PPA/helloworld_1.0-0ubuntu1~ppa1_source.changes
As you can see, you have to point the dput command at the .changes file that you have just created. It won't upload just that file though; it will also upload the source-code tarball.
A few minutes later, you'll get an e-mail from Launchpad saying that the package has been accepted and added to the queue. It could take anything from a couple of minutes to a couple of hours for your source code to be turned into an actual .deb package and be available in your PPA.
Relax and have a cup of tea, and think about which friends you'll brag to about your new techno-skills.
---------------------
There is more to learn than this, but my assumption is that you need the psychological boost of successfully packaging something, and that after all this you will look into learning how to tweak this for more complex tasks.
creating a Launchpad account (https://launchpad.net/ubuntu/+ppas/+login)
setting up a GPG key (https://help.launchpad.net/YourAccount/ImportingYourPGPKey)
signing the code of conduct (https://help.launchpad.net/BecomingAnUbuntero)
The official documentation is at https://help.launchpad.net/Packaging/PPA and https://wiki.ubuntu.com/PackagingGuide/Complete.
The first thing that newbie packagers will notice is that a lot of the documentation assumes that you already have a basic understanding of compiling code, writing makefiles, and the packaging process. It also assumes that you want to package quite complex stuff. All this may be true, but what if you're just trying to package a picture or a bash script?
This tutoral walks you through every step of doing that basic packaging work.
---------------------
Let's say that you have written a script with the following content:
#!/bin/bash
echo "Hello, world!"
You could just save it as /usr/local/bin/helloworld.sh. However, you want to share your fabulous code with the world. This is how you do it.
First, make a directory for your code. It needs to end in the version number of the software. We will be creating files both inside this directory and also one step above it.
mkdir -p ~/PPA/helloworld/helloworld-1.0/
cd ~/PPA/helloworld/helloworld-1.0/
Put your script in that directory.
Put any documentation you have written in there too.
If you just wanted to distribute source code, you could at this stage just archive this directory as helloworld-1.0.tgz and send it to people, but we want to go further than that.
The key to Debian/Ubuntu packaging is the “debian” directory. So let's create it.
mkdir debian
cd debian
There are a few files that we need to put into this directory. Let's create them all:
touch changelog compat control copyright install rules
gedit * &
All the files will now be open in gedit, in various tabs.
Go to the changelog tab, and put something like this:
helloworld (1.0-0ubuntu1~ppa1) hardy; urgency=low
* Initial release
-- Joe Bloggs <j.bloggs@example.com> Sun, 01 Jan 2000 01:01:01 +0000
The version number should be constructed like this:
First, you have the version of the actual software. If it's your own, then you get to decide what version it is at. Let's say it is “1.0”.
Then, we put a hyphen and the Debian version number. Since this is your own stuff, you know that it is not in Debian, so we put a zero.
The, we write “ubuntu1”, because this is the first version of it available for Ubuntu.
Then, we put “~ppa1”, to say that this is the first PPA version.
Put the same e-mail address that you gave when you created your Launchpad account. It must have a GPG fingerprint associated with it.
To get the correct date, type “date -R” on the command line. Copy and paste it into the file. In must be in that format exactly.
Go to the compat tab, and put this:
5
Go to the control tab, and put this:
Source: helloworld
Section: utils
Priority: extra
Maintainer: Joe Bloggs <j.bloggs@example.com>
Build-Depends: debhelper (>= 5), cdbs (>= 0.2)
Standards-Version: 3.8.0
Package: helloworld
Architecture: all
Depends: ${shlibs:Depends}, ${misc:Depends}, bash (>= 2)
Description: Prints a pointless message
This is a long description of the package and most of
the stuff it does. I don't want each line to be more
than about 50 or 60 characters. Each line starts with
a space.
.
If I need to make a new paragraph, I have to put a dot
as you can see above.
Depending on what you are packaging, you may need to change the section to something other than ”utils”.
I have added “bash” to the dependencies, because this is a bash script. Specify a recent version of bash if your script uses some new feature of bash. Also specify any other programs which are called by your script. For example, if your script compresses something with bzip2, then you would add “bzip2” as a dependency.
Go to the copyright tab, and put something like this:
This package was debianised by Joe Bloggs <j.bloggs@example.com> on
Sun, 01 Jan 2000 01:01:01 +0000
It can be downloaded from https://launchpad.net/~joebloggs/+archive
Upstream Author:
Joe Bloggs <j.bloggs@example.com>
Copyright:
This software (including its Debian packaging)
is under the copyright of the above author.
Licence:
This software (including its Debian packaging)
is available to you under the terms
of the GPL-3, see "/usr/share/common-licenses/GPL-3".
You can also use it under the terms of any other GPL version.
Put the name and e-mail exactly as in the changelog file. Also enter the date in the same way. Include the actual copyright and licence of the software. It must be under a Free licence.
If you are not packaging your own work, then you have to be slightly more careful, making sure that everything in the package is properly licensed.
For the “downloaded from” address, you normally put the address that you found the source code at. If it is your own, then you give your website (where people can download the source code). If you have created the code just to upload it to Launchpad, then your full Launchpad URL is probably the most sensible website to give.
Go to the install tab, and put something like this:
helloworld.sh /usr/bin/
As you can see, this is a file that consists of lines which consist of: a file in your package directory, some spaces or tabs, and then the location that they will be installed to. There can be as many lines as you need.
The proper place for most executable files is /usr/bin/. Do your research to find out where other files ought to go. A GRUB background picture would go in /boot/grub/splashimages/, for example. Make sure that the files installed by your package do not clash with those installed by those in any other commonly used package.
Go to the rules tab, and put something like this:
#!/usr/bin/make -f
include /usr/share/cdbs/1/rules/debhelper.mk
binary-install/helloworld::
dh_icons
binary-fixup/helloworld::
dh_gconf --priority=16
With most packages, this is a bit complicated. However, since we have nothing to compile, we can use a nice simple rules file like this.
Save all, and close.
Return to your terminal, and exit the debian directory:
cd ..
Into this directory you can now put a file called “README” with any basic notes about the package; a file called “THANKS” with any people who really helped with the software; a file called “COPYING” with the full text of the licence under which the software is released; and a file called “AUTHORS” with the names and e-mail addresses of the people who wrote the software (you, in this case). These are files that are expected to be in any tarball of source code anyway. They aren't specifically to do with Debian packaging. That's why they aren't in the debian directory.
Now make sure that you have the software needed to work with Launchpad:
sudo apt-get install devscripts dput
Now let's prepare this stuff for Launchpad:
debuild -S
That will take a while to complete, and spit out a load of info. If there is an error, then you messed something up. Go to the top of this guide and check that you did each step properly.
At the end, debuild will ask your for your GPG password so that it can sign the package with your name. This is for security. Launchpad won't accept unsigned stuff.
If all goes well, debuild will have created several files in the parent of the current directory. In our case, this is ~/PPA/helloworld.
You can now do “ls ..” or “cd .. && ls” to check that the files are indeed there.
Let's make sure that your computer knows where to upload the stuff. Do this:
gedit ~/.dput.cf
In the window that comes up, paste the following:
[my-ppa]
fqdn = ppa.launchpad.net
method = ftp
incoming = ~joebloggs/ubuntu/
login = anonymous
allow_unsigned_uploads = 0
[DEFAULT]
default_host_main = my-ppa
Change “joebloggs” to your actual Launchpad ID. Save and close.
Now upload your work to Launchpad:
dput my-ppa ~/PPA/helloworld_1.0-0ubuntu1~ppa1_source.changes
As you can see, you have to point the dput command at the .changes file that you have just created. It won't upload just that file though; it will also upload the source-code tarball.
A few minutes later, you'll get an e-mail from Launchpad saying that the package has been accepted and added to the queue. It could take anything from a couple of minutes to a couple of hours for your source code to be turned into an actual .deb package and be available in your PPA.
Relax and have a cup of tea, and think about which friends you'll brag to about your new techno-skills.
---------------------
There is more to learn than this, but my assumption is that you need the psychological boost of successfully packaging something, and that after all this you will look into learning how to tweak this for more complex tasks.