DOC

PolyPackage  - a distributable cross-platform packaging system

This document describes the generic packaging interface.

Features

- redistributable for source packages
- assumes simple common case
- based on Bourne Shell; embeddable shell
- provides signal-based native 'service' integration
- uses notion of 'components' (runtime, debugging, development, doc)

Examples

1. Simple binary tool package

  	%set
	name="hello"
	description="Hello, world"

	%files run
	/usr/bin/*

2. Service example

	%set
	name="hellod"
	description="Hello, world service"

	%files run
	/usr/libexec/*

	%service hellod

3. Library example

	%set
	name="libhello"
	description="Hello, world library"

	%files run
	/usr/lib/libhello.%so

	%files dev
	/usr/lib/libhello.a
	/usr/include/hello.h

4. Diagnostic example

	%set
	name="hello"
	description="Hello tool"

	%files run
	/usr/bin/hello

	%files dbg
	/usr/bin/hello-dump

Invocation

        pp [options] [input-file] [var=value...]

	   -d --debug                  -- write copious info to stderr
	      --destdir=path           -- defaults to $DESTDIR
	   -i --install-script=path    -- create a helper install script
	   -l --list                   -- write package filenames to stdout
	      --no-clean               -- don't remove files in wrkdir
	      --no-package             -- do everything but create packages
	      --only-front             -- only perform front-end actions
	   -p --platform=platform      -- defaults to local platform
	      --probe                  -- print host identifier and exit
	      --wrkdir=path            -- defaults to $TMPDIR or /tmp
	      --vas-platforms          -- print VAS platform equivalent IDs
	   -v --verbose                -- write info to stderr
	      --version                -- write version and exit

	   input-file               -- defaults to '-', meaning stdin

Platforms

    PolyPackage determines the platform type by invoking 'uname -s'.

    PolyPackage is a shell script that runs on most versions of the
    Bourne or Korn shell. For file globbing on Solaris, ksh must be
    used instead of sh.  The following tests are used to determine if
    the current shell is sufficient or if another shell should
    be executed to run the pp script.

	echo /{usr,bin}                  - {}-mode, no re-execute
	echo /@(usr|bin)                 - @()-mode, no re-execute
	ksh -c 'echo /{usr,bin}'         - re-execute
	ksh -c 'echo /@(usr|bin)'        - re-execute
	bash -c 'echo /{usr,bin}'        - re-execute
	bash -c 'echo /@(usr|bin)'       - re-execute

Helper install script

    The --install-script option directs pp to generate a helper shell
    script that provides a uniform interface to the platform's packaging
    tool.

    The helper script takes one of the following as command arguments:

           list-services              -- lists services defined in the pkg
           list-components            -- lists components defined in the pkg
           list-files {cpt...|all}    -- lists package files containing cpts
           install {cpt...|all}       -- installs pkgs containing cpts
           uninstall {cpt...|all}     -- uninstalls pkgs containing cpts
           start {svc...}             -- starts the service
           stop {svc...}              -- stops the service
           print-platform             -- prints lowest platform for pkg

    The 'install' command performs an upgrade if another version of
    the software is already installed. Even if you are installing an
    older version, this command will still succeed.

    The following options are understood before the script command argument:

           -q          -- quiet mode: do not show package tool invocations

Sections

    Sections are introduced by %-directives. These directives are
    on a line by themselves.  The first character the line must be a '%'.
    Whitespace after the first '%' is always removed. e.g.:

	%foo
	% bar

    A line that starts with '%%' is be treated as if it were a
    literal line and the first '%' and following whitespace
    will be removed.

    	%% this line will not be interpreted as a %-directive

Conditionals

    The special %-directives %if, %else and %endif are processed
    before sections. The argument to %if and %else is given to the
    shell's "test" builtin.

    		%if $name = "foo"
                % ignore
		  some lines for the foo package only
		%endif

    There is no %elif. Use nested %if instead.

    If the argument to the %if directive starts with '[' then it
    is interpreted as a platform qualifier. A platform qualifier
    is a comma-separated list of platform names enclosed in square
    brackets. No whitespace is permitted within the brackets.

                %if [solaris,rpm]
                    some lines for solaris and rpm systems only
                %endif

                %if [!sd]
                    some lines for non-hpux systems
                %endif

    If a line begins with a [platform] qualifier then it applies to
    that line only. For example:

                %files run
                /etc/foo
                [aix] /etc/aix/bar
                [!aix] /etc/bar

    If a line starts in column 1 with the '#' character, then the
    line is disabled as if it had started with '[!]'.

    Many sections directives (e.g. %files, described below) take
    an optional 'qualifier' argument which selectively enables or
    disables the entire section.

    To prevent a line from being treated specially, either as
    a section directive, or as prefixed with a qualifier, you must
    start the line with the two characters '%\'. The '%\' is removed
    and the rest of the line is treated as an unqualified non-directive.

The %set section

	The %set section directive causes successive lines to
	be interpreted as literal shell code. The section body is stored
	in a text file and then sourced with the shell's '.' operator at
        the end of the section.

		%set
		  name="foo"
		  version="1.0"

	Variables expected to be declared in this section are:

		name		- simple identifier name of the package
		version		- version identifier: must start with
				  a digit, and consist of only digits and
				  periods. At most three periods are
				  permitted.
		summary		- summary of package, limit 40 characters
				  [defaults to "no summary"]
		description	- A paragraph describing the package.
				  Can be placed in quotes where newlines
				  will be replaced by spaces.
				  [defaults to "No description"]
		copyright	- copyright message, limit 40 characters
				  [default is "Copyright YYYY, One Identity..."]

        The %set section is *not* subject to %{} or %() expansion.

    Output of a %set section:

    	Each %set section generates a temporary file, whose contents
	are sourced by the driver shell script at the end of seeing the
	section. The temporary file is then immediately deleted. The
	variables are then available to the rest of the script. Variable
	names starting with $pp_ are private to polypackage.

The %files sections

	The files comprising the various components of the package
	are listed in the %files sections.

	The %files section directive must be followed by one of the
	four standard component names: run dev doc dbg. If the component
	is missing, 'run' is assumed.

	    %files [component]

	The section body ignores blank lines and lines starting with '#'.
	Whitespace at the beginning of lines is ignored. The format
	of body lines is as follows:

	    path-glob [octal-mode] [[owner]:[group]] [flags] [target]

	'Path-glob' is an absolute pathname which may contain the wildcard
	and pattern metacharacters *,?,[,],{,}.

	  Impl note: {,}-patterns are converted into /@(|)-patterns
          for some shells. This is automatically detected and performed.

        If the path-glob is of the form 'path/**' then it is converted
        into a list of all files and directories under (but not including)
        the directories matched by path. If you want to include the
        parent directory as well as all children, you must list the
        directory separately:

                /path/to/dir/
                /path/to/dir/**

	If the path-glob ends with %so then it is replaced with
	platform's native shared library suffix pattern.
	On HP-UX this is .sl*, and on other platforms it is .so*.
	For AIX, .a is used.

		/usr/lib/libfoo.%so

	Source files matching the path-glob must exist in a directory
	rooted under $DESTDIR unless the 'optional' flag is supplied.
	If the path-glob refers to a directory, it *must* end with a
	trailing slash.

	The octal-mode argument must start with a digit or be
	the special word '=' meaning to use the mode of the
	source file.

	The owner:group argument must contain a ':'. Either or both
	of the owner or group paths are optional, or can be specified
	as '=' meaning to use the mode of the source file.

	The defaults for unspecified mode, owner and group depend on the
	platform, path prefix, and the file type.  Generally, if the
	path is a directory, the default mode will be 755. For normal
	files the default mode is generally 644.

	If the source file is a symlink, then the package will include
	a symlink. If the target of the source symlink begins with $DESTDIR,
	then it is stripped. If a target is specified in flags, then
	the source file is ignored. Symlink modes are ignored.

	'Flags' is a comma-delimited list of flags. Valid flags are:
		volatile	- uninstall will ignore changes in the file
		missingok	- uninstall will ignore if the file is missing (rpm only for now)
		optional	- ignore if the path-glob matches nothing
		symlink		- The file must be packaged as a symlink
                ignore          - ignore this file (don't package it)
                ignore-others   - ignore all other mentions of this file
                                  (useful for wildcards)

        If the 'symlink' flag is given, a symlink target should be
        given.

                /etc/foo.conf    volatile,optional

        The %files section is not subjected to %() or %{} expansion.
        However, paths are expanded using shell globbing, so shell
        metacharacters are interpreted.

    Output of %files sections:

	The result of processing all the %files sections is a collection
	of 'expanded' per-component %files lists, called "%files.run", etc.
	Each line of these files is of the form

		[d|f] mode owner group flags path
		s     mode owner group flags path target

	Where d,f,s indicate directory, file or symbolic link.
	The flags can be:
		v flag indicates volatility,
		m flag indicates missingok (do not warn if the file is missing during package removal)
		or '-' for a placeholder.
	The mode of symbolic links is ignored but written as 777.

	The %fixup stage may be used to edit the %files components.

The %post and %preun sections

	The %post and %preun sections define shell scripts that
	are executed after file components are installed, and before
	file components are uninstalled.

		%post [component] [qualifier]
		%preun [component] [qualifier]

	The body of these sections is treated as shell script, but
	%{} and %() expansion takes place. The shell script body is
	appended to any previous %post/%preun scripts for that component.

    %{} and %() expansion

        Because most sections (%set being an exception) are deferred
        until later for execution, it is sometimes useful to be able
        to perform variable expansion early. Otherwise, later %set
        sections may change variables, and variable used in the
        other sections will be different when they eventually get run.

        Substrings of the form "%{FOO}" are replaced by the content of
        the shell variable $FOO. (Other shell variable forms such as
        "%{FOO:-default}" are possible: the '%' is replaced by a '$'
        and then evaluated up to the '}'.

        Substrings of the form %() are expanded using the shell's
        backquote. e.g. "%(echo hello; echo there)" becomes "hello there".

	%{} and %() expressions must not contain the characters '}', ')'
	or newlines. If you must include those characters, create
	them in variables in an earlier %set section, or put them in
	an external file and use %(cat file).

    Output of %post or %preun sections

    	The result of processing the %post or %preun sections are files such as
	"%post.run" or "%preun.dbg". The platform-specific code ensures
	that these scripts are invoked at the right times during
	installation.

    Exit codes

	The %post, %preun, and %check scripts are automatically appended
	with an 'exit 0' statement. For a script to terminate installation,
	it must explicitly invoke 'exit 1'.

The %service section

	A %service section consists of the directive %service followed
	by a simple service identifier. If omitted, the simple name of the
	package is used.

		%service [name] [qualifier]

	The body of a %service section consists of shell text. It is
	expected to set some simple shell variables, and is effectively
	treated much like a %set section.

	The service sections assume the common case of a daemon process
	started at boot time and controlled by native platform service
	management tools.

	A service is assumed to be started as invocation of an executable
	file with some arguments.  Two flavours of service are assumed

	    the program forks, becomes a daemon, the parent writes
	      the child's PID to a well-known path and exits true.

	    the program does not fork or become a daemon. No PID file
	      is written.

	The first style is selected by providing a 'pidfile' variable,
	where the second style is selected by setting the pidfile variable
	to the empty string (the default for each %service section).

	Platform-independent variables expected to be set are:

		cmd		Shell command to execute
		pidfile		Path to a file containing the PID as
				the first word on the first line.
		stop_signal	Signal number that gracefully stops
				the process [default 15]
		user		User to run the service as [default root]
		group		Insert into a virtual service group which
				will shutdown/startup all member services.
		optional	Whether the user will be asked if he wants
				to install the service at installation time
				(where supported). Default: no
		enable		Whether to enable the service during postinst
				(installation time). Default: yes

	Other platform-specific variables may be provided in this
	section and are treated differently.

        The %service section, like other non-%set sections is subject to
        immediate %{} and %() expansion.

   Output of a %service section:

   	The result of processing a %service section is to create or
	append to a file called %service.name, where 'name' is the
	name given to the service. The file will contains the shell
	text. The shell text is sourced and then platform-specific
	changes are made to the other output files before %fixup

The %require section

	* UNIMPLEMENTED *

	The dependency section lists the names of interfaces that
	a component requires in order to function.

	Backends will generate most of a package's requirements
	automatically. This section is provided only for requirements
	which polypkg fails to detect.

	The %require directive is followed by a component name; 'run'
	is assumed if it is omitted.

	    %require [component] [qualifier]

	The body of a require section consists of interface names
	as describe below under 'Interface names'.  Blank lines,
	or lines starting with '#' are ignored.  The lines can
	contain shell variable expansion.

	Lines starting with "+" indicate platform-specific dependency
	information. See the platform backend documentation for details.

        The %require section, like other non-%set sections is subject to
        immediate %{} and %() expansion.

	Multiple %require sections for a component are concatenated
	together. Lines beginning with # and blank lines are removed.
	Whitespace at the beginning of lines is ignored.

    Output of a %require section

    	The result of processing all the %require and %file sections results
	in files called %require.run etc which contain lines of either
	of the forms

		kind:interface
		+ text

The %provide section

	* UNIMPLEMENTED *

	This optional section is a counterpart to %require.
	It is used to indicate interfaces provided by the package.
	You only need to use this section for provided interfaces that
	polypkg was unable to discover.

	It is most useful for specifying virtual packages.

	Like the %require section, lines starting with '+' are passed
	through to the backend, which may ignore them.

    Output of a %provide section

	The result of processing all the %provide and %files sections
	results in files called %provide.run, etc. which contain lines of
	either of the forms

		kind:interfaces
		+ text

The %check section

        The check section body contains a shell script that
        is executed on the target host to ensure that dependencies
        are met. It is processed in a manner very similar to %post
        or %preun.

	If the script calls 'exit 1', installation will be
	canceled. The script *must* write an explanation
	to the standard output before calling 'exit 1'.

            %check [component]

        The check section must not be interactive.

        The check script might not be executed on some platforms.


The %fixup section

	The fixup section body contains shell text that is run
	immediately before the platform packaging tools are executed.
	It is processed in a manner similar to %set.

                %fixup [qualifier]

	The %fixup directive is not followed by any component identifier.
	This is really only intended as a last-resort place to hold
	any horrible hackery required. It is a last chance to perform
	changes before the active backend creates its package files.

    Output of a %fixup section

    	The bodies of fixup sections are concatenated together
	into a temporary file, and executed together.

The %pp section

	This optional section has no body. It specifies a version of
	the PolyPackage API that the file expects to use. This
	document describes version 1.0.

		%pp 1.0

	This section can be specified early to make use of
	particular features of an older interface.

The %ignore section

        These sections contain text that is always ignored by
	polypkg. This could be useful for comments.

                %ignore

The %depend section

	The package's dependencies as they will appear verbatim in the
	package's control file. A component can be specified, otherwise
	the "run" component is assumed.

	Dependencies are specified in the %depend section up until the
	next section. Dependencies should be specified on a single line,
	but may be split - each line is simply concatenated *without*
	adding any separator characters (such as ",").

	At time of writing only the deb backend implements this kind of
	explicit dependency. Its syntax is subject to change. See
	http://www.debian.org/doc/debian-policy/ch-relationships.html#s-depsyntax
	for the syntax.

The %conflict section

	A collection of conflicting packages that will prevent
	installation of the package.  A component can be specified,
	otherwise the "run" component is assumed.

	Conflicts are specified in the %conflict section up until
	the next section.  The format of the line is:

	    package_name [version]

	If the version is specified, any installed package_name
	with a version greater than or equal to version will be
	considered a conflict.

Output filenames

    The output from polypkg is one or more package files, and optionally
    a helper script (inst) that can be used to manipulate the package file(s)
    through a uniform interface.

    Package filenames default to the following:

	rpm	    <name>[-<cpt>]-<version>-1.<arch>.rpm
	deb	    <name>[-<cpt>]_<version>-1_<arch>.deb
	aix	    <name>.<version>.bff
	sd	    <name>-<version>.depot
	solaris	    <name>-<version>.pkg
	macos	    <name>-<version>.dmg
        FreeBSD     <name>-<version>.txz


Interface names

    * UNIMPLEMENTED *

    polypkg can compute the full canonical dependency list of a package,
    and record it in the helper script.

    Dependencies (and provisions) are specified as a set of interfaces names.
    All interface names are of the form as:

	<kind>:<identifier>

    Examples of 'primitive' interface names are:

	isa:sparc.1	        - Processor executes Sparc1 instructions
	isa:x86_64	        - Processor executes AMD64/EM64T instrs
	exe:elf32.EM_386        - OS loads ELF32 exes with e_type=EM_386
	exe:elf64.EM_X86_64     - OS loads ELF64 exes with e_type=EM_X86_64
	ld:libc.so.1	        - Dynamic loader that can load libc.so.1
	file:/bin/sh	        - The file /bin/sh
	pkg:rpm:openssl-0.9.8g  - Particular openSSL RPM package

    Interfaces normally have no linear order. That is, you can't express
    "versions after x.y.z". All version info must be explicit and match
    exactly. Expressed interfaces are not optional. Disjunction is not
    supported.

    Polypkg will scan the files in %files to generate a list of required
    interfaces. The list can be supplemented by entries in the %depend
    section, or explicit checks can be added to the %check section.

    Virtual interfaces are of the form virtual:<identifier> and are not
    checked by polypkg. However, you

    Polypkg will generate package metadata that tests for the existence
    of all dependencies. Usually this is created as an extra %check script,
    but it may be split between the %check script and the packaging system,
    should it be capable of testing for some of the native dependencies.

    Polypkg's helper script can be run in a mode to list all the primitive
    interfaces required by the package, and all the interfaces provided,
    should the package be installed.

	inst.sh --required-interfaces   > ifc.list
	inst.sh --provided-interfaces   > ifc.list

    Polypkg can be run in a mode where it can check for all the interfaces
    supplied on standard input. Any missing interfaces are printed to standard
    output, and cause the script to exit with an error at the end.

	pp --check-interfaces  < ifc.list