1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
|
.\" $NetBSD: pkg_alternatives.8,v 1.3 2005/01/25 16:47:20 jmmv Exp $
.\"
.\" pkg_alternatives - Generic wrappers for programs with similar interfaces
.\" Copyright (c) 2005 Julio M. Merino Vidal <jmmv@NetBSD.org>
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\" notice, this list of conditions and the following disclaimer.
.\" 2. Neither the name of The NetBSD Foundation nor the names of its
.\" contributors may be used to endorse or promote products derived
.\" from this software without specific prior written permission.
.\" 3. Neither the name of author nor the names of its contributors may
.\" be used to endorse or promote products derived from this software
.\" without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd January 25, 2005
.Dt ALTERNATIVES 8
.Os
.Sh NAME
.Nm pkg_alternatives
.Nd generic wrappers for programs with similar interfaces
.Sh SYNOPSIS
.Nm
.Op Fl gsw
.Op Fl p Ar prefix
action
.Ar arg1 ... argN
.Sh DESCRIPTION
.Nm
is a tool to manage the
.Em alternatives system
provided by The NetBSD Packages Collection, also known as pkgsrc.
It creates, configures and destroys generic wrappers used to run programs
with similar interfaces.
.Pp
Consider, for example, the
.Xr vi 1
editor.
Both
.Xr nvi 1
and
.Xr vim 1
provide very similar functionality, although neither of them is named
.Sq vi .
In this situation, it may be useful to have a
.Em wrapper
in place of the generic name which points to one of the multiple
.Em alternatives
available.
.Pp
The alternatives are classified according to the package they belong to,
forming
.Em groups
of alternatives.
In other words, a concrete package contains a list of all the wrappers it
affects by providing alternatives to them.
This makes things easier to the end user and/or the administrator who has
to deal with them, as they can manually select a group (package) rather than a
bunch of wrappers.
.Pp
Wrappers are identified by its file name relative to the installation
prefix, i.e.,
.Pa @PREFIX@
if the
.Fl p
option is not used.
In the example above, the wrapper could be identified by the
.Pa bin/vi
string.
The identifier is the string used as the
.Sq wrapper
argument in all the actions that require it.
.Pp
The generic wrapper scans a list of available alternatives and tries to
execute them in order; the first one that succeeds is the one used for
that run.
This list of alternatives is read from multiple configuration files.
Each one contains a list of possible alternatives, one per line, with
optional arguments to them.
Lines starting with
.Sq #
are considered comments and are ignored.
.Pp
The following configuration files are read, in strict order, for each
wrapper (replace the
.Sq wrapper
word with the wrapper's absolute file name):
.Bl -tag -width XXXX
.It ~/.alternatives/wrapper
This is called the
.Em user configuration file
and is only read when not running as
.Sq @ROOT_USER@ .
Otherwise, tools such as
.Xr sudo 8
could be used to execute any program in the system.
This file can be freely edited by the user, either by hand or by using
the
.Sq manual
action described below.
.It @CONFDIR@/wrapper
This is called the
.Em system configuration file
and is read if found.
This file can be freely edited by the administrator, either by hand or
by using the
.Sq manual
action described below.
.It @DATADIR@/wrapper
This is called the
.Em database configuration file
and is always read.
This file must not be edited by hand; packages providing alternatives
will take care to (un)register themselves from them when (de)installed.
.El
.Ss Options
The following options are available:
.Bl -tag -width XpXprefixX
.It Fl g
Operate on groups of wrappers rather than individual files.
This is the opposite of
.Fl w
and is currently the default behavior.
Affects the behavior of all actions.
.It Fl p Ar prefix
Set installation prefix.
This affects where wrappers and their manual pages are looked for.
The prefix defaults to
.Pa @PREFIX@
if this flag is not given.
.It Fl s
Run in silent mode: no output except for errors.
.It Fl w
Operate on individual wrappers rather than on groups.
This is the opposite of
.Fl g .
Affects the behavior of all actions.
.El
.Ss Actions in group mode
The following table describes each available action and its behavior when
working in group mode.
All these actions are at a higher level than the same actions in wrapper
mode.
They always end up using the later at some point, so you should also
read the next section to be aware of the exact effect of each the command.
.Bl -tag -width XXXX
.It auto Ar package
Removes any manual configuration from each wrapper associated to the given
package.
This means that all the affected wrappers are then free to choose whichever
alternative they prefer.
.It destroy
Removes the alternative database, found in
.Pa @DBDIR@ ,
and all its associated wrappers and manual pages.
This action is intended to be used by the
.Nm
package.
.It list
Lists which of the installed packages provide alternatives.
Any of the packages shown by this command can then be fed back to the
.Sq auto
and
.Sq manual
actions.
.It manual Ar package
Manually selects all the alternatives that belong to
.Ar package
to be the default for their respective wrappers.
.It rebuild
Rebuilds the alternatives database, found in
.Pa @DBDIR@ ,
based on the contents of the package database, usually available in
.Pa @PKG_DBDIR@ .
Basically, it scans the later looking for packages with an
.Pa +ALTERNATIVES
file in them, and, for each of those, the
.Sq register
action is called with the appropriate file name.
This action is intended to be used by the
.Nm
package or in case of database corruption.
.It register Ar package wrapper alternative arguments
Registers a new
.Ar alternative
for the given
.Ar wrapper
in the specified
.Ar package .
If the package does not exist in the database, it is created.
.Pp
This action must not be used directly; packages providing alternatives
will take care to execute it at installation time.
.It status Ar package
For each wrapper that belongs to
.Ar package ,
shows which alternative will be used by it in the next run.
It also displays all available candidates for each of them.
.It unregister Ar package
Removes the
.Ar package
from the database.
All alternatives associated to it are also removed.
.Pp
This action must not be used directly; packages providing alternatives
will take care to execute it at deinstallation time.
.El
.Ss Actions in wrapper mode
The following table describes each available action and its behavior when
working in wrapper mode.
Note that these actions work at a very low level as they are used to manage
wrappers and alternative commands directly.
In most situations, you will want to use these actions in group mode.
.Bl -tag -width XXXX
.It auto Ar wrapper
Removes any manual configuration created for the given
.Ar wrapper .
That is, if running as
.Sq @ROOT_USER@ ,
the system configuration file is deleted; otherwise, the user configuration
file is removed.
The effect of this action is that the wrapper is then free to choose any
alternative it wants.
.It manual Ar wrapper alternative arguments
Manually selects the
.Ar alternative
for the given
.Ar wrapper .
If running as
.Sq @ROOT_USER@ ,
the system configuration file is modified; otherwise, the user configuration
file is changed.
The effect of this action is that the wrapper will try to use your preferred
alternatives, regardless of what is installed on the system.
.It register Ar wrapper alternative arguments
Registers a new
.Ar alternative
for the given
.Ar wrapper .
If the wrapper did not exist before, it is created.
You may optionally pass several
.Ar arguments
to the
.Ar alternative
program.
.Pp
This action should not be used directly; packages providing alternatives
will take care to execute it at installation time.
.It status Ar wrapper
Shows which alternative will be used by the
.Ar wrapper
in the next run.
It also displays all available candidates for it.
.It unregister Ar wrapper alternative
Removes the
.Ar alternative
from the given
.Ar wrapper .
If there are no more alternatives available, the wrapper is removed.
.Pp
This action should not be used directly; packages providing alternatives
will take care to execute it at deinstallation time.
.El
.Sh ENVIRONMENT
.Bl -tag -width PKG_DBDIR
.It Ev PKG_DBDIR
Location of the package database directory.
Defaults to
.Pa @PKG_DBDIR@ .
.El
.Sh FILES
.Bl -tag -width XXXX
.It Pa ~/.pkg_alternatives/
User-specific configuration directory.
.It Pa @CONFDIR@/
System-wide configuration directory.
.It Pa @DATADIR@/
System-wide configuration database.
.El
.Sh DIAGNOSTICS
.Nm
exists 0 on success and 1 if an error occurred.
.Sh SEE ALSO
.Xr pkg_add 1 ,
.Xr pkg_delete 1
.Sh HISTORY
The
.Nm
utility first appeared in pkgsrc-2005Q1.
.Pp
This utility was inspired by the alternatives system found in the Debian
operating system.
.Sh AUTHORS
.An Julio M. Merino Vidal Aq jmmv@NetBSD.org
|