jargon

• wig & pen a.k.a. source format 2.0
  => can merge multiple upstream tarballs
  => can use a changes tarball instead of raw .diff
  => supports bzip2

• BTS
  => Bug Tracking System

• PTS
  => Package Tracking System

• WNPP pseudo-package pseudo-bugs
  => "Work-Needing and Prospective Packages"
  => overseen by debian-qa@lists.debian.org => reportbug wnpp
  -> ITP
  -> "Intent to package"
  -> a bug ticket that represents a request to introduce a new package
  -> ITA
  -> "Intent to adopt"
  -> RFH
  -> "Request for help"
  -> RFA
  -> "Request for adopter"
  -> O
  -> "Orphaned package"
  -> RFP
  -> "Request for package"
  => other tools
  -> wnpp-alert
  -> how-can-i-help

• sponsorship-requests pseudo-package pseudo-bugs
  => RFS
  => "Request for Sponsorship
  => a bug ticket that represents a request for a sponsor for a new package

• NMU
  => non-maintainer upload

---

environment

• DEBFULLNAME="Package Monkey"
• DEBMAIL="package-monkey@debian.org" # or
• DEBMAIL="Package Monkey package-monkey@debian.org" # satisfies both

---

tools

stage 0 tools

• dget URL/to/some.dsc
  => fetch pre-made source package

• debcheckout 'package'
  => fetch pre-made source package from a (declared) version control system:

• dpkg-source -x file.dsc
  => extract pre-made source package

stage 0 manual sanity checks

• upstream tarball must exist PROJECT_VERSION.orig.tar.gz
• sources should be in a directory named PROJECT-VERSION
• debian control files will live here PROJECT-VERSION/debian
• e.g. manually implode or rename tarball if necessary
  => tar -cvzf PROJECT_VERSION.orig.tar.gz PROJECT-VERSION
• e.g. manually explode tarball if necessary
  => tar -xvzf PROJECT_VERSION.orig.tar.gz PROJECT-VERSION

stage 1 tools (preparation)

• dh_make -f path/to/upstream-tarball.tar.gz
  (also variants dh-make-perl, dh-make-php, ...)
  => populate debian/ skeleton directory

• dch -i
  => adds new entry to changelog with auto-incremented debian version

• gbp dch
  => adds new entry to changelog

• git deborig \[-f\] \[REF\]
  => creates *orig.tar.gz via git archive

• sbuild-createchroot
  => sudo sbuild-createchroot --make-sbuild-tarball=/path/to/any-dir/unstable-amd64.tar.gz

                        unstable `mktemp -d` http://httpredir.debian.org/debian
  

• quilt

  ~/.quiltrc
  QUILT_PATCHES=debian/patches
  #QUILT_NO_DIFF_INDEX=1
  #QUILT_NO_DIFF_TIMESTAMPS=1
  #QUILT_REFRESH_ARGS="-p ab"
  QUILT_REFRESH_ARGS=”-p ab –no-timestamps –no-index”
  QUILT_DIFF_ARGS="--color=auto"
  

stage 1 manual sanity checks

Q: Required targets: => build, build-arch, build-indep:

-> should perform all the configuration and compilation

=> binary, binary-arch, binary-indep: build the binary packages

-> dpkg-buildpackage will call binary to build all the packages,
   or binary-arch to build only the Architecture: any packages

=> clean: clean up the source directory

• dh_* functions in 'rules' file are configurable via debian/package.* files (compat >=7)

*? patch targets: => debian/rules patch: apply all patches => debian/rules unpatch: de-apply all patches

*? debconf => prompt the user during preinst, postinst, prerm, postrm stages

stage 2 tools (make 'rules')

• dpkg-buildpackage [--fakeroot]
  => builds package in current environment
  => requires upstream tarball named ../PROJECT_VERSION.orig.tar.gz
  => produces several files:
  --> PROJECT_VERSION-DEBREV.dsc
  --> PROJECT_VERSION-DEBREV_amd64.buildinfo
  --> PROJECT_VERSION-DEBREV_amd64.changes
  --> PROJECT_VERSION-DEBREV_amd64.deb
  --> PROJECT_VERSION-DEBREV.debian.tar.xz

• cvs-buildpackage, git-buildpackage, mercurial-buildpackage, svn-buildpackage
  => VCS-specific versions of dpkg-buildpackage
  => uses debian/control fields Vcs-Browser:, Vcs-Git:, Vcs-Svn:, etc

• git-buildpackage
  => builds in-tree

• git-buildpackage --git-export-dir=../build-area/
  => builds out-of-tree (svn-buildpackage implicit behavior)

• debcheckout, debcommit, debrelease
  => VCS-agnostic interface to debian VCS-based packages

• pbuilder
  => builds package in chroot environment

• sbuild # from source directory

• sbuild path/to/unpackaged/sources/

• sbuild path/to/the.dsc

• sbuild 'source-package-in-repo'

