all: $(MANUAL) $(MANPAGES)
-$(MANUAL): manual.sgml chapters/*.sgml manpages/*.sgml
+$(MANUAL): main.sgml manual.sgml manual-rpm.sgml chapters/*.sgml manpages/*.sgml
ifeq ($(HAVE_SGML2X),1)
docbook-2-html -s local $<
+ rm -rf $(MANUAL)
+ mv main-html $(MANUAL)
else
docbook2html -d local-nosgml2x.dsl -c $(GTK_DOC_CATALOG_FILE) -o $(MANUAL) $<
endif
git-pbuilder.1: ../bin/git-pbuilder
pod2man $< $@
-manual.sgml: $(VERSION_ENT)
+main.sgml: $(VERSION_ENT)
$(VERSION_ENT): $(GBP_VERSION)
echo '<!ENTITY gbp-version "$(DEB_VERSION)">' > $(VERSION_ENT)
--- /dev/null
+<chapter id="gbp.rpm.building">
+ <title>Building RPM packages from the &git; repository</title>
+ <para>
+ The &gbp-buildpackage-rpm; tool is used for building.
+ The tool creates the source tarball and copies it and the packaging files
+ to a separate build directory and builds the package there. By default,
+ &rpmbuild; is used as the builder command. You can define a different
+ builder command with the <option>--git-builder</option> option.
+ </para>
+
+ <para>
+ To build the (non-native) package when on <emphasis>packaging-branch</>,
+ using pristine-tar to create upstream tarball:
+ <screen>
+ $ &gbp-buildpackage-rpm; --pristine-tar
+ </screen>
+ During development, if you have unclean git tree (untracked files and/or
+ uncommitted changes) you may use:
+ <screen>
+ $ &gbp-buildpackage-rpm; --git-ignore-untracked
+ </screen>
+ or:
+ <screen>
+ $ &gbp-buildpackage-rpm; --git-ignore-new
+ </screen>
+ </para>
+
+ <para>
+ Git-buildpackage-rpm always builds in a separate build directory
+ (<emphasis>./rpmbuild/</emphasis> by default). You may change that and also
+ build a different revision that your current branch HEAD. The revision can
+ be any git "commit-ish", i.e. branch or tag name or a commit sha1.
+ Git-buildpackage also supports some "special revisions", i.e.
+ <emphasis>INDEX</> refer to the current index,
+ <emphasis>WC</> or <emphasis>WC.IGNORED</> refer to the current working
+ copy with all (even untracked and ignored) files,
+ <emphasis>WC.TRACKED</> refers to the current working copy of the files
+ tracked by git,
+ <emphasis>WC.UNTRACKED</> refers to the current working copy of all files
+ excluding ignore files.
+ Some examples:
+ <screen>
+ $ &gbp-buildpackage-rpm; --git-export-dir=/home/user/rpmbuild
+ $ &gbp-buildpackage-rpm; --git-export-dir=/home/user/rpmbuild --git-export=v1.2.3
+ $ &gbp-buildpackage-rpm; --git-export=WC.UNTRACKED
+ $ &gbp-buildpackage-rpm; --git-export=INDEX
+ $ &gbp-buildpackage-rpm; --git-export=feature/cool-new-thing
+ $ &gbp-buildpackage-rpm; --git-export=8d55173610f
+ </screen>
+ </para>
+
+ <sect1 id="gbp.rpm.building.patch-generation">
+ <title>Automatic patch generation</title>
+ <para>
+ When developing a non-native package with packaging and sources
+ in the same branch
+ (see <xref linkend="gbp.rpm.development.models.nonnative1">)
+ you usually want for &gbp-buildpackage-rpm; to automatically generate
+ patches. In this mode, &gbp-buildpackage-rpm; generates the upstream
+ tarball and copies packaging files to the build dir. After that it
+ generates patches from commits between <option>upstream</> and the
+ revision to be built, and, updates the spec file accordingly.
+ Git-buildpackage-rpm also have some options to alter the patch
+ generation. Build package with patch generation:
+ <screen>
+ $ &gbp-buildpackage-rpm; --git-patch-export
+ </screen>
+ Ignore changes to packaging/ directory and compress patches larger
+ than 100 kilobytes:
+ <screen>
+ $ &gbp-buildpackage-rpm; --git-patch-export --git-patch-export-compress=100k --git-patch-export-ignore-path='^packaging/.*'
+ </screen>
+ </para>
+ </sect1>
+
+ <sect1 id="gbp.rpm.building.patch-queue">
+ <title>Working with separate development branch</title>
+ <para>
+ When developing a non-native package with packaging data and source
+ code in separate branches
+ (see <xref linkend="gbp.rpm.development.models.nonnative2">)
+ you use the &gbp-pq-rpm; tool to handle the patches. You work on the
+ source code on the development branch and then <emphasis>export</>
+ the patches to the packaging branch when building the RPM package.
+ </para>
+
+ <para>
+ Create a <emphasis>development</> (or <emphasis>patch-queue</>) branch
+ by applying the patches in current packaging branch on top of the
+ upstream version. This will create a new branch, e.g.
+ <emphasis>development/master</> assuming your current branch is
+ <emphasis>master</>. Simply:
+ <screen>
+ $ &gbp-pq-rpm; import
+ </screen>
+ Now you can develop normally on the development branch (add, remove,
+ rebase, amend commits). Just make sure you stay based on the correct
+ upstream version, if doing git-rebase. After you're happy with your
+ changes and you're ready to build an RPM package, you have to
+ <emphasis>export</> the patches with &gbp-pq-rpm;. This will change
+ back to you packaging branch, generate patches from commits between
+ between <emphasis>upstream</> and the HEAD of the development branch
+ and update the spec file with the new patches:
+ <screen>
+ $ &gbp-pq-rpm; export
+ </screen>
+ Commit the changes to packaging branch, and build. For example:
+ <screen>
+ $ <command>git add</> *patch *spec
+ $ <command>git commit</> -a
+ $ &gbp-buildpackage-rpm;
+ </screen>
+ Of course you can build even without committing by using the
+ <option>--git-export=WC.UNTRACKED</> option of &gbp-buildpackage-rpm;.
+ </para>
+
+ <para>
+ Moving to a new upstream version is basically simple. Assuming you
+ have imported/pulled new upstream version to your git-tree, just:
+ <screen>
+ $ <command>git checkout</> master
+ # Edit the spec file and change the 'Version:' tag to new upstream version
+ $ <command>vim</> *spec
+ $ <command>git commit</> *spec
+ $ &gbp-pq-rpm; rebase
+ </screen>
+ However, if the patches do not apply cleanly, you have to manually
+ apply and resolve the patches.
+ </para>
+ </sect1>
+
+</chapter>
--- /dev/null
+<!ENTITY ch.intro-rpm SYSTEM "intro-rpm.sgml">
+<!ENTITY ch.development-rpm SYSTEM "development-rpm.sgml">
+<!ENTITY ch.building-rpm SYSTEM "building-rpm.sgml">
--- /dev/null
+<chapter id="gbp.rpm.development">
+ <title>Development flow</title>
+
+ <sect1 id="gbp.rpm.development.models">
+ <title>Development models</title>
+ <para>
+ The &gbp-buildpackage-rpm; toolset basically supports three different
+ models of package maintenance.
+ </para>
+
+ <sect2 id="gbp.rpm.development.models.native"
+ xreflabel="Native package">
+ <title>Native package</title>
+ <para>
+ This means that you are the upstream, there is no separate
+ upstream with which you have to sync. Basically, only
+ <option>packaging-branch</> is used - it contains both the source
+ code and packaging files. No patches should be present as all
+ changes can be directly committed to upstream (which is you).
+ When building, &gbp-buildpackage-rpm; will create the source
+ tarball and copy it and the packaging to the build directory.
+ </para>
+ </sect2>
+
+ <sect2 id="gbp.rpm.development.models.nonnative1"
+ xreflabel="Non-native package, model 1">
+ <title>Upstream package, alternative 1: packaging and sources in
+ the same branch</title>
+ <para>
+ This represents somewhat Debian-style package maintenance.
+ All changes (packaging and source code) are done to the same
+ branch, i.e., the <option>packaging-branch</>, based on the
+ <option>upstream-branch</>. When package is built,
+ &gbp-buildpackage-rpm; can automatically generate patches from
+ upstream version to packaging branch head (one patch per commit).
+ and modify the spec file accordingly.
+ </para>
+ </sect2>
+
+ <sect2 id="gbp.rpm.development.models.nonnative2"
+ xreflabel="Non-native package, model 2">
+ <title>Upstream package, alternative 2: packaging and sources in
+ separate branches</title>
+ <para>
+ In this model packaging files (spec and patches) are held in
+ <option>packaging-branch</> and upstream sources in
+ <option>upstream-branch</>.
+ Your code development is done on the <option>patch-queue-branch</>,
+ based on the <option>upstream-branch</>, which only contains source
+ code but no packaging files. When building the package,
+ &gbp-pq-rpm; tool is used to export patches from the patch queue
+ branch to the packaging branch and edit the spec file accordingly.
+ Finally, &gbp-buildpackage-rpm; will create the upstream source
+ tarball and export it and the packaging files to the build
+ directory, and, build the RPM package.
+ </para>
+ </sect2>
+ </sect1>
+
+ <sect1 id="gbp.rpm.development.scratch">
+ <title>Starting from scratch with a non-native package</title>
+ <para>
+ In this case, you most probably want to package software not yet
+ found in your distro. First, create an empty repository:
+ <screen>
+ $ <command>mkdir</> mypackage
+ $ <command>cd</> mypackage
+ $ <command>git init</>
+ </screen>
+ Then, import the upstream sources, create the packaging/development
+ branch and add the rpm packaging files. You have two choices:
+ </para>
+
+ <orderedlist>
+ <listitem><para>
+ packaging files and development sources in the same branch
+ <screen>
+ $ <command>git-import-orig-rpm</> ../mypackage.tar.gz
+ # Optionally (recommended): add gbp.conf
+ $ <command>vim</> .gbp.conf && <command>git add</> .gbp.conf && <command>git commit</> -m"Add gbp.conf"
+ # Add packaging files to source tree under subdir 'packaging'
+ $ <command>mkdir</> packaging && <command>cd</> packaging
+ $ <command>vim</> mypackage.spec
+ $ <command>git add</> .
+ $ <command>git commit</> -m"Add packaging files"
+ </screen></para>
+ </listitem>
+
+ <listitem><para>
+ development sources and packaging files in separate branches
+ <screen>
+ $ <command>git-import-orig-rpm</> --no-merge ../mypackage.tar.gz
+ # Optionally (recommended): add gbp.conf
+ $ <command>vim</> .gbp.conf && <command>git add</> .gbp.conf && <command>git commit</> -m"Add gbp.conf"
+ # Add packaging files (to root of master branch)
+ $ <command>vim</> mypackage.spec
+ $ <command>git add </> .
+ $ <command>git commit</> -m"Add packaging files"
+ </screen></para>
+ </listitem>
+ </orderedlist>
+ </sect1>
+
+ <sect1 id="gbp.rpm.development.convert">
+ <title>Converting an existing git repository of a non-native package</>
+ <para>
+ In this case, you already have a git repository containing the
+ upstream source, but it was created neither with &gbp-clone; nor
+ &gbp-import-srpm;.
+ You need to have a separate branch for upstream sources.
+ If you already have that, you can simply rename that branch to the
+ default upstream-branch:
+ <screen>
+ $ <command>git branch</> -m my-old-upstream-branch upstream
+ </screen>
+ OR just add the name of your upstream branch to gbp.conf.
+ Then, you just create a packaging/development branch(es) with git and
+ add packaging files to the packaging branch. If you want to maintain
+ sources and packaging in the same branch
+ (<xref linkend="gbp.rpm.development.models.nonnative1">)
+ do something like:
+ <screen>
+ $ <command>git checkout</> -b master upstream
+ # Optionally (recommended): add gbp.conf
+ $ <command>vim</> .gbp.conf && <command>git add</> .gbp.conf && <command>git commit</> -m"Add gbp.conf"
+ # Add packaging files to source tree, add and commit the packaging files
+ # ...
+ </screen>
+ If you want to maintain development sources and packaging in separate
+ branches
+ (<xref linkend="gbp.rpm.development.models.nonnative2">):
+ <screen>
+ $ <command>git checkout</> --orphan master
+ $ <command>rm</> .git/index
+ $ <command>git commit</> --allow-empty -m"Create packaging branch"
+ # Optionally (recommended): add gbp.conf
+ $ <command>vim</> .gbp.conf && <command>git add</> .gbp.conf && <command>git commit</> -m"Add gbp.conf"
+ # Next, add and commit the packaging files (.spec etc)
+ $ <command>vim</> mypackage.spec && <command>git add</> mypackage.spec && <command>git commit</> -m"Add packaging files"
+ # Now, you can create the development branch (and import possible patches)
+ $ &gbp-pq-rpm; import
+ </screen>
+ </para>
+ </sect1>
+</chapter>
+
--- /dev/null
+<chapter id="gbp.rpm.intro">
+ <title>Introduction</title>
+
+ <para>
+ Git-buildpackage is a <ulink url="http://www.debian.org/">Debian</ulink>
+ toolset for maintaining and building packages in/from git repositories.
+ The still experimental RPM variants of the tool, extend the support
+ from Debian-only to building and maintaining RPM packages, too.
+ The documentation of git-buildpackage-rpm here reflects the the
+ <ulink url="gbp.html">Debian git-buildpackage documentation</>
+ <!--<xref linkend="gbp">Debian git-buildpackage documentation</xref>.-->
+ </para>
+
+ <para>
+ The RPM versions of the tools can in their current state
+ do basically all the same tasks as the Debian versions, except for changelog generation.
+ However, the philosophy is somewhat different in some parts. The RPM tools
+ read the .spec file instead of changelog in determining packaging
+ information (version number, name etc). Another clear difference is
+ that &gbp-buildpackage-rpm; will always build in a separate build
+ directory whereas &gbp-buildpackage; (the Debian) tool builds in the
+ git working dir, by default.
+ Third, conceptual, difference (for non-native packages) is that you may
+ have packaging files in an orphan branch, without development sources:
+ i.e. you develop code in 'patch-queue' branch that doesn't contain any
+ packaging files, and, do 'pq-rpm export' to 'packaging' branch that only
+ contains packaging files (.spec file, patches etc.) but no sources.
+ The Debian/RPM tool equivalence is:
+ <itemizedlist>
+ <listitem><para>&gbp-buildpackage; -> RPM: &gbp-buildpackage-rpm;</para></listitem>
+ <listitem><para>&gbp-import-dsc; -> RPM: &gbp-import-srpm;</para></listitem>
+ <listitem><para>&gbp-import-orig; -> RPM: &gbp-import-orig-rpm;</para></listitem>
+ <listitem><para>&gbp-pq; -> RPM: &gbp-pq-rpm;</para></listitem>
+ <listitem><para>&gbp-clone; -> RPM: &gbp-clone; (the same tool)</para></listitem>
+ <listitem><para>&gbp-pull; -> RPM: &gbp-pull; (the same tool)</para></listitem>
+ <listitem><para>&gbp-dch; -> RPM: not available</para></listitem>
+ <listitem><para>&gbp-import-dscs; -> RPM: not available</para></listitem>
+ </itemizedlist>
+ </para>
+
+<sect1 id="gbp.rpm.repository">
+ <title>RPM Repository Layout</title>
+
+ <para>
+ The required repository layout is similar to Debian: basically the only
+ requirement is that non-native packages must have clean upstream sources
+ in a separate branch. Other branches are:
+ </para>
+
+ <itemizedlist>
+ <listitem><para>
+ <option>packaging-branch</> contains packaging files (spec
+ and source files, e.g. patches, needed by rpmbuild, except for the orig
+ tarball). This branch <emphasis>may</> contain the development sources as well
+ (always true for native packages).
+ </para></listitem>
+
+ <listitem><para>
+ <option>upstream-branch</> contains upstream sources.
+ This can either be a branch you import to or a branch of an upstream
+ repository you pull from.
+ </para></listitem>
+
+ <listitem><para>
+ <option>pristine-tar-branch</> contains pristine-tar data to
+ recreate the original upstream tarball from the upstream-branch.
+ </para></listitem>
+
+ <listitem><para>
+ <option>patch-queue-branch(es)</> are related to
+ <option>packaging-branch(es)</>. These are also called the
+ <emphasis>development</> branhces in the RPM tools.
+ The development/patch-queue branch is the upstream
+ plus the patches from packaging branch applied. In RPM tools the
+ default branch name of the development/patch-queue branch is
+ <option>development/<packaging-branch-name></>.
+ </para></listitem>
+ </itemizedlist>
+</sect1>
+
+<sect1 id="gbp.rpm.workflow">
+ <title>RPM Workflow</title>
+
+ <para>
+ The basic workflow is very similar to Debian:
+ </para>
+
+ <orderedlist>
+ <listitem><para>
+ Import a package via &gbp-import-srpm; OR clone from the
+ distro git with &gbp-clone; if the package is already maintained with
+ &gbp-buildpackage-rpm;.
+ </para></listitem>
+
+ <listitem><para>
+ Develop, test, commit changes.</para></listitem>
+ <listitem><para>Once satisfied you can build the final package with
+ &gbp-buildpackage-rpm; (optionally with --git-tag to create a tag in
+ git) and push it to git server.
+ </para></listitem>
+ </orderedlist>
+</sect1>
+
+</chapter>
<!ENTITY debuildcmd "<command>debuild</command>">
<!ENTITY gbp.conf "<filename>gbp.conf</filename>">
+ <!ENTITY gbp-buildpackage-rpm "<command>gbp buildpackage-rpm</command>">
+ <!ENTITY gbp-import-orig-rpm "<command>gbp import-orig-rpm</command>">
+ <!ENTITY gbp-import-srpm "<command>gbp import-srpm</command>">
+ <!ENTITY gbp-pq-rpm "<command>gbp pq-rpm</command>">
+ <!ENTITY rpmbuild "<command>rpmbuild</command>">
+
<!ENTITY debian "<productname>Debian</productname>">
<!ENTITY git "<productname>Git</productname>">
<!ENTITY dch "<productname>dch</productname>">
--- /dev/null
+<!DOCTYPE set PUBLIC "-//OASIS//DTD DocBook V4.1//EN"
+[
+ <!ENTITY % COMMON SYSTEM "common.ent">
+ %COMMON;
+ <!ENTITY % VERSION SYSTEM "version.ent">
+ %VERSION;
+ <!ENTITY % MANPAGES SYSTEM "manpages/manpages.ent">
+ %MANPAGES;
+ <!ENTITY % CHAPTERS SYSTEM "chapters/chapters.ent">
+ %CHAPTERS;
+ <!ENTITY % CHAPTERS.RPM SYSTEM "chapters/chapters-rpm.ent">
+ %CHAPTERS.RPM;
+ <!ENTITY book.debian SYSTEM "manual.sgml">
+ <!ENTITY book.rpm SYSTEM "manual-rpm.sgml">
+ <!ENTITY gbp.copyright SYSTEM "copyright.sgml">
+]>
+
+<set id="index">
+ <setinfo>
+ <title>Building Packages with git-buildpackage suite</title>
+ <subtitle>Version: &gbp-version;</subtitle>
+ </setinfo>
+
+ &book.debian;
+ &book.rpm;
+</set>
+
--- /dev/null
+<book id="gbp-rpm">
+ <bookinfo>
+ <title>Building RPM Packages with git-buildpackage-rpm</title>
+ <author><firstname>Markus</firstname> <surname>Lehtonen</surname></author>
+ <address><email>markus.lehtonen@linux.intel.com</email></address>
+ <subtitle>Version: &gbp-version;</subtitle>
+ </bookinfo>
+
+ &ch.intro-rpm;
+ &ch.development-rpm;
+ &ch.building-rpm;
+
+ <appendix id="gbp.rpm.copyleft">
+ <title>Copyright</title>
+ &gbp.copyright;
+ </appendix>
+</book>
+
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V4.1//EN" [
- <!ENTITY % COMMON SYSTEM "common.ent">
- %COMMON;
- <!ENTITY % VERSION SYSTEM "version.ent">
- %VERSION;
- <!ENTITY % MANPAGES SYSTEM "manpages/manpages.ent">
- %MANPAGES;
- <!ENTITY % CHAPTERS SYSTEM "chapters/chapters.ent">
- %CHAPTERS;
- <!ENTITY gbp.copyright SYSTEM "copyright.sgml">
-]>
-
<book id="gbp">
<bookinfo>
<title>Building Debian Packages with git-buildpackage</title>
projects / tools / git-buildpackage.git / commitdiff