aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorMark Loeser <halcy0n@gentoo.org>2006-03-09 03:41:25 +0000
committerMark Loeser <halcy0n@gentoo.org>2006-03-09 03:41:25 +0000
commitbbfb28e736823048a90981ef1fa350ed9ddb463a (patch)
treec2ab8f116041ed201426123d09c38ddfd62e63c2
parentAdd the eclass writing guide (diff)
downloaddevmanual-bbfb28e736823048a90981ef1fa350ed9ddb463a.tar.gz
devmanual-bbfb28e736823048a90981ef1fa350ed9ddb463a.tar.bz2
devmanual-bbfb28e736823048a90981ef1fa350ed9ddb463a.zip
Add profiles/
git-svn-id: svn+ssh://svn.gentoo.org/var/svnroot/devmanual/trunk@16 176d3534-300d-0410-8db8-84e73ed771c3
-rw-r--r--profiles/categories/text.xml20
-rw-r--r--profiles/info_files/text.xml17
-rw-r--r--profiles/make.defaults/text.xml22
-rw-r--r--profiles/package.mask/text.xml20
-rw-r--r--profiles/packages/text.xml16
-rw-r--r--profiles/profiles.desc/text.xml14
-rw-r--r--profiles/text.xml31
-rw-r--r--profiles/updates/text.xml14
-rw-r--r--profiles/use.desc/text.xml32
-rw-r--r--profiles/use.mask/text.xml45
-rw-r--r--profiles/virtuals/text.xml18
-rw-r--r--text.xml1
12 files changed, 250 insertions, 0 deletions
diff --git a/profiles/categories/text.xml b/profiles/categories/text.xml
new file mode 100644
index 0000000..a2a4625
--- /dev/null
+++ b/profiles/categories/text.xml
@@ -0,0 +1,20 @@
+<?xml version="1.0"?>
+<guide self="profiles/categories/">
+<chapter>
+<title>Profiles <c>categories</c> File</title>
+
+<body>
+<p>
+The <c>profiles/categories</c> file contains an asciibetically sorted list of all
+the valid categories in the portage tree. When adding a new category, remember
+to update and commit this file <e>before</e> making any related commits.
+</p>
+
+<p>
+The <c>categories</c> file is a straight list. For descriptions, see `Category
+Metadata`_.
+</p>
+</body>
+
+</chapter>
+</guide>
diff --git a/profiles/info_files/text.xml b/profiles/info_files/text.xml
new file mode 100644
index 0000000..ae68b30
--- /dev/null
+++ b/profiles/info_files/text.xml
@@ -0,0 +1,17 @@
+<?xml version="1.0"?>
+<guide self="profiles/info_files/">
+<chapter>
+<title>Profiles <c>info_</c> Files</title>
+<body>
+
+<p>
+The <c>profiles/info_pkgs</c> file controls the packages whose versions are listed
+when <c>emerge info</c> is run. The <c>profiles/info_vars</c> file controls the
+displayed environment variables. Do not add to these files without discussion on
+the <c>gentoo-dev</c> mailing list.
+</p>
+
+</body>
+</chapter>
+</guide>
+
diff --git a/profiles/make.defaults/text.xml b/profiles/make.defaults/text.xml
new file mode 100644
index 0000000..15ea2c6
--- /dev/null
+++ b/profiles/make.defaults/text.xml
@@ -0,0 +1,22 @@
+<?xml version="1.0"?>
+<guide self="profiles/make.defaults/">
+<chapter>
+<title>Profiles <c>make.defaults</c> File</title>
+<body>
+
+<p>
+The <c>make.defaults</c> file in <c>profiles/</c> provides a minimal set of defaults
+for the kinds of values which may be set in <c>make.conf</c> (<c>CFLAGS</c>, <c>USE</c>,
+<c>FEATURES</c> etc) along with certain control variables (eg <c>USE_EXPAND</c>).
+These values can further be refined by additional <c>make.defaults</c> files in
+subprofiles.
+</p>
+
+<p>
+In general, <c>make.defaults</c> should not be modified without consulting the
+relevant arch team, or <c>gentoo-dev</c> for high-up <c>make.defaults</c> files.
+</p>
+
+</body>
+</chapter>
+</guide>
diff --git a/profiles/package.mask/text.xml b/profiles/package.mask/text.xml
new file mode 100644
index 0000000..577c12b
--- /dev/null
+++ b/profiles/package.mask/text.xml
@@ -0,0 +1,20 @@
+<?xml version="1.0"?>
+<guide self="profiles/package.mask/">
+<chapter>
+<title>Profiles <c>package.mask</c> File</title>
+<body>
+
+<p>
+The <c>package.mask</c> file can be used to hard mask packages or certain versions
+of packages. This is often used when adding certain experimental (either in
+ebuild or upstream terms) packages to the tree. The format is described in
+`portage-5`_.
+</p>
+
+<p>
+This file can be used in subprofiles to mask packages only for certain setups.
+</p>
+
+</body>
+</chapter>
+</guide>
diff --git a/profiles/packages/text.xml b/profiles/packages/text.xml
new file mode 100644
index 0000000..f4527ca
--- /dev/null
+++ b/profiles/packages/text.xml
@@ -0,0 +1,16 @@
+<?xml version="1.0"?>
+<guide self="profiles/packages/">
+<chapter>
+<title>Profiles <c>packages</c> File</title>
+<body>
+
+<p>
+The <c>packages</c> file in <c>profiles/</c> controls the packages pulled in by the
+<c>system</c> target. The <c>base/packages</c> file must not be modified without
+discussion on the <c>gentoo-dev</c> list; subprofile overrides are up to the
+relevant arch teams.
+</p>
+
+</body>
+</chapter>
+</guide>
diff --git a/profiles/profiles.desc/text.xml b/profiles/profiles.desc/text.xml
new file mode 100644
index 0000000..16dc52a
--- /dev/null
+++ b/profiles/profiles.desc/text.xml
@@ -0,0 +1,14 @@
+<?xml version="1.0"?>
+<guide self="profiles/profiles.desc/">
+<chapter>
+<title>Profiles <c>profiles.desc</c> File</title>
+<body>
+
+<todo>
+Find someone who knows exactly what this file's really used for with
+current portage versions and what is and isn't allowed.
+</todo>
+
+</body>
+</chapter>
+</guide>
diff --git a/profiles/text.xml b/profiles/text.xml
new file mode 100644
index 0000000..44b7774
--- /dev/null
+++ b/profiles/text.xml
@@ -0,0 +1,31 @@
+<?xml version="1.0"?>
+<guide self="profiles/">
+<chapter>
+<title>Profiles</title>
+
+<body>
+<p>
+This section provides details on the <c>profiles/</c> directory. All of these files
+are also documented in `portage-5`_.
+</p>
+</body>
+
+<section>
+<title>Contents</title>
+<body>
+<contentsTree/>
+</body>
+</section>
+</chapter>
+
+<include href="categories/"/>
+<include href="info_files/"/>
+<include href="package.mask/"/>
+<include href="packages/"/>
+<include href="profiles.desc/"/>
+<include href="updates/"/>
+<include href="use.desc/"/>
+<include href="use.mask/"/>
+<include href="virtuals/"/>
+
+</guide>
diff --git a/profiles/updates/text.xml b/profiles/updates/text.xml
new file mode 100644
index 0000000..d450374
--- /dev/null
+++ b/profiles/updates/text.xml
@@ -0,0 +1,14 @@
+<?xml version="1.0"?>
+<guide self="profiles/updates/">
+<chapter>
+<title>Profiles <c>updates/</c> Directory</title>
+<body>
+
+<todo>
+move and slotmove
+</todo>
+
+</body>
+</chapter>
+</guide>
+
diff --git a/profiles/use.desc/text.xml b/profiles/use.desc/text.xml
new file mode 100644
index 0000000..5ac2524
--- /dev/null
+++ b/profiles/use.desc/text.xml
@@ -0,0 +1,32 @@
+<?xml version="1.0"?>
+<guide self="profiles/use.desc/">
+<chapter>
+<title>Profiles <c>use.desc</c> and <c>use.local.desc</c> Files</title>
+<body>
+
+<p>
+The <c>use.desc</c> file contains a list of all global non-expanded <c>USE</c> flags,
+together with a short description. This file should not be modified without
+discussion on the <c>gentoo-dev</c> list.
+</p>
+
+<p>
+The <c>use.local.desc</c> file contains a list of all local <c>USE</c> flags, together
+with the relevant packages, and a short description. This file can be added to
+without general discussion.
+</p>
+
+<p>
+Having a small number of packages using identically named local <c>USE</c> flags is
+allowed. If the number starts to grow substantially, it may be worth proposing
+that the flag becomes a global <d /> see
+<uri link="::general-concepts/use-flags#Local and Global USE Flags"/>.
+</p>
+
+<p>
+All non-expand flags must be listed in exactly one of these files.
+</p>
+
+</body>
+</chapter>
+</guide>
diff --git a/profiles/use.mask/text.xml b/profiles/use.mask/text.xml
new file mode 100644
index 0000000..2effe8b
--- /dev/null
+++ b/profiles/use.mask/text.xml
@@ -0,0 +1,45 @@
+<?xml version="1.0"?>
+<guide self="profiles/use.mask/">
+<chapter>
+<title>Profiles <c>use.mask</c> File</title>
+<body>
+
+<p>
+The <c>use.mask</c> file can be used to mark <c>USE</c> flags as unavailable on a
+particular profile. This can be useful for various reasons:
+</p>
+
+<ul>
+ <li>
+ Masking hardware-specific feature flags. For example, <c>mmx</c> and <c>sse</c> are
+ only available on x86, <c>altivec</c> is only available on <c>ppc</c> and <c>vis</c> is
+ only available on sparc v9.
+ </li>
+ <li>
+ Disabling unavailable soft dependencies. A simple hypothetical example <d /> say
+ <c>fooapp</c> works on <c>mips</c>, but has an optional dependency (controlled by
+ the <c>bar</c> flag) upon <c>libbar</c>, which doesn't work on <c>mips</c>. Then by
+ adding the <c>bar</c> flag to <c>profiles/default-linux/mips/use.mask</c>,
+ <c>fooapp</c> could be made available to <c>mips</c> users with the unresolvable
+ dependency forcibly disabled.
+ </li>
+</ul>
+
+<p>
+Note that <c>use.mask</c> is a per-flag thing, not per package's use of a given
+flag. This is one of the reasons that USE flags must have a specific well
+defined purpose.
+</p>
+
+<p>
+Updates to <c>use.mask</c> should be handled via the relevant arch team.
+</p>
+
+<p>
+See `noblah USE Flags`_ for more discussion.
+</p>
+
+</body>
+</chapter>
+</guide>
+
diff --git a/profiles/virtuals/text.xml b/profiles/virtuals/text.xml
new file mode 100644
index 0000000..3446cbd
--- /dev/null
+++ b/profiles/virtuals/text.xml
@@ -0,0 +1,18 @@
+<?xml version="1.0"?>
+<guide self="profiles/virtuals/">
+<chapter>
+<title>Profiles <c>virtuals</c> Files</title>
+<body>
+
+<p>
+The <c>virtuals</c> files in <c>profiles/</c> control the default provider for
+virtuals. It can be overridden in subprofiles for profile-specific defaults.
+</p>
+
+<p>
+Before adding a new virtual, it should be discussed on <c>gentoo-dev</c>.
+</p>
+
+</body>
+</chapter>
+</guide>
diff --git a/text.xml b/text.xml
index 47e02b9..7e18f85 100644
--- a/text.xml
+++ b/text.xml
@@ -37,4 +37,5 @@ section for how to get started.
<include href="general-concepts/"/>
<include href="ebuild-writing/"/>
<include href="eclass-writing/"/>
+<include href="profiles/"/>
</guide>