Mercurial > hg > octave-lyh
changeset 6537:062bade36bf7
[project @ 2007-04-18 16:40:25 by jwe]
author | jwe |
---|---|
date | Wed, 18 Apr 2007 16:40:25 +0000 |
parents | 3c89a3f9d23e |
children | e3a7611430a8 |
files | doc/ChangeLog doc/interpreter/Makefile.in doc/interpreter/contributors.in doc/interpreter/octave.texi doc/interpreter/package.txi |
diffstat | 5 files changed, 486 insertions(+), 2 deletions(-) [+] |
line wrap: on
line diff
--- a/doc/ChangeLog +++ b/doc/ChangeLog @@ -1,3 +1,8 @@ +2007-04-18 Søren Hauberg <hauberg@gmail.com> + + * interpreter/package.texi: New file. + * octave/texi: @include it, add it to the menus. + 2007-04-18 John W. Eaton <jwe@octave.org> * interpreter/contributors.in: New file.
--- a/doc/interpreter/Makefile.in +++ b/doc/interpreter/Makefile.in @@ -42,7 +42,7 @@ expr.txi finance.txi fn-idx.txi func.txi gpl.txi \ grammar.txi image.txi install.txi intro.txi io.txi \ linalg.txi matrix.txi nonlin.txi numbers.txi \ - op-idx.txi optim.txi plot.txi poly.txi preface.txi \ + op-idx.txi optim.txi package.txi plot.txi poly.txi preface.txi \ quad.txi quaternion.txi set.txi signal.txi sparse.txi stats.txi \ stmt.txi strings.txi struct.txi system.txi \ testfun.txi tips.txi var.txi vr-idx.txi
--- a/doc/interpreter/contributors.in +++ b/doc/interpreter/contributors.in @@ -125,7 +125,6 @@ Thorsten Ohl Arno Onken Luis F. Ortiz -Luis Ortiz Scott Pakin Gabriele Pannocchia Sylvain Pelissier
--- a/doc/interpreter/octave.texi +++ b/doc/interpreter/octave.texi @@ -156,6 +156,7 @@ * Audio Processing:: * Quaternions:: * System Utilities:: +* Packages:: * Test and Demo Functions:: * Tips:: * Trouble:: If you have trouble installing Octave. @@ -468,6 +469,16 @@ * Group Database Functions:: * System Information:: +Packages + +* Installing and Removing Packages:: +* Using Packages:: +* Administrating Packages:: +* Creating Packages:: +* The DESCRIPTION File:: +* The INDEX file:: +* PKG_ADD and PKG_DEL directives:: + Test and Demo Functions * Test Functions:: @@ -553,6 +564,7 @@ @include audio.texi @include quaternion.texi @include system.texi +@include package.texi @c maybe add again later, if anyone every writes any really interesting @c fun stuff for Octave.
new file mode 100644 --- /dev/null +++ b/doc/interpreter/package.txi @@ -0,0 +1,468 @@ +@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)