Mercurial > octave

comparison scripts/pkg/pkg.m @ 30411:0fee9e910d84 stable

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
doc: Update pkg documentation related to local/global install (bug #59821). * scripts/pkg/pkg.m: Clarify global/local selection, limitations of pkg update. * doc/interpreter/package.txi: Add website URL. Add note on warnings.
author Nicholas R. Jankowski <jankowskin@asme.org>
date Tue, 11 May 2021 13:26:38 -0400
parents 2cc14e275a51
children 420608d1d370
comparison
equal deleted inserted replaced
30410:bc0de453fb6a 30411:0fee9e910d84
33 ## locally (i.e., for the current user only). 33 ## locally (i.e., for the current user only).
34 ## 34 ##
35 ## Global packages are installed by default in a system-wide location. This is 35 ## Global packages are installed by default in a system-wide location. This is
36 ## usually a subdirectory of the folder where Octave itself is installed. 36 ## usually a subdirectory of the folder where Octave itself is installed.
37 ## Therefore, Octave needs write access to this folder to install global 37 ## Therefore, Octave needs write access to this folder to install global
38 ## packages. That usually means that Octave has to run with root access (or 38 ## packages, which is usually only available when Octave is run with
39 ## "Run as administrator" on Windows) to be able to install packages globally. 39 ## administrative privileges, such as when run as root (or superuser) on
40 ## 40 ## Unix-like systems, or run with elevated privileges ("Run as administrator")
41 ## In contrast, local packages are installed by default in the user's 41 ## on Windows.
42 ## home directory (profile on Windows) and are only available to that specific 42 ##
43 ## user. Usually, they can be installed without root access (or administrative 43 ## In contrast, local packages are installed by default in the user's home
44 ## privileges). 44 ## directory (or user profile on Windows) and are only available to that
45 ## specific user. Usually, they can be installed without administrative
46 ## privileges.
47 ##
48 ## When Octave is running with administrative privileges, @code{pkg} will
49 ## install packages to the global package location by default. Otherwise,
50 ## packages will be installed to the local location by default. The user can
51 ## override this default installation location with optional arguments
52 ## (@option{-local} or @option{-global}) as described below. The currently
53 ## used default package installation location can be queried with
54 ## @code{pkg prefix}.
45 ## 55 ##
46 ## For global and local packages, there are separate databases holding the 56 ## For global and local packages, there are separate databases holding the
47 ## information about the installed packages. If some package is installed 57 ## information about the installed packages. If some package is installed
48 ## globally as well as locally, the local installation takes precedence over 58 ## globally as well as locally, the local installation takes precedence over
49 ## ("shadows") the global one. Which package installation (global or local) is 59 ## ("shadows") the global one. Which (global or local) package installation is
50 ## used can also be manipulated by using prefixes and/or using the 60 ## used can also be manipulated by using prefixes and/or using the
51 ## @samp{local_list} input argument. Using these mechanisms, several different 61 ## @samp{local_list} input argument. Using these mechanisms, several different
52 ## releases of one and the same package can be installed side by side as well 62 ## releases of the same package can be installed side by side as well (but
53 ## (but cannot be loaded simultaneously). 63 ## cannot be loaded simultaneously).
54 ## 64 ##
55 ## Packages might depend on external software and/or other packages. To be 65 ## Packages might depend on external software and/or other packages. To be
56 ## able to install such packages, these dependencies should be installed 66 ## able to install such packages, these dependencies should be installed
57 ## beforehand. A package that depends on other package(s) can still be 67 ## beforehand. A package that depends on other package(s) can still be
58 ## installed using the @option{-nodeps} flag. The effects of unsatisfied 68 ## installed using the @option{-nodeps} flag. The effects of unsatisfied
126 ## is possible to install a package even when it depends on another package 136 ## is possible to install a package even when it depends on another package
127 ## which is not installed on the system. @strong{Use this option with care.} 137 ## which is not installed on the system. @strong{Use this option with care.}
128 ## 138 ##
129 ## @item -local 139 ## @item -local
130 ## A local installation (package available only to current user) is forced, 140 ## A local installation (package available only to current user) is forced,
131 ## even if the user has system privileges. 141 ## even if Octave is being run with administrative privileges.
132 ## 142 ##
133 ## @item -global 143 ## @item -global
134 ## A global installation (package available to all users) is forced, even if 144 ## A global installation (package available to all users) is forced, even if
135 ## the user doesn't normally have system privileges. 145 ## Octave is not being run with administrative privileges. The user must have
146 ## write access to the global package store.
136 ## 147 ##
137 ## @item -forge 148 ## @item -forge
138 ## Install a package directly from the Octave Forge repository. This 149 ## Install a package directly from the Octave Forge repository. This
139 ## requires an internet connection and the cURL library. 150 ## requires an internet connection and the cURL library.
140 ## 151 ##
141 ## @emph{Security risk}: no verification of the package is performed 152 ## @emph{Security risk}: no verification of the package is performed
142 ## before the installation. There are no signature for packages, or 153 ## before the installation. There are no signatures for packages, or
143 ## checksums to confirm the correct file was downloaded. It has the 154 ## checksums to confirm the correct file was downloaded. It has the
144 ## same security issues as manually downloading the package from the 155 ## same security issues as manually downloading the package from the
145 ## Octave Forge repository and installing it. 156 ## Octave Forge repository and installing it.
146 ## 157 ##
147 ## @item -verbose 158 ## @item -verbose
149 ## they are performed. 160 ## they are performed.
150 ## @end table 161 ## @end table
151 ## 162 ##
152 ## @item update 163 ## @item update
153 ## Check installed Octave Forge packages against repository and update any 164 ## Check installed Octave Forge packages against repository and update any
154 ## outdated items. This requires an internet connection and the cURL library. 165 ## outdated items. Updated packages are installed either globally or locally
155 ## Usage: 166 ## depending on whether Octave is running with elevated privileges. This
167 ## requires an internet connection and the cURL library. Usage:
156 ## 168 ##
157 ## @example 169 ## @example
158 ## pkg update 170 ## pkg update
159 ## @end example 171 ## @end example
160 ## 172 ##
161 ## @noindent 173 ## @noindent
162 ## To update a single package use @code{pkg install -forge} 174 ## To update a single package use @code{pkg install -forge}
175 ##
176 ## @noindent
177 ## Updates for multiple packages are sorted alphabetically and not checked for
178 ## dependencies affected by installation order. If dependency order related
179 ## @code{pkg update} failures occur, use @code{pkg install -forge} to update
180 ## packages individually.
163 ## 181 ##
164 ## @item uninstall 182 ## @item uninstall
165 ## Uninstall named packages. For example, 183 ## Uninstall named packages. For example,
166 ## 184 ##
167 ## @example 185 ## @example