File: dbp.regular.html

package info (click to toggle)
darcs-buildpackage 0.5.12.2
links: PTS
area: main
in suites: squeeze
size: 716 kB
ctags: 2
sloc: haskell: 452; sh: 62; makefile: 56
file content (603 lines) | stat: -rw-r--r-- 12,817 bytes
parent folder | download | duplicates (2)
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN""http://www.w3.org/TR/html4/loose.dtd">
<HTML
><HEAD
><TITLE
>Common Tasks</TITLE
><META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK
REL="HOME"
TITLE="Building Debian Packages with darcs-buildpackage"
HREF="dbp.html"><LINK
REL="PREVIOUS"
TITLE="Importing Packages"
HREF="dbp.import.html"><LINK
REL="NEXT"
TITLE="Command Reference"
HREF="dbp.man.reference.html"><STYLE
TYPE="text/css"
>.synopsis, .classsynopsis {
    background: #eeeeee;
    border: solid 1px #aaaaaa;
    padding: 0.5em;
}
.programlisting {
    background: #eeeeff;
    border: solid 1px #aaaaff;
    padding: 0.5em;
}
.variablelist {
    padding: 4px;
    margin-left: 3em;
}
.navigation {
    background: #ffeeee;
    border: solid 1px #ffaaaa;
    margin-top: 0.5em;
    margin-bottom: 0.5em;
}
.navigation a {
    color: #770000;
}
.navigation a:visited {
    color: #550000;
}
.navigation .title {
    font-size: 200%;
}</STYLE
></HEAD
><BODY
CLASS="CHAPTER"
BGCOLOR="#FFFFFF"
TEXT="#000000"
LINK="#0000FF"
VLINK="#840084"
ALINK="#0000FF"
><TABLE
WIDTH="100%"
CLASS="navigation"
SUMMARY="Navigation header"
CELLPADDING="2"
CELLSPACING="2"
><TR
VALIGN="middle"
><TD
><A
ACCESSKEY="p"
HREF="dbp.import.html"
><IMG
SRC="left.png"
WIDTH="24"
HEIGHT="24"
BORDER="0"
ALT="Prev"></A
></TD
><TD
><A
ACCESSKEY="h"
HREF="dbp.html"
><IMG
SRC="home.png"
WIDTH="24"
HEIGHT="24"
BORDER="0"
ALT="Home"></A
></TD
><TH
WIDTH="100%"
align="center"
>Building Debian Packages with darcs-buildpackage</TH
><TD
><A
ACCESSKEY="n"
HREF="dbp.man.reference.html"
><IMG
SRC="right.png"
WIDTH="24"
HEIGHT="24"
BORDER="0"
ALT="Next"></A
></TD
></TR
></TABLE
><DIV
CLASS="CHAPTER"
><H1
><A
NAME="DBP.REGULAR"
></A
>Common Tasks</H1
><DIV
CLASS="TOC"
><DL
><DT
><B
>Table of Contents</B
></DT
><DT
><A
HREF="dbp.regular.html#DBP.REGULAR.GETTING"
>Getting Sources</A
></DT
><DT
><A
HREF="dbp.regular.html#DBP.REGULAR.BUILDING"
>Building and Working With Source</A
></DT
><DT
><A
HREF="dbp.regular.html#DBP.REGULAR.UPSTREAM-UPDATE"
>Handling New Upstream Versions</A
></DT
><DT
><A
HREF="dbp.regular.html#TLA.REGULAR.DEBIAN-UPDATE"
>Finalizing New Debian Versions</A
></DT
><DT
><A
HREF="dbp.regular.html#DBP.REGULAR.HISTORIC-VERSIONS"
>Finding Historic Versions</A
></DT
><DT
><A
HREF="dbp.regular.html#DBP.REGULAR.FETCHING"
>Fetching Source from History</A
></DT
></DL
></DIV
><P
>      This chapter describes how to use <SPAN
CLASS="APPLICATION"
>darcs-buildpackage</SPAN
> to carry out regular,
      every-day development activities.
    </P
