Full Circle THE INDEPENDENT MAGAZINE FOR THE UBUNTU COMMUNITY

UBUNTU DEVELOPMENT SERIES SPECIAL EDITION

SINGLE TOPIC SERIES FROM MAGAZINE ISSUES #49 - #52 Full Circle Magazine is neither affiliated, with nor endorsed by, Canonical Ltd. Full Circle Magazine Specials About Full Circle Full Circle is a free, Find Us independent, magazine Website: dedicated to the Ubuntu http://www.fullcirclemagazine.org/ family of Linux operating systems. Each month, it Forums: contains helpful how-to http://ubuntuforums.org/ articles and reader- forumdisplay.php?f=270 submitted stories. Welcome to another 'single-topic special' IRC: #fullcirclemagazine on Full Circle also features a In response to reader requests, we are assembling the chat.freenode.net companion podcast, the Full content of some of our serialised articles into dedicated Editorial Team Circle Podcast which covers editions. the magazine, along with Editor: Ronnie Tucker other news of interest. For now, this is a straight reprint of the series 'Ubuntu (aka: RonnieTucker) Development', Parts 1-4, by Daniel Holbach from issues [email protected] Please note: this Special #49 through #52; nothing fancy, just the facts. Webmaster: Rob Kerfia Edition is provided with (aka: admin / linuxgeekery- Please bear in mind the original publication date; current [email protected] absolutely no warranty versions of hardware and software may differ from those whatsoever; neither the Podcaster: Robin Catling contributors nor Full Circle illustrated, so check your hardware and software versions before attempting to emulate the tutorials in these special (aka RobinCatling) Magazine accept any [email protected] responsibility or liability for editions. You may have later versions of software installed loss or damage resulting from or available in your distributions' repositories. Communications Manager: readers choosing to apply this Robert Clipsham content to theirs or others Enjoy! (aka: mrmonday) - computers and equipment. [email protected]

The articles contained in this magazine are released under the Creative Commons Attribution-Share Alike 3.0 Unported 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.

Full Circle Magazine HHOOWW--TTOO Written by Daniel Holbach IInnttrroo TToo UUbbuunnttuu DDeevveellooppmmeenntt

buntu is made up of to an archive or mirror. Every day strict freeze dates. With every fixed, and a release candidate thousands of different CD images are built for a selection freeze date that is reached, release is made, and if it does not components, written in of different Ubuntu flavours. developers are expected to make contain any serious problems, it U many different Ubuntu Desktop, Ubuntu Server, fewer, less-intrusive changes. becomes the final release. programming languages. Every Kubuntu, and others, specify a list Feature Freeze is the first big component - be it a software of required packages that get on freeze date after the first half of Thousands of source packages, library, a tool, or a graphical the CD. These CD images are then the cycle has passed. At this stage, billions of lines of code, and application - is available as a used for installation tests, and features must be largely hundreds of contributors, require source package. Source packages provide the feedback for further implemented. The rest of the cycle a lot of communication and in most cases consist of two parts: release planning. is supposed to be focused on planning to maintain high the actual source code, and fixing bugs. After that, the user standards of quality. At the metadata. Metadata includes the Ubuntu’s development is very interface, then the beginning of each release cycle, dependencies of the package, much dependent on the current documentation, the kernel, etc, we have the Ubuntu Developer copyright and licensing stage of the release cycle. We are frozen, then the beta release is Summit where developers and information, and instructions on release a new version of Ubuntu put out which receives a lot of contributors come together to how to build the package. Once every six months, which is possible testing. From the beta release plan the features of the next this source package is compiled, only because we have established onwards, only critical bugs get releases. Every feature is the build process provides binary packages, which are the .deb files users can install.

Every time a new version of an application is released, or when someone makes a change to the source code that goes into Ubuntu, the source package must be uploaded to the build machines to be compiled. The resulting binary packages then are distributed to the archive and its mirrors in different countries. The URLs in /etc/apt/sources.list point

