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