  Instructions for creating Ubuntu debs from the XAMSDK
-----------------------------------------------------

IMPORTANT NOTES
---------------
1. you should NEVER build deb packages when logged in as root. 
If you are reading this document, it is assumed that you have unzipped
the original archive, and have a copy of the zip file somewhere in your
home directory.

2. The publically available zipfile does not ship with 3rd party jar files
required for the Java_Reference_VIM.
Most of these are listed as build dependencies , however, the Sun JavaMailAPI (javamail) and JavaBeans Activation Framework (jaf) are not available as Debian packages. JAF is only required with JDK1.5 or lower.
In this case, the packages must be obtained as zip files from the java website. Refer to XAMSDKGuide.pdf for the location. For each dependency, unxip the files and copy the mailapi.jar and/or the activation.jar file into the lib directory in the source tree prior to initiaitng the package build process.

3. The files under pkg/Linux/deb/debian are regenerated as part of the ant build process.
Please make edits to control.template and sniaxam*M.* files to ensure your changes
are propagated to the package build process.

4. JAVA_HOME *must*  be set in your environment for the build to complete successfully.

5. You will need to have the following packages installed to complete
the package build process:

debhelper
fakeroot


Building from the SNIA distributed zip file
-------------------------------------------

Building debs by hand
---------------------

1. Obtain a copy of pristine, patched sources, as noted above.
Unzip them to a directory named sniaxam-a.b.c, where a,b and c 
correspond to the sdk major, minor and rev numbers in the
package.properties file.
Patch the tree with mailapi.jar and/or activation.jar as described above.

2. Create a sratch directory to hold the sources and generated 
packages.

3. Create a tar gz file from the sources. For instance, if working
with sdk 0.3.0

cd to the containing directory and issue the following:

tar cvfz sniaxam-0.3.0.tar.gz sniaxam-0.3.0

4. Extract the tarball into the scratch directory.

5. Ensure that the files under pkg/Linux/deb/debian match with
the version numbers above. The binary package build uses files
of the form sniaxamX.*, where X is the major version number.
These files are regenerated from sniaxam*M.* as well as the control
file which is generated from control.template.
Rgenerate using the ant target 'regen_debian':

e.g. ant -f pkg/Linux/deb/builddeb.xml regen_debian

if necessary (this should only be necessary after a major version change).

6. Create a orig.tar.gz file from the modified and patched sources:

e.g.

cd scratch

tar cvfz sniaxam_0.3.0.orig.tar.gz sniaxam-0.3.0

The precise filename is important to the debian packaging process.
Note the change from '-' to '_'. 

NOTE 
Steps 5 and 6 can be acconplished using ant target 'tgz'.

e.g. 
cd scratch/sniaxam-0.3.0
ant -f pkg/Linux/deb/builddeb.xml tgz

will create the orig.tar.gz in sniaxam-0.3.0

7. Create a directory 'debian' under the source directory.

8. copy the files in pkg/Linux/deb/debian to the debian
directory just created.

e.g.
cd sniaxam-0.3.0
mkdir debian
cd debian
cp -rp pkg/Linux/deb/debian/* .

9. Ensure that debian/rules is executable

10 cd to the root of the sourece directory,
and issue the command

dpkg-buildpackage -rfakeroot

11. This should build the sources, create the diff.gz
and dsc files for the source package, and create two
deb packages for binary and development files in the
directory above the root of the source tree.

Typical output is:

Source pakcage files
--------------------
sniaxam_0.3.0-1.diff.gz
sniaxam_0.3.0-1.dsc
sniaxam_0.3.0-1_i386.changes
sniaxam_0.3.0.orig.tar.gz

Binary and doc packages
-----------------------
sniaxam0_0.3.0-1_i386.deb
sniaxam-dev_0.3.0-1_i386.deb
sniaxam-java0_0.3.0-1_all.deb
sniaxam-javadoc_0.3.0-1_all.deb


12. If the build fails, you must clean the source tree
of build artefacts, temporary files etc before attempting
to run the package build again.


Building debs using the ant buildfile
-------------------------------------

1. Observe the notes above regarding patching the
source with dependent libraries, environment etc.

2. Change directory to the root of the source tree

3. Run the following command:

ant -f pkg/Linux/deb/builddeb.xml

4. This should automatically create the debian sandbox,
copy the sources to it, build them and produce the debian
packages. They will be copied back to pkg/Linux/deb:

e.g. 
 
Source pakcage files
--------------------
sniaxam_0.3.0-1.diff.gz
sniaxam_0.3.0-1.dsc
sniaxam_0.3.0-1_i386.changes
sniaxam_0.3.0.orig.tar.gz

Binary and doc packages
-----------------------
sniaxam0_0.3.0-1_i386.deb
sniaxam-dev_0.3.0-1_i386.deb
sniaxam-java0_0.3.0-1_all.deb
sniaxam-javadoc_0.3.0-1_all.deb


5. The build file supports the following targets:

build		- builds the debian packages entirely
check_deps  - checks for patched jar files in the sources
clean		- removes stale packages from previous runs
deliver		- builds and copies packages to output directory
pkg			- builds the packages
regen_debian- regenerates debian files with version sensitive names or data
sandbox		- creates the debian sandbox
tgz			- creates the 'orig.tar.gz' tarball
tidy		- cleans up sandbox area and stale tarballs.