full circle magazine #49 17 contents ^ HOWTO - INTRO TO UBUNTU DEVELOPMENT discussed by its stakeholders, and a specification is written that contains detailed information about its assumptions, implementation, the necessary changes in other places, how to test it, and so on. This is all done in an open and transparent fashion, so even if you cannot attend the event in person, you can participate remotely and listen to a streamcast, chat with attendants, and subscribe to changes of specifications - so you are always up to date. collected in that report and its Upstreams get users, bug reports, willingness. Not every single change can be importance, status, and assignee, and patches, from Ubuntu (and discussed in a meeting though, updated when necessary. This other distributions). Getting a change into Ubuntu particularly because Ubuntu relies makes it an effective tool to stay as a new contributor is not as on changes that are done in other on top of bugs in a package or The most important Upstream daunting as it seems, and can be a projects. That is why contributors project, and organise the workload. for Ubuntu is Debian. Debian is the very rewarding experience. It is to Ubuntu constantly stay in touch. distribution that Ubuntu is based not only about learning something Most teams or projects use Most of the software available on, and many of the design new and exciting, but also about dedicated mailing lists to avoid too through Ubuntu is not written by decisions regarding the packaging sharing the solution, and solving a much unrelated noise. For more Ubuntu developers themselves. infrastructure are made there. problem for millions of users out immediate coordination, Most of it is written by developers Traditionally, Debian has always there. developers and contributers use of other Open Source projects, and had dedicated maintainers for Internet Relay Chat (IRC). All then integrated into Ubuntu. every single package or dedicated Open Source Development discussions are open and public. These projects are called maintenance teams. In Ubuntu happens in a distributed world “Upstreams”, because their source there are teams that have an with different goals and different Another important tool code flows into Ubuntu, where we interest in a subset of packages areas of focus. For example, there regarding communication is bug “just” integrate it. The relationship too, and naturally every developer might be the case that a particular reports. Whenever a defect is to Upstreams is critically has a special area of expertise, but Upstream might be interested in found in a package or piece of important to Ubuntu. It is not just participation (and upload rights) working on a new big feature, infrastructure, a bug report is filed code that Ubuntu gets from generally is open to everyone who while Ubuntu, because of the tight in Launchpad. All information is Upstreams, but it is also that demonstrates ability and release schedule, might be

full circle magazine #49 18 contents ^ HOWTO - INTRO TO UBUNTU DEVELOPMENT interested in shipping a solid and users, then build the package again,” not being afraid version with just an additional bug to test it. After you have tested it, to read documentation A PLEA ON BEHALF OF THE fix. That is why we make use of you can easily propose the change and ask questions, being “Distributed Development”, where to be included in the current a team player, and PODCAST PARTY code is being worked on in various Ubuntu development release. A enjoying some detective branches that are merged with developer with upload rights will work. As you heard in episode #15 of the each other after code reviews and review it for you, and then get it podcast, we're calling for opinion topics sufficient discussion. integrated into Ubuntu. Good places to ask for that section of the show. your questions are In the example mentioned When trying to find a solution, ubuntu-motu- Instead of us having a rant about above, it would make sense to ship it is usually a good idea to check [email protected] whatever strikes us, why not prompt us Ubuntu with the existing version with Upstream and see if the m and #ubuntu-motu on with a topic and watch for the mushroom of the project, add the bugfix, get problem (or a possible solution) is irc.freenode.net. You will clouds over the horizon! It's highly it into Upstream for their next known already, and, if not, do your easily find a lot of new unlikely that the three of us will agree. release, and ship that (if suitable) best to make the solution a friends and people with in the next Ubuntu release. It concerted effort. Additional steps the same passion that Or, an even more radical thought, send us would be the best possible might involve getting the change you have: making the an opinion by way of a contribution! compromise and a situation where backported to an older, still world a better place by everybody wins. supported, version of Ubuntu, and making better Open You can post comments and opinions on forwarding it to Upstream. Source software. the podcast page at To fix a bug in Ubuntu, you fullcirclemagazine.org, in our Ubuntu would first get the source code for The most important Forums section, or email the package, then work on the fix, requirements for success in [email protected]. You can document it so it is easy to Ubuntu development are having a also send us a comment by recording an understand for other developers knack for “making things work audio clip of no more than 30 seconds and sending it to the same address. Comments and audio may be edited for length. Please remember this is a family-friendly show.

It would be great to have contributors come on the show and express an opinion in person.

full circle magazine #49 19 contents ^ HHOOWW--TTOO Written by Daniel Holbach UUbbuunnttuu DDeevveellooppmmeenntt PPtt.. 22-- SSeett UUpp

