octave-nkf: doc/interpreter/package.txi comparison

comparison doc/interpreter/package.txi @ 6537:062bade36bf7

[project @ 2007-04-18 16:40:25 by jwe]

author	jwe
date	Wed, 18 Apr 2007 16:40:25 +0000
parents
children	e3a7611430a8

comparison

equal deleted inserted replaced

-:3c89a3f9d23e
+:062bade36bf7
+@c Copyright (C) 2007 Søren Hauberg
+@c This is part of the Octave manual.
+@c For copying conditions, see the file gpl.texi.
+@node Packages
+@chapter Packages
+Since Octave is Free Software users are encouraged to share their
+programs amongst each other. To aid this sharing Octave supports the
+installation of extra packages. The `Octave-Forge' project is a
+community-maintained set of packages that can be downloaded and
+installed in Octave. At the time of writing the `Octave-Forge' project
+can be found on-line at @uref{http://octave.sourceforge.net}, but
+since the Internet is an ever-changing place this may not be true at
+the time of reading. Therefore it is recommended to see the Octave
+website for an updated reference.
+@menu
+* Installing and Removing Packages::
+* Using Packages::
+* Administrating Packages::
+* Creating Packages::
+@end menu
+@node Installing and Removing Packages
+@section Installing and Removing Packages
+Assuming a package is available in the file @code{image-1.0.0.tar.gz}
+it can be installed from the Octave prompt by writing
+@example
+pkg install image-1.0.0.tar.gz
+@end example
+@noindent
+If the package is installed successfully nothing will be printed on
+the prompt, but if an error occurred during installation it will be
+reported. It is possible to install several packages at once by
+writing several package files after the @code{pkg install} command.
+If a different version of the package is already installed it will
+be removed prior to installing the new package. This makes it easy to
+upgrade and downgrade the version of a package, but makes it
+impossible to have several versions of the same package installed at
+once.
+To see which packages are installed type
+@example
+@group
+pkg list
+@print{} Package Name | Version | Installation directory
+@print{} -------------+---------+-----------------------
+@print{}        image |   1.0.0 | /home/jwe/octave/image-1.0.0
+@end group
+@end example
+@noindent
+In this case only version 1.0.0 of the @code{image} package is
+installed.
+It is possible to remove a package from the system using the
+@code{pkg uninstall} command like this
+@example
+pkg uninstall image
+@end example
+@noindent
+If the package is removed successfully nothing will be printed in the
+prompt, but if an error occurred it will be reported. It should be
+noted that the package file used for installation is not needed for
+removal, and that only the package name as reported by @code{pkg list}
+should be used when removing a package. It is possible to remove
+several packages at once by writing several package names after the
+@code{pkg uninstall} command.
+To minimize the amount of code duplication between packages it is
+possible that one package depends on another one. If a package
+depends on another, it will check if that package is installed
+during installation. If it is not, an error will be reported and
+the package will not be installed. This behaviour can be disabled
+by passing the @code{-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.
+@node Using Packages
+@section Using Packages
+By default installed packages are 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
+removed from the Octave path by typing
+@example
+pkg unload package_name
+@end example
+@noindent
+where @code{package_name} is the name of the package to be removed
+from the path.
+In much the same way a package can be added to the Octave path by
+typing
+@example
+pkg load package_name
+@end example
+@node Administrating Packages
+@section Administrating Packages
+On UNIX-like systems it is possible to make both per-user and
+system-wide installations of a package. If the user performing the
+installation is @code{root} the packages will be installed in a
+system-wide directory that defaults to
+@code{OCTAVE_HOME/share/octave/packages/}. If the user is not
+@code{root} the default installation directory is
+@code{~/octave/}. Packages will be installed in a subdirectory of the
+installation directory that will be named after the package. It is
+possible to change the installation directory by using the
+@code{pkg prefix} command
+@example
+pkg prefix new_installation_directory
+@end example
+@noindent
+The current installation directory can be retrieved by typing
+@example
+current_installation_directory = pkg prefix
+@end example
+To function properly the package manager needs to keep some
+information about the installed packages. For per-user packages this
+information is by default stored in the file @code{~/.octave_packages}
+and for system-wide installations it is stored in
+@code{OCTAVE_HOME/share/octave/octave_packages}. The path to the
+per-user file can be changed with the @code{pkg local_list} command
+@example
+pkg local_list /path/to/new_file
+@end example
+@noindent
+For system-wide installations this can be changed in the same way
+using the @code{pkg global_list} command. If these commands are
+called without a new path, the current path will be returned.
+@node Creating Packages
+@section Creating Packages
+Internally a package is simply a gzipped tar file that contains a
+top level directory of any given name. This directory will in the
+following be referred to as @code{package} and may contain the
+following files
+@noindent
+@table @code
+@item package/DESCRIPTION
+This is a required file containing information about the package.
+@xref{The DESCRIPTION File}, for details on this file.
+@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/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 @code{DESCRIPTION} file.
+@xref{The INDEX file}, for details on this file.
+@item package/PKG_ADD
+An optional file that includes commands that are run when the package
+is added to the users path. Note that @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 @code{PKG_ADD}
+directives.
+@item package/PKG_DEL
+An optional file that includes commands that are run when the package
+is removed from the users path. Note that @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 @code{PKG_DEL}
+directives.
+@item package/pre_install.m
+This is an optional script that is run prior to the installation of a
+package.
+@item package/post_install.m
+This is an optional script that is run after the installation of a
+package.
+@item package/on_uninstall.m
+This is an optional script that is run prior to the removal of a
+package.
+@end table
+Besides the above mentioned files, a package can also contain on or
+more of the following directories
+@noindent
+@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
+@code{./configure} in this directory if this script exists, and will
+then call @code{make} if a file @code{Makefile} exists in this
+directory. @code{make install} will however not be called. If a file
+called @code{FILES} exist 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, @code{src/*.m} and @code{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 @code{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::
+@end menu
+@node The DESCRIPTION File
+@subsection The DESCRIPTION File
+The @code{DESCRIPTION} file contains various information about the
+package, such as it's name, author, and version. This file has a very
+simple format
+@noindent
+@itemize
+@item
+Lines starting with @code{#} 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 @code{DESCRIPTION} file
+@example
+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 2 or later
+@end example
+The package manager currently recognizes the following keywords
+@noindent
+@table @code
+@item Name
+Name of the package.
+@item Version
+Version of the package.
+@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 @code{INDEX} file is
+given this is mandatory).
+@item Problems
+Optional list of known problems.
+@item Url
+Optional list of homepages related to the package.
+@item Autoload
+Optional field that sets the default loading behavior for the package.
+If set to @code{yes}, @code{true} or @code{on}, then Octave will
+automatically load the package when starting. Otherwise the package
+must be manually loaded with the pkg load command. This default
+behavior can be overridden when the package is installed.
+@item Depends
+A list of other Octave packages that this package depends on. This can
+include dependencies on particular versions, with a format
+@example
+Depends: package (>= 1.0.0)
+@end example
+@noindent
+Possible operators are @code{<}, @code{<=}, @code{==}, @code{>=} or
+@code{>}. If the part of the dependency in @code{()} is missing, any
+version of the package is acceptable. Multiple dependencies can be
+defined either as a comma separated list or on separate @code{Depends}
+lines.
+@item License
+An optional short description of the used license (e.g. GPL version 2
+or newer). This is optional since the file @code{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 follows 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 follows the same conventions as the
+@code{Depends} keyword. Note that in general, packaging systems such
+as @code{rpm} or @code{deb} and autoprobe the install dependencies
+from the build dependencies, and therefore the often a
+@code{BuildRequires} dependency removes the need for a
+@code{SystemRequirements} dependency.
+@end table
+@noindent
+The developer is free to add additional arguments to the
+@code{DESCRIPTION} file for their own purposes. One further detail to
+aid the packager is that the @code{SystemRequirments} and
+@code{BuildRequires} keywords can have 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 @code{INDEX} file provides an categorical view of the
+functions in the package. This file has a very simple format
+@noindent
+@itemize
+@item Lines beginning with @code{#} 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 last mentioned category.
+@end itemize
+@noindent
+The format can be summarized with the following example
+@example
+# A comment
+toolbox >> Toolbox name
+Category Name 1
+function1 function2 function3
+function4
+Category Name 2
+functio2 function5
+@end example
+@node PKG_ADD and PKG_DEL directives
+@subsection PKG_ADD and PKG_DEL directives
+If the package contains files called @code{PKG_ADD} or @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 @code{PKG_ADD} or @code{PKG_DEL} directive they will be
+added to either the @code{PKG_ADD} or @code{PKG_DEL} files.
+In @code{m}-files a @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 @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 @code{PKG_ADD} file.
+@code{PKG_DEL} directives work in the same way, except the @code{PKG_ADD}
+keyword is replaced with @code{PKG_DEL} and the commands get added
+to the @code{PKG_DEL} file.
+@c Perhaps we should include this line when creating info files?
+@c That way the user can still type 'doc pkg'.
+@c DOCSTRING(pkg)

Mercurial > octave-nkf

comparison doc/interpreter/package.txi @ 6537:062bade36bf7