|
6537
|
1 @c Copyright (C) 2007 S�ren Hauberg |
|
7018
|
2 @c |
|
|
3 @c This file is part of Octave. |
|
|
4 @c |
|
|
5 @c Octave is free software; you can redistribute it and/or modify it |
|
|
6 @c under the terms of the GNU General Public License as published by the |
|
|
7 @c Free Software Foundation; either version 3 of the License, or (at |
|
|
8 @c your option) any later version. |
|
|
9 @c |
|
|
10 @c Octave is distributed in the hope that it will be useful, but WITHOUT |
|
|
11 @c ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or |
|
|
12 @c FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License |
|
|
13 @c for more details. |
|
|
14 @c |
|
|
15 @c You should have received a copy of the GNU General Public License |
|
|
16 @c along with Octave; see the file COPYING. If not, see |
|
|
17 @c <http://www.gnu.org/licenses/>. |
|
6537
|
18 |
|
|
19 @node Packages |
|
|
20 @chapter Packages |
|
|
21 |
|
|
22 Since Octave is Free Software users are encouraged to share their |
|
|
23 programs amongst each other. To aid this sharing Octave supports the |
|
|
24 installation of extra packages. The `Octave-Forge' project is a |
|
|
25 community-maintained set of packages that can be downloaded and |
|
|
26 installed in Octave. At the time of writing the `Octave-Forge' project |
|
|
27 can be found on-line at @uref{http://octave.sourceforge.net}, but |
|
|
28 since the Internet is an ever-changing place this may not be true at |
|
|
29 the time of reading. Therefore it is recommended to see the Octave |
|
|
30 website for an updated reference. |
|
|
31 |
|
|
32 @menu |
|
|
33 * Installing and Removing Packages:: |
|
|
34 * Using Packages:: |
|
|
35 * Administrating Packages:: |
|
|
36 * Creating Packages:: |
|
|
37 @end menu |
|
|
38 |
|
6538
|
39 @findex pkg |
|
6537
|
40 @node Installing and Removing Packages |
|
|
41 @section Installing and Removing Packages |
|
|
42 |
|
|
43 Assuming a package is available in the file @code{image-1.0.0.tar.gz} |
|
|
44 it can be installed from the Octave prompt by writing |
|
|
45 |
|
|
46 @example |
|
|
47 pkg install image-1.0.0.tar.gz |
|
|
48 @end example |
|
|
49 |
|
|
50 @noindent |
|
|
51 If the package is installed successfully nothing will be printed on |
|
|
52 the prompt, but if an error occurred during installation it will be |
|
|
53 reported. It is possible to install several packages at once by |
|
|
54 writing several package files after the @code{pkg install} command. |
|
|
55 If a different version of the package is already installed it will |
|
|
56 be removed prior to installing the new package. This makes it easy to |
|
|
57 upgrade and downgrade the version of a package, but makes it |
|
|
58 impossible to have several versions of the same package installed at |
|
|
59 once. |
|
|
60 |
|
|
61 To see which packages are installed type |
|
|
62 |
|
|
63 @example |
|
|
64 @group |
|
|
65 pkg list |
|
7031
|
66 @print{} Package Name | Version | Installation directory |
|
|
67 @print{} --------------+---------+----------------------- |
|
|
68 @print{} image *| 1.0.0 | /home/jwe/octave/image-1.0.0 |
|
6537
|
69 @end group |
|
|
70 @end example |
|
|
71 |
|
|
72 @noindent |
|
|
73 In this case only version 1.0.0 of the @code{image} package is |
|
6616
|
74 installed. The '*' character next to the package name shows that the |
|
|
75 image package is loaded and ready for use. |
|
6537
|
76 |
|
|
77 It is possible to remove a package from the system using the |
|
|
78 @code{pkg uninstall} command like this |
|
|
79 |
|
|
80 @example |
|
|
81 pkg uninstall image |
|
|
82 @end example |
|
|
83 |
|
|
84 @noindent |
|
|
85 If the package is removed successfully nothing will be printed in the |
|
|
86 prompt, but if an error occurred it will be reported. It should be |
|
|
87 noted that the package file used for installation is not needed for |
|
|
88 removal, and that only the package name as reported by @code{pkg list} |
|
|
89 should be used when removing a package. It is possible to remove |
|
|
90 several packages at once by writing several package names after the |
|
|
91 @code{pkg uninstall} command. |
|
|
92 |
|
|
93 To minimize the amount of code duplication between packages it is |
|
|
94 possible that one package depends on another one. If a package |
|
|
95 depends on another, it will check if that package is installed |
|
|
96 during installation. If it is not, an error will be reported and |
|
|
97 the package will not be installed. This behaviour can be disabled |
|
|
98 by passing the @code{-nodeps} flag to the @code{pkg install} |
|
|
99 command |
|
|
100 |
|
|
101 @example |
|
|
102 pkg install -nodeps my_package_with_dependencies.tar.gz |
|
|
103 @end example |
|
|
104 |
|
|
105 @noindent |
|
|
106 Since the installed package expects its dependencies to be installed |
|
|
107 it may not function correctly. Because of this it is not recommended |
|
|
108 to disable dependency checking. |
|
|
109 |
|
|
110 @node Using Packages |
|
|
111 @section Using Packages |
|
|
112 |
|
|
113 By default installed packages are available from the Octave prompt, |
|
|
114 but it is possible to control this using the @code{pkg load} and |
|
|
115 @code{pkg unload} commands. The functions from a package can be |
|
|
116 removed from the Octave path by typing |
|
|
117 |
|
|
118 @example |
|
|
119 pkg unload package_name |
|
|
120 @end example |
|
|
121 |
|
|
122 @noindent |
|
|
123 where @code{package_name} is the name of the package to be removed |
|
|
124 from the path. |
|
|
125 |
|
|
126 In much the same way a package can be added to the Octave path by |
|
|
127 typing |
|
|
128 |
|
|
129 @example |
|
|
130 pkg load package_name |
|
|
131 @end example |
|
|
132 |
|
|
133 @node Administrating Packages |
|
|
134 @section Administrating Packages |
|
|
135 |
|
|
136 On UNIX-like systems it is possible to make both per-user and |
|
|
137 system-wide installations of a package. If the user performing the |
|
|
138 installation is @code{root} the packages will be installed in a |
|
|
139 system-wide directory that defaults to |
|
|
140 @code{OCTAVE_HOME/share/octave/packages/}. If the user is not |
|
|
141 @code{root} the default installation directory is |
|
|
142 @code{~/octave/}. Packages will be installed in a subdirectory of the |
|
|
143 installation directory that will be named after the package. It is |
|
|
144 possible to change the installation directory by using the |
|
|
145 @code{pkg prefix} command |
|
|
146 |
|
|
147 @example |
|
|
148 pkg prefix new_installation_directory |
|
|
149 @end example |
|
|
150 |
|
|
151 @noindent |
|
|
152 The current installation directory can be retrieved by typing |
|
|
153 |
|
|
154 @example |
|
|
155 current_installation_directory = pkg prefix |
|
|
156 @end example |
|
|
157 |
|
|
158 To function properly the package manager needs to keep some |
|
|
159 information about the installed packages. For per-user packages this |
|
|
160 information is by default stored in the file @code{~/.octave_packages} |
|
|
161 and for system-wide installations it is stored in |
|
|
162 @code{OCTAVE_HOME/share/octave/octave_packages}. The path to the |
|
|
163 per-user file can be changed with the @code{pkg local_list} command |
|
|
164 |
|
|
165 @example |
|
|
166 pkg local_list /path/to/new_file |
|
|
167 @end example |
|
|
168 |
|
|
169 @noindent |
|
|
170 For system-wide installations this can be changed in the same way |
|
|
171 using the @code{pkg global_list} command. If these commands are |
|
|
172 called without a new path, the current path will be returned. |
|
|
173 |
|
|
174 @node Creating Packages |
|
|
175 @section Creating Packages |
|
|
176 |
|
|
177 Internally a package is simply a gzipped tar file that contains a |
|
|
178 top level directory of any given name. This directory will in the |
|
|
179 following be referred to as @code{package} and may contain the |
|
|
180 following files |
|
|
181 |
|
|
182 @noindent |
|
|
183 @table @code |
|
|
184 @item package/DESCRIPTION |
|
|
185 This is a required file containing information about the package. |
|
|
186 @xref{The DESCRIPTION File}, for details on this file. |
|
|
187 |
|
|
188 @item package/COPYING |
|
|
189 This is a required file containing the license of the package. No |
|
|
190 restrictions is made on the license in general. If however the |
|
|
191 package contains dynamically linked functions the license must be |
|
|
192 compatible with the GNU General Public License. |
|
|
193 |
|
|
194 @item package/INDEX |
|
|
195 This is an optional file describing the functions provided by the |
|
|
196 package. If this file is not given then one with be created |
|
|
197 automatically from the functions in the package and the |
|
|
198 @code{Categories} keyword in the @code{DESCRIPTION} file. |
|
|
199 @xref{The INDEX file}, for details on this file. |
|
|
200 |
|
|
201 @item package/PKG_ADD |
|
|
202 An optional file that includes commands that are run when the package |
|
|
203 is added to the users path. Note that @code{PKG_ADD} directives in the |
|
|
204 source code of the package will also be added to this file by the |
|
|
205 Octave package manager. Note that symbolic links are to be avoided in |
|
|
206 packages, as symbolic links do not exist on some file systems, and so |
|
|
207 a typical use for this file is the replacement of the symbolic link |
|
|
208 |
|
|
209 @example |
|
|
210 ln -s foo.oct bar.oct |
|
|
211 @end example |
|
|
212 |
|
|
213 @noindent |
|
|
214 with an autoload directive like |
|
|
215 |
|
|
216 @example |
|
|
217 autoload ('bar', which ('foo')); |
|
|
218 @end example |
|
|
219 |
|
|
220 @noindent |
|
|
221 @xref{PKG_ADD and PKG_DEL directives}, for details on @code{PKG_ADD} |
|
|
222 directives. |
|
|
223 |
|
|
224 @item package/PKG_DEL |
|
|
225 An optional file that includes commands that are run when the package |
|
|
226 is removed from the users path. Note that @code{PKG_DEL} directives in |
|
|
227 the source code of the package will also be added to this file by the |
|
|
228 Octave package manager. |
|
|
229 @xref{PKG_ADD and PKG_DEL directives}, for details on @code{PKG_DEL} |
|
|
230 directives. |
|
|
231 |
|
|
232 @item package/pre_install.m |
|
|
233 This is an optional script that is run prior to the installation of a |
|
|
234 package. |
|
|
235 |
|
|
236 @item package/post_install.m |
|
|
237 This is an optional script that is run after the installation of a |
|
|
238 package. |
|
|
239 |
|
|
240 @item package/on_uninstall.m |
|
|
241 This is an optional script that is run prior to the removal of a |
|
|
242 package. |
|
|
243 @end table |
|
|
244 |
|
|
245 Besides the above mentioned files, a package can also contain on or |
|
|
246 more of the following directories |
|
|
247 |
|
|
248 @noindent |
|
|
249 @table @code |
|
|
250 @item package/inst |
|
|
251 An optional directory containing any files that are directly installed |
|
|
252 by the package. Typically this will include any @code{m}-files. |
|
|
253 |
|
|
254 @item package/src |
|
|
255 An optional directory containing code that must be built prior to the |
|
|
256 packages installation. The Octave package manager will execute |
|
|
257 @code{./configure} in this directory if this script exists, and will |
|
|
258 then call @code{make} if a file @code{Makefile} exists in this |
|
|
259 directory. @code{make install} will however not be called. If a file |
|
|
260 called @code{FILES} exist all files listed there will be copied to the |
|
|
261 @code{inst} directory, so they also will be installed. If the |
|
|
262 @code{FILES} file doesn't exist, @code{src/*.m} and @code{src/*.oct} |
|
|
263 will be copied to the @code{inst} directory. |
|
|
264 |
|
|
265 @item package/doc |
|
|
266 An optional directory containing documentation for the package. The |
|
|
267 files in this directory will be directly installed in a sub-directory |
|
|
268 of the installed package for future reference. |
|
|
269 |
|
|
270 @item package/bin |
|
|
271 An optional directory containing files that will be added to the |
|
|
272 Octave @code{EXEC_PATH} when the package is loaded. This might contain |
|
|
273 external scripts, etc, called by functions within the package. |
|
|
274 @end table |
|
|
275 |
|
|
276 @menu |
|
|
277 * The DESCRIPTION File:: |
|
|
278 * The INDEX file:: |
|
|
279 * PKG_ADD and PKG_DEL directives:: |
|
|
280 @end menu |
|
|
281 |
|
|
282 @node The DESCRIPTION File |
|
|
283 @subsection The DESCRIPTION File |
|
|
284 |
|
|
285 The @code{DESCRIPTION} file contains various information about the |
|
|
286 package, such as it's name, author, and version. This file has a very |
|
|
287 simple format |
|
|
288 |
|
|
289 @noindent |
|
|
290 @itemize |
|
|
291 @item |
|
|
292 Lines starting with @code{#} are comments. |
|
|
293 |
|
|
294 @item |
|
|
295 Lines starting with a blank character are continuations from the |
|
|
296 previous line. |
|
|
297 |
|
|
298 @item |
|
|
299 Everything else is of the form @code{NameOfOption: ValueOfOption}. |
|
|
300 @end itemize |
|
|
301 |
|
|
302 @noindent |
|
|
303 The following is a simple example of a @code{DESCRIPTION} file |
|
|
304 |
|
|
305 @example |
|
|
306 Name: The name of my package |
|
|
307 Version: 1.0.0 |
|
|
308 Date: 2007-18-04 |
|
|
309 Author: The name (and possibly email) of the package author. |
|
7031
|
310 Maintainer: The name (and possibly email) of the current |
|
|
311 package maintainer. |
|
6537
|
312 Title: The title of the package |
|
7031
|
313 Description: A short description of the package. If this |
|
|
314 description gets too long for one line it can continue |
|
|
315 on the next by adding a space to the beginning of the |
|
|
316 following lines. |
|
7016
|
317 License: GPL version 3 or later |
|
6537
|
318 @end example |
|
|
319 |
|
|
320 The package manager currently recognizes the following keywords |
|
|
321 |
|
|
322 @noindent |
|
|
323 @table @code |
|
|
324 @item Name |
|
|
325 Name of the package. |
|
|
326 |
|
|
327 @item Version |
|
|
328 Version of the package. |
|
|
329 |
|
|
330 @item Date |
|
|
331 Date of last update. |
|
|
332 |
|
|
333 @item Author |
|
|
334 Original author of the package. |
|
|
335 |
|
|
336 @item Maintainer |
|
|
337 Maintainer of the package. |
|
|
338 |
|
|
339 @item Title |
|
|
340 A one line description of the package. |
|
|
341 |
|
|
342 @item Description |
|
|
343 A one paragraph description of the package. |
|
|
344 |
|
|
345 @item Categories |
|
|
346 Optional keyword describing the package (if no @code{INDEX} file is |
|
|
347 given this is mandatory). |
|
|
348 |
|
|
349 @item Problems |
|
|
350 Optional list of known problems. |
|
|
351 |
|
|
352 @item Url |
|
|
353 Optional list of homepages related to the package. |
|
|
354 |
|
|
355 @item Autoload |
|
|
356 Optional field that sets the default loading behavior for the package. |
|
|
357 If set to @code{yes}, @code{true} or @code{on}, then Octave will |
|
|
358 automatically load the package when starting. Otherwise the package |
|
|
359 must be manually loaded with the pkg load command. This default |
|
|
360 behavior can be overridden when the package is installed. |
|
|
361 |
|
|
362 @item Depends |
|
|
363 A list of other Octave packages that this package depends on. This can |
|
|
364 include dependencies on particular versions, with a format |
|
|
365 |
|
|
366 @example |
|
|
367 Depends: package (>= 1.0.0) |
|
|
368 @end example |
|
|
369 |
|
|
370 @noindent |
|
|
371 Possible operators are @code{<}, @code{<=}, @code{==}, @code{>=} or |
|
|
372 @code{>}. If the part of the dependency in @code{()} is missing, any |
|
|
373 version of the package is acceptable. Multiple dependencies can be |
|
|
374 defined either as a comma separated list or on separate @code{Depends} |
|
|
375 lines. |
|
|
376 |
|
|
377 @item License |
|
7016
|
378 An optional short description of the used license (e.g. GPL version 3 |
|
6537
|
379 or newer). This is optional since the file @code{COPYING} is mandatory. |
|
|
380 |
|
|
381 @item SystemRequirements |
|
|
382 These are the external install dependencies of the package and are not |
|
|
383 checked by the package manager. This is here as a hint to the |
|
|
384 distribution packager. They follows the same conventions as the |
|
|
385 @code{Depends} keyword. |
|
|
386 |
|
|
387 @item BuildRequires |
|
|
388 These are the external build dependencies of the package and are not |
|
|
389 checked by the package manager. This is here as a hint to the |
|
|
390 distribution packager. They follows the same conventions as the |
|
|
391 @code{Depends} keyword. Note that in general, packaging systems such |
|
|
392 as @code{rpm} or @code{deb} and autoprobe the install dependencies |
|
|
393 from the build dependencies, and therefore the often a |
|
|
394 @code{BuildRequires} dependency removes the need for a |
|
|
395 @code{SystemRequirements} dependency. |
|
|
396 |
|
|
397 @end table |
|
|
398 |
|
|
399 @noindent |
|
|
400 The developer is free to add additional arguments to the |
|
|
401 @code{DESCRIPTION} file for their own purposes. One further detail to |
|
|
402 aid the packager is that the @code{SystemRequirments} and |
|
|
403 @code{BuildRequires} keywords can have distribution dependent section, |
|
|
404 and the automatic build process will use these. An example of the |
|
|
405 format of this is |
|
|
406 |
|
|
407 @example |
|
|
408 BuildRequires: libtermcap-devel [Mandriva] libtermcap2-devel |
|
|
409 @end example |
|
|
410 |
|
|
411 @noindent |
|
|
412 where the first package name will be used as a default and if the |
|
|
413 RPMs are built on a Mandriva distribution, then the second package |
|
|
414 name will be used instead. |
|
|
415 |
|
|
416 @node The INDEX file |
|
|
417 @subsection The INDEX file |
|
|
418 |
|
|
419 The optional @code{INDEX} file provides an categorical view of the |
|
|
420 functions in the package. This file has a very simple format |
|
|
421 |
|
|
422 @noindent |
|
|
423 @itemize |
|
|
424 @item Lines beginning with @code{#} are comments. |
|
|
425 |
|
|
426 @item The first non-comment line should look like this |
|
|
427 |
|
|
428 @example |
|
|
429 toolbox >> Toolbox name |
|
|
430 @end example |
|
|
431 |
|
|
432 @item Lines beginning with an alphabetical character indicates a new |
|
|
433 category of functions. |
|
|
434 |
|
|
435 @item Lines starting with a white space character indicate that the |
|
|
436 function names on the line belong to last mentioned category. |
|
|
437 @end itemize |
|
|
438 |
|
|
439 @noindent |
|
|
440 The format can be summarized with the following example |
|
|
441 |
|
|
442 @example |
|
|
443 # A comment |
|
|
444 toolbox >> Toolbox name |
|
|
445 Category Name 1 |
|
|
446 function1 function2 function3 |
|
|
447 function4 |
|
|
448 Category Name 2 |
|
7007
|
449 function2 function5 |
|
6537
|
450 @end example |
|
|
451 |
|
|
452 @node PKG_ADD and PKG_DEL directives |
|
|
453 @subsection PKG_ADD and PKG_DEL directives |
|
|
454 |
|
|
455 If the package contains files called @code{PKG_ADD} or @code{PKG_DEL} |
|
|
456 the commands in these files will be executed when the package is |
|
|
457 added or removed from the users path. In some situations such files |
|
|
458 are a bit cumbersome to maintain, so the package manager supports |
|
|
459 automatic creation of such files. If a source file in the package |
|
|
460 contains a @code{PKG_ADD} or @code{PKG_DEL} directive they will be |
|
|
461 added to either the @code{PKG_ADD} or @code{PKG_DEL} files. |
|
|
462 |
|
|
463 In @code{m}-files a @code{PKG_ADD} directive looks like this |
|
|
464 |
|
|
465 @example |
|
|
466 ## PKG_ADD: some_octave_command |
|
|
467 @end example |
|
|
468 |
|
|
469 @noindent |
|
|
470 Such lines should be added before the @code{function} keyword. |
|
|
471 In C++ files a @code{PKG_ADD} directive looks like this |
|
|
472 |
|
|
473 @example |
|
|
474 // PKG_ADD: some_octave_command |
|
|
475 @end example |
|
|
476 |
|
|
477 @noindent |
|
|
478 In both cases @code{some_octave_command} should be replaced by the |
|
|
479 command that should be placed in the @code{PKG_ADD} file. |
|
|
480 @code{PKG_DEL} directives work in the same way, except the @code{PKG_ADD} |
|
|
481 keyword is replaced with @code{PKG_DEL} and the commands get added |
|
|
482 to the @code{PKG_DEL} file. |
