summaryrefslogtreecommitdiff
blob: dc26b1a0c80665a6345ee2743d825d591ffdf222 (plain)
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
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
<chapter id='config-set'>
	<title>Package Set Configuration</title>
	<sect1 id='config-set-locations'>
		<title>sets.conf locations</title>
		<para>
		There are multiple locations where portage looks for set configuration 
		files, which are usually named <filename>sets.conf</filename>. Not all 
		of these locations have to contain a sets.conf, missing files are simply 
		ignored.
		</para>
		<para>
		At first it looks for the default configuration in 
		<filename>/usr/share/portage/config</filename>.
		The default config includes sets that are expected on all systems and 
		often critical for normal operation, like <varname>world</varname>, 
		<varname>system</varname> or <varname>security</varname>.
		<!-- TODO: Add reference to currently non-existing documentation about
		set usage and default sets -->
		After that it will read repository specific configurations from 
		<envar>PORTDIR</envar> and <envar>PORTDIR_OVERLAY</envar> that might
		include definitions of sets included in the repository.
		Finally a system-specific set configuration may reside in 
		<filename>/etc/portage</filename> to either define additional sets or
		alter the default and repository sets.
		</para>
	</sect1>
	
	<sect1 id='config-set-syntax'>
		<title>sets.conf Syntax</title>
		<para>
		Unlike other Portage configuration files <filename>sets.conf</filename> 
		uses Pythons <classname>ConfigParser</classname> module, which implements
		the syntax usually found in .ini files. At its core it allows various
		named sections that each can contain any number of key-value pairs, see
		the <ulink url="http://doc.python.org/lib/module-ConfigParser.html" type="text/html">Python documentation</ulink>
		for the full details.
		</para>
		<para>
		In a <filename>sets.conf</filename> file, a section can define either a 
		single package set, or a complete class of sets. These cases are handled 
		in different ways, and will be explained in detail in the following sections.
		</para>
		<sect2 id='config-set-syntax-single'>
			<title>Single Set Configuration</title>
			<para>
			The configuration of a single set can be very simple as in most cases
			it only requires a single option <varname>class</varname> to be 
			complete <footnote><para>Technically the <varname>class</varname> option
			isn't stricly required, but it should always be used as the default 
			handler might be changed in future versions.</para></footnote>.
			That option defines which handler class should be used to 
			create the set. Other universal options available for single sets are:
			<itemizedlist>
			<listitem><varname>name</varname> (which is usually not needed as the name
			of the set is generated from the section name if <varname>name</varname>
			is missing)</listitem>
			<listitem><varname>world-candidate</varname>, which determines if
			given package should be added to the <varname>world</varname> set</listitem>
			<listitem><varname>extend</varname> to include the contents of other package sets
			</listitem>
			<listitem><varname>remove</varname> to remove the contents of other package sets
			</listitem>
			<listitem><varname>intersect</varname> to only include packages that are also 
			included in one or more other package sets</listitem>
			</itemizedlist>
			Some handler classes might require additional options for their configuration,
			these will be covered later in this chapter.
			</para>
			<para>
			Here are a few examples for single sets taken from the default 
			configuration file:
			<programlisting>
			# The classic world set
			[world]
			class = portage.sets.files.WorldSet
			world-candidate = False
			
			# The classic system set
			[system]
			class = portage.sets.profiles.PackagesSystemSet
			</programlisting>
			<!-- TODO: reference list of available set handler classes here -->
			</para>
		</sect2>
	
		<sect2 id='config-set-syntax-multi'>
			<title>Multi Set Configuration</title>
			<para>
			As configuring each single set manually could be quite annoying if 
			you want many sets with the same options Portage also allows to
			define whole classes of sets in a single section. Like with single
			sets each section still requires the <varname>class</varname> option,
			but to indicate that the section should generate multiple sets it's
			also necessary to set the <varname>multiset</varname> option to 
			<parameter>true</parameter>. The <varname>world-candidate</varname>,
			<varname>extend</varname>, <varname>remove</varname> and 
			<varname>intersect</varname> options are also supported like with 
			single sets (they'll apply to all sets generated by the section).
			</para>
			<para>
			As it doesn't make much sense to specify a single name for multiple sets
			the <varname>name</varname> option isn't available for multiset sections.
			Most handler classes will have a reasonable default for generating names,
			and usually you can (but don't have to) set the 
			<varname>name_pattern</varname> option to change the naming rules. That 
			option generally has to include a (handler-specific) placeholder that 
			will be replaced with a unique identifier (e.g. for category sets the 
			category name). As with single sets handler classes might require and/or 
			support additional options, these will be discussed later.
			</para>
			<para>
			Some examples for multiset configurations:
			<programlisting>
			# generate a set for each file in /etc/portage/sets
			# this section is also in the default configuration
			[user sets]
			class = portage.sets.files.StaticFileSet
			multiset = true
			directory = /etc/portage/sets
			
			# Generate a set for each category that includes all installed packages
			# from that category. The sets will be named &lt;category&gt;/*
			[installed category packages]
			class = portage.sets.dbapi.CategorySet
			multiset = true
			name_pattern = $category/*
			intersect = installed
			</programlisting>
			</para>
			<!-- TODO: reference list of available set handler classes here -->
		</sect2>
	</sect1>

	<sect1 id='config-set-classes'>
		<title>Available Set Handler Classes</title>
		<para>
		The following sections contain the available handler classes that can be
		used for the <varname>class</varname> option in 
		<filename>sets.conf</filename>, together with a description about required
		and optional configuration options for single and multi set configurations.
		Note that not all classes support both configuration styles.
		</para>
		
		<sect2 id='config-set-classes-StaticFileSet' xreflabel='StaticFileSet'>
		<title>portage.sets.files.StaticFileSet</title>
		<para>
		This class implements a simple file based package set. All atoms from 
		configured file are used to form the set, and currently only simple and 
		versioned atoms	are supported (no use conditionals or any-of constructs).
		For descriptive purposes the file can be accompanied by a file with the 
		same name plus a <filename>.metadata</filename> suffix which can contain
		metadata sections for description, author, location and so on. Each section
		has the form <msgtext>key: value</msgtext> where <varname>value</varname>
		can contain multiple lines. Therefore sections have to be separated by 
		blank lines. For example:
		<programlisting>
		description: This is a somewhat
		longer description than usual. So it 
		needs more than one line.
		
		homepage: http://www.foobar.org
		
		author: John Doe &lt;john@doe.com&gt;
		</programlisting>
		</para>
		
			<sect3>
			<title>Single Set Configuration</title>
			<para>
			In a single set configuration this class supports the following options:
			<itemizedlist>
			<listitem><varname>filename</varname>: Required. Specifies the path to the file
				that should be used for the package set.</listitem>
			<listitem><varname>greedy</varname>: Optional, defaults to <parameter>false</parameter>.
				Determines if atoms in the package should include all installed slots (when set to
				<parameter>true</parameter>) or if no slot expansion is wanted (when set to 
				<parameter>false</parameter>). This option only affects packages that have multiple
				slots available (e.g. <parameter>sys-kernel/gentoo-sources</parameter>).</listitem>
			</itemizedlist>
			</para>
			</sect3>

			<sect3>
			<title>Multi Set Configuration</title>
			<para>
			In a multi set configuration this class supports the following options:
			<itemizedlist>
			<listitem><varname>directory</varname>: Optional, defaults to 
				<filename>/etc/portage/sets</filename>. Specifies the path to a directory
				containing package set files. For each file (excluding metadata files) in 
				that location a separate package set is created.
			</listitem>
			<listitem><varname>name_pattern</varname>: Optional, defaults to 
				<parameter>$name</parameter>. This describes the naming pattern
				to be used for creating the sets. It must contain either 
				<parameter>$name</parameter> or <parameter>${name}</parameter>, which 
				will be replaced by the filename (without any directory components).
			</listitem>
			</itemizedlist>
			</para>
			</sect3>
		</sect2>
		
		<sect2 id='config-set-classes-ConfigFileSet'>
		<title>portage.sets.files.ConfigFileSet</title>
		<para>
		Similar to <classname>StaticFileSet</classname>, but uses Portage configuration files.
		Namely it can work with <filename>package.use</filename>, 
		<filename>package.keywords</filename>, <filename>package.mask</filename>
		and <filename>package.unmask</filename>. It does not support 
		<filename>.metadata</filename> files, but ignores the extra data (like 
		USE flags or keywords) typically found in those files.
		</para>
		
			<sect3>
			<title>Single Set Configuration</title>
			<para>
			In a single set configuration this class supports the following options:
			<itemizedlist>
			<listitem><varname>filename</varname>: See 
				<xref linkend='config-set-classes-StaticFileSet'>StaticFileSet</xref>
			</listitem>
			</itemizedlist>
			</para>
			</sect3>
			
			<sect3>
			<title>Multi Set Configuration</title>
			<para>
			In a multi set configuration this class supports the following options:
			<itemizedlist>
			<listitem><varname>directory</varname>: Optional, defaults to 
				<filename>/etc/portage</filename>. Specifies the path to a directory
				containing one or more of the following portage configuration files:
				<filename>package.use</filename>, <filename>package.keywords</filename>,
				<filename>package.mask</filename> or <filename>package.unmask</filename>.
				No other files in that directory will be used.
			</listitem>
			<listitem><varname>name_pattern</varname>: Optional, defaults to 
				<parameter>package_$suffix</parameter>. This describes the naming 
				pattern to be used for creating the sets. It must contain either
				<parameter>$suffix</parameter> or <parameter>${suffix}</parameter>, 
				which will be replaced by the file suffix (e.g. 
				<parameter>use</parameter> or <parameter>mask</parameter>).
			</listitem>
			</itemizedlist>
			</para>
			</sect3>
		</sect2>
		
		<sect2 id='config-set-classes-WorldSet'>
		<title>portage.sets.files.WorldSet</title>
		<para>
		A minor variation of <classname>StaticFileSet</classname>, mainly for implementation 
		reasons. It should never be used in user configurations as it's already configured
		by default, doesn't support any options and will eventually be removed in a future version.
		</para>
		
			<sect3>
			<title>Single Set Configuraton</title>
			<para>
			This class doesn't support any extra options.
			</para>
			</sect3>
		</sect2>
		
		<sect2 id='config-set-classes-PackagesSystemSet'>
		<title>portage.sets.profiles.PackagesSystemSet</title>
		<para>
		This class implements the classic <parameter>system</parameter> set, based on the 
		<filename>packages</filename> files in the profile.
		<!-- TODO: Add reference to profile documentation regarding "packages" -->
		There is no reason to use this in a user configuration as it is already
		confgured by default and doesn't support any options.
		</para>
		
			<sect3>
			<title>Single Set Configuration</title>
			<para>
			This class doesn't support any extra options.
			</para>
			</sect3>
		</sect2>
		
		<sect2 id='config-set-classes-SecuritySet' xreflabel='SecuritySet'>
		<title>portage.sets.security.SecuritySet</title>
		<para>
		The set created by this class contains all atoms that need to be installed 
		to apply all GLSAs in the ebuild repository, no matter if they are already 
		applied or no (it's equivalent to the <parameter>all</parameter> target of
		glsa-check). Generally it should be avoided in configurations in favor of
		<classname>NewAffectedSet</classname> described below.
		</para>

			<sect3>
			<title>Single Set Configuration</title>
			<para>
			In single set configurations this class supports the following options:
			<itemizedlist>
			<listitem><varname>use_emerge_resolver</varname>: Optional, defaults to 
				<parameter>false</parameter>. This option determines which resolver 
				strategy should be used for the set atoms. When set to 
				<parameter>true</parameter>, it	will use the default emerge algorithm 
				and use the highest visible version that matches the GLSA. If set 
				to <parameter>false</parameter> it will use the default glsa-check 
				algorithm and use the lowest version that matches the GLSA and is 
				higher than the currently installed version (least change policy).
			</listitem>
			</itemizedlist>
			</para>
			</sect3>
		</sect2>
		
		<sect2 id='config-set-classes-NewGlsaSet'>
		<title>portage.sets.security.NewGlsaSet</title>
		<para>
		Like <xref linkend='config-set-classes-SecuritySet'>SecuritySet</xref>,
		but ignores all GLSAs that were already applied or injected previously.
		</para>

			<sect3>
			<title>Single Set Configuration</title>
			<para>
			In single set configurations this class supports the following options:
			<itemizedlist>
			<listitem><varname>use_emerge_resolver</varname>: See
				<xref linkend='config-set-classes-SecuritySet'>SecuritySet</xref>
			</listitem>
			</itemizedlist>
			</para>
			</sect3>
		</sect2>
		
		<sect2 id='config-set-classes-NewAffectedSet'>
		<title>portage.sets.security.NewAffectedSet</title>
		<para>
		Like <xref linkend='config-set-classes-SecuritySet'>SecuritySet</xref>,
		but ignores all GLSAs that were already applied or injected previously,
		and all GLSAs that don't affect the current system. Practically there
		should be no difference to <classname>NewGlsaSet</classname> though.
		</para>

			<sect3>
			<title>Single Set Configuration</title>
			<para>
			In single set configurations this class supports the following options:
			<itemizedlist>
			<listitem><varname>use_emerge_resolver</varname>: See
				<xref linkend='config-set-classes-SecuritySet'>SecuritySet</xref>
			</listitem>
			</itemizedlist>
			</para>
			</sect3>
		</sect2>
		
		<sect2 id='config-set-classes-AffectedSet'>
		<title>portage.sets.security.AffectedSet</title>
		<para>
		Like <xref linkend='config-set-classes-SecuritySet'>SecuritySet</xref>,
		but ignores all GLSAs that don't affect the current system. Practically
		there should be no difference to <classname>SecuritySet</classname> though.
		</para>

			<sect3>
			<title>Single Set Configuration</title>
			<para>
			In single set configurations this class supports the following options:
			<itemizedlist>
			<listitem><varname>use_emerge_resolver</varname>: See
				<xref linkend='config-set-classes-SecuritySet'>SecuritySet</xref>
			</listitem>
			</itemizedlist>
			</para>
			</sect3>
		</sect2>
		
		<sect2 id='config-set-classes-CommandOutputSet'>
		<title>portage.sets.shell.CommandOutputSet</title>
		<para>
		As the name says, this class creates a package set based on the output of
		a given command. The command is run once when the set is accessed 
		for the first time during the current session.
		</para>

			<sect3>
			<title>Single Set Configuration</title>
			<para>
			In single set configurations this class supports the following options:
			<itemizedlist>
			<listitem><varname>command</varname>: Required. Specifies the command
				that should be executed to generate the package set. It should 
				output a newline separated list of simple and/or versioned atoms
				on stdout.
			</listitem>
			</itemizedlist>
			</para>
			</sect3>
		</sect2>
		
		<sect2 id='config-set-classes-AgeSet'>
		<title>portage.sets.dbapi.AgeSet</title>
		<para>
		Package sets created by this class will include installed packages that
		have been installed before / after a given date.
		</para>
			
			<sect3>
			<title>Single Set Configuration</title>
			<para>
			In single set configurations this class supports the following options:
			<itemizedlist>
			<listitem><varname>age</varname>: Optional, defaults to 7. Specifies 
				the number of days passed since installation to use as cut-off point.
			</listitem>
			<listitem><varname>mode</varname>: Optional, defaults to "older". Must 
				be either "older" or "newer" to select packages installed either 
				before resp. after the cut-off-date given by <varname>age</varname>.
				E.g. the defaults will select all installed packages that have been 
				installed more than one week ago.
			</listitem>
			</itemizedlist>
			</para>
			</sect3>
		</sect2>
		
		<sect2 id='config-set-classes-CategorySet'>
		<title>portage.sets.dbapi.CategorySet</title>
		<para>
		This class simply creates a set with all packages in a given category.
		</para>

			<sect3>
			<title>Single Set Configuration</title>
			<para>
			In single set configurations this class supports the following options:
			<itemizedlist>
			<listitem><varname>category</varname>: Required. The name of an existing ebuild
				category which should be used to create the package set.
			</listitem>
			<listitem><varname>only_visible</varname>: Optional, defaults to <parameter>true</parameter>.
				When set to <parameter>true</parameter> the set will only include visible packages, 
				when set to <parameter>false</parameter> it will also include masked packages.
				It's currently only effective in combination with the <parameter>porttree</parameter>
				repository.
			</listitem>
			</itemizedlist>
			</para>
			</sect3>
			
			<sect3>
			<title>Multi Set Configuration</title>
			<para>
			In multi set configurations this class supports the following options:
			<itemizedlist>
			<listitem><varname>categories</varname>: Optional, defaults to all categories.
				If set it must be a space separated list of existing ebuild categories for
				which package sets should be created.
			</listitem>
			<listitem><varname>repository</varname>: See previous section.</listitem>
			<listitem><varname>only_visible</varname>: See previous section.</listitem>
			<listitem><varname>name_pattern</varname>: Optional, defaults to 
				<parameter>$category/*</parameter>. This describes the naming pattern
				to be used for creating the sets. It must contain either 
				<parameter>$category</parameter> or <parameter>${category}</parameter>, which 
				will be replaced by the category name.
			</listitem>
			</itemizedlist>
			</para>
			</sect3>
		</sect2>
		
		<sect2 id='config-set-classes-EverythingSet'>
		<title>portage.sets.dbapi.EverythingSet</title>
		<para>
		A superset of the classic <parameter>world</parameter> target, a set created
		by this class contains SLOT atoms to match all installed packages. Note that
		use of this set makes it impossible for emerge to solve blockers by automatic
		uninstallation of blocked packages.
		</para>

			<sect3>
			<title>Single Set Configuration</title>
			<para>
			This class doesn't support any extra options.
			</para>
			</sect3>
		</sect2>
		<sect2 id='config-set-classes-OwnerSet'>
		<title>portage.sets.dbapi.OwnerSet</title>
		<para>
		Package set which contains all packages
		that own one or more files.
		This class supports the following options:
		<itemizedlist>
		<listitem><varname>files</varname>: Required. A list of file paths
		that should be used to create the package set.
		</listitem>
		</itemizedlist>
		</para>
		</sect2>
		<sect2 id='config-set-classes-VariableSet'>
		<title>portage.sets.dbapi.VariableSet</title>
		<para>
		Package set which contains all packages
		that match specified values of specified variable.
		This class supports the following options:
		<itemizedlist>
		<listitem><varname>variable</varname>: The name of
		the specified variable whose values are checked.
		</listitem>
		<listitem><varname>includes</varname>: A list of
		values that must be contained within the specified
		variable.
		</listitem>
		<listitem><varname>excludes</varname>: A list of
		values that must not be contained within the specified
		variable.
		</listitem>
		<listitem><varname>metadata-source</varname>: Optional, defaults to
		"vartree". Specifies the repository to use for getting the metadata
		to check.</listitem>
		</itemizedlist>
		</para>
		</sect2>
		<sect2 id='config-set-classes-UnavailableSet'>
		<title>portage.sets.dbapi.UnavailableSet</title>
		<para>
		Package set which contains all installed
		packages for which there are no visible ebuilds
		corresponding to the same $CATEGORY/$PN:$SLOT.
		This class supports the following options:
		<itemizedlist>
		<listitem><varname>metadata-source</varname>: Optional, defaults to
		"porttree". Specifies the repository to use for getting the metadata
		to check.</listitem>
		</itemizedlist>
		</para>
		</sect2>
		<sect2 id='config-set-classes-DowngradeSet'>
		<title>portage.sets.dbapi.DowngradeSet</title>
		<para>
		Package set which contains all packages
		for which the highest visible ebuild version is lower than
		the currently installed version.
		This class doesn't support any extra options.
		</para>
		</sect2>
		<sect2 id='config-set-classes-PreservedLibraryConsumerSet'>
		<title>portage.sets.libs.PreservedLibraryConsumerSet</title>
		<para>
		A special set used to rebuild all packages that need a preserved library that only
		remains due to <varname>FEATURES="preserve-libs"</varname>.
		</para>

			<sect3>
			<title>Single Set Configuration</title>
			<para>
			This class supports the following option:
			<itemizedlist>
			<listitem><varname>debug</varname>: Generate extra output useful to figure out why
				certain packages are included in the set, as it's not always obvious.
			</listitem>
			</itemizedlist>
			</para>
			</sect3>
		</sect2>
	</sect1>
	
	<sect1 id='config-set-defaults'>
	<title>Default Sets</title>
	<para>
	By default, Portage already creates a few default sets that can be used 
	without further configuration. See <xref linkend='config-set-locations'/>
	and <xref linkend='config-set-syntax'/> for details on how to change those
	defaults.
	</para>
	<para>
	The default sets are:
	<itemizedlist>
	<listitem><varname>system</varname>: uses <classname>PackagesSystemSet</classname></listitem>
	<listitem><varname>world</varname>: uses <classname>WorldSet</classname></listitem>
	<listitem><varname>security</varname>: uses <classname>NewAffectedSet</classname> with default options</listitem>
	<listitem><varname>installed</varname>: uses <classname>EverythingSet</classname></listitem>
	<listitem><varname>preserved-rebuild</varname>: uses <classname>PreservedLibraryConsumerSet</classname></listitem>
	<listitem><varname>live-rebuild</varname>: uses <classname>VariableSet</classname></listitem>
	<listitem><varname>module-rebuild</varname>: uses <classname>OwnerSet</classname></listitem>
	<listitem><varname>downgrade</varname>: uses <classname>DowngradeSet</classname></listitem>
	<listitem><varname>unavailable</varname>: uses <classname>UnavailableSet</classname></listitem>
	</itemizedlist>
	Additionally the default configuration includes a multi set section based on
	the <classname>StaticFileSet</classname> defaults that creates a set for each 
	file in <filename>/etc/portage/sets</filename> for convenience.
	</para>
	</sect1>
</chapter>