@c Copyright (C) 2007 S�ren Hauberg
@c
@c This file is part of Octave.
@c
@c Octave is free software; you can redistribute it and/or modify it
@c under the terms of the GNU General Public License as published by the
@c Free Software Foundation; either version 3 of the License, or (at
@c your option) any later version.
@c 
@c Octave is distributed in the hope that it will be useful, but WITHOUT
@c ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
@c FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
@c for more details.
@c 
@c You should have received a copy of the GNU General Public License
@c along with Octave; see the file COPYING.  If not, see
@c <http://www.gnu.org/licenses/>.

@node Packages
@chapter Packages

Since Octave is Free Software users are encouraged to share their
programs amongst each other. To aid this sharing Octave supports the
installation of extra packages. The `Octave-Forge' project is a
community-maintained set of packages that can be downloaded and
installed in Octave. At the time of writing the `Octave-Forge' project
can be found on-line at @uref{http://octave.sourceforge.net}, but
since the Internet is an ever-changing place this may not be true at
the time of reading. Therefore it is recommended to see the Octave
website for an updated reference.

@menu
* Installing and Removing Packages::  
* Using Packages::              
* Administrating Packages::     
* Creating Packages::           
@end menu

@findex pkg
@node Installing and Removing Packages
@section Installing and Removing Packages

Assuming a package is available in the file @code{image-1.0.0.tar.gz}
it can be installed from the Octave prompt by writing

@example
pkg install image-1.0.0.tar.gz
@end example

@noindent
If the package is installed successfully nothing will be printed on
the prompt, but if an error occurred during installation it will be
reported. It is possible to install several packages at once by
writing several package files after the @code{pkg install} command.
If a different version of the package is already installed it will
be removed prior to installing the new package. This makes it easy to
upgrade and downgrade the version of a package, but makes it
impossible to have several versions of the same package installed at
once.

To see which packages are installed type

@example
@group
pkg list
@print{} Package Name  | Version | Installation directory
@print{} --------------+---------+-----------------------
@print{}        image *|   1.0.0 | /home/jwe/octave/image-1.0.0
@end group
@end example

@noindent
In this case only version 1.0.0 of the @code{image} package is
installed. The '*' character next to the package name shows that the
image package is loaded and ready for use.

It is possible to remove a package from the system using the
@code{pkg uninstall} command like this

@example
pkg uninstall image
@end example

@noindent
If the package is removed successfully nothing will be printed in the
prompt, but if an error occurred it will be reported. It should be
noted that the package file used for installation is not needed for
removal, and that only the package name as reported by @code{pkg list}
should be used when removing a package. It is possible to remove
several packages at once by writing several package names after the
@code{pkg uninstall} command.

To minimize the amount of code duplication between packages it is
possible that one package depends on another one. If a package
depends on another, it will check if that package is installed
during installation. If it is not, an error will be reported and
the package will not be installed. This behaviour can be disabled
by passing the @code{-nodeps} flag to the @code{pkg install}
command

@example
pkg install -nodeps my_package_with_dependencies.tar.gz
@end example

@noindent
Since the installed package expects its dependencies to be installed
it may not function correctly. Because of this it is not recommended
to disable dependency checking.

@node Using Packages
@section Using Packages

By default installed packages are available from the Octave prompt,
but it is possible to control this using the @code{pkg load} and 
@code{pkg unload} commands. The functions from a package can be 
removed from the Octave path by typing

@example
pkg unload package_name
@end example

@noindent
where @code{package_name} is the name of the package to be removed
from the path.

In much the same way a package can be added to the Octave path by
typing

@example
pkg load package_name
@end example

@node Administrating Packages
@section Administrating Packages

On UNIX-like systems it is possible to make both per-user and
system-wide installations of a package. If the user performing the
installation is @code{root} the packages will be installed in a
system-wide directory that defaults to 
@code{OCTAVE_HOME/share/octave/packages/}. If the user is not 
@code{root} the default installation directory is
@code{~/octave/}. Packages will be installed in a subdirectory of the
installation directory that will be named after the package. It is
possible to change the installation directory by using the
@code{pkg prefix} command

@example
pkg prefix new_installation_directory
@end example

@noindent
The current installation directory can be retrieved by typing

@example
current_installation_directory = pkg prefix
@end example

To function properly the package manager needs to keep some
information about the installed packages. For per-user packages this
information is by default stored in the file @code{~/.octave_packages}
and for system-wide installations it is stored in
@code{OCTAVE_HOME/share/octave/octave_packages}. The path to the
per-user file can be changed with the @code{pkg local_list} command

@example
pkg local_list /path/to/new_file
@end example

@noindent
For system-wide installations this can be changed in the same way
using the @code{pkg global_list} command. If these commands are
called without a new path, the current path will be returned.

@node Creating Packages
@section Creating Packages

Internally a package is simply a gzipped tar file that contains a
top level directory of any given name. This directory will in the
following be referred to as @code{package} and may contain the
following files

@noindent
@table @code
@item package/DESCRIPTION
This is a required file containing information about the package.
@xref{The DESCRIPTION File}, for details on this file.

@item package/COPYING
This is a required file containing the license of the package. No
restrictions is made on the license in general. If however the
package contains dynamically linked functions the license must be
compatible with the GNU General Public License.

@item package/INDEX
This is an optional file describing the functions provided by the
package. If this file is not given then one with be created
automatically from the functions in the package and the
@code{Categories} keyword in the @code{DESCRIPTION} file.
@xref{The INDEX file}, for details on this file.

@item package/PKG_ADD
An optional file that includes commands that are run when the package
is added to the users path. Note that @code{PKG_ADD} directives in the
source code of the package will also be added to this file by the
Octave package manager. Note that symbolic links are to be avoided in
packages, as symbolic links do not exist on some file systems, and so
a typical use for this file is the replacement of the symbolic link

@example
ln -s foo.oct bar.oct
@end example

@noindent
with an autoload directive like

@example
autoload ('bar', which ('foo'));
@end example

@noindent
@xref{PKG_ADD and PKG_DEL directives}, for details on @code{PKG_ADD}
directives.

@item package/PKG_DEL
An optional file that includes commands that are run when the package
is removed from the users path. Note that @code{PKG_DEL} directives in
the source code of the package will also be added to this file by the
Octave package manager. 
@xref{PKG_ADD and PKG_DEL directives}, for details on @code{PKG_DEL}
directives.

@item package/pre_install.m
This is an optional script that is run prior to the installation of a
package. 

@item package/post_install.m
This is an optional script that is run after the installation of a
package. 

@item package/on_uninstall.m
This is an optional script that is run prior to the removal of a
package. 
@end table

Besides the above mentioned files, a package can also contain on or
more of the following directories

@noindent
@table @code
@item package/inst
An optional directory containing any files that are directly installed
by the package. Typically this will include any @code{m}-files. 

@item package/src
An optional directory containing code that must be built prior to the
packages installation. The Octave package manager will execute
@code{./configure} in this directory if this script exists, and will
then call @code{make} if a file @code{Makefile} exists in this
directory. @code{make install} will however not be called. If a file
called @code{FILES} exist all files listed there will be copied to the
@code{inst} directory, so they also will be installed. If the
@code{FILES} file doesn't exist, @code{src/*.m} and @code{src/*.oct}
will be copied to the @code{inst} directory.

@item package/doc
An optional directory containing documentation for the package. The
files in this directory will be directly installed in a sub-directory
of the installed package for future reference.

@item package/bin
An optional directory containing files that will be added to the
Octave @code{EXEC_PATH} when the package is loaded. This might contain
external scripts, etc, called by functions within the package.
@end table

@menu
* The DESCRIPTION File::        
* The INDEX file::              
* PKG_ADD and PKG_DEL directives::  
@end menu

@node The DESCRIPTION File
@subsection The DESCRIPTION File

The @code{DESCRIPTION} file contains various information about the
package, such as it's name, author, and version. This file has a very
simple format

@noindent
@itemize
@item
Lines starting with @code{#} are comments.

@item
Lines starting with a blank character are continuations from the 
previous line.

@item
Everything else is of the form @code{NameOfOption: ValueOfOption}.
@end itemize

@noindent
The following is a simple example of a @code{DESCRIPTION} file

@example
Name: The name of my package
Version: 1.0.0
Date: 2007-18-04
Author: The name (and possibly email) of the package author.
Maintainer: The name (and possibly email) of the current
 package maintainer.
Title: The title of the package
Description: A short description of the package. If this
 description gets too long for one line it can continue
 on the next by adding a space to the beginning of the
 following lines.
License: GPL version 3 or later
@end example

The package manager currently recognizes the following keywords

@noindent
@table @code
@item Name
Name of the package.

@item Version
Version of the package.

@item Date
Date of last update.

@item Author
Original author of the package.

@item Maintainer
Maintainer of the package.

@item Title
A one line description of the package.

@item Description
A one paragraph description of the package.

@item Categories
Optional keyword describing the package (if no @code{INDEX} file is
given this is mandatory).

@item Problems
Optional list of known problems.

@item Url
Optional list of homepages related to the package.

@item Autoload
Optional field that sets the default loading behavior for the package.
If set to @code{yes}, @code{true} or @code{on}, then Octave will
automatically load the package when starting. Otherwise the package
must be manually loaded with the pkg load command. This default
behavior can be overridden when the package is installed.

@item Depends
A list of other Octave packages that this package depends on. This can
include dependencies on particular versions, with a format

@example
Depends: package (>= 1.0.0)
@end example

@noindent
Possible operators are @code{<}, @code{<=}, @code{==}, @code{>=} or
@code{>}. If the part of the dependency in @code{()} is missing, any
version of the package is acceptable. Multiple dependencies can be
defined either as a comma separated list or on separate @code{Depends}
lines.

@item License
An optional short description of the used license (e.g. GPL version 3
or newer). This is optional since the file @code{COPYING} is mandatory.

@item SystemRequirements
These are the external install dependencies of the package and are not
checked by the package manager. This is here as a hint to the
distribution packager. They follows the same conventions as the
@code{Depends} keyword.

@item BuildRequires
These are the external build dependencies of the package and are not
checked by the package manager. This is here as a hint to the
distribution packager. They follows the same conventions as the 
@code{Depends} keyword. Note that in general, packaging systems such
as @code{rpm} or @code{deb} and autoprobe the install dependencies
from the build dependencies, and therefore the often a
@code{BuildRequires} dependency removes the need for a
@code{SystemRequirements} dependency.

@end table

@noindent
The developer is free to add additional arguments to the 
@code{DESCRIPTION} file for their own purposes. One further detail to
aid the packager is that the @code{SystemRequirments} and
@code{BuildRequires} keywords can have distribution dependent section,
and the automatic build process will use these. An example of the
format of this is

@example
BuildRequires: libtermcap-devel [Mandriva] libtermcap2-devel
@end example

@noindent
where the first package name will be used as a default and if the
RPMs are built on a Mandriva distribution, then the second package
name will be used instead. 

@node The INDEX file
@subsection The INDEX file

The optional @code{INDEX} file provides an categorical view of the
functions in the package. This file has a very simple format

@noindent
@itemize
@item Lines beginning with @code{#} are comments.

@item The first non-comment line should look like this

@example
toolbox >> Toolbox name
@end example

@item Lines beginning with an alphabetical character indicates a new
category of functions.

@item Lines starting with a white space character indicate that the
function names on the line belong to last mentioned category.
@end itemize

@noindent
The format can be summarized with the following example

@example
# A comment
toolbox >> Toolbox name
Category Name 1
 function1 function2 function3
 function4
Category Name 2
 function2 function5
@end example

If you wish to refer to a function that users might expect
to find in your package but is not there, providing a work around or 
ponting out that  the function is available elsewhere, you can use:

@example
fn = workaround description
@end example

@noindent
This workaround description will not appear when listing functions in the 
package with @code{pkg describe} but they will be published
in the html documentation online.
Workaround descriptions can use any html markup, but
keep in mind that it will be enclosed in a bold-italic environment.  
For the special case of:

@example
fn = use <code>alternate expression</code>
@end example

@noindent
the bold-italic is automatically suppressed.  You will need
to use @code{<code>} even in references:

@example
fn = use <a href="someothersite.html"><code>fn</code></a>
@end example

@noindent
Sometimes functions are only partially compatible, in which
case you can list the non-compatible cases separately. To
refer to another function in the package, use @code{<f>fn</f>}.
For example,

@example
eig (a, b) = use <f>qz</f>
@end example

@noindent
Since sites may have many missing functions, you can define
a macro rather than typing the same link over and again.

@example
$id = expansion
@end example

@noindent
defines the macro id.  You can use @code{$id} anywhere in the
description and it will be expanded.  For example,

@example
$TSA = see <a href="link_to_spctools">SPC Tools</a>
arcov = $TSA <code>armcv</code>
@end example

@noindent
id is any string of letters, numbers and @code{_}.

@node PKG_ADD and PKG_DEL directives
@subsection PKG_ADD and PKG_DEL directives

If the package contains files called @code{PKG_ADD} or @code{PKG_DEL}
the commands in these files will be executed when the package is
added or removed from the users path. In some situations such files
are a bit cumbersome to maintain, so the package manager supports
automatic creation of such files. If a source file in the package
contains a @code{PKG_ADD} or @code{PKG_DEL} directive they will be
added to either the @code{PKG_ADD} or @code{PKG_DEL} files.

In @code{m}-files a @code{PKG_ADD} directive looks like this

@example
## PKG_ADD: some_octave_command
@end example

@noindent
Such lines should be added before the @code{function} keyword.
In C++ files a @code{PKG_ADD} directive looks like this

@example
// PKG_ADD: some_octave_command
@end example

@noindent
In both cases @code{some_octave_command} should be replaced by the
command that should be placed in the @code{PKG_ADD} file.
@code{PKG_DEL} directives work in the same way, except the @code{PKG_ADD}
keyword is replaced with @code{PKG_DEL} and the commands get added
to the @code{PKG_DEL} file.