><BR
CLEAR="all"><DIV
CLASS="SECT1"
><H1
CLASS="SECT1"
><A
NAME="DBP.REGULAR.GETTING"
>Getting Sources</A
></H1
><P
>        FIXME: write this.
        Please see dbp-get manpage for info about getting and mirrors!
      </P
></DIV
><BR
CLEAR="all"><DIV
CLASS="SECT1"
><H1
CLASS="SECT1"
><A
NAME="DBP.REGULAR.BUILDING"
>Building and Working With Source</A
></H1
><P
>        Before you start working on any source package with <SPAN
CLASS="APPLICATION"
>darcs-buildpackage</SPAN
>,
        first check it out as described in <A
HREF="dbp.regular.html#DBP.REGULAR.FETCHING"
>the Section called <I
>Fetching Source from History</I
></A
> to make sure it is in its
        proper location.  Then, as you work, you will use
        <B
CLASS="COMMAND"
>darcs record</B
> to commit your changes to the
        Debian repository.  (If you just want to build an old package,
        there's no need to do this.)
      </P
><P
>        When you're ready to build a package, just run
        <B
CLASS="COMMAND"
>darcs-buildpackage</B
> to build it.  The <B
CLASS="COMMAND"
>darcs-buildpackage</B
>
        command takes the same arguments as
        <B
CLASS="COMMAND"
>debuild</B
>, and passes them on to
        <B
CLASS="COMMAND"
>debuild</B
>, so give it your usual set.
        <B
CLASS="COMMAND"
>darcs-buildpackage</B
> will use your existing orig.tar.gz file for
        source generation, if it exists; otherwise, it will take care
        of automatically building it from the upstream sources if
        necessary.
      </P
><P
>        FIXME: these examples are from arch and need to be updated for
        Darcs
      </P
><P
>        Here's an example:
      </P
><PRE
CLASS="SCREEN"
>~/tree/debian$ <B
CLASS="COMMAND"
>cd +packages/rdiff-backup/rdiff-backup-0.12.5</B
>
~/tree/debian/+packages/rdiff-backup/rdiff-backup-0.12.5$ <B
CLASS="COMMAND"
>darcs-buildpackage \
        -rfakeroot -us -uc</B
>
...
Building .orig from archive.
 * tla buildcfg upstream/rdiff-backup/0.12.5
* from import revision: jgoerzen@complete.org--debian/rdiff-backup--head--1.0--base-0
* patching for revision: jgoerzen@complete.org--debian/rdiff-backup--head--1.0--patch-1
* patching for revision: jgoerzen@complete.org--debian/rdiff-backup--head--1.0--patch-2
* making pristine copy
* tree version set jgoerzen@complete.org--debian/rdiff-backup--head--1.0
 * tla inventory -s "rdiff-backup-0.12.5.orig" | tar -cSpf - -T- | gzip -9 &#62; "rdiff-backup_0.12.5.orig.tar.gz"
 *** Running build program
Running:  debuild ['-i\\+\\+pristine-trees|,,*|\\{arch\\}|\\.arch-ids', '-rfakeroot', '-us', '-uc']
...
      </PRE
><P
>        In this case, I had not checked out the upstream source and
        did not have my orig.tar.gz file handy.  Therefore,
        <B
CLASS="COMMAND"
>darcs-buildpackage</B
> checked out the upstream sources for me,
        generated the tar.gz file, and then called
        <B
CLASS="COMMAND"
>debuild</B
>
        to do the
        rest.
      </P
><P
>        If you are building for Debian, you will want to keep your
        orig.tar.gz around so that future source uploads use the same
        MD5 sum in the .dsc file.
      </P
><P
>        For more details, please see the manpage for
        <A
HREF="dbp.man.darcs.buildpackage.html"
>darcs-buildpackage(1)</A
>.
      </P
></DIV
><BR
CLEAR="all"><DIV
CLASS="SECT1"
><H1
CLASS="SECT1"
><A
NAME="DBP.REGULAR.UPSTREAM-UPDATE"
>Handling New Upstream Versions</A
></H1
><P
>        A common scenario for a Debian developer to deal with is that
        of a new upstream release.  The Debian patches from the most
        recent Debian release must be merged into the upstream one.
      </P
><P
>        There have been a few tools to do that:
        <B
CLASS="COMMAND"
>uupdate</B
> is one.  However, now that you are
        using Darcs, you can use its built-in <B
CLASS="COMMAND"
>pull</B
> command to make this
        easier.
      </P
><P
>        The first thing that you will do is to import the new upstream
        sources into your <SPAN
CLASS="APPLICATION"
>darcs-buildpackage</SPAN
> archive.  Please see <A
HREF="dbp.import.html#DBP.IMPORT.ORIG"
>the Section called <I
>Importing Upstream Sources</I
> in the Chapter called <I
>Importing Packages</I
></A
> for instructions.
      </P
><P
>        Next, check out the latest Debian version if you don't already
        have it (see <A
HREF="dbp.regular.html#DBP.REGULAR.FETCHING"
>the Section called <I
>Fetching Source from History</I
></A
>) and then
        cd into the Debian source directory.
      </P
><P
>        [ Note: I anticipate writing a program to automate the
        following steps. ]
      </P
><BR
CLEAR="all"><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="DBP.UPSTREAM.MERGING"
>Merging In Upstream</A
></H2
><P
>          Now, you are ready to merge in the new upstream.  Run
          <B
CLASS="COMMAND"
>darcs pull</B
>, giving it the path to your
          canonical upstream repository.
        </P
><P
>FIXME: add a sect3 demonstrating</P
></DIV
><BR
CLEAR="all"><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="DBP.UPSTREAM.MERGE.EXAMINING"
>Examining the Merge</A
></H2
><P
>          Now, you will want to examine the merge, especially if <SPAN
CLASS="APPLICATION"
>Darcs</SPAN
>
          complained of any conflicts.
        </P
><P
>          You'll also want to note the new version in
          <TT
CLASS="FILENAME"
>debian/changelog</TT
> and rename your
          directory based on the new version.  I find it easy to run a
          command like
          <B
CLASS="COMMAND"
>debchange -v 0.13.3-1</B
>, then modify the
          changelog as appropriate.  debchange will handle the rename
          for you.
        </P
></DIV
><BR
CLEAR="all"><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="DBP.UPSTREAM.COMMITING"
>Committing the Merge</A
></H2
><P
>          Finally, you will want to commit the merge.  If you want to
          just use a simple log message, a command like this will
          work:
        </P
><PRE
CLASS="SCREEN"
>$ <B
CLASS="COMMAND"
>darcs record -m "Merged in upstream 0.13.3"</B
>
FIXME: show output
        </PRE
><P
>          The string supplied after the -m is the log message.
        </P
><P
>          If you want to add a more detailed log, try this, just run
          <B
CLASS="COMMAND"
>darcs record</B
> and it will prompt you for one.
        </P
><P
>          You can see what happened by using <B
CLASS="COMMAND"
>darcs changes
          -s</B
>:
        </P
><PRE
CLASS="SCREEN"
>$ <B
CLASS="COMMAND"
>darcs changes -s</B
>
FIXME: show output
        </PRE
><P
>          Slick -- it shows exactly which upstream patches you used.
        </P
></DIV
></DIV
><BR
CLEAR="all"><DIV
CLASS="SECT1"
><H1
CLASS="SECT1"
><A
NAME="TLA.REGULAR.DEBIAN-UPDATE"
>Finalizing New Debian Versions</A
></H1
><P
>        When you have uploaded a Debian package to the archive, you
        should ask <SPAN
CLASS="APPLICATION"
>darcs-buildpackage</SPAN
> to note this for you.  That way, you can
        request this specific version later.  Just run this:
      </P
><PRE
CLASS="SCREEN"
>$ <B
CLASS="COMMAND"
>dbp-markdeb</B
>
FIXME: show output.
      </PRE
><P
>        The reason for this is that you might make several commits
        during the course of hacking on a given Debian version.  This
        command lets you note the final version, and to run it again,
        you must update the changelog.
      </P
><P
>        Technically speaking, this creates the DEBIAN_ tag.
      </P
></DIV
><BR
CLEAR="all"><DIV
CLASS="SECT1"
><H1
CLASS="SECT1"
><A
NAME="DBP.REGULAR.HISTORIC-VERSIONS"
>Finding Historic Versions</A
></H1
><P
>FIXME: this is not yet updated for Darcs</P
><P
>        To find the versions available in your <SPAN
CLASS="APPLICATION"
>darcs-buildpackage</SPAN
> archive, first cd
        to its top level and then run:
      </P
><PRE
CLASS="SCREEN"
>$ <B
CLASS="COMMAND"
>ls configs/*/*</B
>
configs/debian/rdiff-backup:
0.12.3-1  0.12.5-1

configs/upstream/rdiff-backup:
0.12.3  0.12.5
      </PRE
><P
>        This shows you that two Debian versions and two upstream
        versions of rdiff-backup are present.
      </P
></DIV
><BR
CLEAR="all"><DIV
CLASS="SECT1"
><H1
CLASS="SECT1"
><A
NAME="DBP.REGULAR.FETCHING"
>Fetching Source from History</A
></H1
><P
>        To fetch the source code from the <SPAN
CLASS="APPLICATION"
>darcs-buildpackage</SPAN
> archive, first
        <B
CLASS="COMMAND"
>cd</B
> into your top-level working copy.
        Then, using the name of the config file (see <A
HREF="dbp.regular.html#DBP.REGULAR.HISTORIC-VERSIONS"
>the Section called <I
>Finding Historic Versions</I
></A
>), use the
        <B
CLASS="COMMAND"
>tla buildcfg</B
> command:
      </P
><PRE
CLASS="SCREEN"
>$ <B
CLASS="COMMAND"
>tla buildcfg debian/rdiff-backup/0.12.5-1</B
>
* from import revision: jgoerzen@complete.org--debian/rdiff-backup--head--1.0--base-0
* patching for revision: jgoerzen@complete.org--debian/rdiff-backup--head--1.0--patch-1
* patching for revision: jgoerzen@complete.org--debian/rdiff-backup--debian--1.0--base-0
* patching for revision: jgoerzen@complete.org--debian/rdiff-backup--debian--1.0--patch-1
* patching for revision: jgoerzen@complete.org--debian/rdiff-backup--debian--1.0--patch-2
* making pristine copy
* tree version set jgoerzen@complete.org--debian/rdiff-backup--debian--1.0
      </PRE
><P
>        This command will have created the directory
        <TT
CLASS="FILENAME"
>+packages/rdiff-backup/rdiff-backup-0.12.5</TT
>
        to contain the sources.  Generating upstream sources works the
        same, and puts them into a directory ending in .orig.
      </P
><P
>	If you don't know what version you want but just want the
	latest, you can simply use a command such as <B
CLASS="COMMAND"
>tla
	  buildcfg debian/rdiff-backup/latest</B
>.
      </P
></DIV
></DIV
><TABLE
CLASS="navigation"
WIDTH="100%"
SUMMARY="Navigation footer"
CELLPADDING="2"
CELLSPACING="2"
><TR
VALIGN="middle"
><TD
ALIGN="left"
><A
ACCESSKEY="p"
HREF="dbp.import.html"
><B
>&lt;&lt;&lt;&nbsp;Importing Packages</B
></A
></TD
><TD
ALIGN="right"
><A
ACCESSKEY="n"
HREF="dbp.man.reference.html"
><B
>Command Reference&nbsp;&gt;&gt;&gt;</B
></A
></TD
></TR
></TABLE
></BODY
></HTML
>