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

@c Copyright (C) 2007-2026 The Octave Project Developers
@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
@c the Free Software Foundation, either version 3 of the License, or
@c (at your option) any later version.
@c
@c Octave is distributed in the hope that it will be useful, but
@c WITHOUT ANY WARRANTY; without even the implied warranty of
@c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
@c GNU General Public License 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 <https://www.gnu.org/licenses/>.

@node Packages
@chapter Packages

Since Octave is Free Software users are encouraged to share their
programs with others.  To aid this sharing Octave supports the
installation of extra packages maintained by the Octave community at
@url{https://packages.octave.org}.

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

@findex pkg
@node Background Information
@section Background Information

Packages can be installed globally (i.e., for all users of the system) or
locally (i.e., for the current user only).

Global packages are installed by default in a system-wide location.  This is
usually a subdirectory of the folder where Octave itself is installed.
Therefore, Octave needs write access to this folder to install global packages,
which is usually only available when Octave is run with administrative
privileges, such as when run as root (or superuser) on Unix-like systems, or
run with elevated privileges ("Run as administrator") on Windows.

In contrast, local packages are installed by default in the user's home
directory (or user profile on Windows) and are only available to that specific
user.  Usually, they can be installed without administrative privileges.

When Octave is running with administrative privileges, @code{pkg} will install
packages to the global package location by default.  Otherwise, packages will
be installed to the local location by default.  The user can override this
default installation location with optional arguments (@option{-local} or
@option{-global}) as described below.  The currently used default package
installation location can be queried with @code{pkg prefix}.

For global and local packages, there are separate databases holding the
information about the installed packages.  If some package is installed
globally as well as locally, the local installation takes precedence over
("shadows") the global one.  Which (global or local) package installation is
used can also be manipulated by using prefixes and/or using the
@samp{local_list} input argument.  Using these mechanisms, several different
releases of the same package can be installed side by side as well (but cannot
be loaded simultaneously).

Packages might depend on external software and/or other packages.  To be able
to install such packages, these dependencies should be installed beforehand.
A package that depends on other package(s) can still be installed using the
@option{-nodeps} flag.  The effects of unsatisfied dependencies on external
software---like libraries---depends on the individual package.

Packages must be loaded before they can be used.  When loading a package,
Octave performs the following tasks:

@enumerate
@item
If the package depends on other packages (and @code{pkg load} is called without
the @option{-nodeps} option), the package is not loaded immediately.  Instead,
those dependencies are loaded first (recursively if needed).

@item
When all dependencies are satisfied, the package's subdirectories are added to
the search path.
@end enumerate

This load order leads to functions that are provided by dependencies being
potentially shadowed by functions of the same name that are provided by
top-level packages.

Each time, a package is added to the search path, initialization script(s) for
the package are automatically executed if they are provided by the package.

@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 a warning or error occurred during installation it
will be reported.  It is possible to install several packages at once
by writing several package file names 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, 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 a warning or 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}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {} pkg @var{command}
@deftypefnx {} {} pkg @var{command} @var{pkg_name}
@deftypefnx {} {} pkg @var{command} @var{pkg_name1} @var{pkg_name2} @dots{}
@deftypefnx {} {} pkg @var{command} @var{option1} @dots{} @var{pkg_name1} @dots{}
@deftypefnx {} {[@var{out1}, @dots{}] =} pkg (@var{command}, @dots{})
Manage or query packages (groups of add-on functions) for Octave.

Depending on the value of @var{command} and on the number of requested
return arguments, @code{pkg} can be used to perform several tasks.
Possible values for @var{command} are:

@table @samp

@item search
Search for packages having the specified search terms in the Octave Packages
index.  This may require an internet connection and the cURL library.

@example
pkg search foo bar baz
@end example

@noindent
shows packages whose descriptions contain all the search terms.

Search terms are case-insensitive and can be regular expressions as well.
For example,

@example
pkg search "[aeiou]@{4,@}"
@end example

@noindent
shows all packages whose descriptions have four or more consecutive vowels.

The option @option{-all} as in

@example
pkg search -all
@end example

@noindent
shows @emph{all} packages available on the Octave Packages index (not only
those that can be installed with the @command{pkg} command).

By default, the Octave Packages index is downloaded only once per Octave
session in order to improve performance and to reduce the load on the index
server during repeated searches.  An update of the index can be enforced
with the option @option{-refresh}:

