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
|
.Dd January 21, 2020
.Dt BOSUN 1
.Os
.Sh NAME
.Nm bosun
.Nd manage portage roles with stow
.Sh SYNOPSIS
.Nm
.Ic add
.Ar role ...
.Nm
.Ic flush
.Nm
.Op Ic list Op Ar type
.Nm
.Ic rebuild
.Op Ar role ...
.Nm
.Ic remove
.Ar role ...
.Sh DESCRIPTION
.Nm
is a program to add, remove, and list portage roles.
.Pp
A
.Dq role
is a directory comprised of a set of portage configuration files
pertaining to a specific service, usage, et cetera.
Roles are placed into
.Em /etc/portage/stow .
.Pp
.Nm
uses
.Xr stow 8
to build a full set of portage configuration files in
.Em /etc/portage .
It does so by creating symlinks in
.Em /etc/portage
that point back to the actual files in the role directories.
.Pp
The commands are as follows:
.Bl -tag -width Ds
.It Sy add Em role ...
Activates the given roles on the system.
.It Sy flush
Deactivates all actives roles on the system.
.It Sy list Op Ar type
Lists roles of the given type.
If no type is given, list roles of the
.Dq active
type.
The types are as follows:
.Bl -tag -width Ds
.It Sy active
Lists roles that are active on the system.
.It Sy all
Lists all roles.
.It Sy available
Lists roles that are not active on the system.
.El
.It Sy rebuild Op Ar role ...
Deactivates the given roles and then activates them again.
This is used to incorporate files that have been added to an already
active role.
.Pp
If no roles are given, rebuild all active roles.
.It Sy remove Em role ...
Deactivates the given roles on the system.
.El
.Pp
If no command is given,
.Nm
will list active roles.
.Sh FILES
.Bl -tag -width Ds
.It Pa /etc/portage/stow
The base directory containing all portage roles.
.El
.Sh EXAMPLES
The following directory structure under
.Pa /etc/portage/stow
describes a simple setup of bosun with three roles,
.Em service-mail ,
.Em app-tex ,
and
.Em group-musl .
.Bd -literal -offset indent
service-mail/package.accept_keywords/20-service-mail
service-mail/package.use/20-service-mail
app-tex/sets/tex
group-musl/package.accept_keywords/02-group-musl
group-musl/repos.conf/musl.conf
group-musl/patches/net-misc/openssh/disable-utmp-in-musl.patch
.Ed
.Pp
After activating
.Em group-musl
and
.Em service-mail ,
.Pa /etc/portage
will look something like this:
.Bd -literal -offset indent
package.accept_keywords/02-group-musl@
package.accept_keywords/20-service-mail@
package.use/20-service-mail@
patches/net-misc/openssh/disable-utmp-in-musl.patch@
repos.conf/musl.conf@
.Ed
.Pp
Here, each symbolic link points to the corresponding file in
.Pa /etc/portage/stow .
.Nm
transparently merged the given roles into one structure.
After removing
.Em group-musl
and activating
.Em app-tex ,
the directory will look like this:
.Bd -literal -offset indent
package.accept_keywords/20-service-mail@
package.use/20-service-mail@
sets/tex@
.Ed
.Pp
As roles are activated or removed, the role directory stays untouched; it is
merely the symbolic links that are added or removed.
This makes it suitable to manage
.Pa /etc/portage/stow
in
.Xr git 1 .
.Pp
Suppose we add another file to the
.Em service-mail
role in a new directory
.Pa package.use .
The role is already active, but since
.Nm
cannot know that it has been changed, we need to rebuild the symbolic links:
.Bd -literal -offset indent
bosun rebuild service-mail
.Ed
.Sh SEE ALSO
.Xr portage 5 ,
.Xr stow 8
.Sh AUTHORS
.An -nosplit
.Nm
was written by
.An Wynn Wolf Arbor Aq Mt wolf@oriole.systems
|
