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