diff options
| -rw-r--r-- | docs/chapters/building-rpm.sgml | 128 | ||||
| -rw-r--r-- | docs/chapters/chapters-rpm.ent | 2 | ||||
| -rw-r--r-- | docs/chapters/development-rpm.sgml | 146 | ||||
| -rw-r--r-- | docs/chapters/intro-rpm.sgml | 122 | ||||
| -rw-r--r-- | docs/chapters/setup-rpm.sgml | 99 | ||||
| -rw-r--r-- | docs/manual-rpm.sgml | 2 |
6 files changed, 347 insertions, 152 deletions
diff --git a/docs/chapters/building-rpm.sgml b/docs/chapters/building-rpm.sgml index 3cd632a5..b03ccbd2 100644 --- a/docs/chapters/building-rpm.sgml +++ b/docs/chapters/building-rpm.sgml @@ -3,8 +3,130 @@ <para> The &git-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. + 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> + $ &git-buildpackage-rpm; --pristine-tar + </screen> + During development, if you have unclean git tree (untracked files and/or + uncommitted changes) you may use: + <screen> + $ &git-buildpackage-rpm; --git-ignore-untracked + </screen> + or: + <screen> + $ &git-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> + $ &git-buildpackage-rpm; --git-export-dir=/home/user/rpmbuild + $ &git-buildpackage-rpm; --git-export-dir=/home/user/rpmbuild --git-export=v1.2.3 + $ &git-buildpackage-rpm; --git-export=WC.UNTRACKED + $ &git-buildpackage-rpm; --git-export=INDEX + $ &git-buildpackage-rpm; --git-export=feature/cool-new-thing + $ &git-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 git-buildpackage-rpm to automatically generate + patches. In this mode, git-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> + $ &git-buildpackage-rpm; --git-patch-export + </screen> + Ignore changes to packaging/ directory and compress patches larger + than 100 kilobytes: + <screen> + $ &git-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 + $ &git-buildpackage-rpm + </screen> + Of course you can build even without committing by using the + <option>--git-export=WC.UNTRACKED</> option of &git-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> diff --git a/docs/chapters/chapters-rpm.ent b/docs/chapters/chapters-rpm.ent index 5fcb4372..165e0c02 100644 --- a/docs/chapters/chapters-rpm.ent +++ b/docs/chapters/chapters-rpm.ent @@ -1,3 +1,3 @@ <!ENTITY ch.intro-rpm SYSTEM "intro-rpm.sgml"> -<!ENTITY ch.setup-rpm SYSTEM "setup-rpm.sgml"> +<!ENTITY ch.development-rpm SYSTEM "development-rpm.sgml"> <!ENTITY ch.building-rpm SYSTEM "building-rpm.sgml"> diff --git a/docs/chapters/development-rpm.sgml b/docs/chapters/development-rpm.sgml new file mode 100644 index 00000000..4aec8bca --- /dev/null +++ b/docs/chapters/development-rpm.sgml @@ -0,0 +1,146 @@ +<chapter id="gbp.rpm.development"> + <title>Development flow</title> + + <sect1 id="gbp.rpm.development.models"> + <title>Development models</title> + <para> + The &git-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, &git-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, + &git-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, &git-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 + &git-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 index 2e15bc86..b262534d 100644 --- a/docs/chapters/intro-rpm.sgml +++ b/docs/chapters/intro-rpm.sgml @@ -1,77 +1,103 @@ <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>.--> + 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 &git-buildpackage-rpm; will always build in a separate build - directory whereas &git-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>&git-buildpackage; -> RPM: &git-buildpackage-rpm;</para></listitem> - <listitem><para>&git-import-dsc; -> RPM: &git-import-srpm;</para></listitem> - <listitem><para>&git-import-orig; -> RPM: &git-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>&git-dch; -> RPM: not available</para></listitem> - <listitem><para>&git-import-dscs; -> RPM: not available</para></listitem> - </itemizedlist> + 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 &git-buildpackage-rpm; will always build in a separate build + directory whereas &git-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>&git-buildpackage; -> RPM: &git-buildpackage-rpm;</para></listitem> + <listitem><para>&git-import-dsc; -> RPM: &git-import-srpm;</para></listitem> + <listitem><para>&git-import-orig; -> RPM: &git-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>&git-dch; -> RPM: not available</para></listitem> + <listitem><para>&git-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: + 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 + <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. + (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/* branches</> are related to - <option>packaging-branch(es)</>. The patch-queue branch is the upstream - plus the patches from packaging branch applied.</para></listitem> + 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: + The basic workflow is very similar to Debian: </para> + <orderedlist> - <listitem><para>Import a package via &git-import-srpm; OR clone from the + <listitem><para> + Import a package via &git-import-srpm; OR clone from the distro git with &gbp-clone; if the package is already maintained with - &git-buildpackage-rpm;.</para></listitem> - <listitem><para>Develop, test, commit changes.</para></listitem> + &git-buildpackage-rpm;. + </para></listitem> + + <listitem><para> + Develop, test, commit changes.</para></listitem> <listitem><para>Once satisfied you can build the final package with &git-buildpackage-rpm; (optionally with --git-tag to create a tag in - git) and push it to git server.</para></listitem> + git) and push it to git server. + </para></listitem> </orderedlist> </sect1> diff --git a/docs/chapters/setup-rpm.sgml b/docs/chapters/setup-rpm.sgml deleted file mode 100644 index d6d24d37..00000000 --- a/docs/chapters/setup-rpm.sgml +++ /dev/null @@ -1,99 +0,0 @@ -<chapter id="gbp.rpm.development"> - <title>Development flow</title> - - <sect1 id="gbp.rpm.setup.models"> - <title>Development models</title> - <para>The &git-buildpackage-rpm; toolset basically supports three different - models of package maintenance.</para> - <sect2> - <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, &git-buildpackage-rpm; will create - the source tarball and copy it and the packaging to the build directory. - </para> - </sect2> - <sect2> - <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, - &git-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> - <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, &git-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.setup.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: - <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> - </para> - </sect1> - - <sect1 id="gbp.rpm.setup.convert"> - <title>Converting an existing git repository of a non-native package</title> - <para>In this case, you already have a git repository containing the - upstream source, but it was created neither with &gbp-clone; nor &git-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. - </para> - </sect1> -</chapter> - diff --git a/docs/manual-rpm.sgml b/docs/manual-rpm.sgml index 5baf3cad..9f1ddb97 100644 --- a/docs/manual-rpm.sgml +++ b/docs/manual-rpm.sgml @@ -17,7 +17,7 @@ </bookinfo> &ch.intro-rpm; - &ch.setup-rpm; + &ch.development-rpm; &ch.building-rpm; <appendix id="gbp.copyleft"> |