apk-tools Code

<?xml version='1.0' encoding='ISO-8859-1'?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [

<!--

Process this file with an XSLT processor: `xsltproc \
-''-nonet /usr/share/sgml/docbook/stylesheet/xsl/nwalsh/\
manpages/docbook.xsl manpage.dbk'.  A manual page
<package>.<section> will be generated.  You may view the
manual page with: nroff -man <package>.<section> | less'.  A
typical entry in a Makefile or Makefile.am is:

DB2MAN=/usr/share/sgml/docbook/stylesheet/xsl/nwalsh/\
manpages/docbook.xsl
XP=xsltproc -''-nonet

manpage.1: manpage.dbk
	$(XP) $(DB2MAN) $<
				    
	The xsltproc binary is found in the xsltproc package.  The
	XSL files are in docbook-xsl.  Please remember that if you
	create the nroff version in one of the debian/rules file
	targets (such as build), you will need to include xsltproc
	and docbook-xsl in your Build-Depends control field.

-->

<!-- Fill in your name for FIRSTNAME and SURNAME. -->
<!ENTITY dhfirstname "<firstname>Natanael</firstname>">
<!ENTITY dhsurname   "<surname>Copa</surname>">
<!-- Please adjust the date whenever revising the manpage. -->
<!ENTITY dhdate      "<date>September 12, 2006</date>">
<!-- SECTION should be 1-8, maybe w/ subsection other parameters are
allowed: see man(7), man(1). -->
<!ENTITY dhsection   "<manvolnum>1</manvolnum>">
<!ENTITY dhemail     "<email>ncopa@users.sourceforge.net</email>">
<!ENTITY dhusername  "Natanael Copa">
<!ENTITY dhucpackage "<refentrytitle>APK_ADD</refentrytitle>">
<!ENTITY dhpackage   "apk_add">

<!ENTITY apktools    "<productname>apk-tools</productname>">
<!ENTITY gnu         "<acronym>GNU</acronym>">
<!ENTITY gpl         "&gnu; <acronym>GPL</acronym>">
]>

<refentry>

<!--
	<refentryinfo>
		<address>&dhemail;</address>
		<author>&dhfirstname; &dhsurname;</author>
		<copyright><year>2005</year><holder>&dhusername;</holder></copyright>
		&dhdate;
	</refentryinfo>
-->	
	<refmeta>&dhucpackage; &dhsection;</refmeta>
	
	<refnamediv id="name">
		<refname>&dhpackage;</refname>
		<refpurpose>a utility for installing software packages</refpurpose>
	</refnamediv>
	
	<refsynopsisdiv id="synopsis">
		<cmdsynopsis>
			<command>&dhpackage;</command>
			<arg><option>-dfhInoqrsuv</option></arg>
			<arg rep='repeat' choice='plain'>
				<replaceable>apkname</replaceable>
			</arg>
		</cmdsynopsis>
	</refsynopsisdiv>

	<refsect1 id="description"><title>DESCRIPTION</title>
		<para>
			The <command>&dhpackage;</command> command is used to install software
			packages.
		</para>
	</refsect1>

	<refsect1><title>WARNING</title>
		<para>
			Since the <command>&dhpackage;</command> command may execute scripts
			or programs contained within a package file, your system may be
			susceptible to <quote>trojan horses</quote> or other subtle attacks from
			miscreants who create dangerous package files.
		</para>
		<para>
			You are advised to verify the competence and identity of those who
			provide installable package files.
		</para>
	</refsect1>

	<refsect1 id="options"><title>OPTIONS</title>
		<para>
			The following command line arguments are supported:
		</para>
		<variablelist>
		
			<varlistentry>
				<term><replaceable>apkname</replaceable></term>
				<listitem>
					<para>
						Specify a full package file, a package name with version, a package
						name without version, or a 
						full <acronym>URI</acronym>. Packages (that 
						are not local pkgfiles) will be fetched
						from <envar>APK_PATH</envar>. If a full <acronym>URI</acronym> is 
						supplied, dependencies are also fetched from
						the same site.
					</para>
				</listitem>
			</varlistentry>
				
			<varlistentry>
				<term><option>-d</option></term>
				<listitem>
					<para>
						Don't install any dependecies.
					</para>
				</listitem>
			</varlistentry>

			<varlistentry>
				<term><option>-f</option></term>
				<listitem>
					<para>
						Force installation to proceed even if prerequisite packages 
						are not installed or the requirements script 
						fails. Although <command>&dhpackage;</command> will still try to 
						find and auto-install	missing prerequisite packages, a failure to 
						find one will not be 
						fatal.
					</para>
				</listitem>
			</varlistentry>
	
			<varlistentry>
				<term><option>-h</option></term>
				<listitem>
					<para>Show help and exit.</para>
				</listitem>
			</varlistentry>
	
			<varlistentry>
				<term><option>-I</option></term>
				<listitem>
					<para>
						Don't execute any installation 
						scripts (pre-update, pre-install, post-install or post-update).
					</para>
				</listitem>
			</varlistentry>
			
			<varlistentry>
				<term><option>-n</option></term>
				<listitem>
					<para>
						Don't actually install a package, just report the steps that
						would be taken if it was.
					</para>
				</listitem>
			</varlistentry>

			<varlistentry>
				<term><option>-q</option></term>
				<listitem>
					<para>
						Quiet mode. Supress non-error messages.
					</para>
				</listitem>
			</varlistentry>

			<varlistentry>
				<term><option>-r</option><replaceable>reqby</replaceable></term>
				<listitem>
					<para>
						Register package as required by <replaceable>reqby</replaceable>.
					</para>
				</listitem>
			</varlistentry>

			<varlistentry>
				<term><option>-s</option></term>
				<listitem>
					<para>
						Don't verify the checksum of the package against the index.
					</para>
				</listitem>
			</varlistentry>
	
			<varlistentry>
				<term><option>-u</option></term>
				<listitem>
					<para>
						Update already installed packages. 
					</para>
				</listitem>
			</varlistentry>

			<varlistentry>
				<term><option>-v</option></term>
				<listitem>
					<para>
						Turn on verbose output.
					</para>
				</listitem>
			</varlistentry>
	</variablelist>

	</refsect1>

	
	<refsect1 id="techical_details"><title>TECHNICAL DETAILS</title>
	<para>
		If the <replaceable>apkname</replaceable> is not a file in the local file
		system and the package is not already 
		installed, the <command>&dhpackage;</command> utility will fetch the package
		to the <filename>$ROOT/var/cache/packages</filename> directory and verify the checksum.
		The <command>&dhpackage;</command> utility then runs through the following
		sequence to install a package:
	</para>
	<orderedlist>
<!-- >
		<listitem>
			<para>
				A check is made to determine if the package is already recorded as
				installed. If it is, installation is terminated 
				unless update mode (<option>-u</option>) is specified.
			</para>
		</listitem>

		<listitem>
			<para>
				If package is not a local file then download the 
				file to the <filename>$PACKAGES</filename> directory. The 
				checksum of downloaded file will be checked against the
				checksum recorded in the index; if the checksums does not
				match, the installation is terminated. 
			</para>
		</listitem>
-->
		<listitem>
			<para>
				Create a unique temporary directory in /usr/tmp, unpack 
				the package and create 
				the <filename>$ROOT/var/db/apk/pkgname-ver/CONTENTS</filename> file
				where <replaceable>pkgname-ver</replaceable> is the package
				name (with version) in question. 
			</para>
		</listitem>

		<listitem>
			<para>
				Remove a downloaded package if <envar>$APK_KEEPCACHE</envar> is
				not set.
			</para>
		</listitem>

		<listitem>
			<para>
				Scan all the package dependencies. If any of these required packages
				is not currently installed, an attempt is made to find and install
				it; if the missing package cannot be found or installed, the 
				installation is terminated.
			</para>
		</listitem>

		<listitem>
			<para>
				If the package is an update for an already installed 
				package and it contains a <filename>pre-update</filename> file, it 
				is then executed as
			</para>
			<para>
				<command>sh</command> &nbsp;<filename>pre-update</filename>&nbsp;<replaceable>pkgname-ver</replaceable>&nbsp;<replaceable>pkgname-oldver</replaceable>
			</para>
			<para>
				where <replaceable>pkgname-ver</replaceable> is the package 
				name (with version) in question 
				and <replaceable>pkgname-oldver</replaceable> is the currently 
				installed version of the package.
			</para>
			<para>
				If the <filename>pre-update</filename> script fails, installation
				terminates.
			</para>
		</listitem>

		<listitem>
			<para>
				If the package contains a <filename>pre-install</filename> file, it 
				is then executed as 
			</para>
			<para>
				<command>sh</command>&nbsp;<filename>pre-install</filename>&nbsp;<replaceable>pkgname-ver</replaceable>
				<!-- &nbsp;<replaceable>pkgname-oldver</replaceable> -->
			</para>
			<para>
				where <replaceable>pkgname-ver</replaceable> is the package 
				name (with version) in question 
				and <replaceable>pkgname-oldver</replaceable> is the currently 
				installed version of the package.
			</para>
			<para>
				If the <filename>pre-install</filename> script fails, installation
				terminates.
			</para>
		</listitem>

		<listitem>
			<para>
				Register or update all config files in 
				the <filename>$ROOT/var/lib/apk/default.tdb</filename> <command>sfic</command> database 
				of the package.
			</para>
			<para>
				The config files are defined by the <envar>$APK_LBUDIRS</envar> envirnoment
				variable or <filename>/etc/apk/apk.conf</filename> keyword.
			</para>
		</listitem>

		<listitem>
			<para>
				Merge the files extracted to <filename>/usr/tmp</filename> into
				<filename>$ROOT</filename>. This is done by parsing the temporary 
				directory and moving files and directories 
				to <filename>$ROOT</filename>.
			</para>
		</listitem>

		<listitem>
			<para>
				Create 
				the <filename>$ROOT/var/db/apk/pkgname-ver/CONTENTS</filename> file
				where <replaceable>pkgname-ver</replaceable> is the package
				name (with version) in question. 
			</para>
		</listitem>
				
<!--		
		<listitem>
			<para>
				create sha1sums?
			</para>
		</listitem>
-->		
		<listitem>
			<para>
				Any dependencies are recorded or updated in the other
				packages' <filename>REQUIRED_BY</filename> list.
			</para>
		</listitem>

		<listitem>
			<para>
				If the package contains a <filename>post-install</filename> file, it 
				is then executed as
			</para>
			<para>
				<command>sh</command>&nbsp;<filename>var/db/apk/pkgname-ver/post-install</filename>&nbsp;<replaceable>pkgname-ver</replaceable>
				<!-- &nbsp;<replaceable>pkgname-oldver</replaceable> -->
			</para>
			<para>
				where <replaceable>pkgname-ver</replaceable> is the package 
				name (with version) in question.
			</para>
		</listitem>
		
		<listitem>
			<para>
				If package is an update, then remove all files that exist in the old
				packages' <filename>CONTENTS</filename> list but not in the 
				new <filename>CONTENTS</filename> list. 
				Remove also the old packages' meta 
				data, the <filename>$ROOT/var/db/apk/pkgname-ver.tar.gz</filename> file.
			</para>
		</listitem>

		<listitem>
			<para>
				If package is an update and contains a <filename>post-update</filename> file, it
				is then executed as
			</para>
			<para>
				<command>sh</command>&nbsp;<filename>var/db/apk/pkgname-ver/post-update</filename>&nbsp;<replaceable>pkgname-ver</replaceable>&nbsp;<replaceable>pkgname-oldver</replaceable>
			</para>
			<para>
				where <replaceable>pkgname-ver</replaceable> is the package 
				name (with version) in question
				and <replaceable>pkgname-oldver</replaceable> is the old version of the package.
			</para>
			
		</listitem>
		
		<listitem>
			<para>
				Finally the <filename>$ROOT/var/db/apk/<replaceable>pkgname-ver</replaceable></filename> directory 
				is compressed to <filename>$ROOT/var/db/apk/pkgname-ver.tar.gz</filename>
				and the temporay directory and the <filename>$ROOT/var/db/apk/pkgname-ver</filename> directory are deleted. 
			</para>
		</listitem>
		
	</orderedlist>
	</refsect1>
	
	
	<refsect1 id="environment"><title>ENVIRONMENT</title>
		<variablelist>
			<varlistentry>
				<term><envar>APK_ADD_TMP</envar></term>
				<listitem>
					<para>
						Directory where <command>&dhpackage;</command> stores
						temporary files. Default is <filename>/usr/tmp</filename>. 
					</para>
				</listitem>
			</varlistentry>
	
			<varlistentry>
				<term><envar>APK_DATA</envar></term>
				<listitem>
					<para>
						Alternative location for the cached index file.
						Default is <filename>$ROOT/var/lib/apk</filename>.
					</para>
				</listitem>
			</varlistentry>

			<varlistentry>
				<term><envar>APK_DBDIR</envar></term>
				<listitem>
					<para>
						Alternative location for the installed package database.
						Default is <filename>$ROOT/var/db/apk</filename>.
					</para>
				</listitem>
			</varlistentry>

			<varlistentry>
				<term><envar>APK_KEEPCACHE</envar></term>
				<listitem>
					<para>
						Downloaded files will not be deleted if this is set to "yes".
					</para>
				</listitem>
			</varlistentry>
				
			<varlistentry>
				<term><envar>APK_PATH</envar></term>
				<listitem>
					<para>
						List of <acronym>URI</acronym>'s to remote package repository 
						mirrors. The <acronym>URI</acronym>'s are separated by a
						semicolon (;).
					</para>
				</listitem>
			</varlistentry>
				
			<varlistentry>
				<term><envar>APKTOOLS_CONF</envar></term>
				<listitem>
					<para>
						Configuration file for the apk-tools suite.
						Default is <filename>/etc/apk/apk.conf</filename>.
					</para>
				</listitem>
			</varlistentry>

			<varlistentry>
				<term><envar>PACKAGES</envar></term>
				<listitem>
					<para>
						Base directory where <command>apk_add</command> saves downloaded
						packages.	Default is <filename>$ROOT/var/cache/packages</filename>.
					</para>
				</listitem>
			</varlistentry>
	
		</variablelist>
	</refsect1>

	<refsect1 id="files"><title>FILES</title>
		<variablelist>

			<varlistentry>
				<term><filename>$ROOT/var/cache/packages</filename></term>
				<listitem>
					<para>
						Default location to save downloaded files	into.
					</para>
				</listitem>
			</varlistentry>
				
			<varlistentry>
				<term><filename>$ROOT/var/db/apk</filename></term>
				<listitem>
					<para>
						Default location for the installed package database.
					</para>
				</listitem>
			</varlistentry>
				
			<varlistentry>
				<term><filename>$ROOT/var/lib/apk/INDEX.sha1.gz</filename></term>
				<listitem>
					<para>
						The cached index file.
					</para>
				</listitem>
			</varlistentry>
				
			<varlistentry>
				<term><filename>$ROOT/var/lib/apk/default.tdb</filename></term>
				<listitem>
					<para>
						The <command>sfic</command> database that contains the default 
						config files' status.
					</para>
				</listitem>
			</varlistentry>
				
			<varlistentry>
				<term><filename>/etc/apk.conf</filename></term>
				<listitem>
					<para>
						Default location of the apk-tools configuration file.
					</para>
				</listitem>
			</varlistentry>
			
			<varlistentry>
				<term><filename>/usr/tmp</filename></term>
				<listitem>
					<para>
						Default location for temporary files and directories.
					</para>
				</listitem>
			</varlistentry>

		</variablelist>
	</refsect1>
	
	<refsect1 id="see_also"><title>SEE ALSO</title>
		<para>apk_fetch (1), apk.conf (5)</para>
	</refsect1>
	
</refentry>
<!--
SEE ALSO
     pkg_create(1), pkg_delete(1), pkg_info(1), pkg_version(1), mktemp(3),
     sysconf(3), mtree(8)

AUTHORS
     Jordan Hubbard

CONTRIBUTORS
     John Kohl <jtk@rational.com>

BUGS
     Hard links between files in a distribution are only preserved if either
     (1) the staging area is on the same file system as the target directory
     of all the links to the file, or (2) all the links to the file are brack-
     eted by @cwd directives in the contents file, and the link names are
     extracted with a single tar command (not split between invocations due to
     exec argument-space limitations - this depends on the value returned by
     sysconf(_SC_ARG_MAX)).

     Sure to be others.
     
-->