@example
pkg search -all -refresh foo
@end example

If an output variable is provided, as in

@example
mypackages = pkg ("search", "foo")
@end example

@noindent
then @code{pkg search} returns only those package names matching the search
term(s) @emph{and} which can be installed with @code{pkg install}.

@item install
Install named packages.  For example, each of the following commands:

@example
@group
pkg install pkgname
pkg install 'pkgname-1.0.0.tar.gz'
pkg install 'https://somewebsite.org/pkgname-1.0.0.tar.gz'
@end group
@end example

@noindent
might install the package @code{pkgname}.  The sequence for the resolution
of the arguments after @code{pkg install} is:

@enumerate
@item
If @code{pkgname} is a local file, Octave installs it.

@item
Otherwise, if @code{pkgname} resembles a URL, Octave downloads and
installs it.

@item
Otherwise, Octave queries the Octave Packages index online for a package
named @code{pkgname}, and if found, downloads and installs its latest
version.  If the Octave Packages index cannot be reached, a locally cached
version of the index might be used.  The Octave Packages index is only
downloaded once per Octave session (unless an index refresh is requested
with the option @option{-refresh}).
@end enumerate

Online access requires an internet connection and the cURL library.

@noindent
@emph{No support}: the GNU Octave community is not responsible for any
installed packages.  For support or for reporting bugs, you need to contact
the maintainers of the installed package directly (run @code{pkg describe}
on the package to get information).

The following options are accepted for @code{pkg install}:

@table @code
@item -nodeps
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 -local
A local installation (package available only to current user) is forced,
even if Octave is being run with administrative privileges.

@item -global
Force a global installation (package available to all users), even if
Octave is not being run with administrative privileges.  The user must have
write access to the global package store.

@item -verbose
Print the output of all commands as they are performed.

@item -refresh
Force an update of the cached package database from the online index.  By
default, Octave tries to download the Octave Packages index only once per
Octave session.  This option forces refreshing the index even if it was
already downloaded in the current Octave session.  The option
@option{-refresh} applies to @code{install}, @code{search}, and
@code{update} commands.

@item -forge
The option @option{-forge} forces an installation of a package from the
Octave Packages index.  It cannot be used to install packages from a URL or
a local file.  It implies @option{-refresh}.
@end table

If the package tarball contains a @file{configure} script, it is run during
the installation of the package.  If it contains a @file{Makefile}, the
command @command{make} is used by default.  It is possible to override the
default command with the environment variable @env{MAKE}.  Some Octave
packages might require GNU @command{make} which may be present under a
different name such as @command{gmake}.

@item update
Check installed Octave packages against the latest version on the Octave
Packages index and update any outdated items.  Updated packages are
installed either globally or locally depending on whether Octave is running
with elevated privileges.  This requires an internet connection and the cURL
library.

Options for the install command and the names of individual packages to be
checked for updates may be specified as a list following the update command.
If the option @option{-local} or @option{-global} is specified,
@code{pkg update} limits the update check to the local or global installed
packages, and installs updates in that same context.  For example,

Update all packages:

@example
pkg update
@end example

Update all local packages:

@example
pkg update -local
@end example

Update certain packages, ignore dependencies, max verbosity:

@example
pkg update -verbose -nodeps image signal geometry
@end example

@noindent
Updates for multiple packages are sorted alphabetically and not checked
for dependencies affected by installation order.  If a dependency order
related @code{pkg update} failure occurs, use @code{pkg update -nodeps} to
ignore dependencies, or @code{pkg install <package_name>} to update
individual packages manually.

@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 is issued.  The package
removal can be forced by using the @option{-nodeps} option.

Depending on whether Octave is being run with administrative privileges
only global or local packages are removed by default.  See @option{-global}
or @option{-local} to override that default behavior.

@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.

Note: When loading a package, @code{pkg} automatically tries to load any
unloaded dependencies as well, unless the @option{-nodeps} flag has been
specified.  For example,

@example
pkg load signal
@end example

@noindent
adds the @code{signal} package and also tries to load its dependency: the
@code{control} package.  Be aware that use of the @option{-nodeps} option
can adversely affect package functionality.

@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.  Trying to
unload a package that other loaded packages still depend on causes an error;
no packages are unloaded in this case.  A package can be forcibly unloaded
with the @option{-nodeps} flag, at the risk of breaking dependent packages
that are still loaded.

