en/glep/glep-0052.txt

GLEP: 52
Title: RESTRICT=unattended
Version: $Revision: 1.2 $
Last-Modified: $Date: 2006/10/14 02:47:31 $
Author: Marius Mauch <genone@gentoo.org>,
Status: Draft
Type: Standards Track
Content-Type: text/x-rst
Created: 13-Oct-2006
Post-History: 14-Oct-2006


Abstract
========

This GLEP proposes a new value for the RESTRICT metadata variable in ebuilds to
indicate that an ebuild requires interaction by the user.

Motivation
==========

Certain ebuilds in the current tree require certain actions from the user to 
progress. A popular example are ebuilds that require physical media (cd/dvd-rom)
for their distfiles instead of fetching them form the net.
However ebuilds are supposed to be non-interactive, so this behavior, while 
sometimes necessary, violates existing policies. To account for this situation
a new RESTRICT value should be added to allow filtering those ebuilds based on
metadata and to inform users upfront (when displaying the depgraph) that a 
certain package will require their attention during the build process.

Specification
=============

Portage (and by extension other package managers) will support a new value for 
the RESTRICT metadata variable called ``unattended``. This value may be used by
the package manager and tools using its API to filter packages that require 
interactive actions (for example to mask them in automated build environments).
How the package manager exactly reacts on the presence of this new flag is beyond
this specification, but it's recommended to indicate it's presence to the user
whenever relevant.

This new setting should be used in ebuilds if it is known that they _typically_
require user attention during the build process. If an ebuild just has a limited
``risk`` of becoming interactive (like using the ``built_with_use`` function)
it shouldn't be restricted.

Rationale
=========

The new RESTRICT=unattended metadata setting will give us the following benefits:

1. Enable masking of interactive ebuilds for automated build environments

2. Metadata based searching for interactive ebuilds (superior to grep)

3. Less frustrated users caused by ``hanging`` build processes

This proposal does not change the existing policy regarding interactive ebuilds
(ebuilds still should be non-interactive whenever possible), it merely states a 
way to identify them.

Backwards Compatibility
=======================

Strictly speaking this extension would requires an EAPI bump, however as existing 
portage ignore unknown RESTRICT values it shouldn't cause any real breakage to 
introduce it without.

Reference Implementation
========================

A `patch against portage-2.1.2_pre2-r6`__ is available with this document.

.. __: glep-0052-extras/portage-2.1.2_pre2-r6-interactive-restrict.diff.txt


Credits
=======

Thanks to the following persons for their input on or related to this GLEP
(even though they might not have known it):
Alec Warner, Zac Medico, Simon Stelling

References
==========

.. [#bug151113] http://bugs.gentoo.org/151113


Copyright
=========

This document has been placed in the public domain.

1	genone	1.1	GLEP: 52
2	genone	1.3	Title: RESTRICT=unattended
3			Version: $Revision: 1.2 $
4			Last-Modified: $Date: 2006/10/14 02:47:31 $
5	genone	1.1	Author: Marius Mauch <genone@gentoo.org>,
6			Status: Draft
7			Type: Standards Track
8			Content-Type: text/x-rst
9			Created: 13-Oct-2006
10			Post-History: 14-Oct-2006
11
12
13			Abstract
14			========
15
16			This GLEP proposes a new value for the RESTRICT metadata variable in ebuilds to
17			indicate that an ebuild requires interaction by the user.
18
19			Motivation
20			==========
21
22			Certain ebuilds in the current tree require certain actions from the user to
23			progress. A popular example are ebuilds that require physical media (cd/dvd-rom)
24			for their distfiles instead of fetching them form the net.
25			However ebuilds are supposed to be non-interactive, so this behavior, while
26			sometimes necessary, violates existing policies. To account for this situation
27			a new RESTRICT value should be added to allow filtering those ebuilds based on
28			metadata and to inform users upfront (when displaying the depgraph) that a
29			certain package will require their attention during the build process.
30
31			Specification
32			=============
33
34			Portage (and by extension other package managers) will support a new value for
35	genone	1.3	the RESTRICT metadata variable called ``unattended``. This value may be used by
36	genone	1.1	the package manager and tools using its API to filter packages that require
37			interactive actions (for example to mask them in automated build environments).
38			How the package manager exactly reacts on the presence of this new flag is beyond
39			this specification, but it's recommended to indicate it's presence to the user
40			whenever relevant.
41
42			This new setting should be used in ebuilds if it is known that they _typically_
43			require user attention during the build process. If an ebuild just has a limited
44			``risk`` of becoming interactive (like using the ``built_with_use`` function)
45			it shouldn't be restricted.
46
47			Rationale
48			=========
49
50	genone	1.3	The new RESTRICT=unattended metadata setting will give us the following benefits:
51	genone	1.1
52			1. Enable masking of interactive ebuilds for automated build environments
53
54			2. Metadata based searching for interactive ebuilds (superior to grep)
55
56			3. Less frustrated users caused by ``hanging`` build processes
57
58			This proposal does not change the existing policy regarding interactive ebuilds
59			(ebuilds still should be non-interactive whenever possible), it merely states a
60			way to identify them.
61
62			Backwards Compatibility
63			=======================
64
65			Strictly speaking this extension would requires an EAPI bump, however as existing
66			portage ignore unknown RESTRICT values it shouldn't cause any real breakage to
67			introduce it without.
68
69			Reference Implementation
70			========================
71
72	genone	1.2	A `patch against portage-2.1.2_pre2-r6`__ is available with this document.
73
74			.. __: glep-0052-extras/portage-2.1.2_pre2-r6-interactive-restrict.diff.txt
75
76	genone	1.1
77			Credits
78			=======
79
80			Thanks to the following persons for their input on or related to this GLEP
81			(even though they might not have known it):
82			Alec Warner, Zac Medico, Simon Stelling
83
84			References
85			==========
86
87			.. [#bug151113] http://bugs.gentoo.org/151113
88
89
90			Copyright
91			=========
92
93			This document has been placed in the public domain.
94