/usr/share/doc/ubuntu-packaging-guide-html/packaging-new-software.html is in ubuntu-packaging-guide-html 0.3.7.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>6. Packaging New Software — Ubuntu Packaging Guide</title>
<link rel="shortcut icon" href="./_static/images/favicon.ico" type="image/x-icon" />
<link rel="stylesheet" href="./_static/reset.css" type="text/css" />
<link rel="stylesheet" href="./_static/960.css" type="text/css" />
<link rel="stylesheet" href="./_static/base.css" type="text/css" />
<link rel="stylesheet" href="./_static/home.css" type="text/css" />
<link rel="stylesheet" href="./_static/pygments.css" type="text/css" />
<link rel="stylesheet" href="./_static/guide.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '../',
VERSION: '0.3.7',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="./_static/jquery.js"></script>
<script type="text/javascript" src="./_static/underscore.js"></script>
<script type="text/javascript" src="./_static/doctools.js"></script>
<script type="text/javascript" src="./_static/main.js"></script>
<link rel="top" title="Ubuntu Packaging Guide" href="./index.html" />
<link rel="next" title="7. Security and Stable Release Updates" href="security-and-stable-release-updates.html" />
<link rel="prev" title="5. Tutorial: Fixing a bug in Ubuntu" href="fixing-a-bug-example.html" />
</head>
<body class="home">
<a name="top"></a>
<div class="header-navigation">
<div>
<nav role="navigation">
<ul>
<li class="page_item current_page_item"><a title="Contents" href="index.html">Contents</a>
<li>
<form id="form-search" method="get" action="search.html">
<fieldset>
<input id="input-search" type="text" name="q" value="Search" />
</fieldset>
</form>
</li>
</ul>
</nav>
<a class="logo-ubuntu" href="http://packaging.ubuntu.com/">
<img src="./_static/images/logo-ubuntu.png" width="119" height="27" alt="Ubuntu logo" />
</a>
<a href="http://packaging.ubuntu.com/"><h2>Packaging Guide</h2></a>
</div>
</div>
<div class="header-content">
<div class="clearfix">
<div class="header-navigation-secondary">
<div>
<nav role="navigation">
<ul class="clearfix">
<li class="page_item"><a style="margin-right: 10px"
href="security-and-stable-release-updates.html" title="7. Security and Stable Release Updates"
accesskey="N">next</a></li>
<li class="page_item"><a
href="fixing-a-bug-example.html" title="5. Tutorial: Fixing a bug in Ubuntu"
accesskey="P">previous</a></li>
<li class="page_item"><a class="sub-nav-item" href="index.html">Ubuntu Packaging Guide »</a></li>
</ul>
</nav>
</div>
</div>
</div>
</div>
<div id="content" class="body container_12">
<div class="grid_12">
<!--<section id="main-section">-->
<div class="grid_9 alpha">
<div class="section" id="packaging-new-software">
<h1>6. Packaging New Software<a class="headerlink" href="#packaging-new-software" title="Permalink to this headline">¶</a></h1>
<p>While there are thousands of packages in the Ubuntu archive, there are still
a lot nobody has gotten to yet. If there is an exciting new piece of software
that you feel needs wider exposure, maybe you want to try your hand at
creating a package for Ubuntu or a <a class="reference external" href="https://help.launchpad.net/Packaging/PPA">PPA</a>. This guide will take you through the
steps of packaging new software.</p>
<p>You will want to read the <a class="reference internal" href="getting-set-up.html"><em>Getting Set Up</em></a> article first
in order to prepare your development environment.</p>
<div class="section" id="checking-the-program">
<h2>6.1. Checking the Program<a class="headerlink" href="#checking-the-program" title="Permalink to this headline">¶</a></h2>
<p>The first stage in packaging is to get the released tar from upstream (we call
the authors of applications “upstream”) and check that it compiles and runs.</p>
<p>This guide will take you through packaging a simple application called GNU Hello
which has been posted on <a class="reference external" href="http://www.gnu.org/software/hello/">GNU.org</a>.</p>
<p>If you don’t have the build tools lets make sure we have them first. Also if you
don’t have the required dependencies lets install those as well.</p>
<p>Install build tools:</p>
<div class="highlight-python"><div class="highlight"><pre>$ sudo apt-get install build-essential
</pre></div>
</div>
<p>Download main package:</p>
<div class="highlight-python"><div class="highlight"><pre>$ wget -O hello-2.7.tar.gz "http://ftp.gnu.org/gnu/hello/hello-2.7.tar.gz"
</pre></div>
</div>
<p>Now uncompress main package:</p>
<div class="highlight-python"><div class="highlight"><pre>$ tar xf hello-2.7.tar.gz
$ cd hello-2.7
</pre></div>
</div>
<p>This application uses the autoconf build system so we want to run <tt class="docutils literal"><span class="pre">./configure</span></tt>
to prepare for compilation.</p>
<p>This will check for the required build dependencies. As <tt class="docutils literal"><span class="pre">hello</span></tt> is a simple
example, <tt class="docutils literal"><span class="pre">build-essential</span></tt> should provide everything we need. For more
complex programs, the command will fail if you do not have the needed libraries
and development files. Install the needed packages and repeat until the command
runs successfully.:</p>
<div class="highlight-python"><div class="highlight"><pre>$ ./configure
</pre></div>
</div>
<p>Now you can compile the source:</p>
<div class="highlight-python"><div class="highlight"><pre>$ make
</pre></div>
</div>
<p>If compilation completes successfully you can install and run the program:</p>
<div class="highlight-python"><div class="highlight"><pre>$ sudo make install
$ hello
</pre></div>
</div>
</div>
<div class="section" id="starting-a-package">
<h2>6.2. Starting a Package<a class="headerlink" href="#starting-a-package" title="Permalink to this headline">¶</a></h2>
<p><tt class="docutils literal"><span class="pre">bzr-builddeb</span></tt> includes a plugin to create a new package from a template. The
plugin is a wrapper around the <tt class="docutils literal"><span class="pre">dh_make</span></tt> command. You should already have
these if you installed <tt class="docutils literal"><span class="pre">packaging-dev</span></tt>. Run the command providing the package
name, version number, and path to the upstream tarball:</p>
<div class="highlight-python"><div class="highlight"><pre>$ sudo apt-get install dh-make bzr-builddeb
$ cd ..
$ bzr dh-make hello 2.7 hello-2.7.tar.gz
</pre></div>
</div>
<p>When it asks what type of package type <tt class="docutils literal"><span class="pre">s</span></tt> for single binary. This will import
the code into a branch and add the <tt class="docutils literal"><span class="pre">debian/</span></tt> packaging directory. Have a look
at the contents. Most of the files it adds are only needed for specialist
packages (such as Emacs modules) so you can start by removing the optional
example files:</p>
<div class="highlight-python"><div class="highlight"><pre>$ cd hello/debian
$ rm *ex *EX
</pre></div>
</div>
<p>You should now customise each of the files.</p>
<p>In <tt class="docutils literal"><span class="pre">debian/changelog</span></tt> change the
version number to an Ubuntu version: <tt class="docutils literal"><span class="pre">2.7-0ubuntu1</span></tt> (upstream version 2.7,
Debian version 0, Ubuntu version 1). Also change <tt class="docutils literal"><span class="pre">unstable</span></tt> to the current
development Ubuntu release such as <tt class="docutils literal"><span class="pre">trusty</span></tt>.</p>
<p>Much of the package building work is done by a series of scripts
called <tt class="docutils literal"><span class="pre">debhelper</span></tt>. The exact behaviour of <tt class="docutils literal"><span class="pre">debhelper</span></tt> changes
with new major versions, the compat file instructs <tt class="docutils literal"><span class="pre">debhelper</span></tt> which
version to act as. You will generally want to set this to the most
recent version which is <tt class="docutils literal"><span class="pre">9</span></tt>.</p>
<p><tt class="docutils literal"><span class="pre">control</span></tt> contains all the metadata of the package. The first paragraph
describes the source package. The second and following paragraphs describe
the binary packages to be built. We will need to add the packages needed to
compile the application to <tt class="docutils literal"><span class="pre">Build-Depends:</span></tt>. For <tt class="docutils literal"><span class="pre">hello</span></tt>, make sure that it
includes at least:</p>
<div class="highlight-python"><div class="highlight"><pre>Build-Depends: debhelper (>= 9)
</pre></div>
</div>
<p>You will also need to fill in a description of the program in the
<tt class="docutils literal"><span class="pre">Description:</span></tt> field.</p>
<p><tt class="docutils literal"><span class="pre">copyright</span></tt> needs to be filled in to follow the licence of the upstream
source. According to the hello/COPYING file this is GNU GPL 3 or later.</p>
<p><tt class="docutils literal"><span class="pre">docs</span></tt> contains any upstream documentation files you think should be included
in the final package.</p>
<p><tt class="docutils literal"><span class="pre">README.source</span></tt> and <tt class="docutils literal"><span class="pre">README.Debian</span></tt> are only needed if your package has any
non-standard features, we don’t so you can delete them.</p>
<p><tt class="docutils literal"><span class="pre">source/format</span></tt> can be left as is, this describes the version format of the
source package and should be <tt class="docutils literal"><span class="pre">3.0</span> <span class="pre">(quilt)</span></tt>.</p>
<p><tt class="docutils literal"><span class="pre">rules</span></tt> is the most complex file. This is a Makefile which compiles the
code and turns it into a binary package. Fortunately most of the work is
automatically done these days by <tt class="docutils literal"><span class="pre">debhelper</span> <span class="pre">7</span></tt> so the universal <tt class="docutils literal"><span class="pre">%</span></tt>
Makefile target just runs the <tt class="docutils literal"><span class="pre">dh</span></tt> script which will run everything needed.</p>
<p>All of these file are explained in more detail in the <a class="reference internal" href="debian-dir-overview.html"><em>overview of the
debian directory</em></a> article.</p>
<p>Finally commit the code to your packaging branch:</p>
<div class="highlight-python"><div class="highlight"><pre>$ bzr add debian/source/format
$ bzr commit -m "Initial commit of Debian packaging."
</pre></div>
</div>
</div>
<div class="section" id="building-the-package">
<h2>6.3. Building the package<a class="headerlink" href="#building-the-package" title="Permalink to this headline">¶</a></h2>
<p>Now we need to check that our packaging successfully compiles the package and
builds the .deb binary package:</p>
<div class="highlight-python"><div class="highlight"><pre>$ bzr builddeb -- -us -uc
$ cd ../../
</pre></div>
</div>
<p><tt class="docutils literal"><span class="pre">bzr</span> <span class="pre">builddeb</span></tt> is a command to build the package in its current location.
The <tt class="docutils literal"><span class="pre">-us</span> <span class="pre">-uc</span></tt> tell it there is no need to GPG sign the package. The result
will be placed in <tt class="docutils literal"><span class="pre">..</span></tt>.</p>
<p>You can view the contents of the package with:</p>
<div class="highlight-python"><div class="highlight"><pre>$ lesspipe hello_2.7-0ubuntu1_amd64.deb
</pre></div>
</div>
<p>Install the package and check it works (later you will be able to uninstall it
using <tt class="docutils literal"><span class="pre">sudo</span> <span class="pre">apt-get</span> <span class="pre">remove</span> <span class="pre">hello</span></tt> if you want):</p>
<div class="highlight-python"><div class="highlight"><pre>$ sudo dpkg --install hello_2.7-0ubuntu1_amd64.deb
</pre></div>
</div>
<p>You can also install all packages at once using:</p>
<div class="highlight-python"><div class="highlight"><pre>$ sudo debi
</pre></div>
</div>
</div>
<div class="section" id="next-steps">
<h2>6.4. Next Steps<a class="headerlink" href="#next-steps" title="Permalink to this headline">¶</a></h2>
<p>Even if it builds the .deb binary package, your packaging may have
bugs. Many errors can be automatically detected by our tool
<tt class="docutils literal"><span class="pre">lintian</span></tt> which can be run on the source .dsc metadata file, .deb
binary packages or .changes file:</p>
<div class="highlight-python"><div class="highlight"><pre>$ lintian hello_2.7-0ubuntu1.dsc
$ lintian hello_2.7-0ubuntu1_amd64.deb
</pre></div>
</div>
<p>To see verbose description of the problems use <tt class="docutils literal"><span class="pre">--info</span></tt> lintian flag
or <tt class="docutils literal"><span class="pre">lintian-info</span></tt> command.</p>
<p>Results of Ubuntu archive checks can be found online on
<a class="reference external" href="http://lintian.ubuntuwire.org">http://lintian.ubuntuwire.org</a>.</p>
<p>For Python packages, there is also a <tt class="docutils literal"><span class="pre">lintian4python</span></tt> tool that provides
some additional lintian checks.</p>
<p>After making a fix to the packaging you can rebuild using <tt class="docutils literal"><span class="pre">-nc</span></tt> “no clean”
without having to build from scratch:</p>
<div class="highlight-python"><div class="highlight"><pre>$ bzr builddeb -- -nc -us -uc
</pre></div>
</div>
<p>Having checked that the package builds locally you should ensure it builds on a
clean system using <tt class="docutils literal"><span class="pre">pbuilder</span></tt>. Since we are going to upload to a PPA
(Personal Package Archive) shortly, this upload will need to be <em>signed</em> to
allow Launchpad to verify that the upload comes from you (you can tell the
upload will be signed because the <tt class="docutils literal"><span class="pre">-us</span></tt> and <tt class="docutils literal"><span class="pre">-uc</span></tt> flags are not passed to
<tt class="docutils literal"><span class="pre">bzr</span> <span class="pre">builddeb</span></tt> like they were before). For signing to work you need to have
set up GPG. If you haven’t set up <tt class="docutils literal"><span class="pre">pbuilder-dist</span></tt> or GPG yet, <a class="reference internal" href="getting-set-up.html"><em>do so
now</em></a>:</p>
<div class="highlight-python"><div class="highlight"><pre>$ bzr builddeb -S
$ cd ../build-area
$ pbuilder-dist trusty build hello_2.7-0ubuntu1.dsc
</pre></div>
</div>
<p>When you are happy with your package you will want others to review it. You
can upload the branch to Launchpad for review:</p>
<div class="highlight-python"><div class="highlight"><pre>$ bzr push lp:~<lp-username>/+junk/hello-package
</pre></div>
</div>
<p>Uploading it to a PPA will ensure it builds and give an easy way for you and
others to test the binary packages. You will need to set up a PPA in Launchpad
and then upload with <tt class="docutils literal"><span class="pre">dput</span></tt>:</p>
<div class="highlight-python"><div class="highlight"><pre>$ dput ppa:<lp-username>/<ppa-name> hello_2.7-0ubuntu1.changes
</pre></div>
</div>
<p>See <a class="reference internal" href="udd-uploading.html"><em>uploading</em></a> for more information.</p>
<p>You can ask for reviews in <tt class="docutils literal"><span class="pre">#ubuntu-motu</span></tt> IRC channel, or on the
<a class="reference external" href="https://lists.ubuntu.com/mailman/listinfo/ubuntu-motu">MOTU mailing list</a>. There might also be a more specific
team you could ask such as the GNU team for more specific questions.</p>
</div>
<div class="section" id="submitting-for-inclusion">
<h2>6.5. Submitting for inclusion<a class="headerlink" href="#submitting-for-inclusion" title="Permalink to this headline">¶</a></h2>
<p>There are a number of paths that a package can take to enter Ubuntu.
In most cases, going through Debian first can be the best path. This
way ensures that your package will reach the largest number of users
as it will be available in not just Debian and Ubuntu but all of their
derivatives as well. Here are some useful links for submitting new
packages to Debian:</p>
<blockquote>
<div><ul class="simple">
<li><a class="reference external" href="https://wiki.debian.org/DebianMentorsFaq">Debian Mentors FAQ</a> - debian-mentors is for the mentoring of new and
prospective Debian Developers. It is where you can find a sponsor
to upload your package to the archive.</li>
<li><a class="reference external" href="http://www.debian.org/devel/wnpp/">Work-Needing and Prospective Packages</a> - Information on how to file
“Intent to Package” and “Request for Package” bugs as well as list
of open ITPs and RFPs.</li>
<li><a class="reference external" href="http://www.debian.org/doc/manuals/developers-reference/pkgs.html#newpackage">Debian Developer’s Reference, 5.1. New packages</a> - The entire
document is invaluable for both Ubuntu and Debian packagers. This
section documents processes for submitting new packages.</li>
</ul>
</div></blockquote>
<p>In some cases, it might make sense to go directly into Ubuntu first. For
instance, Debian might be in a freeze making it unlikely that your
package will make it into Ubuntu in time for the next release. This
process is documented on the <a class="reference external" href="https://wiki.ubuntu.com/UbuntuDevelopment/NewPackages">“New Packages”</a> section of the Ubuntu wiki.</p>
</div>
<div class="section" id="screenshots">
<h2>6.6. Screenshots<a class="headerlink" href="#screenshots" title="Permalink to this headline">¶</a></h2>
<p>Once you have uploaded a package to debian, you should add screenshots
to allow propective users to see what the program is like. These should
be uploaded to <a class="reference external" href="http://screenshots.debian.net/upload">http://screenshots.debian.net/upload</a> .</p>
</div>
</div>
<div class="divide"></div>
</div>
<div id="sidebar" class="grid_3 omega">
<div class="container-tweet">
<h3>Table Of Contents</h3>
<div class="toc">
<ul>
<li><a class="reference internal" href="#">6. Packaging New Software</a><ul>
<li><a class="reference internal" href="#checking-the-program">6.1. Checking the Program</a></li>
<li><a class="reference internal" href="#starting-a-package">6.2. Starting a Package</a></li>
<li><a class="reference internal" href="#building-the-package">6.3. Building the package</a></li>
<li><a class="reference internal" href="#next-steps">6.4. Next Steps</a></li>
<li><a class="reference internal" href="#submitting-for-inclusion">6.5. Submitting for inclusion</a></li>
<li><a class="reference internal" href="#screenshots">6.6. Screenshots</a></li>
</ul>
</li>
</ul>
</div>
<div class="browse-guide">
<h3>Browse The Guide:</h3>
<ul>
<li class="prev">
<a href="fixing-a-bug-example.html"
title="Previous topic: 5. Tutorial: Fixing a bug in Ubuntu">Go Previous</a>
</li>
<li class="center">
<a title="Back to Index" href="index.html">Index Guide</a>
</li>
<li class="next">
<a href="security-and-stable-release-updates.html"
title="Next topic: 7. Security and Stable Release Updates">Go Next</a>
</li>
</ul>
<span>This Page:</span> <a href="./_sources/packaging-new-software.txt"
rel="nofollow">Show Source</a>
</div>
</div>
<div id="back_top"><a href="#top">Back to Top</a></div>
</div>
<!--</section>-->
</div>
</div>
<div class="shadow"></div>
<footer>
<div>
Version: 0.3.7.
<a href="https://bugs.launchpad.net/ubuntu-packaging-guide">Report bugs</a> or
<a href="https://code.launchpad.net/~ubuntu-packaging-guide-team/ubuntu-packaging-guide/trunk">grab the source code</a> from Launchpad.
Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.3.
<br />
© Copyright 2010-2015, Ubuntu Developers, Creative Commons Attribution-ShareAlike 3.0.
<a rel="license" href="http://creativecommons.org/licenses/by-sa/3.0/">
Creative Commons Attribution-ShareAlike 3.0 Unported License</a>.
<a rel="license" href="http://creativecommons.org/licenses/by-sa/3.0/">
<img alt="Creative Commons License" style="border-width:0"
src="./_static/images/cc-by-sa.png" /></a>
<br />
<a href="http://people.ubuntu.com/~mitya57/ubuntu-packaging-guide-readme.html#translating">Help translate</a> or
<a href="./_static/translators.html">view the list of translators</a>.
</div>
</footer>
</body>
</html>
|