 DEBIAN PACKAGING SCRIPTS & related stuff
==========================================

Contents:
0) About
1) dsc - debian source package
2) deb - debian binary package
3) Packaging utilities
4) Basic outline of U++ packaging scripts
5) Additional notes

0) About
--------
This file is just a summary of notes about different parts of debian 
packaging process, intended mainly to ease authors work on packaging 
scripts for U++. Most of the knowledge here comes from Debian Policy 
Manual, version 3.8.3.

If you want to learn something about packaging, you should read 
Debian Policy Manual (http://www.debian.org/doc/debian-policy)
Also Debian New Maintainers Guide might be helpful. It is located
at http://www.debian.org/doc/maint-guide .

If you want to know how the upp packaging implementation works,
see the scripts in this directory, they are heavily commented.

1) dsc - debian source package
------------------------------
Source package actually consist of several files. They are:
	upp_<version>.orig.tar.gz
	upp_<version>.diff.gz
	upp_<version>_source.dsc
	upp_<version>_source.changes

What do they do:
*.orig.tar.gz: holds all the original sources - do not ever modify that!
*.diff.gz:     here come all the changes to original source tree in the 
               form of gzipped diff (includes also debian directory,
               see below)
*.dsc:         !signed! file containing information about package (name,
               version, dependencies, maintainer, etc.) and SHA sums of
               the two previously mentioned files
*.changes      !signed! file with info and changlog

How to prepare all this?
I)   unpack *.orig.tar.gz
II)  add debian directory in the unpacked source tree
III) create files in debian directory:
debian/rules
	Basically a makefile. Following structure is minimal required:
#####################debian/rules#######################################
#!/usr/bin/make -f

clean:
	
build:
	
binary-indep:

binary-arch: 
	#here we must produce .deb in $(CURDIR)/..

binary: binary-indep binary-arch 

.PHONY: build binary-arch binary install
########################################################################

debian/control
	Minimal structure for this follows. There can be multiple binary
	sections if package produces more packages.
##################debian/control########################################
Source: upp
Section: devel
Priority: optional
Maintainer: Jan Dolinar <dolik.rce@seznam.cz>
Standards-Version: 3.8.3.0
Build-Depends: libx11-dev (>= 1.0.0), libxft-dev (>= 2.1.8), libpng12-dev (>= 1.2.8), g++, libgtk2.0-dev (>= 2.8.17), libnotify-dev, rsync

Package: upp
Architecture: any
Depends: libx11-dev (>= 1.0.0), libxft-dev (>= 2.1.8), libpng12-dev (>= 1.2.8), g++, libgtk2.0-dev (>= 2.8.17), libnotify-dev
Description: C++ library for cross-platform development with IDE
 Ultimate++ is a radical and innovative GUI toolkit whose number one priority
 is programmer productivity. C++ is a great programming language but
 C++ programmers are sometimes hampered by the lack of effective libraries.
 U++ libraries enable genuine productivity gains with shorter development
 times and greatly reduced application source code size.
########################################################################

debian/copyright:
	This will later became /usr/share/doc/package/copyright	in final 
	users machine
########################################################################
This package was debianized by Jan Dolinar <dolik.rce@seznam.cz> on
Fri, 15 Jan 2010 17:30:00 +0100.
 
Copyright © 1999-2010 Ultimate++ team (http://ultimatepp.org)
Authors: Mirek Fídler, Tomáš Rylek, Daniel Kos

License: BSD (please see /usr/share/common-licenses/BSD).
########################################################################
	
debian/changelog:
	Info about packaging process, not the original source. The build 
	scripts read distribution info from here! Exact format decribed on
  http://www.debian.org/doc/debian-policy/ch-source.html#s-dpkgchangelog

IV) run debuild -S inside this directory structure


2) deb - debian binary package
------------------------------
Single gzipped file containing following three files
debian-binary - just string with version of packaging standards.
data.tar.gz - complete directory structure as it will be installed on
	end-users root partition
control.tar.gz - control file, md5sums and any maintainer scripts 
	(postinst, prerm, etc.)


3) Packaging utilities
----------------------
dpkg-architecture - usefull to get architecture info during the build
                  - option "-L" list all possible architectures

dpkg-deb - option "-b src dest.deb" builds deb from src diretory tree
         - files in DEBIAN will become control.tar.gz, the rest goes to
           data.tar.gz
dpkg-shlibdeps - scans binary (or shared lib) for dependencies, which
                 are then stored as field shlibs:Depend
                 in debian/substvar and later used for substitutions
                 when building the package
debuild - option "-S" builds .dsc in .. from files in current directory
        - "-k12456789" might be needed to correctly sign the files
          where 123456789 is gpg fingerprint (see gpg --fingerprint)
          alternatively specify the key in gpg config file
        - options -us -uc prevent signing, so it must be done later, but 
          it allows to use --passphrase-fd to supply the passphrase 
          in a little bit more secure way

fakeroot - used by debuild

dput - used to upload dsc to launchpad ppa
     - correct configuration in ~/.dput.cf is required

You can find all these files in packages devscripts and dpkg.


4) Basic outline of U++ packaging scripts
-----------------------------------------
Dsc building:
	Acquire sources
	Generate Makefile
	Create debian directory
	Create distro independent files{
		debian/control
		debian/copyright
		debian/postinst
		debian/prerm
		debian/rules
		debian/theide.desktop
		debian/theide.1
	}
	For distributions in supported distro list
		Create distribution dependent files{
			debian/changelog
			debian/dopack
		}
		Call debuild -S to build dsc
		Sign tha .dsc and .changes files
		Call dput to upload dsc to launchpad
		Clean-up distribution dependent file
	}
	Clean-up everything

Server side (launchpad) deb build:
	(from our point of view, it starts in debian/rules, when buildd
	 system launches target binary-arch)
	call make to build theide
	create tmp directory
	copy source files in tmp/usr/share/upp/
	copy compiled theide executable to tmp/usr/bin
	create icon, .desktop entry 
	add DEBIAN directory
	create DEBIAN{control,postinst,prerm,md5sums}
	call dpkg-deb -b to build deb
	generate debian/files


5) Additional notes
-------------------
U++ build dependencies: 
	libx11-dev (>= 1.0.0)
	libxft-dev (>= 2.1.8)
	libpng12-dev (>= 1.2.8)
	libgtk2.0-dev (>= 2.8.17)
	libnotify-dev
	rsync  #used in scripts
	svn #not sure...
	theide #exports Makefile

U++ deb/runtime dependencies
	gtk
	libx11-dev (>= 1.0.0)
	libxft-dev (>= 2.1.8)
	libpng12-dev (>= 1.2.8)
	libgtk2.0-dev (>= 2.8.17)
	libnotify-dev

Signing:
	Launchpad is pretty carefull about the signing. The signature must 
	be registred with ppa and added to ubuntu keyserver. 

How to get package to Debian:
	http://people.debian.org/~mpalmer/debian-mentors_FAQ.html

How to get package to Ubuntu:
	https://wiki.ubuntu.com/UbuntuDevelopment/NewPackages
	Actualy it seems taht easiest way is to push it to Debian first :-)


TODO:	Implement debian/watch (see DPM 4.11)
		Get rid of the rsync dependency
