aboutsummaryrefslogtreecommitdiff
path: root/docs/chapters/building.sgml
blob: 6a131ffa2274e113db5513ad72e39ff1acf214fa (plain)
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
<chapter id="gbp.building">
    <title>Building packages from the &git; repository</title>
    <para>
    In order to build a &debian; package from the &git; repository you use:
    &git-buildpackage;. This builds the upstream tarball as will be described below and
    invokes &debuild; to build the package. To use another build command you
    can use the <option>--git-builder</option> option as described later in the manual
    but &debuild; is nice since it can invoke <productname>linda</productname>
    und <productname>lintian</productname>.
    During the development phase (when you're either not on the
    <emphasis>debian-branch</emphasis> or when you have uncommitted changes in
    your repository) you'll usually use:
<screen>
&git-buildpackage; <option>--git-ignore-new</option>
</screen>
    <para>If &git-buildpackage; doesn't find a valid upstream tarball it will create
    one by looking at the tag matching the upstream version, if no tag can be
    found it uses the tip of the current <option>upstream-branch</option>. Any
    other treeish object to create the upstream tarball from can be given with
    the <option>--upstream-branch</option> option.</para>
    <para>Once you're satisfied with the build and want to do a release you commit all
    your changes and issue:</para>
<screen>
&git-buildpackage; <option>--git-tag</option>
</screen>
    <para>This will again build the debian package and tag the final result after
    extracting the current version from the changelog. If you want &gpg; signed
    tags you can use the <option>--git-sign</option> and
    <option>--git-keyid</option> options. To save typing these option can be
    specified via the configuration files. You can futhermore change the tag
    format used when creating tags with the <option>debian-tag</option>
    option, the default is <replaceable>debian/&lt;version&gt;</replaceable>.</para>
    <sect1 id="gbp.building.export">
    <title>Using a separate build dir</title>
    <para>Tools like &svn-buildpackage; use a separate build-area. To achieve a similar behaviour
    with &git-buildpackage; use the <option>--git-export-dir</option> option:</para>
<screen>
&git-buildpackage; <option>--git-export-dir</option>=<replaceable>../build-area/</replaceable>
</screen>
    <para>This will export the head of the ecurrent branch to
    <replaceable>../build-area/package-version</replaceable>, build the
    package. If you don't want to export the current branch head you can use
    <option>--git-export</option> to export any treeish object, here are some
    examples:</para>
<screen>
&git-buildpackage; <option>--git-export-dir</option>=<replaceable>../build-area</replaceable> <option>--git-export</option>=<replaceable>debian/0.4.3</replaceable>
&git-buildpackage; <option>--git-export-dir</option>=<replaceable>../build-area</replaceable> <option>--git-export</option>=<replaceable>etch</replaceable>
&git-buildpackage; <option>--git-export-dir</option>=<replaceable>../build-area</replaceable> <option>--git-export</option>=<replaceable>8caed309653d69b7ab440e3d35abc090eb4c6697</replaceable>
&git-buildpackage; <option>--git-export-dir</option>=<replaceable>../build-area</replaceable> <option>--git-export</option>=<replaceable>INDEX</replaceable>
</screen>
    <para>The special argument <replaceable>INDEX</replaceable> exports the
    state of the current index which can be used to include staged but
    uncommitted changes in the build.</para>
    <para>If you want to default to build in a separate build area you can
    specify the directory to use in the gbp.conf.
<programlisting>
[git-buildpackage]
# use a build area relative to the git repository
export-dir=../build-area
# to use the same build area for all packages use an absolute path:
#export-dir=/home/debian-packages/build-area
</programlisting>
    </para>
    </sect1>
    <sect1 id="gbp.building.push">
    <title>Pushing into a remote repository</title>
	<para>If you want to push your changes automatically after a succesful build and tag
	you can use &git-buildpackage;'s posttag hook. A very simple invocation would look like this:
<programlisting>
<command>git-buildpackage</command> <option>--git-tag</option> <option>--git-posttag</option>=<replaceable>"git push && git push --tags"</replaceable>
</programlisting>
	This assumes you have set up a remote repository to push to in
        <filename>.git/config</filename>.</para>

	<para>Usually you want to make sure you don't push out any
        unrelated changes into the remote repository. This is handled by the
        following hook which only pushes out the created tag to where you pulled
        from and also forwards the corresponding remote branch to that position:
<programlisting>
#!/bin/sh -e
#
# gbp-push: post tag hook to push out the newly created tag and to forward the
# remote branch to that position

if ! REMOTE=$(git config --get branch."${GBP_BRANCH}".remote); then
    REMOTE=origin
fi

if [ "$GBP_TAG" ]; then
     echo "Pushing $GBP_TAG to $REMOTE"
     git push "$REMOTE" "$GBP_TAG"
else
     echo "GBP_TAG no set."
     exit 1
fi

if [ "$GBP_SHA1" ] && [ "$GBP_BRANCH" ]; then
    git push "$REMOTE" "$GBP_SHA1":"$GBP_BRANCH"
else
    echo "GBP_SHA1 or GBP_BRANCH not set."
    exit 1
fi
echo "done."
</programlisting>
	<replaceable>GBP_TAG</replaceable>, <replaceable>GBP_SHA1</replaceable>
        and <replaceable>GBP_BRANCH</replaceable> are passed to the hook via the
        environment. To call this hook automatically upon tag creation add:
<programlisting>
<option>posttag</option>=<replaceable>"gbp-push"</replaceable>
</programlisting>
	to your <filename>.gbp.conf</filename> and make sure <filename>gbp-push</filename>
        is somewhere in your <replaceable>$PATH</replaceable>.
    </para>
    </sect1>
</chapter>