.\" /usr/share/man/man1/makesourcepackage.1(.gz)
.\" author Neil Franklin, last modification 2006.12.19
.\" copyright ETH Zuerich Physics Departement
.\"   use under either modified/non-advertising BSD or GPL license

.TH MAKESOURCEPACKAGE 1 "2006.12.19" "D-PHYS Package Tools"

.SH NAME

makesourcepackage \- make and upload Debian packages

.SH SYNOPSIS

.B makesourcepackage
\fB-g\fP [\fB-a\fP \fIarch\fP \fB-s\fP \fIsection\fP]
[\fB-l\fP \fIlogtext\fP] [\fB-pt\fP] [\fB-ui\fP [\fB-b\fP \fIbaseaddress\fP]
[\fB-d\fP \fIdistributiondir\fP]] [\fB-rqvD\fP] \fIpackagename\fP
.PP
.B makesourcepackage
\fB-c\fP \fIoldpackage\fP
[\fB-l\fP \fIlogtext\fP] [\fB-pt\fP] [\fB-ui\fP [\fB-b\fP \fIbaseaddress\fP]
[\fB-d\fP \fIdistributiondir\fP]] [\fB-rqvD\fP] \fIpackagename\fP
.PP
.B makesourcepackage
\fB-x\fP
[\fB-l\fP \fIlogtext\fP] [\fB-pt\fP] [\fB-ui\fP [\fB-b\fP \fIbaseaddress\fP]
[\fB-d\fP \fIdistributiondir\fP]] [\fB-rqvD\fP] \fIpackagename\fP
.PP
.B makesourcepackage
\fB-f\fP
[\fB-l\fP \fIlogtext\fP] [\fB-pt\fP] [\fB-ui\fP [\fB-b\fP \fIbaseaddress\fP]
[\fB-d\fP \fIdistributiondir\fP]] [\fB-rqvD\fP] \fIpackagename\fP
.PP
.B makesourcepackage
\fB-h\fP

.SH DESCRIPTION

makesourcepackage generates, clones, fetches or extracts, add changelog texts
to, packages up, deletes work directories of, uploads to package server,
triggers (re-)indexing of package server and removes archive files of source
based Debian packages.
.PP
For indexing the package server it has uploaded packages archive files to it
calls \fImakelocalsite\fP(1) with the proper section.

.SH COMMAND/FUNCTION/ACTION LETTERS

One or multiple of the following commands must be used, else makesourcepackage
defaults to doing nothing. If one or multiple of these are selected, only those
actions are taken, no other default action.
.PP
If multiple of these are used, they are always processed in the row they appear
here, not the row they are typed on the command line.
.PP
Only one of \fB-g\fP or \fB-c\fP or \fB-x\fP or \fB-f\fP should be used per
run, else they destroy each others work. Also \fB-g\fP or \fB-c\fP should be
used only once per package, and that only before anything else when creating
the package, else all previous commands work will be lost.
.TP
.B \-g
generate: Generate work directories and their content from scratch.
.TP
.BI \-c \ oldpackage
clone/copy: Clone contents from <oldpackage>, instead of making new files from
scratch do:
.RS
.PP
* package directory made and Makefile and README copied and package name in
them changed
.PP
* debianisation directory made and control, copyright, rules, etc files copied
and package name them it changed
.PP
* all other files just copied unchanged
.PP
if there is an work directory of the old package clone that, else temporarily
unpack an .tar.gz archive
.RE
.TP
.B \-x
(e)xpand: Take an packaged .tar.gz file and make work directories from it. This
can not work from an .deb, as that has no source in it. This can undo the
effect of \fB-t\fP, so long an \fB-p\fP was done before doing the \fB-t\fP.
\fIGotcha\fP: give only \fIpackage name\fP, not full .tar.gz file name.
.TP
.B \-f
fetch: Fetch the .tar.gz and .dsc from the local Debian mirror and expand it to
an working directory.
.TP
.BI \-l \ logtext
log: Generate an new changelog entry and (dated) version number using the given
log text for the * line.
.TP
.B \-p
pack: Pack up the work directory, making .desc, .deb, .tar.gz and
facultatively .changes package files.
.TP
.B \-t
tidyup: Delete work directory after packaging, leaving only package. A deleted
work directory can be recreated by \fB-x\fP or \fB-f\fP.
.TP
.B \-u
upload: Upload generated package files to local Debian server. This requires
\fBssh\fP(1) and \fBrsync\fP(1) to be running on the server.
.TP
.B \-i
index: (re-)index the package files on local Debian server. This requires
\fBssh\fP and \fBmakelocalsite\fP on the server. This basically just extracts
the section (main, non-free, control) from the package and calls
\fBmakelocalsite\fP with that section name as only parameter. Note: With an
multi binary package all packages must be in the same section (which is most
likely allways the case, else Debian policy may even be violated), as this
info is extracted from the source package.
.TP
.B \-r
remove: Delete package files after upload. This is an alternative way to using
\fB-t\fP, if you want to save disk space.

