From f74313134ea1396b11a16d9c9ba5c724644f1137 Mon Sep 17 00:00:00 2001 From: Markus Lehtonen Date: Wed, 22 Feb 2012 12:48:57 +0200 Subject: [PATCH] docs: add initial RPM documentation Signed-off-by: Markus Lehtonen --- docs/Makefile | 6 +- docs/chapters/building-rpm.sgml | 132 +++++++++++++++++++++++++++++++++ docs/chapters/chapters-rpm.ent | 3 + docs/chapters/development-rpm.sgml | 146 +++++++++++++++++++++++++++++++++++++ docs/chapters/intro-rpm.sgml | 104 ++++++++++++++++++++++++++ docs/common.ent | 6 ++ docs/main.sgml | 27 +++++++ docs/manual-rpm.sgml | 18 +++++ docs/manual.sgml | 12 --- 9 files changed, 440 insertions(+), 14 deletions(-) create mode 100644 docs/chapters/building-rpm.sgml create mode 100644 docs/chapters/chapters-rpm.ent create mode 100644 docs/chapters/development-rpm.sgml create mode 100644 docs/chapters/intro-rpm.sgml create mode 100644 docs/main.sgml create mode 100644 docs/manual-rpm.sgml diff --git a/docs/Makefile b/docs/Makefile index f1dac58..5cd83a0 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -31,9 +31,11 @@ GTK_DOC_CATALOG_FILE ?= /usr/share/sgml/gtk-doc/gtk-doc.cat 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 @@ -55,7 +57,7 @@ manpage.refs: $(BUILD_MAN_XREF_PAGES) git-pbuilder.1: ../bin/git-pbuilder pod2man $< $@ -manual.sgml: $(VERSION_ENT) +main.sgml: $(VERSION_ENT) $(VERSION_ENT): $(GBP_VERSION) echo '' > $(VERSION_ENT) diff --git a/docs/chapters/building-rpm.sgml b/docs/chapters/building-rpm.sgml new file mode 100644 index 0000000..866cd3f --- /dev/null +++ b/docs/chapters/building-rpm.sgml @@ -0,0 +1,132 @@ + + Building RPM packages from the &git; repository + + 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. + + + + To build the (non-native) package when on packaging-branch, + using pristine-tar to create upstream tarball: + + $ &gbp-buildpackage-rpm; --pristine-tar + + During development, if you have unclean git tree (untracked files and/or + uncommitted changes) you may use: + + $ &gbp-buildpackage-rpm; --git-ignore-untracked + + or: + + $ &gbp-buildpackage-rpm; --git-ignore-new + + + + + Git-buildpackage-rpm always builds in a separate build directory + (./rpmbuild/ 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. + INDEX refer to the current index, + WC or WC.IGNORED refer to the current working + copy with all (even untracked and ignored) files, + WC.TRACKED refers to the current working copy of the files + tracked by git, + WC.UNTRACKED refers to the current working copy of all files + excluding ignore files. + Some examples: + + $ &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 + + + + + Automatic patch generation + + When developing a non-native package with packaging and sources + in the same branch + (see ) + 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 + + + + Working with separate development branch + + When developing a non-native package with packaging data and source + code in separate branches + (see ) + you use the &gbp-pq-rpm; tool to handle the patches. You work on the + source code on the development branch and then export + the patches to the packaging branch when building the RPM package. + + + + Create a development (or 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. + development/master assuming your current branch is + master. Simply: + + $ &gbp-pq-rpm; import + + 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 + export the patches with &gbp-pq-rpm;. This will change + back to you packaging branch, generate patches from commits between + between upstream and the HEAD of the development branch + and update the spec file with the new patches: + + $ &gbp-pq-rpm; export + + Commit the changes to packaging branch, and build. For example: + + $ git add *patch *spec + $ git commit -a + $ &gbp-buildpackage-rpm; + + Of course you can build even without committing by using the + + + + Moving to a new upstream version is basically simple. Assuming you + have imported/pulled new upstream version to your git-tree, just: + + $ git checkout master + # Edit the spec file and change the 'Version:' tag to new upstream version + $ vim *spec + $ git commit *spec + $ &gbp-pq-rpm; rebase + + However, if the patches do not apply cleanly, you have to manually + apply and resolve the patches. + + + + diff --git a/docs/chapters/chapters-rpm.ent b/docs/chapters/chapters-rpm.ent new file mode 100644 index 0000000..165e0c0 --- /dev/null +++ b/docs/chapters/chapters-rpm.ent @@ -0,0 +1,3 @@ + + + diff --git a/docs/chapters/development-rpm.sgml b/docs/chapters/development-rpm.sgml new file mode 100644 index 0000000..1ae5125 --- /dev/null +++ b/docs/chapters/development-rpm.sgml @@ -0,0 +1,146 @@ + + Development flow + + + Development models + + The &gbp-buildpackage-rpm; toolset basically supports three different + models of package maintenance. + + + + Native package + + This means that you are the upstream, there is no separate + upstream with which you have to sync. Basically, only + + + + + Upstream package, alternative 1: packaging and sources in + the same branch + + This represents somewhat Debian-style package maintenance. + All changes (packaging and source code) are done to the same + branch, i.e., the + + + + Upstream package, alternative 2: packaging and sources in + separate branches + + In this model packaging files (spec and patches) are held in + + + + + + Starting from scratch with a non-native package + + In this case, you most probably want to package software not yet + found in your distro. First, create an empty repository: + + $ mkdir mypackage + $ cd mypackage + $ git init + + Then, import the upstream sources, create the packaging/development + branch and add the rpm packaging files. You have two choices: + + + + + packaging files and development sources in the same branch + + $ git-import-orig-rpm ../mypackage.tar.gz + # Optionally (recommended): add gbp.conf + $ vim .gbp.conf && git add .gbp.conf && git commit -m"Add gbp.conf" + # Add packaging files to source tree under subdir 'packaging' + $ mkdir packaging && cd packaging + $ vim mypackage.spec + $ git add . + $ git commit -m"Add packaging files" + + + + + development sources and packaging files in separate branches + + $ git-import-orig-rpm --no-merge ../mypackage.tar.gz + # Optionally (recommended): add gbp.conf + $ vim .gbp.conf && git add .gbp.conf && git commit -m"Add gbp.conf" + # Add packaging files (to root of master branch) + $ vim mypackage.spec + $ git add . + $ git commit -m"Add packaging files" + + + + + + + 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> + diff --git a/docs/chapters/intro-rpm.sgml b/docs/chapters/intro-rpm.sgml new file mode 100644 index 0000000..8cc0471 --- /dev/null +++ b/docs/chapters/intro-rpm.sgml @@ -0,0 +1,104 @@ +<chapter id="gbp.rpm.intro"> + <title>Introduction + + + Git-buildpackage is a Debian + 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 + Debian git-buildpackage documentation + + + + + 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: + + &gbp-buildpackage; -> RPM: &gbp-buildpackage-rpm; + &gbp-import-dsc; -> RPM: &gbp-import-srpm; + &gbp-import-orig; -> RPM: &gbp-import-orig-rpm; + &gbp-pq; -> RPM: &gbp-pq-rpm; + &gbp-clone; -> RPM: &gbp-clone; (the same tool) + &gbp-pull; -> RPM: &gbp-pull; (the same tool) + &gbp-dch; -> RPM: not available + &gbp-import-dscs; -> RPM: not available + + + + + RPM Repository Layout + + + 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: + + + + + + + + + + + + + + + + + + + RPM Workflow + + + The basic workflow is very similar to Debian: + + + + + 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;. + + + + Develop, test, commit changes. + 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. + + + + + diff --git a/docs/common.ent b/docs/common.ent index 005d674..69a703f 100644 --- a/docs/common.ent +++ b/docs/common.ent @@ -24,6 +24,12 @@ debuild"> gbp.conf"> + gbp buildpackage-rpm"> + gbp import-orig-rpm"> + gbp import-srpm"> + gbp pq-rpm"> + rpmbuild"> + Debian"> Git"> dch"> diff --git a/docs/main.sgml b/docs/main.sgml new file mode 100644 index 0000000..bd1d97d --- /dev/null +++ b/docs/main.sgml @@ -0,0 +1,27 @@ + + %COMMON; + + %VERSION; + + %MANPAGES; + + %CHAPTERS; + + %CHAPTERS.RPM; + + + +]> + + + + Building Packages with git-buildpackage suite + Version: &gbp-version; + + + &book.debian; + &book.rpm; + + diff --git a/docs/manual-rpm.sgml b/docs/manual-rpm.sgml new file mode 100644 index 0000000..2e58730 --- /dev/null +++ b/docs/manual-rpm.sgml @@ -0,0 +1,18 @@ + + + Building RPM Packages with git-buildpackage-rpm + Markus Lehtonen +
markus.lehtonen@linux.intel.com
+ Version: &gbp-version; + + + &ch.intro-rpm; + &ch.development-rpm; + &ch.building-rpm; + + + Copyright + &gbp.copyright; + + + diff --git a/docs/manual.sgml b/docs/manual.sgml index af5e12f..c79af07 100644 --- a/docs/manual.sgml +++ b/docs/manual.sgml @@ -1,15 +1,3 @@ - - %COMMON; - - %VERSION; - - %MANPAGES; - - %CHAPTERS; - -]> - Building Debian Packages with git-buildpackage -- 2.7.4