"wpa" sources for Debian
------------------------

This "wpa" source package merges wpa_supplicant and hostapd sources, which are
maintained in one source repository[1] upstream and share considerable/
duplicate amounts of source. Starting with the 1.x branch, both wpa_supplicant
and hostapd are built from this common source package for Debian, while not
released together as tarball by upstream, the source can be obtained from the
upstream git repositories.

The preferred way to generate the orig.tar.gz is by calling

 $ debian/rules get-orig-source

which will clone the upstream git repository under $TMPDIR, using mktemp(1),
and create a new tarball based on the git tag corresponding to the top most
entry in debian/changelog. This newly generated tarball will be stored as
../wpa_${VERSION}.orig.tar.gz or ../tarballs/wpa_${VERSION}.orig.tar.gz, if
a directory called ../tarballs/ exists. Eventually existing tarballs
corresponding to the current version will not be overwritten.

Required dependencies to generate a new orig.tar.gz:
- a SUSv3 compatible shell, like dash or bash
- dpkg-parsechangelog, available from dpkg-dev
- git
- xz, available from xz-utils or busybox
- mktemp and rm, available from coreutils or busybox
- sed, available from sed or busybox
- tar, available from tar or busybox

It is recommended to base tarballs for development snapshots of "wpa" on
according git tags from the upstream git repository, the available git tags
can be queried by:

 $ git clone git://w1.fi/srv/git/hostap-1.git	# 1.x branch

or

 $ git clone git://w1.fi/srv/git/hostap.git	# >= 2.x branches

changing into the corresponding directory (hostap-1 or hostapd) and calling
git tag.

 $ cd hostapd-1
 $ git tag
 hostap_0_6_3
 […]
 hostap_1_0
 […]
 hostap_1_0_rc3
 […]

The Debian versions for these tags would be 0.6.3-1, 1.0 or 1.0~rc3 in
debian/changelog. Intermediate states between tags or HEAD are usually best
dealt with by creating a patch series based on the newest matching tag.

Exporting commits between "hostap_1_0" and the current git HEAD:

 $ git format-patch hostap_1_0..HEAD

Exporting commits between "hostap_1_0_rc3" and "hostap_1_0":

 $ git format-patch hostap_1_0_rc3..hostap_1_0

In both cases numbered patches will be dropped in the base directory of the
git clone. These numbered patches can be imported to the Debian package using
standard procedures for "3.0 (quilt)" source packages.

Tarballs can also be created manually from the upstream git repository:

 $ git clone git://w1.fi/srv/git/hostap-1.git
 $ cd hostap-1
 $ git archive \
	--format=tar \
	--prefix="wpa-1.0/" \
		hostap_1_0 \
			README COPYING patches src wpa_supplicant hostapd | \
				xz -c6 > wpa_1.0.orig.tar.gz

Arbitrary git tags or commit IDs can be used for this purpose.


Upstream git snapshots can be exported by using a specially crafted version
syntax used in the top most (pending) changelog entry. The required syntax for
correctly parsing this is:

 <upstream_version>+git<date>.<revision>+<git_hash>-<debian_revision>
 upstream_version := [0-9\.]*   --> 2.0
 date             := [0-9]*     --> 20131120 (YYYYMMDD)
 revision         := [0-9]*     --> 1
 git_hash         := [0-9a-f]*  --> 594516b
 debian_revision  := [0-9*]     --> 1

e.g.:

 2.0+git20131120.1+594516b-1

Technically any incrementing number can be used for <date>, but it's strongly
recommended to use YYYYMMDD (date --utc +%Y%m%d) and follow it by an
strictly incrementing arbitrary revision number (typically '.1'). The supplied
git hash can be abbreviated, but must be unique (see git describe, without
leading 'g').

The debian/rules get-orig-source target will automatically switch between
hostapd-1.git and hostapd.git (for >= 2.0) as needed, but it will only fetch
the explicitly specified version from a properly formatted, top most,
debian/changelog entry; it will not fetch the last upstream release or git
HEAD automatically.


The Debian packaging for wpa_supplicant/ hostapd is maintained in a subversion
repository at:

 Vcs-Svn: svn://anonscm.debian.org/svn/pkg-wpa/wpa/trunk/
 Vcs-Browser: http://anonscm.debian.org/viewvc/pkg-wpa/wpa/trunk/

The development mailing list and its mailing list archive is located at:

 http://lists.alioth.debian.org/cgi-bin/mailman/listinfo/pkg-wpa-devel

Work for the wpa package can be coordinated on this mailing list through:

 Debian wpasupplicant Maintainers <pkg-wpa-devel@lists.alioth.debian.org>

 -- Stefan Lippers-Hollmann <s.l-h@gmx.de>  Sat, 28 Dec 2013 22:37:03 +0100

[1]	http://hostap.epitest.fi/gitweb/gitweb.cgi?p=hostap-1.git [1.x branch]
	http://hostap.epitest.fi/gitweb/gitweb.cgi?p=hostap.git [development]