@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
(local packages), and those which were installed by the system administrator
(global packages).

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

The option @option{-forge} lists all packages available on the Octave
Packages index that can be installed with the @code{pkg} command.  This
requires an internet connection and the cURL library.  This also updates the
locally cached file of the Octave Packages index.  Calling

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

@noindent
is identical to calling

@example
octave_packages = pkg ("search", "-refresh", "-all")
@end example

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

@example
pkg describe -verbose
@end example

@noindent
describes all installed packages and the functions they provide.

The result can be limited to a set of packages:

@example
@group
## describe control and signal packages
pkg describe control signal
@end group
@end example

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} takes 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 are installed in this directory.

Giving an output argument returns the current installation prefix.
For example:

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

The location in which to install the architecture dependent files can be
independently specified with an additional 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 typically available
only to the current user.  For example:

@example
pkg local_list ~/.octave_packages
@end example

Get the current value of local_list with

@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 typically
available to all users.  For example:

@smallexample
pkg global_list /usr/share/octave/site/api-v59/octave_packages
@end smallexample

Get the current value of global_list with

@example
pkg global_list
@end example

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

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

@noindent
where @code{builddir} is a directory where the binary packages are built.
The options @option{-verbose} and @option{-nodeps} are respected, while
all other options are ignored.

@item rebuild
Rebuild the package database from the installed global and local packages.
This can be used in cases where the package database has been corrupted.

@item test
Perform the built-in self tests contained in all functions provided by
the named packages.  For example:

@example
pkg test image
@end example

@end table
@xseealso{@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

It is possible to make both per-user (local) and system-wide (global)
installations of a package.  If the user performing the installation is
@code{root} (or Administrator with elevated privileges on Windows), the
packages by default install in a system-wide directory that defaults to
@file{@var{OCTAVE_HOME}/share/octave/packages/}.  If the user is not
@code{root} (or Octave is running without elevated privileges),
packages are installed locally.  The default installation directory for
local packages is
@file{@var{user_data_dir}/octave/@var{OCTAVE_API_VERSION}/packages}.
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

The package manager stores some information about the installed
packages in configuration files.  For per-user (local) packages, this
information is stored in the file
@file{@var{user_config_dir}/octave/@var{OCTAVE_API_VERSION}/octave_packages}
by default.  For system-wide (global) installations, it is stored in
@file{@var{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.  To retain these
settings between sessions, they can be set in one of the startup files,
@pxref{Startup Files}.

@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.

If the Octave GUI is running, the optional Qt help file
@file{package/doc/pkg-name.qch} is added to the documentation browser
while loading the package.  The help file is removed from the documentation
browser when the package is unloaded.

@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 is typically digits separated by
dots but may also contain @samp{+}, @samp{-}, @samp{~}, and alphanumeric
characters (in the "C" locale).  For example, @qcode{"2.1.0+"} could indicate
a development version of a package.
@c regexp in get_description.m:is_valid_pkg_version_string
Versions are compared using @ref{XREFcompare_versions,,compare_versions}.

@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 URL to the homepage or repository related to the package.

@item Tracker
Optional URL to the bug tracker related to the package.  It is highly
encouraged that maintainers utilize a dedicated tracker for reporting issues
related to the package's functionality in order to keep Octave's bug tracker at
Savannah.org less bloated and solely for core Octave bug reports.

@item Depends
A list of other Octave packages that this package depends on.  This can include
dependencies on particular versions, with the following 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 as a comma
separated list.  This can be used to define a range of versions of a particular
package:

@example
Depends: package (>= 1.0.0), package (< 1.5.0)
@end example

@noindent
It is also possible to depend on particular versions of Octave core:

@example
Depends: octave (>= 3.8.0)
@end example

@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} autoprobe the
install dependencies from the build dependencies, and therefore a
@code{BuildRequires} dependency usually 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}
@html
<span style="display:block; margin-top:-4.5ex;">&nbsp;</span>
@end html


@deftypefn  {} {@var{val} =} missing_component_hook ()
@deftypefnx {} {@var{old_val} =} missing_component_hook (@var{new_val})
@deftypefnx {} {@var{old_val} =} 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.
@xseealso{@ref{XREFmissing_function_hook,,missing_function_hook}}
@end deftypefn