.SH OPTIONS

[only for \-g generate]
.TP
.BI \-a \ arch
architecture: Set architecture to this; default: all; examples: all, any, i386.
.TP
.BI \-s \ section
section: Set section to this; default: admin; examples: admin, misc,
non-free/admin, contrib/misc.
.PP
[only for \-u upload and \-i index]
.TP
.BI \-b \ baseaddr
base: Package files are uploaded relative to this base directory; default:
whatever is set in CONF_PKG_BASE.
.TP
.BI \-d \ distribution
distribution: Package are uploaded relative to this distribution; default:
whatever is set in CONF_DISTRIB.
.PP
[for all commands]
.TP
.B \-q
quiet: Don't give user an running report of what we are doing.
.TP
.B \-v
verbose: Give large volume output, where sensible.
.TP
.B \-D
Debug: Activate an debug option. See source for how to use this.
.TP
.B \-h
help: Output help text, and then abort operation.
.PP
.I packagename
package name: The name of the package to be handled.

.SH CONFIG

The config files \fI/etc/dphys-pkgtools\fP (sitewide), \fI~/.dphys-pkgtools\fP
(personal) and \fI./dphys-pkgtools\fP (particular project) allow the admin and
users to set up the working environment for \fBmakesourcepackage\fP (and
\fBmakelocalsite\fP also).
.PP
These config files are sh script fragments full of assignments, which are
sourced, in above row, later config files assignments overriding earlier ones.
Standard sh syntax rules apply. Assignments relevant for
\fBmakesourcepackage\fP are:
.TP
.B CONF_ARCH
Set architecture. Used by \fB-g\fP (generate). Overridable with \fB-a\fP
(architecture). Defaults to \fIall\fP, as most packages produced are assumed to
be own scripts.
.TP
.B CONF_SECTION
Set section. Used by \fB-g\fP (generate). Overridable with \fB-s\fP (section).
Defaults to \fIadmin\fP, as most packages are assumed to be for system
administration.
.TP
.B CONF_HOST_TO_PKG_PREFIX
Prepended an prefix to packagenames with no \- in their name. This can be used
to add an <siteprefix>- to every package name generated. This feature is
considered deprecated. Defaults to empty/nothing.
.TP
.B CONF_AUTHOR
Used for author name in "generated by" line of headers of generated files.
Defaults to \fBmakesourcepackage script\fP, which you most likely want to
change in your personal config file, to your name.
.TP
.B CONF_MAINT_NAME
Used for the Maintainer: line in debian/control files and in debian/changelog
files. Defaults to \fINot Configured Full Name\fP.
.TP
.B CONF_MAINT_EMAIL
Used for the Maintainer: line in debian/control files and in debian/changelog
files. Defaults to \fInot-configured-user@not-configured-site\fP.
.TP
.B CONF_COPY
Used for the copyright ownership remarks in file headers. Defaults to an
placing of the files and package in the public domain. You need to change this
if you want to be more restrictive.
.TP
.B CONF_REMOVE_CHANGES_FILE
Auto-delete the *.changes file which is generated and is not used for uploading
to local sites. Defaults to \fIyes\fP (= delete).
.PP
The rest of config file assignments are only used by the \fB-u\fP (upload)
option (and also some by \fBmakelocalsite\fP):
.TP
.B CONF_PKG_SERVER
The server to connect to, to put the package on. Defaults to error message
generating invalid \fInot-configured-server\fP, as there is no sensible default
possible. Your admin must set this.
.TP
.B CONF_USER
The user to login as on above server. Defaults also to error message generating
\fInot-configured-user\fP. Each user must set this. It is strongly advised
against setting this to "root", as this will kill access rights to directories
below the "dist" directory of the Debian website structure.
.TP
.B CONF_GROUP
Make all uploaded files and directories writable by any user in this group.
For use so that all members of this group can work on the package site (adding
or replacing packages). Defaults to nothing, as this is usable for single user
and no sensible group value can be defaulted. Usually the admin will set this.
.TP
.B CONF_PKG_BASE
Set base directory on server for all uploads to go into. Overridable with
\fB-b\fP (base). This should be the base directory of the Debian-like package
archive, and will usually match the DocumentRoot of your HTTP VirtualHost.
Defauls also to error message generating \fI/not/configured/directory\fP.
Usually the admin will set this.
.TP
.B CONF_DISTRIB
Set which distribution directory within our package server to use. We suggest
something like \fI<debian-distribution>/local\fP, analog to how Debian does it
for <debian-distribution>/non-US and <debian-distribution>/updates (on Debian
security). Defaults to \fIwoody/local\fP. Change woody to whatever Debian
version you are using.
.TP
.B CONF_INDEX_SITE
Program to run on server after uploading. This is assumed to be a program that
eliminates duplicate packages and rebuilds all index files and list files.
Defaults to \fB/usr/bin/makelocalsite\fP, which is part of dphys-pkgtools, and
usually what you want to use.

