GNU Octave: 36.4 Creating Packages

36.4 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 package and may contain the following files

package/DESCRIPTION

This is a required file containing information about the package. See section The DESCRIPTION File, for details on this file.

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.

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 Categories keyword in the DESCRIPTION file. See section The INDEX file, for details on this file.

package/PKG_ADD

An optional file that includes commands that are run when the package is added to the users path. Note that 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

ln -s foo.oct bar.oct

with an autoload directive like

autoload ('bar', which ('foo'));

See section PKG_ADD and PKG_DEL directives, for details on PKG_ADD directives.

package/PKG_DEL

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

package/pre_install.m

This is an optional script that is run prior to the installation of a package.

package/post_install.m

This is an optional script that is run after the installation of a package.

package/on_uninstall.m

This is an optional script that is run prior to the removal of a package.

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

package/inst: An optional directory containing any files that are directly installed by the package. Typically this will include any m-files.
package/src: An optional directory containing code that must be built prior to the packages installation. The Octave package manager will execute ./configure in this directory if this script exists, and will then call make if a file Makefile exists in this directory. make install will however not be called. If a file called FILES exist all files listed there will be copied to the inst directory, so they also will be installed. If the FILES file doesn't exist, src/*.m and src/*.oct will be copied to the inst directory.
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.
package/bin: An optional directory containing files that will be added to the Octave EXEC_PATH when the package is loaded. This might contain external scripts, etc, called by functions within the package.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

36.4.1 The DESCRIPTION File

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

Lines starting with # are comments.
Lines starting with a blank character are continuations from the previous line.
Everything else is of the form NameOfOption: ValueOfOption.

The following is a simple example of a DESCRIPTION file

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

The package manager currently recognizes the following keywords

Name

Name of the package.

Version

Version of the package.

Date

Date of last update.

Author

Original author of the package.

Maintainer

Maintainer of the package.

Title

A one line description of the package.

Description

A one paragraph description of the package.

Categories

Optional keyword describing the package (if no INDEX file is given this is mandatory).

Problems

Optional list of known problems.

Url

Optional list of homepages related to the package.

Autoload

Optional field that sets the default loading behavior for the package. If set to yes, true or 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.

Depends

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

Depends: package (>= 1.0.0)

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

License

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

SystemRequirements

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

BuildRequires

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

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

BuildRequires: libtermcap-devel [Mandriva] libtermcap2-devel

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.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

36.4.2 The INDEX file

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

Lines beginning with # are comments.
The first non-comment line should look like this
toolbox >> Toolbox name
Lines beginning with an alphabetical character indicates a new category of functions.
Lines starting with a white space character indicate that the function names on the line belong to last mentioned category.

The format can be summarized with the following example

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

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

36.4.3 PKG_ADD and PKG_DEL directives

If the package contains files called PKG_ADD or 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 PKG_ADD or PKG_DEL directive they will be added to either the PKG_ADD or PKG_DEL files.

In m-files a PKG_ADD directive looks like this

## PKG_ADD: some_octave_command

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

// PKG_ADD: some_octave_command

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

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

This document was generated on December, 26 2007 using texi2html 1.76.