@c DO NOT EDIT!  Generated automatically by munge-texi.pl.

@c Copyright (C) 2007-2015 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 online at @url{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 @file{image-1.0.0.tar.gz}
it can be installed from the Octave prompt with the command

@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 @qcode{'*'} 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 behavior can be disabled
by passing the @option{-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.

@c pkg scripts/pkg/pkg.m
@anchor{XREFpkg}
@deftypefn  {Command} {} pkg @var{command} @var{pkg_name}
@deftypefnx {Command} {} pkg @var{command} @var{option} @var{pkg_name}
Manage packages (groups of add-on functions) for Octave.

Different actions are available depending on the value of @var{command}.

Available commands:

@table @samp

@item install
Install named packages.  For example,

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

@noindent
installs the package found in the file @file{image-1.0.0.tar.gz}.

The @var{option} variable can contain options that affect the manner
in which a package is installed.  These options can be one or more of

@table @code
@item -nodeps
The package manager will disable dependency checking.  With this option it
is possible to install a package even when it depends on another package
which is not installed on the system.  @strong{Use this option with care.}

@item -noauto
The package manager will not automatically load the installed package
when starting Octave.  This overrides any setting within the package.

@item -auto
The package manager will automatically load the installed package when
starting Octave.  This overrides any setting within the package.

@item -local
A local installation (package available only to current user) is forced,
even if the user has system privileges.

@item -global
A global installation (package available to all users) is forced, even if
the user doesn't normally have system privileges.

@item -forge
Install a package directly from the Octave-Forge repository.  This
requires an internet connection and the cURL library.

@item -verbose
The package manager will print the output of all commands as
they are performed.
@end table

@item update
Check installed Octave-Forge packages against repository and update any
outdated items.  This requires an internet connection and the cURL library.
Usage:

@example
pkg update
@end example

@item uninstall
Uninstall named packages.  For example,

@example
pkg uninstall image
@end example

@noindent
removes the @code{image} package from the system.  If another installed
package depends on the @code{image} package an error will be issued.
The package can be uninstalled anyway by using the @option{-nodeps} option.

@item load
Add named packages to the path.  After loading a package it is
possible to use the functions provided by the package.  For example,

@example
pkg load image
@end example

@noindent
adds the @code{image} package to the path.  It is possible to load all
installed packages at once with the keyword @samp{all}.  Usage:

@example
pkg load all
@end example

@item unload
Remove named packages from the path.  After unloading a package it is
no longer possible to use the functions provided by the package.  It is
possible to unload all installed packages at once with the keyword
@samp{all}.  Usage:

@example
pkg unload all
@end example

@item list
Show the list of currently installed packages.  For example,

@example
pkg list
@end example

@noindent
will produce a short report with the package name, version, and installation
directory for each installed package.  Supply a package name to limit
reporting to a particular package.  For example:

@example
pkg list image
@end example

If a single return argument is requested then @code{pkg} returns a cell
array where each element is a structure with information on a single
package.

@example
installed_packages = pkg ("list")
@end example

If two output arguments are requested @code{pkg} splits the list of
installed packages into those which were installed by the current user,
and those which were installed by the system administrator.

@example
[user_packages, system_packages] = pkg ("list")
@end example

The @qcode{"-forge"} option lists packages available at the Octave-Forge
repository.  This requires an internet connection and the cURL library.
For example:

@example
oct_forge_pkgs = pkg ("list", "-forge")
@end example

@item describe
Show a short description of the named installed packages, with the option
@qcode{"-verbose"} also list functions provided by the package.  For example,

@example
pkg describe -verbose all
@end example

@noindent
will describe all installed packages and the functions they provide.
If one output is requested a cell of structure containing the
description and list of functions of each package is returned as
output rather than printed on screen:

@example
desc = pkg ("describe", "secs1d", "image")
@end example

@noindent
If any of the requested packages is not installed, @code{pkg} returns an
error, unless a second output is requested:

@example
[desc, flag] = pkg ("describe", "secs1d", "image")
@end example

@noindent
@var{flag} will take one of the values @qcode{"Not installed"},
@qcode{"Loaded"}, or
@qcode{"Not loaded"} for each of the named packages.

@item prefix
Set the installation prefix directory.  For example,

@example
pkg prefix ~/my_octave_packages
@end example

@noindent
sets the installation prefix to @file{~/my_octave_packages}.
Packages will be installed in this directory.

It is possible to get the current installation prefix by requesting an
output argument.  For example:

@example
pfx = pkg ("prefix")
@end example

The location in which to install the architecture dependent files can be
independently specified with an addition argument.  For example:

@example
pkg prefix ~/my_octave_packages ~/my_arch_dep_pkgs
@end example

@item local_list
Set the file in which to look for information on locally
installed packages.  Locally installed packages are those that are
available only to the current user.  For example:

@example
pkg local_list ~/.octave_packages
@end example

It is possible to get the current value of local_list with the following

@example
pkg local_list
@end example

@item global_list
Set the file in which to look for information on globally
installed packages.  Globally installed packages are those that are
available to all users.  For example:

@example
pkg global_list /usr/share/octave/octave_packages
@end example

It is possible to get the current value of global_list with the following

@example
pkg global_list
@end example

@item build
Build a binary form of a package or packages.  The binary file produced
will itself be an Octave package that can be installed normally with
@code{pkg}.  The form of the command to build a binary package is

@example
pkg build builddir image-1.0.0.tar.gz @dots{}
@end example

@noindent
where @code{builddir} is the name of a directory where the temporary
installation will be produced and the binary packages will be found.
The options @option{-verbose} and @option{-nodeps} are respected, while
all other options are ignored.

@item rebuild
Rebuild the package database from the installed directories.  This can
be used in cases where the package database has been corrupted.
It can also take the @option{-auto} and @option{-noauto} options to allow the
autoloading state of a package to be changed.  For example,

@example
pkg rebuild -noauto image
@end example

@noindent
will remove the autoloading status of the image package.

@end table
@seealso{@ref{XREFver,,ver}, @ref{XREFnews,,news}}
@end deftypefn


@node Using Packages
@section Using Packages

By default installed packages are not 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
added to the Octave path by typing

@example
pkg load package_name
@end example

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

In much the same way a package can be removed from the Octave path by
typing

@example
pkg unload 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
@file{OCTAVE_HOME/share/octave/packages/}.  If the user is not
@code{root} the default installation directory is
@file{~/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 @file{~/.octave_packages}
and for system-wide installations it is stored in
@file{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:

@table @code
@item package/CITATION
This is am optional file describing instructions on how to cite
the package for publication.  It will be displayed verbatim by the
function @code{citation}.

@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/DESCRIPTION
This is a required file containing information about the package.
@xref{The DESCRIPTION File}, for details on this file.

@item package/ChangeLog
This is an optional file describing all the changes made to the
package source files.

@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 @file{DESCRIPTION} file.
@xref{The INDEX File}, for details on this file.

@item package/NEWS
This is an optional file describing all user-visible changes worth
mentioning.  As this file increases on size, old entries can be moved
into @file{package/ONEWS}.

@item package/ONEWS
This is an optional file describing old entries from the @file{NEWS} file.

@cindex PKG_ADD
@anchor{XREFPKG_ADD}
@item package/PKG_ADD
An optional file that includes commands that are run when the package
is added to the users path.  Note that @w{@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 @w{@code{PKG_ADD}}
directives.

@cindex PKG_DEL
@anchor{XREFPKG_DEL}
@item package/PKG_DEL
An optional file that includes commands that are run when the package
is removed from the users path.  Note that @w{@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 @w{@code{PKG_DEL}}
directives.

@item package/pre_install.m
This is an optional function that is run prior to the installation of a
package.  This function is called with a single argument, a struct with
fields names after the data in the @file{DESCRIPTION}, and the paths where
the package functions will be installed.

@item package/post_install.m
This is an optional function that is run after the installation of a
package.  This function is called with a single argument, a struct with
fields names after the data in the @file{DESCRIPTION}, and the paths where
the package functions were installed.

@item package/on_uninstall.m
This is an optional function that is run prior to the removal of a
package.  This function is called with a single argument, a struct with
fields names after the data in the @file{DESCRIPTION}, the paths where
the package functions are installed, and whether the package is currently
loaded.
@end table

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

@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
@file{./configure} in this directory if this script exists, and will
then call @code{make} if a file @file{Makefile} exists in this
directory.  @code{make install} will however not be called.  The
environment variables @env{MKOCTFILE}, @w{@env{OCTAVE_CONFIG}}, and
@env{OCTAVE} will be set to the full paths of the programs
@code{mkoctfile}, @code{octave-config}, and @code{octave}, respectively,
of the correct version when @code{configure} and @code{make} are
called.  If a file called @code{FILES} exists 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, @file{src/*.m} and
@file{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 @w{@env{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::
* Missing Components::
@end menu

@node The DESCRIPTION File
@subsection The DESCRIPTION File

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

@itemize
@item
Lines starting with @samp{#} 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 @file{DESCRIPTION} file

@example
@group
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: GPLv3+
@end group
@end example

The package manager currently recognizes the following keywords

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

@item Version
Version of the package.  A package version must be 3 numbers separated
by dots.

@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 @file{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 @file{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 follow 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 follow 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
@file{DESCRIPTION} file for their own purposes.  One further detail to
aid the packager is that the @code{SystemRequirements} and
@code{BuildRequires} keywords can have a 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 @file{INDEX} file provides a categorical view of the
functions in the package.  This file has a very simple format

@itemize
@item Lines beginning with @samp{#} 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 the last mentioned category.
@end itemize

@noindent
The format can be summarized with the following example:

@example
@group
# A comment
toolbox >> Toolbox name
Category Name 1
 function1 function2 function3
 function4
Category Name 2
 function2 function5
@end group
@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
pointing 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
@group
$TSA = see <a href="link_to_spctools">SPC Tools</a>
arcov = $TSA <code>armcv</code>
@end group
@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 @w{@code{PKG_ADD}} or @w{@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 @w{@code{PKG_ADD}} or @w{@code{PKG_DEL}} directive they will be
added to either the @w{@code{PKG_ADD}} or @w{@code{PKG_DEL}} files.

In @code{m}-files a @w{@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 @w{@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 @w{@code{PKG_ADD}} file.
@w{@code{PKG_DEL}} directives work in the same way, except the
@w{@code{PKG_ADD}} keyword is replaced with @w{@code{PKG_DEL}} and the commands
get added to the @w{@code{PKG_DEL}} file.

@node Missing Components
@subsection Missing Components

If a package relies on a component, such as another Octave package, that may
not be present it may be useful to install a function which informs users what
to do when a particular component is missing.  The function must be written by
the package maintainer and registered with Octave using
@code{missing_component_hook}.

@c missing_component_hook libinterp/corefcn/variables.cc
@anchor{XREFmissing_component_hook}
@deftypefn  {Built-in Function} {@var{val} =} missing_component_hook ()
@deftypefnx {Built-in Function} {@var{old_val} =} missing_component_hook (@var{new_val})
@deftypefnx {Built-in Function} {} missing_component_hook (@var{new_val}, "local")
Query or set the internal variable that specifies the function to call when
a component of Octave is missing.  This can be useful for packagers that
may split the Octave installation into multiple sub-packages, for example,
to provide a hint to users for how to install the missing components.

When called from inside a function with the @qcode{"local"} option, the
variable is changed locally for the function and any subroutines it calls.  
The original variable value is restored when exiting the function.

The hook function is expected to be of the form

@example
@var{fcn} (@var{component})
@end example

Octave will call @var{fcn} with the name of the function that requires the
component and a string describing the missing component.  The hook function
should return an error message to be displayed.
@seealso{@ref{XREFmissing_function_hook,,missing_function_hook}}
@end deftypefn

