README.ppa

   1
   2 How to build packages for the Launchpad PPA
   3 -------------------------------------------
   4
   5 As you may have noticed already, Launchpad and Ubuntu are tightly connected,
   6 so this HowTo assumes you run Ubuntu or an Ubuntu derivate. It may work similar
   7 on Debian, but no guarantees.
   8
   9 This HowTo also assumes you build for Ubuntu release 'vivid'. In case you build
  10 for another release, simply replace each occurence of 'vivid' with that other
  11 release name.
  12
  13
  14 Web references, prerequisites
  15 -----------------------------
  16
  17 What a PPA, a Personal Package Archive, is:
  18
  19   https://help.launchpad.net/Packaging/PPA
  20
  21
  22 Packaging for a PPA happens the same way as packaging for Debian or Ubuntu it's
  23 self. Ubuntu wiki pages about packaging start here:
  24
  25   http://packaging.ubuntu.com/html/
  26
  27
  28 About the few differences between PPAs and regular packages (e.g. version
  29 number):
  30
  31   https://help.launchpad.net/Packaging
  32
  33
  34 Required packages, next to the environment to build gEDA it's self:
  35
  36   sudo apt-get install packaging-dev ubuntu-dev-tools
  37
  38
  39 Other than that you also have to be member of the gEDAhead Launchpad team,
  40 signed Ubuntus Code of Conduct and uploaded the public part of your SSH key.
  41
  42   https://launchpad.net/~geda
  43   https://launchpad.net/codeofconduct
  44   https://launchpad.net/people/+me/+editsshkeys
  45
  46
  47 Getting started
  48 ---------------
  49
  50 If you want to upload the packages later, you need your personal GPG key. On
  51 how to create such a key, see
  52
  53   https://help.ubuntu.com/community/GnuPrivacyGuardHowto
  54
  55 To use this key it has to be added to your personal Launchpad account. Visit
  56
  57   https://launchpad.net/people/+me/+editpgpkeys
  58
  59 and follow the instructions. 'gpg --fingerprint' lists your keys with
  60 fingerprints. After the fingerprint is imported, Launchpad will send you an
  61 encrypted email and being able to decrypt it (your emailer should do this)
  62 means this part works fine. Click the activation link in the email and be done.
  63
  64 Without the key you can still build the package, e.g. to find out wether
  65 packaging works or to install it locally. The build process will abort a moment
  66 before completion, but after creating the packages.
  67
  68
  69 We want to build straight from the Git repo. However, Debian packaging builds
  70 much on the assumption that developers ("upstream") and packagers are two
  71 different entities. Some packaging tools assume source code tarballs in
  72 specific places, which we don't have, unless we create them just for building
  73 the package.
  74
  75 Luckily, the existence of Git has come to the attention of Debianers these
  76 days, so they start to use repository clones for packaging ... which is very
  77 similar to packaging from the original repo. See
  78
  79   https://wiki.debian.org/PackagingWithGit
  80
  81 The debian/ directory is already part of our Git repo.
  82
  83 Central tool is 'git-buildpackage'. It creates a temporary "upstream" tarball
  84 straight from a Git stored object (usually a branch), not from the currently
  85 checked out files of this repository. This temporary tarball is then passed to
  86 the usual packaging tools, which in turn unpack it again.
  87
  88 To deal with the upstream-less situation 'git-buildpackage' needs a few
  89 parameters. This is how it's run:
  90
  91   git-buildpackage --git-ignore-new --git-force-create \
  92                    --git-upstream-branch=master --git-upstream-tree=BRANCH \
  93                    --git-export-dir=packagebuild
  94
  95 Explanation:
  96
  97   --git-ignore-new
  98     Ignores that there are uncommitted files when fetching the temporary build
  99     tarball from Git. Without this flag, such files cause an abort.
 100
 101   --git-force-create
 102     Overwrites an eventually already existing result tarball.
 103
 104   --git-upstream-branch=master
 105   --git-upstream-tree=BRANCH
 106     Tells which branch to fetch the temporary build tarball from and that
 107     'master' is a branch.
 108
 109   --git-export-dir=packagebuild
 110     Unpacks the temporary build tarball in 'packagebuild'. Without this flag,
 111     this happens in the main directory and then dpkg-buildpackage complains
 112     about files existing, but not being part of the build tarball.
 113
 114
 115 Doing a (weekly) PPA upload
 116 ---------------------------
 117
 118 First you have to update the changelog. Debian packaging insists on this and
 119 also uses the signature of the top changelog entry to look for the signature
 120 GPG key.
 121
 122   # For simplicity, take the first available signature.
 123   MY_SIGNATURE=$(gpg --list-secret-keys | \
 124                  awk '/^uid/ { $1 = ""; sub(/^[ ]+/, ""); print; }' | \
 125                  head -1)
 126   echo "My signature is ${MY_SIGNATURE}."
 127   TODAY=$(date +%Y%m%d)
 128   TIMESTAMP=$(date -R)
 129   REL=vivid
 130   mv debian/changelog temp
 131   echo "pcb (${TODAY}-gedahead-weekly) ${REL};" \
 132        "urgency=low"                                    > debian/changelog
 133   echo                                                 >> debian/changelog
 134   echo "  * Weekly build."                             >> debian/changelog
 135   echo                                                 >> debian/changelog
 136   echo "  For changes see" \
 137        "http://git.geda-project.org/pcb/log/"          >> debian/changelog
 138   echo                                                 >> debian/changelog
 139   echo " -- ${MY_SIGNATURE}  ${TIMESTAMP}"             >> debian/changelog
 140   echo                                                 >> debian/changelog
 141   cat temp >>debian/changelog
 142   rm temp
 143   sed -i "s/^Uploaders:.*/Uploaders: ${MY_SIGNATURE}/" debian/control
 144   unset MY_SIGNATURE TODAY TIMESTAMP REL
 145   # git-buildpackage picks up comitted stuff, only, so commit the above.
 146   git commit debian/changelog debian/control -m "weekly build"
 147
 148
 149 Then build as explained above:
 150
 151   # We want to build from our current branch, which is not always 'master'.
 152   THIS=$(git symbolic-ref --short HEAD)
 153   rm -rf packagebuild
 154   git-buildpackage --git-ignore-new --git-force-create \
 155                    --git-upstream-branch=${THIS} --git-upstream-tree=BRANCH \
 156                    --git-export-dir=packagebuild
 157   unset THIS
 158
 159
 160 Launchpad PPAs accept only sources, they build binaries them selfs. Trying
 161 to upload binaries results in a rejection of the whole package, so let's see
 162 the above as a preparation and build test and rebuild for source-only packages.
 163 It takes only a few seconds.
 164
 165   THIS=$(git symbolic-ref --short HEAD)
 166   rm -rf packagebuild
 167   git-buildpackage --git-ignore-new --git-force-create \
 168                    --git-upstream-branch=${THIS} --git-upstream-tree=BRANCH \
 169                    --git-export-dir=packagebuild --git-builder='debuild -S'
 170   unset THIS
 171
 172
 173 Last build step is to upload the package to the gEDAhead PPA:
 174
 175   dput ppa:geda/weekly packagebuild/pcb_*-gedahead-weekly_source.changes
 176
 177
 178 To round up, remove this committed changelog entry and the build:
 179
 180   git reset --hard HEAD^
 181   rm -rf packagebuild
 182
 183
 184 Building with pbuilder
 185 ----------------------
 186
 187 If you want to modify the packaging system, e.g. for testing dependencies, it's
 188 a good idea to build in a chroot'ed environment. There are many tools out there
 189 to make this easy ... and almost as many which I (Traumflug) found to not
 190 work as described. If you think that's me, well, have a look at
 191
 192   https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=779255
 193
 194 The tool which was found to actually work is 'pbuilder'. It's very similar to
 195 the tool used by these build farm machines (sbuild).
 196
 197
 198 We have build dependencies in 'universe', so let's pbuilder know this:
 199
 200   echo "COMPONENTS=\"main restricted universe multiverse\"" > ${HOME}/.pbuilderrc
 201
 202 Then build a base chroot image:
 203
 204   # To build for 32-bit on a 64-bit machine, add --architecture i386
 205   # To build for a different distribution, add --distribution vivid
 206   sudo pbuilder create --debootstrapopts --variant=buildd
 207
 208 It's recommended to update this chroot image once daily:
 209
 210   sudo pbuilder update
 211
 212
 213 The above has to be done only once. To actually build the package, prepare the
 214 source package as shown in the previous section, but don't upload to Launchpad
 215 and also don't remove packagebuild/. Then it's as simple as this:
 216
 217   (cd packagebuild && sudo pbuilder build *.dsc)
 218
 219 Built packages end up in /var/cache/pbuilder/result/.
 220
 221
 222 Cleaning:
 223
 224   sudo rm -r /var/cache/pbuilder  # remove chroot image and apt cache
 225
 226 ... and don't forget to remove the stuff made in the previous section.
 227
 228
 229 TODO:
 230 -----
 231
 232 pcb version isn't set, after packaging the application its self still reports
 233 "pcb-1.99z". The --git-prebuild=COMMAND parameter for git-buildpackage might
 234 come in handy here for setting this on the fly (citation for its man page):
 235
 236   execute COMMAND from the build directory before calling debuild or the
 237   application specified via --git-builder. Exported environment variables
 238   are: GBP_GIT_DIR (the repository the package is being built from),
 239   GBP_BUILD_DIR (the build dir).
 240
 241
 242 Put all this into a script, perhaps a Makefile target.
 243
 244
 245 Review each dependency. Like removing it from the build machine, then trying to
 246 build and run the binary. Likely this dependency list is a decade old, so it
 247 well might contain obsolete entries.
 248
 249
 250 There are tools to create a package changelog from Git history. Might be
 251 better than putting a link to the public Git repository.
 252
 253   https://marquiz.github.io/git-buildpackage-rpm/man.gbp.dch.html