here are a number of changes in the same environment create a cryptographic key with things you need to do to where those changes will actually which you will sign files you want get started developing be applied and used. to upload to Launchpad. T for Ubuntu. This article is pbuilder – a tool to do designed to get your computer set Don’t worry, though, the reproducible builds of a package in up so that you can start working Ubuntu development release wiki a clean and isolated environment. number of purposes. In our case, it with packages, and upload your page ubuntu-dev-tools (and devscripts, is important that you can sign files packages to Launchpad. Here’s (https://wiki.ubuntu.com/UsingDev a direct dependency) – a collection with your key so they can be what we’ll cover: elopmentReleases) shows a of tools that make many packaging identified as something that you variety of ways to safely use the tasks easier. worked on. If you upload a source • Installing packaging-related development release. bzr-builddeb (and bzr, a package to Launchpad, it will software. This includes: dependency) – distributed version- accept the package only if it can • Ubuntu-specific packaging control tools that make it easy for Install Basic Packaging absolutely determine who utilities many developers to collaborate uploaded the package. • Encryption software so your Software and work on the same code while work can be verified as being done keeping it trivial to merge each There are a number of tools To generate a new GPG key, run: by you other’s work. that will make your life as an • Additional encryption software apt-file provides an easy way to Ubuntu developer much easier. gpg --gen-key so you can securely transfer files find the binary package that You will encounter these tools • Creating and configuring your contains a given file. later in this guide. To install most GPG will first ask you which account on Launchpad apt-cache (part of the apt of the required tools, run this kind of key you want to generate. • Setting up your development package) provides even more command: Choosing the default (RSA and environment to help you do local information about packages on DSA) is fine. Next it will ask you builds of packages, interact with Ubuntu. sudo apt-get install gnupg about the keysize. The default other developers, and propose pbuilder ubuntu-dev-tools (currently 2048) is fine, but 4096 is your changes on Launchpad. bzr-builddeb apt-file Create your GPG key more secure. Afterwards, it will ask you if you want it to expire the This command will install the GPG stands for GNU Privacy key at some stage. It is safe to say Note: It is advisable to do following software: Guard and it implements the “0”, which means the key will never packaging work using the current OpenPGP standard which allows expire. The last questions will be development version of Ubuntu. gnupg – GNU Privacy Guard you to sign and encrypt messages about your name and email Doing so will allow you to test contains tools you will need to and files. This is useful for a address. Just pick the ones you are

full circle magazine #50 17 contents ^ HOWTO - UBUNTU DEVELOPMENT 2 - SET UP going to use for Ubuntu gpg --send-keys development here, you can add Pbuilder allows additional email addresses later This will send your key to one you to build packages on. Adding a comment is not keyserver, but a network of locally on your necessary. Then you will have to keyservers will automatically sync machine. It serves a set a passphrase. Choose a safe the key between themselves. Once couple of purposes: case of Debian, maybe sid. This will one. this syncing is complete, your take a while as it will download all signed public key will be ready to • The build will be done in a the necessary packages for a Now GPG will create a key for verify your contributions around minimal and clean environment. “minimal installation”. These will you, which can take a little bit of the world. This helps you make sure your be cached though. time; it needs random bytes, so if builds succeed in a reproducible you give the system some work to Create your SSH key way, but without modifying your Get Set Up To Work do it will be just fine. Move the local system. With Launchpad cursor around! SSH stands for Secure Shell, • There is no need to install all and it is a protocol that allows you necessary build dependencies With a basic local configuration Once this is done, you will get a to exchange data in a secure way locally. in place, your next step will be to message similar to this one: over a network. It is common to • You can set up multiple instances configure your system to work use SSH to access and open a shell for various Ubuntu and Debian with Launchpad. This section will pub 4096R/43CDE61D 2010-12- on another computer, and to use it releases. 06 focus on the following topics: Key fingerprint = 5C28 0144 to securely transfer files. For our FB08 91C0 2CF3 37AC 6F0B purposes, we will mainly be using Setting pbuilder up is very easy. • What Launchpad is, and creating F90F 43CD E61D SSH to securely communicate with Edit ~/.pbuilderrc and add the a Launchpad account uid Daniel Launchpad. following line to it: Holbach • Uploading your GPG and SSH keys sub 4096R/51FBE68C 2010-12- to Launchpad 06 To generate a SSH key, enter: COMPONENTS="main universe multiverse restricted" • Configuring Bazaar to work with Launchpad In this case 43CDE61D is the ssh-keygen -t rsa This will ensure that build • Configuring to work with key ID. The default file name usually dependencies are satisfied using Bazaar all components. Then run: Next, you need to upload the makes sense, so you can just leave public part of your key to a it as it is. For security purposes, it About Launchpad is highly recommended that you pbuilder-dist keyserver so the world can identify create messages and files as yours. To do use a passphrase. Launchpad is the central piece so, enter: where is, for example, of infrastructure we use in Ubuntu. Set up pbuilder natty, maverick, lucid, or, in the It not only stores our packages and

full circle magazine #50 18 contents ^ HOWTO - UBUNTU DEVELOPMENT 2 - SET UP our code, but also things like that your Ubuntu developer sub 4096R/51FBE68C 2010-12- window. translations, bug reports and colleagues will be able to get to 06 information about the people who know you better. Back on the Launchpad work on Ubuntu and their team Head to website, use the Confirm button memberships. You will also use When you register a new https://launchpad.net/people/+me and Launchpad will complete the Launchpad to publish your account, Launchpad will send you /+editpgpkeys and copy the part import of your OpenPGP key. proposed fixes, and get other an email with a link you need to about your “Key fingerprint” into Ubuntu developers to review and open in your browser in order to the text box. In the case above this Find more information at sponsor them. verify your email address. If you would be 5C28 0144 FB08 91C0 https://help.launchpad.net/YourAc don’t receive it, check in your spam 2CF3 37AC 6F0B F90F 43CD E61D. count/ImportingYourPGPKey You will need to register with folder. Now click on “Import Key”. Launchpad and provide a minimal Upload your SSH key to amount of information. This will The new account help page Launchpad will use the allow you to download and upload (https://help.launchpad.net/YourAc fingerprint to check the Ubuntu Launchpad code, submit bug reports, and count/NewAccount) on Launchpad key server for your key and, if more. has more information about the successful, send you an encrypted Open process, and additional settings email asking you to confirm the https://launchpad.net/people/+me you can change. key import. Check your email /+editsshkeys in a web browser, Get a Launchpad account, and read the email that also open ~/.ssh/id_rsa.pub in a account Upload your GPG key to Launchpad sent you. If your email text editor. This is the public part Launchpad client supports OpenPGP of your SSH key, so it is safe to If you don’t already have a encryption, it will prompt you for share it with Launchpad. Copy the Launchpad account, you can easily To find out about your GPG the password you chose for the contents of the file and paste create one (at: fingerprint, run: key when GPG generated it. Enter them into the text box on the web https://launchpad.net/+login). If the password, then click the link to page that says “Add an SSH key”. you have a Launchpad account but gpg --fingerprint confirm that the key is yours. Now click “Import Public Key”. cannot remember your Launchpad id, you can find this out by going to Launchpad encrypts the email, For more information on this https://launchpad.net/people/+me, and it will print out something using your public key, so that it can process, visit the creating an SSH and looking for the part after the like: be sure that the key is yours. If keypair page ~ in the URL. your email software does not (https://help.launchpad.net/YourAc pub 4096R/43CDE61D 2010-12- support OpenPGP encryption, 06 count/CreatingAnSSHKeyPair) on Launchpad’s registration Key fingerprint = 5C28 0144 copy the encrypted email’s Launchpad. process will ask you to choose a FB08 91C0 2CF3 37AC 6F0B contents, type gpg in your display name. It is encouraged for F90F 43CD E61D terminal, then paste the email Configure Bazaar uid Daniel contents into your terminal you to use your real name here so Holbach

full circle magazine #50 19 contents ^ HOWTO - UBUNTU DEVELOPMENT 2 - SET UP Bazaar is the tool we use to store code changes in a logical export DEBFULLNAME="Bob way, to exchange proposed Dobbs" A PLEA ON BEHALF OF THE changes and merge them, even if export PODCAST PARTY development is done concurrently. DEBEMAIL="[email protected] To tell Bazaar who you are, simply om" As you heard in episode #15 of the podcast, run: we're calling for opinion topics for that section Now save the file, and either of the show. bzr whoami "Bob Dobbs restart your terminal or run: " Instead of us having a rant about whatever source ~/.bashrc bzr launchpad-login subgenius strikes us, why not prompt us with a topic and watch for the mushroom clouds over the (If you use a shell different horizon! It's highly unlikely that the three of us whoami will tell Bazaar which from the default (which is bash), will agree. name and email address it should please edit the configuration file use for your commit messages. for that shell accordingly.) With launchpad-login you set your Or, an even more radical thought, send us an opinion by way of a contribution! Launchpad ID. This way, code that NEXT MONTH: Fixing a bug you publish in Launchpad will be associated with you. You can post comments and opinions on the podcast page at fullcirclemagazine.org, in our Note: If you can not remember Ubuntu Forums section, or email the ID, go to [email protected]. You can also https://launchpad.net/people/+me send us a comment by recording an audio clip and see where it redirects you. The of no more than 30 seconds and sending it to part after the “~” in the URL is your the same address. Comments and audio may Launchpad ID.) be edited for length. Please remember this is a family-friendly show. Configure your shell It would be great to have contributors come on the show Similar to Bazaar, the and express an opinion in Debian/Ubuntu packaging tools person. need to learn about you as well. Simply open your ~/.bashrc in a Robin text editor, and add something like this to the bottom of it:

full circle magazine #50 20 contents ^ HHOOWW--TTOO Written by Daniel Holbach UUbbuunnttuu DDeevveellooppmmeenntt PPtt.. 33 -- BBuugg FFiixxiinngg

f you followed the Debian already, instructions to get set up with lists small bugs Ubuntu Development, you (we call them I should be all set and ready to ‘bitesize’), and so go. on. Check it out and find your first As you can see in the image bug to work on. shiwn right, there are no surprises in the process of fixing bugs in Figuring out Ubuntu: you found a problem, you get the code, work on the fix, test what to fix it, push your changes to If you don’t Launchpad, and ask for it to be know the source reviewed and merged. In this package guide we will go through all the containing the code that has the necessary steps one-by-one. problem, but you do know the This would print out: In this case, nothing is printed, path to the affected program on meaning that tomboy is also the Finding the problem your system, you can discover the tomboy: /usr/bin/tomboy name of the binary package. An source package that you’ll need to example where the source and There are a lot of different work on. Note that the part preceding binary package names differ is ways to find things to work on. It the colon is the binary package python-vigra. While that is the might be a bug report you are Let’s say you’ve found a bug in name. It’s often the case that the binary package name, the source encountering yourself (which gives Tomboy, a note taking desktop source package and binary package is actually libvigraimpex you a good opportunity to test the application. The Tomboy package will have different names. and can be found with this fix), or a problem you noted application can be started by This is most common when a single command (and its output): elsewhere, maybe in a bug report. running /usr/bin/tomboy on the source package is used to build command line. To find the binary multiple different binary packages. apt-cache show python-vigra Harvest is where we keep track package containing this To find the source package for a | grep ^Source: of various TODO lists regarding application, use this command: particular binary package, type: Ubuntu development. It lists bugs Source: libvigraimpex that were fixed upstream or in apt-file find /usr/bin/tomboy apt-cache show tomboy | grep ^Source:

full circle magazine #51 17 contents ^ HOWTO - UBUNTU DEVELOPMENT 3 - BUG FIXING Getting the code for options and arguments such as - guess what your reasoning was There are entire books written -dry-run, -p, etc. and what your assumptions were. Once you know the source about finding bugs, fixing them, Every Debian and Ubuntu package package to work on, you will want testing them, etc. If you are Testing the fix source includes debian/changelog, to get a copy of the code on your completely new to programming, where changes of each uploaded system, so that you can debug it. try to fix easy bugs such as obvious To build a test package with package are tracked. This is done by *branching* the typos first. Try to keep changes as your changes, run these source package branch minimal as possible and document commands: The easiest way to update this corresponding to the source your change and assumptions is to run: package. Launchpad maintains clearly. bzr bd -- -S -us -uc source package branches for all dch -i pbuilder-dist the packages in Ubuntu. Once Before working on a fix build This will add a boilerplate you’ve got a local branch of the yourself, make sure to investigate ../_.dsc changelog entry for you and source package, you can if nobody else has fixed it already launch an editor where you can fill investigate the bug, create a fix, or is currently working on a fix. This will create a source in the blanks. An example of this and upload your proposed fix to Good sources to check are: package from the branch contents could be: Launchpad, in the form of a Bazaar (-us -uc will just omit the step to branch. When you are happy with • Upstream (and Debian) bug sign the source package) and specialpackage (1.2- your fix, you can submit a *merge tracker (open and closed bugs), pbuilder-dist will build the package 3ubuntu4) natty; urgency=low proposal*, which asks other from source for whatever release * debian/control: updated Ubuntu developers to review and • Upstream revision history (or you choose. description to include frobnicator (LP: #123456) approve your change. If they agree newer release) might have fixed -- Emma Adams with your changes, an Ubuntu the problem, Once the build succeeds, install Sat, developer will upload the new the package from 17 Jul 2010 02:53:39 +0200 version of the package to Ubuntu • bugs or package uploads of ~/pbuilder/_result/ so that everyone gets the benefit Debian or other distributions. (using sudo dpkg -i dch should fill out the first and of your excellent fix - and you get _.deb). Then last line of such a changelog entry a little bit of credit. You’re now on If you find a patch to fix the test to see if the bug is fixed. for you already. Line 1 consists of your way to becoming an Ubuntu problem, say, attached to a bug the source package name, the developer! We’ll describe specifics report, running this command in Documenting the fix version number, which Ubuntu on how to branch the code, push the source directory should apply release it is uploaded to, the urgency (which almost always is your fix, and request a review in the patch: It is very important to ‘low’). The last line always contains the following sections. document your change sufficiently patch -p1 < ../bugfix.patch the name, email address and so developers who look at the timestamp (in RFC 5322 format) of code in the future won’t have to Work on a fix Refer to the patch(1) manpage the change.

full circle magazine #51 18 contents ^ HOWTO - UBUNTU DEVELOPMENT 3 - BUG FIXING

With that out of the way, let’s To push it to Launchpad, as the focus on the actual changelog remote branch name, you need to entry itself: it is very important to stick to the following document: nomenclature: • where the change was done Zero Downtime • what was changed lp:~/ubuntu/// change happened This could, for example, be In our (very sparse) example, lp:~emmaadams/ubuntu/natty/sp Below Zero is a Co-located Server Hosting specialist in the UK. the last point is covered by (LP: ecialpackage/fix-for-123456 #123456) which refers to Uniquely we only provide rack space Launchpad bug 123456. Bug So, if you just run and bandwidth. This makes our service reports or mailing list threads or more reliable, more flexible, more specifications are usually good bzr push focused and more competitively information to provide as a lp:~emmaadams/ubuntu/natty/sp ecialpackage/fix-for-123456 priced. We concentrate solely on the rationale for a change. As a bonus, hosting of Co-located Servers and their if you use the LP: # bzr lp-open associated systems, within Scotland's notation for Launchpad bugs, the Data Centres. bug will be automatically closed you should be all set. The push when the package is uploaded to command should push it to At the heart of our networking Ubuntu. Launchpad, and the second infrastructure is state-of-the-art BGP4 command will open the Launchpad routing that offers optimal data page of the remote branch in your Committing the fix delivery and automatic multihomed browser. There, find the “(+) failover between our outstanding Propose for merging” link, and With the changelog entry providers. Customers may rest assured click it to get the change reviewed written and saved, you can just run: that we only use the highest quality of by somebody and included in bandwidth; our policy is to pay more for the best of breed providers Ubuntu. debcommit and because we buy in bulk this doesn't impact our extremely competitive pricing. and the change will be Next month: an overview of the committed (locally) with your Debian directory structure. At Below Zero we help you to achieve Zero Downtime. changelog entry as a commit message. www.zerodowntime.co.uk

full circle magazine #51 19 contents ^ HHOOWW--TTOO Written by Daniel Holbach UUbbuunnttuu DDeevveellooppmmeenntt PPtt.. 44 -- ddeebbiiaann//

his article will briefly changelog: * New upstream release For further information, see the explain the different files with lots of bug fixes and changelog section (Section 4.4) of feature improvements. important to the package (version) the Debian Policy Manual. distribution; urgency=urgency packaging of Ubuntu -- Jane Doe T Thu, packages which are contained in * change details The Control File the debian/ directory. The most - more change details 21 Apr 2011 11:12:00 -0400 * even more change details important of them are changelog, Notice that the version has a - The control file contains the control, copyright, and rules. These -- maintainer name [two spaces] date the distro revision, used so that manager (such as apt-get, synaptic, number of additional files in the packaging can be updated (to and adept) uses, build-time debian/ may be used in order to The format (especially of the fix bugs for example) with new dependencies, maintainer customize and configure the date) is important. The date uploads within the same source information, and much more. behavior of the package. Some of should be in RFC 5322 format, release version. these files are discussed in this which can be obtained by using the For the Ubuntu hello package, article, but this is not meant to be command date -. For Ubuntu and Debian have the control file looks something a complete list. convenience, the command dch slightly different package like: may be used to edit changelog. It versioning schemes to avoid The Changelog will update the date automatically. conflicting packages with the same Source: hello Section: devel Minor bullet points are indicated source version. If a Debian package by a dash “-“, while major points Priority: optional This file is, as its name implies, has been changed in Ubuntu, it has Maintainer: Ubuntu a listing of the changes made in use an asterisk “*”. If you are ubuntuX (where X is the Ubuntu Developers XSBC-Original-Maintainer: format that gives the package create (dch is in the devscripts end of the Debian version. So, if package) will create a standard Jane Doe name, version, distribution, the Debian hello 2.6-1 package changes, and who made the debian/changelog for you. was changed by Ubuntu, the Standards-Version: 3.9.1 changes at a given time. If you version string would be 2.6- Build-Depends: debhelper (>= 7) have a GPG key (see: Getting set Here is a sample changelog file 1ubuntu1. If a package for the for hello: Bzr-Vcs: lp:ubuntu/hello up) make sure to use the same application does not exist in Homepage: name and email address in Debian, then the Debian revision is http://www.gnu.org/software/h changelog as you have in your key. hello (2.6-0ubuntu1) natty; 0 (e.g. 2.6-0ubuntu1). ello/ urgency=low The following is a template Package: hello

full circle magazine #52 19 contents ^ HOWTO - UBUNTU DEVELOPMENT 4 - debian/ Architecture: any Ubuntu should generally have the information is found in the See the GNU General Public Depends: ${shlibs:Depends} Maintainer field set to Ubuntu COPYING file in the program’s License for more details. Description: The classic . greeting, and a good example Developers . If the include such information as the copy of the GNU General produces a familiar, Maintainer field is modified, the names of the author and the Public License along with friendly greeting. It allows old value should be saved in the packager, the URL from which the this package; if not, write non-programmers to use a to the classic computer science XSBC-Original-Maintainer field. source came, a Copyright line with Foundation, Inc., 51 tool which would otherwise This can be done automatically the year and copyright holder, and Franklin St, Fifth Floor, be unavailable to them. with the update-maintainer script the text of the copyright itself. An Boston, MA 02110-1301 USA Seriously, though: this is available in the ubuntu-dev-tools example template would be: . an example of how to do a On Debian systems, the full Debian package. It is the package. For further information, text of the GNU General Debian version of the GNU see the Debian Maintainer Field Format: Public License version 2 can Project's `hello world' spec on the Ubuntu wiki. http://svn.debian.org/wsvn/de be found in the file program (which is itself an p/web/deps/dep5.mdwn?op=file& `/usr/share/common- example for the GNU Project). rev=166 licenses/GPL-2'. Each additional paragraph Upstream-Name: Hello describes a binary package to be Source: The first paragraph describes Files: debian/* built. ftp://ftp.example.com/pub/gam Copyright: Copyright 1998 the source package - including the es Jane Doe list of packages required to build For further information, see the the package from source in the Files: * License: GPL-2+ control file section (Chapter 5) of Copyright: Copyright 1998 Build-Depends field. It also the Debian Policy Manual. John Doe contains some meta-information License: GPL-2+ This example follows the DEP- such as the maintainer’s name, the This program is free 5: Machine-parseable version of Debian Policy that the The Copyright File software; you can debian/copyright proposal. You redistribute it and/or are encouraged to use this format package complies with, the modify it under the terms of location of the packaging version This file gives the copyright the GNU General Public as well. control repository, and the information for both the upstream License as published by the upstream home page. source and the packaging. Ubuntu ; either version 2 of the The Rules File and Debian Policy (Section 12.5) License, or (at your option) Note that, in Ubuntu, we set require that each package installs any later version. The last file we need to look at the Maintainer field to a general a verbatim copy of its copyright . is rules. This does all the work for address because anyone can and license information to This program is distributed in the hope that it will be creating our package. It is a change any package (this differs /usr/share/doc/$(package_name)/c useful, but WITHOUT ANY Makefile with targets to compile from Debian where changing opyright. WARRANTY; without even the and install the application, then packages is usually restricted to an implied warranty of create the .deb file from the individual or a team). Packages in Generally, copyright MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. installed files. It also has a target

full circle magazine #52 20 contents ^ HOWTO - UBUNTU DEVELOPMENT 4 - debian/ to clean up all the build files so in the sequence. The --until, -- Also see the rules section (Section you end up with just a source Commands in the binary-indep before, --after, and --remaining 4.9) of the Debian Policy Manual. package again. sequence are passed the “-i” options can override this behavior. option to ensure they work only on Additional Files Here is a simplified version of binary independent packages, and If debian/rules contains a the rules file created by dh_make commands in the binary-arch target with a name like (which can be found in the dh- sequences are passed the “-a” override_dh_command, then when The Install File make package): option to ensure they work only on it gets to that command in the architecture dependent packages. sequence, dh will run that target The install file is used by #!/usr/bin/make -f from the rules file, rather than dh_install to install files into the # -*- makefile -*- Each debhelper command will running the actual command. The binary package. It has two # Uncomment this to turn on record when it’s successfully run in override target can then run the standard use cases: verbose mode. debian/package.debhelper.log. command with additional options, • To install files into your #export DH_VERBOSE=1 (Which dh_clean deletes.) So dh or run entirely different package that are not handled by commands instead. (Note that to the upstream build system. %: can tell which commands have dh $@ already been run, for which use this feature, you should Build- • Splitting a single large source packages, and skip running those Depend on debhelper 7.0.50 or package into multiple binary Let us go through this file in commands again. Each time dh is above.) packages. some detail. What this does is pass run, it examines the log, and finds every build target that the last logged command that is in Have a look at In the first case, the install file debian/rules is called with as an the specified sequence. It then /usr/share/doc/debhelper/example should have one line per file argument to /usr/bin/dh, which continues with the next command s/ and man dh for more examples. installed, specifying both the file itself will call all the necessary and the installation directory. For dh_* commands. example, the following install file would install the script foo in the dh runs a sequence of source package’s root directory to debhelper commands. The usr/bin, and a desktop file in the supported sequences correspond debian directory to to the targets of a debian/rules usr/share/applications: file: “build”, “clean”, “install”, “binary-arch”, “binary-indep”, and foo usr/bin debian/bar.desktop “binary”. In order to see what usr/share/applications commands are run in each target, run: When a source package is producing multiple binary dh binary-arch --no-act

full circle magazine #52 21 contents ^ HOWTO - UBUNTU DEVELOPMENT 4 - debian/ packages, dh will install the files install file section (Section 5.11) of downloaded updated package default for the package source into debian/tmp rather than the Debian New Maintainers’ hello-2.7.tar.gz format. and symlinked directly into debian/. Guide for additional details. hello_2.7.orig.tar.gz to it Files installed into debian/tmp can http://wiki.debian.org/Projects/ then be moved into separate The Watch File For further information, see DebSrc3.0 summarizes information binary packages using multiple man uscan and the watch file concerning, and the benefits of $package_name.install files. This is The debian/watch file allows us section (Section 4.11) of the the switch to, the 3.0 source often done to split large amounts to check automatically for new Debian Policy Manual. package formats. of architecture independent data upstream versions using the tool out of architecture dependent uscan found in the devscripts For a list of packages where the See man dpkg-source and the packages and into Architecture: all package. The first line of the watch file reports they are not in source/format section (Section packages. In this case, only the watch file must be the format sync with upstream, see Ubuntu 5.21) of the Debian New name of the files (or directories) to version (3, at the time of this External Health Status. Maintainers’ Guide for additional be installed are needed without writing), while the following lines details. the installation directory. For contain any URLs to parse. For The Source/Format File example, foo.install containing example: Additional Resources only the architecture dependent This file indicates the format of files might look like: version=3 the source package. Currently, the In addition to the links to the http://ftp.gnu.org/gnu/hello/ package source format defaults to Debian Policy Manual in each usr/bin/ hello-(.*).tar.gz usr/lib/foo/*.so 1.0 if this file does not exist. You section above, the Debian New Maintainers’ Guide has more Running uscan in the root are encouraged to use the newer detailed descriptions of each file. While foo-common.install source directory will now compare 3.0 source format. In this case, the Chapter 4, “Required files under containing only the architecture the upstream version number in file should contain a single line the debian directory” further independent file might look like: debian/changelog with the latest indicating the desired format: discusses the control, changelog, available upstream version. If a • 3.0 (native) for Debian native copyright, and rules files. Chapter /usr/share/doc/ new upstream version is found, it packages (no upstream version) or /usr/share/icons/ 5, “Other files under the debian will be automatically downloaded. • 3.0 (quilt) for packages with a /usr/share/foo/ separate upstream tarball directory” discusses additional /usr/share/locale/ For example: files that may be used. This would create two binary $ uscan If, for some reason, you wish to packages, foo and foo-common. hello: Newer version (2.7) keep using the old format, please available on remote site: Both would require their own create this file and put 1.0 in it to http://ftp.gnu.org/gnu/hell be explicit about the source paragraph in debian/control. o/hello-2.7.tar.gz (local version is 2.6) package version. This allows for See man dh_install and the hello: Successfully the future removal of the 1.0

full circle magazine #52 22 contents ^