Next: Using Packages, Up: Packages [Contents][Index]
Assuming a package is available in the file image-1.0.0.tar.gz it can be installed from the Octave prompt with the command
pkg install image-1.0.0.tar.gz
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 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
pkg list -| Package Name | Version | Installation directory -| --------------+---------+----------------------- -| image *| 1.0.0 | /home/jwe/octave/image-1.0.0
In this case, version 1.0.0 of the image
package is installed.
The '*'
character next to the package name shows that the image
package is loaded and ready for use.
It is possible to remove a package from the system using the
pkg uninstall
command like this
pkg uninstall image
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
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 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 -nodeps flag to the pkg install
command
pkg install -nodeps my_package_with_dependencies.tar.gz
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.
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, 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
(-local or -global) as described below. The currently
used default package installation location can be queried with
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 ‘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 -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:
pkg load
is called
without the -nodeps option), the package is not loaded
immediately. Instead, those dependencies are loaded first (recursively if
needed).
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 command and on the number of requested
return arguments, pkg
can be used to perform several tasks.
Possible values for command are:
Install named packages. For example,
pkg install image-1.0.0.tar.gz
installs the package found in the file image-1.0.0.tar.gz. The file containing the package can be a URL, e.g.,
pkg install 'http://somewebsite.org/image-1.0.0.tar.gz'
installs the package found in the given URL. This requires an internet connection and the cURL library.
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.
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 DESCRIPTION file of the package)
The option variable can contain options that affect the manner in which a package is installed. These options can be one or more of
-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. Use this option with care.
-local
A local installation (package available only to current user) is forced, even if Octave is being run with administrative privileges.
-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.
-forge
Install a package directly from the Octave Forge repository. This requires an internet connection and the cURL library.
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.
-verbose
The package manager will print the output of all commands as they are performed.
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 -local or -global option is specified,
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:
pkg update
Update all local packages:
pkg update -local
Update certain packages, ignore dependencies, max verbosity:
pkg update -verbose -nodeps image signal geometry
Updates for multiple packages are sorted alphabetically and not checked
for dependencies affected by installation order. If dependency order
related pkg update
failure occurs, use pkg update -nodeps
to
ignore dependencies, or pkg install -forge <package_name>
to update
individual packages manually.
Uninstall named packages. For example,
pkg uninstall image
removes the image
package from the system. If another installed
package depends on the image
package an error will be issued.
The package can be uninstalled anyway by using the -nodeps option.
Add named packages to the path. After loading a package it is possible to use the functions provided by the package. For example,
pkg load image
adds the image
package to the path.
Note: When loading a package, pkg
will automatically try to load
any unloaded dependencies as well, unless the -nodeps flag has
been specified. For example,
pkg load signal
adds the signal
package and also tries to load its dependency: the
control
package. Be aware that the functionality of package(s)
loaded will probably be impacted by use of the -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.
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 -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 -nodeps flag may not restore all functionality of the dependent packages as the required loading order may be incorrect.
Show the list of currently installed packages. For example,
pkg list
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:
pkg list image
If a single return argument is requested then pkg
returns a cell
array where each element is a structure with information on a single
package.
installed_packages = pkg ("list")
If two output arguments are requested 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.
[user_packages, system_packages] = pkg ("list")
The "-forge"
option lists packages available at the Octave Forge
repository. This requires an internet connection and the cURL library.
For example:
oct_forge_pkgs = pkg ("list", "-forge")
Show a short description of installed packages. With the option
"-verbose"
also list functions provided by the package. For
example,
pkg describe -verbose
will describe all installed packages and the functions they provide. Display can be limited to a set of packages:
## describe control and signal packages pkg describe control signal
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:
desc = pkg ("describe", "secs1d", "image")
If any of the requested packages is not installed, pkg
returns an
error, unless a second output is requested:
[desc, flag] = pkg ("describe", "secs1d", "image")
flag will take one of the values "Not installed"
,
"Loaded"
, or
"Not loaded"
for each of the named packages.
Set the installation prefix directory. For example,
pkg prefix ~/my_octave_packages
sets the installation prefix to ~/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:
pfx = pkg ("prefix")
The location in which to install the architecture dependent files can be independently specified with an addition argument. For example:
pkg prefix ~/my_octave_packages ~/my_arch_dep_pkgs
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:
pkg local_list ~/.octave_packages
It is possible to get the current value of local_list with the following
pkg local_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:
pkg global_list /usr/share/octave/octave_packages
It is possible to get the current value of global_list with the following
pkg global_list
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
pkg
. The form of the command to build a binary package is
pkg build builddir image-1.0.0.tar.gz …
where builddir
is the name of a directory where the temporary
installation will be produced and the binary packages will be found.
The options -verbose and -nodeps are respected, while
all other options are ignored.
Rebuild the package database from the installed directories. This can be used in cases where the package database has been corrupted.
Perform the built-in self tests contained in all functions provided by the named packages. For example:
pkg test image
Next: Using Packages, Up: Packages [Contents][Index]