• sbuild --dist=$SBUILD_DIST --arch=$SBUILD_ARCH\
  --run-piuparts --piuparts-opts="--basetgz=$CHROOTBALL"
  => builds package in chroot environment and allows LVM snapshopts
  => uses schroot by default or bbuild
  => will leave .dsc, .debian.tar.xz, and .orig.tar.gz packages
  in /var/lib/sbuild/build/loopidity-gLEk7K/

• git-pbuilder
  => Wrapper around cowbuilder/qemubuilder for gbp buildpackage

stage 3 tools (verfication)

• lintian # from source directory
• lintian ../*.deb
  
• lintian ../*.changes
  => lint checks

• lintian -EviIL +pedantic => maximimal warnings and verbose explanations

• linda
  => lint checks => obsolete?

• piuparts /path/to/.deb # default dist, arch, and mirror
  => verify install/uninstall/re-install in chroot
  -> --install-purge-install
  -> --install-remove-install

• piuparts --distribution=$SBUILD_DIST --arch=$SBUILD_ARCH\
  --mirror="http://httpredir.debian.org/debian main" --save=$CHROOTBALL\
  /path/to/.deb
  => this form creates new chroot wth debootstrap and saves chrootball

• piuparts --basetgz=$CHROOTBALL /path/to/.deb
  => this form uses existing chrootball

• piuparts --schroot='SCHROOT-NAME' /path/to/.deb
  => this form uses existing schroot session

• piuparts --distribution=$BUILD_DIST --arch=$BUILD_ARCH\
  --existing-chroot=$PIUPARTS_CHROOT /path/to/some.deb
  => this form uses existing standard chroot tree

• debdiff ../*changes => view diff in binary package based on nmost recent changeset

• debdiff ../*dsc => view diff in source package based on nmost recent changeset

stage 4 tools

• dput PROJECT_VERSION-DEBREV_amd64.changes

• dput mentors PROJECT_VERSION-DEBREV_amd64.changes?
  => upload package to debian (mentors?)

• dupload
  => upload package to debian?

multi-stage tools

• debuild
  => dpkg-buildpackage + lintian + GPG sign
• debuild -uc -us
  => dpkg-buildpackage + lintian

misc helpers

• git-dpm
  => Manage Debian source packages in an git archive, storing possible changes to the upstream source as git commits that are stored in "3.0 (quilt)" format patch series.

• gitpkg
  => creates a source package from specified repository versions.

• git-debimport
  => creates a git repository from a set of existing packages.

• dgit
  => treats the Debian archive as a version control system, and bidirectionally gateways between the archive and git. The git view of the package can contain the usual upstream git history, and will be augmented by commits representing uploads done by other developers not using dgit. This git history is stored in a canonical location known as dgit-repos which lives outside the Debian archive

• devscripts
  => bts
  -> CLI interface toi the BTS

• reportbug --template
  => creates bug report for submission to submit@bugs.debian.org

• reportbug
  => requires local mail setup

• dpatch
  => dunno

• dbs
  => dunno

• cdbs
  => dunno

files

• 'changelog'
  => debian-specific changes aside from upstream

• 'README.debian' , 'README.source'
  => verbose explanation of the differences from upstream

• init.d
  => install init scripts?

• preinst , postinst , prerm , postrm
  => installation hooks

• debian/watch
  => poll for new upstream versions and notify the maintainer via: -> https://tracker.debian.org/ -> https://udd.debian.org/dmd/ => uscan: run a manual check => uupdate: try to update your package to the latest upstream version

---

common configuration

• the dh_auto_install step calls "make -j1" by default
  this can be chaged in /etc/devscripts.conf or ~/.devscripts:
  => DEBUILD_DPKG_BUILDPACKAGE_OPTS=-j2 (or -J2)
  dpkg-buildpackage -j, --jobs[=jobs|auto] # sets MAKEFLAGS
  dpkg-buildpackage -J, --jobs-try[=jobs|auto] # $(MAKE) -j 1

---

common errors

• dpkg-buildpackage error:

  dpkg-source: error: cannot represent change to some-file: binary file contents changed
  dpkg-source: error: add some-file in debian/source/include-binaries if you want to store the modified binary in the debian tarball
  

  ensure said files are removed by Makefile 'clean' target

• quilt push
  => whenever quilt push mentions "fuzz" you need to double check that patch did the right thing
  and update those patches because dpkg-source doesn’t accept any fuzz
  => When the patch can be reverse-applied, it means that the upstream authors included the Debian patch
  (or that they made the same change). You can thus get rid of it:

---

bugs/typos

• man piuparts:
  not currently jessie

  in the 'EXAMPLES' section
  If you want to test that a package installs properly in the stable (currently jessie) Debian
  release, then can be upgraded to the testing (currently stretch) and unstable (sid) versions,
  and then uninstalled without problems, you would give the following command:
  piuparts -a -d jessie -d stretch -d sid foo
  

• dpkg-buildpackage:

  if (not -x 'debian/rules') {
  

  does not consider that the file may not exist - so it blindly tries to chmod the nonexisting file which does not fail the build nor indicate an error - but instead shows a warning stating that the problem was fixed but in fact nothing was done

  dpkg-buildpackage: warning: debian/rules is not executable; fixing that
  

  suggest:

  if (not -e 'debian/rules') {
  syserr(g_('cannot read %s'), "$dir/debian/rules");
  } else if (not -x 'debian/rules') {
  

---

Q1:

per: https://www.debian.org/doc/debian-policy/ch-controlfields#s-controlsyntax

5.2.  Source package control files -- debian/control
The debian/control file contains the most vital (and version-independent) information about the source package and about the binary packages it creates.
5.3.  Binary package control files -- DEBIAN/control
The DEBIAN/control file contains the most vital (and version-dependent) information about a binary package. It consists of a single paragraph.

is this implying there would be a 'DEBIAN' directory containing a 'control' file

that is distinct from (or exclusive to) the 'control' file in the 'debian' directory?

Q2:

per: https://www.youtube.com/watch?v=fQ6YD0yLYKs
dood sad the minimum package must install a man page and something to usr/share/doc/package-name/

but the skeletin README.debian says it can be deleted ??

Q3:

per: https://wiki.debian.org/DebianMultimedia/Sponsoring

Tell how you tested the package

Q4:

per: https://wiki.debian.org/DebianMultimedia/Sponsoring

this situation will improve as:
* A) more team members become DMs able upload their own packages, 
* B) new DDs join the team 
* C) and existing team members make it through the NM process.)

arent A and C exactly the same?

Q4:

per: https://wiki.debian.org/DebianMultimedia/Sponsoring
why is it so explicitly specified the sponsor's preference of CDBS or debhelper?
aren't these just tools? do these not produce the same packages?

Q5:

per: https://wiki.debian.org/DebianMultimedia/DevelopPackaging

Packages should use git, as mentioned above.

then it says:

Don't bother with git for packaging new software. Instead, package it properly following DebianPolicy and the DevelopersReference.

then it says:

If the package is "good enough" they will setup a repository on git.debian.org and integrate your package

per: https://wiki.debian.org/DebianMultimedia/Sponsoring also git is mandatory

this is mandatory in pkg-multimedia anyway (git)

Q6:

to be clear, the git requirement in 'Q5' is not referring in any way to the upstream VCS
this is referring only to how the debian packaging is maintained outside the upstream tree
i.e. upsteam sources are always in tarball form so that none of the upstream git commits will ever appear in the packaging repo

Q7:

per: https://wiki.debian.org/Packaging/Intro
tutorials specify the '--unsigned-source' and '--unsigned-changes' options to debuild
what is the reason for not signing the artifacts - is this only for convenience within the scope of a tutorial - or is there some valid reason not to sign the artifacts in production?
packages should not be signed until they have been inspected/tested by a human
why is the '--unsigned-buildinfo' or '--no-sign' options not used? does this imply that the tutorial is requiring the '.buildinfo' file to be signed or was that an oversight not relevant to the tutorial?
probably the tutorial predates buildinfo, since it is relatively recent

Q8:

running debuild - i noticed the dh_auto_install step calls "make -j1" - there is some way i can specify more cores?
in pbuilder config: DEBBUILDOPTS=-J2 (or -j2) (see the dpkg-buildpackage manual for details re -j/-J)
the debuild manual says the files are /etc/devscripts.conf and ~/.devscripts and the option is DEBUILD_DPKG_BUILDPACKAGE_OPTS

Q9:

where is the location of the chroot directory defined for unpacking a chrootball created with sbuild-createchroot --make-sbuild-tarball ?
there does not appear to be any command-line arg for sbuild ro schroot to specify this - it seems they both use profile names
such as dist-arch-sbuild which looks up definitions under /etc/schroot/chroot.d/
the entry under /etc/schroot/chroot.d/ refers only to the tarball itself as 'type=file' but does not specfy a directory
the only documentation i found was in the file /etc/schroot/setup.d/10mount

# schroot will mount -o bind /home/m/ch to /var/lib/schroot/mount/ch-123

but the actual mount location is /var/run/schroot/mount - when specifying the directory this 'mount' file uses the values of '$CHROOT_FILE_UNPACK_DIR' and '$CHROOT_MOUNT_LOCATION' but neither of these are defined in any file under /etc/schroot

-# Q10: i always see warnings aout unmet dependencies but the build succeeds anyways - i have read these can be pre-satisfied - but why bother? -* dpkg --force-depends -i build-deps.deb && apt-get -f install -* (same as?) mk-build-deps -r -i - It is how the classic pbuilder satisfy depends works, so it is proven -technique. - If you want code which looks at the ./debian/control file in the same -way as dpkg-checkbuilddeps and then builds an apt-get install command, -use embuilddeps from the xapt package.

-* /usr/lib/pbuilder/pbuilder-satisfydepends - That creates a package that pulls in the dependenices.

---

TODO:

rebase onto obs

• remove Disclaimer from debian.copyright

WARNINGS:

dpkg-source: warning: ignoring deletion of file obs/loopidity.spec, use --include-removal to override  
dpkg-source: warning: missing information for output field Standards-Version  
dpkg-gencontrol: warning: Depends field of package loopidity: unknown substitution variable ${shlibs:Depends}