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

@c Copyright (C) 2007-2024 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.  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{https://octave.sourceforge.io}, 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
@url{https://octave.org, 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 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} @var{pkg_name}
@deftypefnx {} {} pkg @var{command} @var{option} @var{pkg_name}
@deftypefnx {} {[@var{out1}, @dots{}] =} pkg (@var{command}, @dots{} )
Manage or query packages (groups of add-on functions) for Octave.

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.

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 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
file containing the package can be a URL, e.g.,

@example
pkg install 'http://somewebsite.org/image-1.0.0.tar.gz'
@end example

@noindent
installs the package found in the given URL@.  This
requires an internet connection and the cURL library.

@noindent
@emph{Security risk}: no verification of the package is performed
before the installation.  It has the same security issues as manually
downloading the package from the given URL and installing it.

@noindent
@emph{No support}: the GNU Octave community is not responsible for
packages installed from foreign sites.  For support or for
reporting bugs you need to contact the maintainers of the installed
package directly (see the @file{DESCRIPTION} file of the package)

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

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

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

@emph{Security risk}: no verification of the package is performed
before the installation.  There are no signatures for packages, or
checksums to confirm the correct file was downloaded.  It has the
same security issues as manually downloading the package from the
Octave Forge repository and installing it.

@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.  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{-local} or @option{-global} option 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 dependency order
related @code{pkg update} failure occurs, use @code{pkg update -nodeps} to
ignore dependencies, or @code{pkg install -forge <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 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.

Note: When loading a package, @code{pkg} will automatically try 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 the functionality of package(s)
loaded will probably be impacted by use of the @option{-nodeps} flag.  Even
if necessary dependencies are loaded later, the functionality of top-level
packages can still be affected because the optimal loading order may not
have been followed.

@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 will result
in an error; no packages will be unloaded in this case.  A package can
be forcibly removed with the @option{-nodeps} flag, but be aware that the
functionality of dependent packages will likely be affected.  As when
loading packages, reloading dependencies after having unloaded them with the
@option{-nodeps} flag may not restore all functionality of the dependent
packages as the required loading order may be incorrect.

@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 installed packages.  With the option
@qcode{"-verbose"} also list functions provided by the package.  For
example,

@example
pkg describe -verbose
@end example

@noindent
will describe all installed packages and the functions they provide.
Display 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} 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.

@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,
see @ref{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.

@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 list of homepages related to the package.

@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