.SH FILES

.TP
.B /etc/dphys-pkgtools
site admin config
.TP
.B ~/.dphys-pkgtools
users personal config
.TP
.B ./dphys-pkgtools
individual projects config

.SH EXAMPLES

The following allows the sysadmin to set an site policy on copyright:
.PP
In \fI/etc/dphys-pkgtools\fP:
.PP
CONF_COPY="copyright Example Organisation,
  use under either non-advertising BSD or GPL license"
.PP
Note that the line break must be inside the "", else the second line will
confuse the shell. Do not use an \\ before the line break, because it would
appear in the output. Also put in the 2 blanks at the beginning of the second
line, as these then also appear in the output files, indenting this line.
.PP
The following then would be additionally set by an typical user as their
identity:
.PP
In \fI~/.dphys-pkgtools\fP:
.PP
CONF_AUTHOR="makesourcepackage script run Jay Random"
CONF_MAINT_NAME="Jay Random"
CONF_MAINT_EMAIL="jrandom@example.org"
.PP
If you want to use the upload feature, the following allows the sysadmin to
tell how all users upload to the package server:
.PP
In \fI/etc/dphys-pkgtools\fP:
.PP
.nf
  CONF_PKG_SERVER=debian-local.example.org
  CONF_USER=luser-failled-to-set-username
  CONF_GROUP=""
  CONF_PKG_BASE=/www/debian-local
.fi
.PP
Note that CONF_USER has been set to make user ommission of setting this to an
personal value highly visible in ssh login faillure logs. And CONF_PKG_BASE
should be the base directory or your Debian package tree, usually the
DocumentRoot of your VirtualServer.
.PP
The following then would allow an single user to use his specific account on
that server:
.PP
In \fI~/.dphys-pkgtools\fP:
.PP
CONF_USER=jrandom
.PP
The user now can start making packages.

.SH PACKAGE MAKING

First generate the basic directory structure and a few default files for an
new package (here for foo-bar) with: 
.PP
\fBmakesourcepackage \-g foo-bar\fP
.PP
If there already was an existing directory foo-bar (an non-packaged existing
project, or even an already generated project) only missing files will be
added (good if you wreck one, simply delete it and re-generate). Add the
\fI-a\fP or \fI-s\fP options to above command if required (for non-all
architecture or non-admin section packages).
.PP
Then add what ever content the package is supposed to deliver, such as:
programs/scripts, their man pages (obligatoric for Debian!), README (or modify
the generated one) and other docs.
.PP
Then make an \fIMakefile\fP (or expand the generated one). It is assumed to do
\fBall\fP of the installing of programs/scripts and their man pages (incl
compressing the later with gzip \-9), like any real (= non-Debian) make install
does, \fPnot\fP leaving man page installation to debian/rules and
dh_installman(1) stuff. A typical Makefile will usually contain for each
programs/script and its man page the following stuff in the noted sections:
.PP
.nf
all:\!
	@gzip \-9 \-c foo-bar.1 > foo-bar.1.gz
clean:\!
	@rm \-f foo-bar.1.gz
install:\!
	@mkdir \-p $(BINDIR)
	@cp \-p foo-bar $(BINDIR)
	@mkdir \-p $(MAN1DIR)
	@cp \-p foo-bar.1.gz $(MAN1DIR)
uninstall:\!
	@rm \-f $(BINDIR)/foo-bar
	@rm \-f $(MAN1DIR)/foo-bar.1.gz
