THE INDEPENDENT MAGAZINE FOR THE UBUNTU LINUX COMMUNITY
UBUNTU DEVELOPMENT SERIES SPECIAL EDITION
SINGLE TOPIC SERIES FROM MAGAZINE ISSUES #49 - #52SINGLE TOPIC SERIES FROM MAGAZINE ISSUES #49 - #52
Full Circle
Full Circle Magazine is neither affiliated, with nor endorsed by, Canonical Ltd.
Full Circle Magazine Specials
Full Circle Magazine
The articles contained in this magazine are released under the Creative Commons Attribution-Share Alike 3.0Unported license. This means you can adapt, copy, distribute and transmit the articles but only under the following conditions:
You must attribute the work to the original author in some way (at least a name, email or URL) and to this magazine by name ('full circle magazine') and the URL www.fullcirclemagazine.org (but not attribute the article(s) in any way that suggests that they endorse you or your use of the work). If you alter, transform, or build upon this work, you must distribute the resulting work under the same, similar or a compatible license.Full Circle Magazine is entirely independent of Canonical, the sponsor of Ubuntu projects and the views and opinions in the magazine should in no way be assumed to have Canonical endorsement.
Please note: this Special Edition is provided with absolutely no warranty whatsoever; neither the contributors nor Full Circle Magazine accept any responsibility or liability for loss or damage resulting from readers choosing to apply this content to theirs or others computers and equipment.
About Full Circle
Full Circle is a free, independent, magazine dedicated to the Ubuntu family of Linux operating systems. Each month, it contains helpful how-to articles and reader- submitted stories.
Full Circle also features a companion podcast, the Full Circle Podcast which covers the magazine, along with other news of interest.
Welcome to another 'single-topic special'In response to reader requests, we are assembling the content of some of our serialised articles into dedicated editions.
For now, this is a straight reprint of the series 'Ubuntu Development', Parts 1-4, by Daniel Holbach from issues #49 through #52; nothing fancy, just the facts.
Please bear in mind the original publication date; current versions of hardware and software may differ from those illustrated, so check your hardware and software versions before attempting to emulate the tutorials in these special editions. You may have later versions of software installed or available in your distributions' repositories.
Enjoy!
Find Us
Website: http://www.fullcirclemagazine.org/
Forums: http://ubuntuforums.org/forumdisplay.php?f=270
IRC: #fullcirclemagazine on chat.freenode.net
Editorial Team
Editor: Ronnie Tucker (aka: RonnieTucker) [email protected]
Webmaster: Rob Kerfia (aka: admin / linuxgeekery- [email protected]
Podcaster: Robin Catling (aka RobinCatling) [email protected]
Communications Manager: Robert Clipsham (aka: mrmonday) - [email protected]
full circle magazine #49 17 contents ^
HHOOWW--TTOOWritten by Daniel Holbach IInnttrroo TToo UUbbuunnttuu DDeevveellooppmmeenntt
Ubuntu is made up ofthousands of differentcomponents, written inmany different
programming languages. Everycomponent - be it a softwarelibrary, a tool, or a graphicalapplication - is available as asource package. Source packagesin most cases consist of two parts:the actual source code, andmetadata. Metadata includes thedependencies of the package,copyright and licensinginformation, and instructions onhow to build the package. Oncethis source package is compiled,the build process provides binarypackages, which are the .deb filesusers can install.
Every time a new version of anapplication is released, or whensomeone makes a change to thesource code that goes intoUbuntu, the source package mustbe uploaded to the build machinesto be compiled. The resultingbinary packages then aredistributed to the archive and itsmirrors in different countries. TheURLs in /etc/apt/sources.list point
to an archive or mirror. Every dayCD images are built for a selectionof different Ubuntu flavours.Ubuntu Desktop, Ubuntu Server,Kubuntu, and others, specify a listof required packages that get onthe CD. These CD images are thenused for installation tests, andprovide the feedback for furtherrelease planning.
Ubuntu’s development is verymuch dependent on the currentstage of the release cycle. Werelease a new version of Ubuntuevery six months, which is possibleonly because we have established
strict freeze dates. With everyfreeze date that is reached,developers are expected to makefewer, less-intrusive changes.Feature Freeze is the first bigfreeze date after the first half ofthe cycle has passed. At this stage,features must be largelyimplemented. The rest of the cycleis supposed to be focused onfixing bugs. After that, the userinterface, then thedocumentation, the kernel, etc,are frozen, then the beta release isput out which receives a lot oftesting. From the beta releaseonwards, only critical bugs get
fixed, and a release candidaterelease is made, and if it does notcontain any serious problems, itbecomes the final release.
Thousands of source packages,billions of lines of code, andhundreds of contributors, requirea lot of communication andplanning to maintain highstandards of quality. At thebeginning of each release cycle,we have the Ubuntu DeveloperSummit where developers andcontributors come together toplan the features of the nextreleases. Every feature is
full circle magazine #49 18 contents ^
HOWTO - INTRO TO UBUNTU DEVELOPMENTdiscussed by its stakeholders, anda specification is written thatcontains detailed informationabout its assumptions,implementation, the necessarychanges in other places, how totest it, and so on. This is all done inan open and transparent fashion,so even if you cannot attend theevent in person, you canparticipate remotely and listen toa streamcast, chat withattendants, and subscribe tochanges of specifications - so youare always up to date.
Not every single change can bediscussed in a meeting though,particularly because Ubuntu relieson changes that are done in otherprojects. That is why contributorsto Ubuntu constantly stay in touch.Most teams or projects usededicated mailing lists to avoid toomuch unrelated noise. For moreimmediate coordination,developers and contributers useInternet Relay Chat (IRC). Alldiscussions are open and public.
Another important toolregarding communication is bugreports. Whenever a defect isfound in a package or piece ofinfrastructure, a bug report is filedin Launchpad. All information is
collected in that report and itsimportance, status, and assignee,updated when necessary. Thismakes it an effective tool to stayon top of bugs in a package orproject, and organise the workload.
Most of the software availablethrough Ubuntu is not written byUbuntu developers themselves.Most of it is written by developersof other Open Source projects, andthen integrated into Ubuntu.These projects are called“Upstreams”, because their sourcecode flows into Ubuntu, where we“just” integrate it. The relationshipto Upstreams is criticallyimportant to Ubuntu. It is not justcode that Ubuntu gets fromUpstreams, but it is also that
Upstreams get users, bug reports,and patches, from Ubuntu (andother distributions).
The most important Upstreamfor Ubuntu is Debian. Debian is thedistribution that Ubuntu is basedon, and many of the designdecisions regarding the packaginginfrastructure are made there.Traditionally, Debian has alwayshad dedicated maintainers forevery single package or dedicatedmaintenance teams. In Ubuntuthere are teams that have aninterest in a subset of packagestoo, and naturally every developerhas a special area of expertise, butparticipation (and upload rights)generally is open to everyone whodemonstrates ability and
willingness.
Getting a change into Ubuntuas a new contributor is not asdaunting as it seems, and can be avery rewarding experience. It isnot only about learning somethingnew and exciting, but also aboutsharing the solution, and solving aproblem for millions of users outthere.
Open Source Developmenthappens in a distributed worldwith different goals and differentareas of focus. For example, theremight be the case that a particularUpstream might be interested inworking on a new big feature,while Ubuntu, because of the tightrelease schedule, might be
full circle magazine #49 19 contents ^
interested in shipping a solidversion with just an additional bugfix. That is why we make use of“Distributed Development”, wherecode is being worked on in variousbranches that are merged witheach other after code reviews andsufficient discussion.
In the example mentionedabove, it would make sense to shipUbuntu with the existing versionof the project, add the bugfix, getit into Upstream for their nextrelease, and ship that (if suitable)in the next Ubuntu release. Itwould be the best possiblecompromise and a situation whereeverybody wins.
To fix a bug in Ubuntu, youwould first get the source code forthe package, then work on the fix,document it so it is easy tounderstand for other developers
and users, then build the packageto test it. After you have tested it,you can easily propose the changeto be included in the currentUbuntu development release. Adeveloper with upload rights willreview it for you, and then get itintegrated into Ubuntu.
When trying to find a solution,it is usually a good idea to checkwith Upstream and see if theproblem (or a possible solution) isknown already, and, if not, do yourbest to make the solution aconcerted effort. Additional stepsmight involve getting the changebackported to an older, stillsupported, version of Ubuntu, andforwarding it to Upstream.
The most importantrequirements for success inUbuntu development are having aknack for “making things work
again,” not being afraidto read documentationand ask questions, beinga team player, andenjoying some detectivework.
Good places to askyour questions [email protected] and #ubuntu-motu onirc.freenode.net. You willeasily find a lot of newfriends and people withthe same passion thatyou have: making theworld a better place bymaking better OpenSource software.
A PLEA ON BEHALF OF THEPODCAST PARTY
As you heard in episode #15 of thepodcast, we're calling for opinion topicsfor that section of the show.
Instead of us having a rant aboutwhatever strikes us, why not prompt uswith a topic and watch for the mushroomclouds over the horizon! It's highlyunlikely that the three of us will agree.
Or, an even more radical thought, send usan opinion by way of a contribution!
You can post comments and opinions onthe podcast page atfullcirclemagazine.org, in our UbuntuForums section, or [email protected]. You canalso send us a comment by recording anaudio clip of no more than 30 secondsand sending it to the same address.Comments and audio may be edited forlength. Please remember this is afamily-friendly show.
It would be great tohave contributors comeon the show andexpress an opinion inperson.
HOWTO - INTRO TO UBUNTU DEVELOPMENT
full circle magazine #50 17 contents ^
HHOOWW--TTOOWritten by Daniel Holbach UUbbuunnttuu DDeevveellooppmmeenntt PPtt.. 22-- SSeett UUpp
There are a number ofthings you need to do toget started developingfor Ubuntu. This article is
designed to get your computer setup so that you can start workingwith packages, and upload yourpackages to Launchpad. Here’swhat we’ll cover:
• Installing packaging-relatedsoftware. This includes:• Ubuntu-specific packaging
utilities• Encryption software so your
work can be verified as being doneby you• Additional encryption software
so you can securely transfer files• Creating and configuring youraccount on Launchpad• Setting up your developmentenvironment to help you do localbuilds of packages, interact withother developers, and proposeyour changes on Launchpad.
Note: It is advisable to dopackaging work using the currentdevelopment version of Ubuntu.Doing so will allow you to test
changes in the same environmentwhere those changes will actuallybe applied and used.
Don’t worry, though, theUbuntu development release wikipage(https://wiki.ubuntu.com/UsingDevelopmentReleases) shows avariety of ways to safely use thedevelopment release.
Install Basic PackagingSoftware
There are a number of toolsthat will make your life as anUbuntu developer much easier.You will encounter these toolslater in this guide. To install mostof the required tools, run thiscommand:
sudo apt-get install gnupgpbuilder ubuntu-dev-toolsbzr-builddeb apt-file
This command will install thefollowing software:
gnupg – GNU Privacy Guardcontains tools you will need to
create a cryptographic key withwhich you will sign files you wantto upload to Launchpad.pbuilder – a tool to doreproducible builds of a package ina clean and isolated environment.ubuntu-dev-tools (and devscripts,a direct dependency) – a collectionof tools that make many packagingtasks easier.bzr-builddeb (and bzr, adependency) – distributed version-control tools that make it easy formany developers to collaborateand work on the same code whilekeeping it trivial to merge eachother’s work.apt-file provides an easy way tofind the binary package thatcontains a given file.apt-cache (part of the aptpackage) provides even moreinformation about packages onUbuntu.
Create your GPG key
GPG stands for GNU PrivacyGuard and it implements theOpenPGP standard which allowsyou to sign and encrypt messagesand files. This is useful for a
number of purposes. In our case, itis important that you can sign fileswith your key so they can beidentified as something that youworked on. If you upload a sourcepackage to Launchpad, it willaccept the package only if it canabsolutely determine whouploaded the package.
To generate a new GPG key, run:
gpg --gen-key
GPG will first ask you whichkind of key you want to generate.Choosing the default (RSA andDSA) is fine. Next it will ask youabout the keysize. The default(currently 2048) is fine, but 4096 ismore secure. Afterwards, it willask you if you want it to expire thekey at some stage. It is safe to say“0”, which means the key will neverexpire. The last questions will beabout your name and emailaddress. Just pick the ones you are
full circle magazine #50 18 contents ^
HOWTO - UBUNTU DEVELOPMENT 2 - SET UPgoing to use for Ubuntudevelopment here, you can addadditional email addresses lateron. Adding a comment is notnecessary. Then you will have toset a passphrase. Choose a safeone.
Now GPG will create a key foryou, which can take a little bit oftime; it needs random bytes, so ifyou give the system some work todo it will be just fine. Move thecursor around!
Once this is done, you will get amessage similar to this one:
pub 4096R/43CDE61D 2010-12-06Key fingerprint = 5C28 0144FB08 91C0 2CF3 37AC 6F0BF90F 43CD E61Duid DanielHolbach <[email protected]>sub 4096R/51FBE68C 2010-12-06
In this case 43CDE61D is thekey ID.
Next, you need to upload thepublic part of your key to akeyserver so the world can identifymessages and files as yours. To doso, enter:
gpg --send-keys <KEY ID>
This will send your key to onekeyserver, but a network ofkeyservers will automatically syncthe key between themselves. Oncethis syncing is complete, yoursigned public key will be ready toverify your contributions aroundthe world.
Create your SSH key
SSH stands for Secure Shell,and it is a protocol that allows youto exchange data in a secure wayover a network. It is common touse SSH to access and open a shellon another computer, and to use itto securely transfer files. For ourpurposes, we will mainly be usingSSH to securely communicate withLaunchpad.
To generate a SSH key, enter:
ssh-keygen -t rsa
The default file name usuallymakes sense, so you can just leaveit as it is. For security purposes, itis highly recommended that youuse a passphrase.
Set up pbuilder
Pbuilder allowsyou to build packageslocally on yourmachine. It serves acouple of purposes:
• The build will be done in aminimal and clean environment.This helps you make sure yourbuilds succeed in a reproducibleway, but without modifying yourlocal system.• There is no need to install allnecessary build dependencieslocally.• You can set up multiple instancesfor various Ubuntu and Debianreleases.
Setting pbuilder up is very easy.Edit ~/.pbuilderrc and add thefollowing line to it:
COMPONENTS="main universemultiverse restricted"
This will ensure that builddependencies are satisfied usingall components. Then run:
pbuilder-dist <release>create
where <release> is, for example,natty, maverick, lucid, or, in the
case of Debian, maybe sid. This willtake a while as it will download allthe necessary packages for a“minimal installation”. These willbe cached though.
Get Set Up To WorkWith Launchpad
With a basic local configurationin place, your next step will be toconfigure your system to workwith Launchpad. This section willfocus on the following topics:
• What Launchpad is, and creatinga Launchpad account• Uploading your GPG and SSH keysto Launchpad• Configuring Bazaar to work withLaunchpad• Configuring Bash to work withBazaar
About Launchpad
Launchpad is the central pieceof infrastructure we use in Ubuntu.It not only stores our packages and
full circle magazine #50 19 contents ^
our code, but also things liketranslations, bug reports andinformation about the people whowork on Ubuntu and their teammemberships. You will also useLaunchpad to publish yourproposed fixes, and get otherUbuntu developers to review andsponsor them.
You will need to register withLaunchpad and provide a minimalamount of information. This willallow you to download and uploadcode, submit bug reports, andmore.
Get a Launchpadaccount
If you don’t already have aLaunchpad account, you can easilycreate one (at:https://launchpad.net/+login). Ifyou have a Launchpad account butcannot remember your Launchpadid, you can find this out by going tohttps://launchpad.net/people/+me,and looking for the part after the~ in the URL.
Launchpad’s registrationprocess will ask you to choose adisplay name. It is encouraged foryou to use your real name here so
that your Ubuntu developercolleagues will be able to get toknow you better.
When you register a newaccount, Launchpad will send youan email with a link you need toopen in your browser in order toverify your email address. If youdon’t receive it, check in your spamfolder.
The new account help page(https://help.launchpad.net/YourAccount/NewAccount) on Launchpadhas more information about theprocess, and additional settingsyou can change.
Upload your GPG key toLaunchpad
To find out about your GPGfingerprint, run:
gpg --fingerprint<[email protected]>
and it will print out somethinglike:
pub 4096R/43CDE61D 2010-12-06Key fingerprint = 5C28 0144FB08 91C0 2CF3 37AC 6F0BF90F 43CD E61Duid DanielHolbach <[email protected]>
sub 4096R/51FBE68C 2010-12-06
Head tohttps://launchpad.net/people/+me/+editpgpkeys and copy the partabout your “Key fingerprint” intothe text box. In the case above thiswould be 5C28 0144 FB08 91C02CF3 37AC 6F0B F90F 43CD E61D.Now click on “Import Key”.
Launchpad will use thefingerprint to check the Ubuntukey server for your key and, ifsuccessful, send you an encryptedemail asking you to confirm thekey import. Check your emailaccount, and read the email thatLaunchpad sent you. If your emailclient supports OpenPGPencryption, it will prompt you forthe password you chose for thekey when GPG generated it. Enterthe password, then click the link toconfirm that the key is yours.
Launchpad encrypts the email,using your public key, so that it canbe sure that the key is yours. Ifyour email software does notsupport OpenPGP encryption,copy the encrypted email’scontents, type gpg in yourterminal, then paste the emailcontents into your terminal
window.
Back on the Launchpadwebsite, use the Confirm buttonand Launchpad will complete theimport of your OpenPGP key.
Find more information athttps://help.launchpad.net/YourAccount/ImportingYourPGPKey
Upload your SSH key toLaunchpad
Openhttps://launchpad.net/people/+me/+editsshkeys in a web browser,also open ~/.ssh/id_rsa.pub in atext editor. This is the public partof your SSH key, so it is safe toshare it with Launchpad. Copy thecontents of the file and pastethem into the text box on the webpage that says “Add an SSH key”.Now click “Import Public Key”.
For more information on thisprocess, visit the creating an SSHkeypair page(https://help.launchpad.net/YourAccount/CreatingAnSSHKeyPair) onLaunchpad.
Configure Bazaar
HOWTO - UBUNTU DEVELOPMENT 2 - SET UP
full circle magazine #50 20 contents ^
A PLEA ON BEHALF OF THEPODCAST PARTY
As you heard in episode #15 of the podcast,we're calling for opinion topics for that sectionof the show.
Instead of us having a rant about whateverstrikes us, why not prompt us with a topic andwatch for the mushroom clouds over thehorizon! It's highly unlikely that the three of uswill agree.
Or, an even more radical thought, send us anopinion by way of a contribution!
You can post comments and opinions on thepodcast page at fullcirclemagazine.org, in ourUbuntu Forums section, or [email protected]. You can alsosend us a comment by recording an audio clipof no more than 30 seconds and sending it tothe same address. Comments and audio maybe edited for length. Please remember this isa family-friendly show.
It would be great to havecontributors come on the showand express an opinion inperson.
Robin
HOWTO - UBUNTU DEVELOPMENT 2 - SET UPBazaar is the tool we use to
store code changes in a logicalway, to exchange proposedchanges and merge them, even ifdevelopment is done concurrently.To tell Bazaar who you are, simplyrun:
bzr whoami "Bob Dobbs<[email protected]>"
bzr launchpad-login subgenius
whoami will tell Bazaar whichname and email address it shoulduse for your commit messages.With launchpad-login you set yourLaunchpad ID. This way, code thatyou publish in Launchpad will beassociated with you.
Note: If you can not rememberthe ID, go tohttps://launchpad.net/people/+meand see where it redirects you. Thepart after the “~” in the URL is yourLaunchpad ID.)
Configure your shell
Similar to Bazaar, theDebian/Ubuntu packaging toolsneed to learn about you as well.Simply open your ~/.bashrc in atext editor, and add something likethis to the bottom of it:
export DEBFULLNAME="BobDobbs"
exportDEBEMAIL="[email protected]"
Now save the file, and eitherrestart your terminal or run:
source ~/.bashrc
(If you use a shell differentfrom the default (which is bash),please edit the configuration filefor that shell accordingly.)
NEXT MONTH: Fixing a bug
full circle magazine #51 17 contents ^
HHOOWW--TTOOWritten by Daniel Holbach UUbbuunnttuu DDeevveellooppmmeenntt PPtt.. 33 -- BBuugg FFiixxiinngg
Ifyou followed theinstructions to get set up withUbuntu Development, youshould be all set and ready to
go.
As you can see in the imageshiwn right, there are no surprisesin the process of fixing bugs inUbuntu: you found a problem, youget the code, work on the fix, testit, push your changes toLaunchpad, and ask for it to bereviewed and merged. In thisguide we will go through all thenecessary steps one-by-one.
Finding the problem
There are a lot of differentways to find things to work on. Itmight be a bug report you areencountering yourself (which givesyou a good opportunity to test thefix), or a problem you notedelsewhere, maybe in a bug report.
Harvest is where we keep trackof various TODO lists regardingUbuntu development. It lists bugsthat were fixed upstream or in
Debian already,lists small bugs(we call them‘bitesize’), and soon. Check it outand find your firstbug to work on.
Figuring outwhat to fix
If you don’tknow the sourcepackagecontaining the code that has theproblem, but you do know thepath to the affected program onyour system, you can discover thesource package that you’ll need towork on.
Let’s say you’ve found a bug inTomboy, a note taking desktopapplication. The Tomboyapplication can be started byrunning /usr/bin/tomboy on thecommand line. To find the binarypackage containing thisapplication, use this command:
apt-file find /usr/bin/tomboy
This would print out:
tomboy: /usr/bin/tomboy
Note that the part precedingthe colon is the binary packagename. It’s often the case that thesource package and binarypackage will have different names.This is most common when a singlesource package is used to buildmultiple different binary packages.To find the source package for aparticular binary package, type:
apt-cache show tomboy | grep^Source:
In this case, nothing is printed,meaning that tomboy is also thename of the binary package. Anexample where the source andbinary package names differ ispython-vigra. While that is thebinary package name, the sourcepackage is actually libvigraimpexand can be found with thiscommand (and its output):
apt-cache show python-vigra| grep ^Source:
Source: libvigraimpex
full circle magazine #51 18 contents ^
HOWTO - UBUNTU DEVELOPMENT 3 - BUG FIXING
Getting the code
Once you know the sourcepackage to work on, you will wantto get a copy of the code on yoursystem, so that you can debug it.This is done by *branching* thesource package branchcorresponding to the sourcepackage. Launchpad maintainssource package branches for allthe packages in Ubuntu. Onceyou’ve got a local branch of thesource package, you caninvestigate the bug, create a fix,and upload your proposed fix toLaunchpad, in the form of a Bazaarbranch. When you are happy withyour fix, you can submit a *mergeproposal*, which asks otherUbuntu developers to review andapprove your change. If they agreewith your changes, an Ubuntudeveloper will upload the newversion of the package to Ubuntuso that everyone gets the benefitof your excellent fix - and you geta little bit of credit. You’re now onyour way to becoming an Ubuntudeveloper! We’ll describe specificson how to branch the code, pushyour fix, and request a review inthe following sections.
Work on a fix
There are entire books writtenabout finding bugs, fixing them,testing them, etc. If you arecompletely new to programming,try to fix easy bugs such as obvioustypos first. Try to keep changes asminimal as possible and documentyour change and assumptionsclearly.
Before working on a fixyourself, make sure to investigateif nobody else has fixed it alreadyor is currently working on a fix.Good sources to check are:
• Upstream (and Debian) bugtracker (open and closed bugs),
• Upstream revision history (ornewer release) might have fixedthe problem,
• bugs or package uploads ofDebian or other distributions.
If you find a patch to fix theproblem, say, attached to a bugreport, running this command inthe source directory should applythe patch:
patch -p1 < ../bugfix.patch
Refer to the patch(1) manpage
for options and arguments such as --dry-run, -p<num>, etc.
Testing the fix
To build a test package withyour changes, run thesecommands:
bzr bd -- -S -us -uc
pbuilder-dist <release>build../<package>_<version>.dsc
This will create a sourcepackage from the branch contents(-us -uc will just omit the step tosign the source package) andpbuilder-dist will build the packagefrom source for whatever releaseyou choose.
Once the build succeeds, installthe package from~/pbuilder/<release>_result/(using sudo dpkg -i<package>_<version>.deb). Thentest to see if the bug is fixed.
Documenting the fix
It is very important todocument your change sufficientlyso developers who look at thecode in the future won’t have to
guess what your reasoning wasand what your assumptions were.Every Debian and Ubuntu packagesource includes debian/changelog,where changes of each uploadedpackage are tracked.
The easiest way to update thisis to run:
dch -i
This will add a boilerplatechangelog entry for you andlaunch an editor where you can fillin the blanks. An example of thiscould be:
specialpackage (1.2-3ubuntu4) natty; urgency=low* debian/control: updated
description to includefrobnicator (LP: #123456)-- Emma Adams<[email protected]> Sat,17 Jul 2010 02:53:39 +0200
dch should fill out the first andlast line of such a changelog entryfor you already. Line 1 consists ofthe source package name, theversion number, which Ubunturelease it is uploaded to, theurgency (which almost always is‘low’). The last line always containsthe name, email address andtimestamp (in RFC 5322 format) ofthe change.
full circle magazine #51 19 contents ^
With that out of the way, let’sfocus on the actual changelogentry itself: it is very important todocument:• where the change was done• what was changed• where the discussion of thechange happened
In our (very sparse) example,the last point is covered by (LP:#123456) which refers toLaunchpad bug 123456. Bugreports or mailing list threads orspecifications are usually goodinformation to provide as arationale for a change. As a bonus,if you use the LP: #<number>notation for Launchpad bugs, thebug will be automatically closedwhen the package is uploaded toUbuntu.
Committing the fix
With the changelog entrywritten and saved, you can just run:
debcommit
and the change will becommitted (locally) with yourchangelog entry as a commitmessage.
To push it to Launchpad, as theremote branch name, you need tostick to the followingnomenclature:
lp:~<yourlpid>/ubuntu/<release>/<package>/<branchname>
This could, for example, be
lp:~emmaadams/ubuntu/natty/specialpackage/fix-for-123456
So, if you just run
bzr pushlp:~emmaadams/ubuntu/natty/specialpackage/fix-for-123456
bzr lp-open
you should be all set. The pushcommand should push it toLaunchpad, and the secondcommand will open the Launchpadpage of the remote branch in yourbrowser. There, find the “(+)Propose for merging” link, andclick it to get the change reviewedby somebody and included inUbuntu.
Next month: an overview of theDebian directory structure.
HOWTO - UBUNTU DEVELOPMENT 3 - BUG FIXING
Z e r o D ow n t i m e
Below Zero is a Co-located Server Hosting specialist in the UK.
Uniquely we only provide rack spaceand bandwidth. This makes our servicemore reliable, more flexible, morefocused and more competitivelypriced. We concentrate solely on thehosting of Co-located Servers and theirassociated systems, within Scotland'sData Centres.
At the heart of our networkinginfrastructure is state-of-the-art BGP4routing that offers optimal datadelivery and automatic multihomedfailover between our outstandingproviders. Customers may rest assuredthat we only use the highest quality ofbandwidth; our policy is to pay more for the best of breed providersand because we buy in bulk this doesn't impact our extremelycompetitive pricing.
At Below Zero we help you to achieve Zero Downtime.
www.zerodowntime.co.uk
full circle magazine #52 19 contents ^
HHOOWW--TTOOWritten by Daniel Holbach UUbbuunnttuu DDeevveellooppmmeenntt PPtt.. 44 -- ddeebbiiaann//
This article will brieflyexplain the different filesimportant to thepackaging of Ubuntu
packages which are contained inthe debian/ directory. The mostimportant of them are changelog,control, copyright, and rules. Theseare required for all packages. Anumber of additional files indebian/ may be used in order tocustomize and configure thebehavior of the package. Some ofthese files are discussed in thisarticle, but this is not meant to bea complete list.
The Changelog
This file is, as its name implies,a listing of the changes made ineach version. It has a specificformat that gives the packagename, version, distribution,changes, and who made thechanges at a given time. If youhave a GPG key (see: Getting setup) make sure to use the samename and email address inchangelog as you have in your key.The following is a template
changelog:
package (version)distribution; urgency=urgency
* change details- more change details* even more change details
-- maintainer name <emailaddress>[two spaces] date
The format (especially of thedate) is important. The dateshould be in RFC 5322 format,which can be obtained by using thecommand date -R. Forconvenience, the command dchmay be used to edit changelog. Itwill update the date automatically.Minor bullet points are indicatedby a dash “-“, while major pointsuse an asterisk “*”. If you arepackaging from scratch, dch --create (dch is in the devscriptspackage) will create a standarddebian/changelog for you.
Here is a sample changelog filefor hello:
hello (2.6-0ubuntu1) natty;urgency=low
* New upstream releasewith lots of bug fixes andfeature improvements.
-- Jane Doe<[email protected]> Thu,21 Apr 2011 11:12:00 -0400
Notice that the version has a -0ubuntu1 appended to it, this isthe distro revision, used so thatthe packaging can be updated (tofix bugs for example) with newuploads within the same sourcerelease version.
Ubuntu and Debian haveslightly different packageversioning schemes to avoidconflicting packages with the samesource version. If a Debian packagehas been changed in Ubuntu, it hasubuntuX (where X is the Ubunturevision number) appended to theend of the Debian version. So, ifthe Debian hello 2.6-1 packagewas changed by Ubuntu, theversion string would be 2.6-1ubuntu1. If a package for theapplication does not exist inDebian, then the Debian revision is0 (e.g. 2.6-0ubuntu1).
For further information, see thechangelog section (Section 4.4) ofthe Debian Policy Manual.
The Control File
The control file contains theinformation that the packagemanager (such as apt-get, synaptic,and adept) uses, build-timedependencies, maintainerinformation, and much more.
For the Ubuntu hello package,the control file looks somethinglike:
Source: helloSection: develPriority: optionalMaintainer: UbuntuDevelopers <[email protected]>XSBC-Original-Maintainer:Jane Doe<[email protected]>Standards-Version: 3.9.1Build-Depends: debhelper (>=7)Bzr-Vcs: lp:ubuntu/helloHomepage:http://www.gnu.org/software/hello/
Package: hello
full circle magazine #52 20 contents ^
HOWTO - UBUNTU DEVELOPMENT 4 - debian/Architecture: anyDepends: ${shlibs:Depends}Description: The classicgreeting, and a good exampleThe GNU hello programproduces a familiar,friendly greeting. It allowsnon-programmers to use aclassic computer sciencetool which would otherwisebe unavailable to them.Seriously, though: this isan example of how to do aDebian package. It is theDebian version of the GNUProject's `hello world'program (which is itself anexample for the GNU Project).
The first paragraph describesthe source package - including thelist of packages required to buildthe package from source in theBuild-Depends field. It alsocontains some meta-informationsuch as the maintainer’s name, theversion of Debian Policy that thepackage complies with, thelocation of the packaging versioncontrol repository, and theupstream home page.
Note that, in Ubuntu, we setthe Maintainer field to a generaladdress because anyone canchange any package (this differsfrom Debian where changingpackages is usually restricted to anindividual or a team). Packages in
Ubuntu should generally have theMaintainer field set to UbuntuDevelopers <[email protected]>. If theMaintainer field is modified, theold value should be saved in theXSBC-Original-Maintainer field.This can be done automaticallywith the update-maintainer scriptavailable in the ubuntu-dev-toolspackage. For further information,see the Debian Maintainer Fieldspec on the Ubuntu wiki.
Each additional paragraphdescribes a binary package to bebuilt.
For further information, see thecontrol file section (Chapter 5) ofthe Debian Policy Manual.
The Copyright File
This file gives the copyrightinformation for both the upstreamsource and the packaging. Ubuntuand Debian Policy (Section 12.5)require that each package installsa verbatim copy of its copyrightand license information to/usr/share/doc/$(package_name)/copyright.
Generally, copyright
information is found in theCOPYING file in the program’ssource directory. This file shouldinclude such information as thenames of the author and thepackager, the URL from which thesource came, a Copyright line withthe year and copyright holder, andthe text of the copyright itself. Anexample template would be:
Format:http://svn.debian.org/wsvn/dep/web/deps/dep5.mdwn?op=file&rev=166Upstream-Name: HelloSource:ftp://ftp.example.com/pub/games
Files: *Copyright: Copyright 1998John Doe <[email protected]>License: GPL-2+This program is freesoftware; you canredistribute it and/ormodify it under the terms ofthe GNU General PublicLicense as published by theFree Software Foundation;either version 2 of theLicense, or (at your option)any later version..This program is distributedin the hope that it will beuseful, but WITHOUT ANYWARRANTY; without even theimplied warranty ofMERCHANTABILITY or FITNESSFOR A PARTICULAR PURPOSE.
See the GNU General PublicLicense for more details..You should have received acopy of the GNU GeneralPublic License along withthis package; if not, writeto the Free SoftwareFoundation, Inc., 51Franklin St, Fifth Floor,Boston, MA 02110-1301 USA.On Debian systems, the fulltext of the GNU GeneralPublic License version 2 canbe found in the file`/usr/share/common-licenses/GPL-2'.
Files: debian/*Copyright: Copyright 1998Jane Doe<[email protected]>License: GPL-2+
This example follows the DEP-5: Machine-parseabledebian/copyright proposal. Youare encouraged to use this formatas well.
The Rules File
The last file we need to look atis rules. This does all the work forcreating our package. It is aMakefile with targets to compileand install the application, thencreate the .deb file from theinstalled files. It also has a target
full circle magazine #52 21 contents ^
to clean up all the build files soyou end up with just a sourcepackage again.
Here is a simplified version ofthe rules file created by dh_make(which can be found in the dh-make package):
#!/usr/bin/make -f# -*- makefile -*-
# Uncomment this to turn onverbose mode.#export DH_VERBOSE=1
%:dh $@
Let us go through this file insome detail. What this does is passevery build target thatdebian/rules is called with as anargument to /usr/bin/dh, whichitself will call all the necessarydh_* commands.
dh runs a sequence ofdebhelper commands. Thesupported sequences correspondto the targets of a debian/rulesfile: “build”, “clean”, “install”,“binary-arch”, “binary-indep”, and“binary”. In order to see whatcommands are run in each target,run:
dh binary-arch --no-act
Commands in the binary-indepsequence are passed the “-i”option to ensure they work only onbinary independent packages, andcommands in the binary-archsequences are passed the “-a”option to ensure they work only onarchitecture dependent packages.
Each debhelper command willrecord when it’s successfully run indebian/package.debhelper.log.(Which dh_clean deletes.) So dhcan tell which commands havealready been run, for whichpackages, and skip running thosecommands again. Each time dh isrun, it examines the log, and findsthe last logged command that is inthe specified sequence. It thencontinues with the next command
in the sequence. The --until, --before, --after, and --remainingoptions can override this behavior.
If debian/rules contains atarget with a name likeoverride_dh_command, then whenit gets to that command in thesequence, dh will run that targetfrom the rules file, rather thanrunning the actual command. Theoverride target can then run thecommand with additional options,or run entirely differentcommands instead. (Note that touse this feature, you should Build-Depend on debhelper 7.0.50 orabove.)
Have a look at/usr/share/doc/debhelper/examples/ and man dh for more examples.
Also see the rules section (Section4.9) of the Debian Policy Manual.
Additional Files
The Install File
The install file is used bydh_install to install files into thebinary package. It has twostandard use cases:
• To install files into yourpackage that are not handled bythe upstream build system.
• Splitting a single large sourcepackage into multiple binarypackages.
In the first case, the install fileshould have one line per fileinstalled, specifying both the fileand the installation directory. Forexample, the following install filewould install the script foo in thesource package’s root directory tousr/bin, and a desktop file in thedebian directory tousr/share/applications:
foo usr/bindebian/bar.desktopusr/share/applications
When a source package isproducing multiple binary
HOWTO - UBUNTU DEVELOPMENT 4 - debian/
full circle magazine #52 22 contents ^
packages, dh will install the filesinto debian/tmp rather thandirectly into debian/<package>.Files installed into debian/tmp canthen be moved into separatebinary packages using multiple$package_name.install files. This isoften done to split large amountsof architecture independent dataout of architecture dependentpackages and into Architecture: allpackages. In this case, only thename of the files (or directories) tobe installed are needed withoutthe installation directory. Forexample, foo.install containingonly the architecture dependentfiles might look like:
usr/bin/usr/lib/foo/*.so
While foo-common.installcontaining only the architectureindependent file might look like:
/usr/share/doc//usr/share/icons//usr/share/foo//usr/share/locale/
This would create two binarypackages, foo and foo-common.Both would require their ownparagraph in debian/control.
See man dh_install and the
install file section (Section 5.11) ofthe Debian New Maintainers’Guide for additional details.
The Watch File
The debian/watch file allows usto check automatically for newupstream versions using the tooluscan found in the devscriptspackage. The first line of thewatch file must be the formatversion (3, at the time of thiswriting), while the following linescontain any URLs to parse. Forexample:
version=3http://ftp.gnu.org/gnu/hello/hello-(.*).tar.gz
Running uscan in the rootsource directory will now comparethe upstream version number indebian/changelog with the latestavailable upstream version. If anew upstream version is found, itwill be automatically downloaded.For example:
$ uscanhello: Newer version (2.7)available on remote site:
http://ftp.gnu.org/gnu/hello/hello-2.7.tar.gz
(local version is 2.6)hello: Successfully
downloaded updated packagehello-2.7.tar.gz
and symlinkedhello_2.7.orig.tar.gz to it
For further information, seeman uscan and the watch filesection (Section 4.11) of theDebian Policy Manual.
For a list of packages where thewatch file reports they are not insync with upstream, see UbuntuExternal Health Status.
The Source/Format File
This file indicates the format ofthe source package. Currently, thepackage source format defaults to1.0 if this file does not exist. Youare encouraged to use the newer3.0 source format. In this case, thefile should contain a single lineindicating the desired format:
• 3.0 (native) for Debian nativepackages (no upstream version) or
• 3.0 (quilt) for packages with aseparate upstream tarball
If, for some reason, you wish tokeep using the old format, pleasecreate this file and put 1.0 in it tobe explicit about the sourcepackage version. This allows forthe future removal of the 1.0
default for the package sourceformat.
http://wiki.debian.org/Projects/DebSrc3.0 summarizes informationconcerning, and the benefits ofthe switch to, the 3.0 sourcepackage formats.
See man dpkg-source and thesource/format section (Section5.21) of the Debian NewMaintainers’ Guide for additionaldetails.
Additional Resources
In addition to the links to theDebian Policy Manual in eachsection above, the Debian NewMaintainers’ Guide has moredetailed descriptions of each file.Chapter 4, “Required files underthe debian directory” furtherdiscusses the control, changelog,copyright, and rules files. Chapter5, “Other files under the debiandirectory” discusses additionalfiles that may be used.
HOWTO - UBUNTU DEVELOPMENT 4 - debian/