.fi
.PP
The variables $(BINDIR) and $(MAN1DIR) and quite a few like them (such as
$(SBINDIR) and $(MAN8DIR) for system programs/scripts) are given in the
generated Makefile. They must all be derived from DESTDIR (which is set by
the Debian packaging tools), such as like this:
.PP
.nf
PREFIX  = $(DESTDIR)/usr
BINDIR  = $(PREFIX)/bin
MAN1DIR = $(PREFIX)/share/man/man1
.fi
.PP
Note that one type of packages that we use contains no programs/scripts or man
pages, just pure Debian postinst (see below) installation scripts. Nothing
needs to be done up to here for such packages.
.PP
Once the package content exists, then files that pertain to installing and
running the package in an Debian system are to be edited/added in the debian/*
directory (this is known as "debianising" the package), such as:
.PP
\fIcontrol\fP says general stuff about this package, and describes what it is
all about. Usually the Description: line and the single-blank indented lines
below it are all that you will need to change.
.PP
\fIcopyright\fP ist just pure text, taken from the sysadmins CONF_COPY
assignment, so you can (or even should) leave it allone.
.PP
\fIfoo-bar.docs\fP lists all docs files that you want copyed into
\fI/usr/share/doc/foo-bar/*\fP, such as README. Default this contains only
one line for README. Extend it by hand, adding whatever files you have made,
as paths relative to the packages base directory. Do not put INSTALL (or
similar stuff) in here, as they are for manual installation which is obsoleted
by the Debian auto-install process for which you are doing the packaging.
.PP
\fIrules\fP script controls package building. The generated one is fairly
universal, so most likely you can leave it allone.
.PP
If you want an init script add it as file \fIfoo-bar.init\fP. Any init script
should contain somewhere in it an trigger line so that all the needed
/etc/rc*.d/ links for starting and stopping it will be added and removed by
autogenerated postinst (= run after install) and prerm (= run before
deinstall) scripts.
.PP
For running at phase 30 in run levels 2 3 4 and 5, do it like this:
.PP
#@rc.d@ default 30
.PP
or for running at phase 40 in run level S, like this (including the dot):
.PP
#@rc.d@ start 40 S .
.PP
If you want cron job entries add them as files \fIfoo-bar.cron.*\fP, where *
stand for any of: d or daily or weekly or monthly.
.PP
If your init script or cron entry (or any other scripts in your package), want
to have an config file in /etc/default, add an \fIfoo-bar.default\fP file.
.PP
If you want to add something else to the autogenerated postinst or prerm files
(such as edit or generate further config files, modify system state), then add
scripts \fIfoo-bar.postinst\fP or \fIfoo-bar.prerm\fP. These are normal
scripts, but with the line #DEBHELPER# in them, at the point where the
automatic stuff is to be inserted, and without the Debian /usr/share/doc
linking stuff (that is also autogenrated). See dh_installdeb(1) for further
Details.
.PP
We use autoinstalled (by \fBdphys-admin\fP(8)) packages containing nothing
more than such config adding/editing postinst scripts as method to
autoconfigure the entire system! Making the packages for this was the original
job of \fBmakesourcepackage\fP.
.PP
\fIchangelog\fP records what was changed from revision to revision. This is
extended as last thing, when all is ready to package, as this file also
defines the version number for the new revision of the package. Best do this
with:
.PP
\fBmakesourcepackage \-l "initial release" foo-bar\fP
.PP
The above automatically generates an verion number in YYYYMMDD.HHMMSS format
from the current time. So on every re-packaging you will need to repeat this
step, preferably with an \fB-l\fP "reason for re-packaging" which describes
what and why you changed it.
.PP
The package is then actually built with:
.PP
\fBmakesourcepackage \-p foo-bar\fP
.PP
And can then be uploaded to an package server and the server reindexed with:
.PP
\fBmakesourcepackage \-ui foo-bar\fP
.PP
For setting up an package server which works together with
\fBmakesourcepackage\fP and how to access it then, see the documentation of
\fBmakelocalsite\fP(1).
.PP
All other features of \fBmakesourcepackage\fP are just comfort stuff.

.SH ERROR MESSAGES

These are graded into categories and marked accordingly, and then sent to
stderr output:
.TP
.B FATAL:
Something happend that was not expected to be so. Looks seriously wrong.
Operation will be immediately aborted. May require sysadmin to fix. Could even
be sign of an bug.
.TP
.B ERROR:
User input looks errorneous. Will try to give out help as far as applicable
help is known. Check up on command line options and filenames.
.TP
.B WARNING:
Something unusual is happening, most likely wrong, but it may be desired. So
continue operation but warn user, to look if it was an desired thing.
.TP
.B NOTE:
Something happend which is completely legal, but may be sign of trouble. Give
user a note that it happened and continue.
.TP
.B INFO:
Tell user what we are doing now. Only happens if user demanded \-v verbosity.
Not unexpected and not an error, so sent to stdout, not stderr.
.TP
.B DEBUG:
Tell user in what state we are at the moment. Only happens if user demanded \-D
PRINT_STEP debug output. Not unexpected and not an error, so sent to stdout,
not stderr.

.SH SEE ALSO

\fIdphys-pkgtools\fP(7), \fImakelocalsite\fP(1)
http://www.debian.org/doc/maint-guide/

.SH AUTHOR

franklin@phys.ethz.ch, http://www.phys.ethz.ch/~franklin/