aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorMark Loeser <halcy0n@gentoo.org>2006-02-27 15:51:45 +0000
committerMark Loeser <halcy0n@gentoo.org>2006-02-27 15:51:45 +0000
commit296c57d3e177875dea9fc69cdc21d25befabce01 (patch)
tree1b1b77add04d0055420e297db39a41b1a8060773
parentAdd some more of general-concepts (diff)
downloaddevmanual-296c57d3e177875dea9fc69cdc21d25befabce01.tar.gz
devmanual-296c57d3e177875dea9fc69cdc21d25befabce01.tar.bz2
devmanual-296c57d3e177875dea9fc69cdc21d25befabce01.zip
Add some more pages. The Makefile now generates the png's at build time, so we don't need the PNGs in the repo anymore
git-svn-id: svn+ssh://svn.gentoo.org/var/svnroot/devmanual/trunk@7 176d3534-300d-0410-8db8-84e73ed771c3
-rw-r--r--Makefile6
-rw-r--r--general-concepts/autotools/diagram.pngbin41702 -> 0 bytes
-rw-r--r--general-concepts/cvs-to-rsync/diagram.pngbin32324 -> 0 bytes
-rw-r--r--general-concepts/ebuild-revisions/text.xml35
-rw-r--r--general-concepts/emerge-and-ebuild/diagram.svg55
-rw-r--r--general-concepts/emerge-and-ebuild/text.xml23
-rw-r--r--general-concepts/features/text.xml68
-rw-r--r--general-concepts/filesystem/text.xml82
-rw-r--r--general-concepts/herds-and-projects/text.xml34
-rw-r--r--general-concepts/install-destinations/text.xml32
-rw-r--r--general-concepts/mirrors/diagram.pngbin31779 -> 0 bytes
-rw-r--r--general-concepts/text.xml6
12 files changed, 341 insertions, 0 deletions
diff --git a/Makefile b/Makefile
index 59b6297..1e9b188 100644
--- a/Makefile
+++ b/Makefile
@@ -2,6 +2,7 @@ all: transform
clean:
@find -name "index.html" | xargs rm
+ @find -name "*.png" | xargs rm
transform:
@for file in $$(find -name text.xml) ; do \
@@ -9,3 +10,8 @@ transform:
echo "Processing $${file} --> $${htmlfile}" ; \
xsltproc devbook.xsl $$file > $$htmlfile ; \
done
+ @for file in $$(find -name *.svg) ; do \
+ pngfile=$${file/.svg/.png} ; \
+ echo "Converting $${file} --> $${pngfile}" ; \
+ convert $$file $$pngfile ; \
+ done
diff --git a/general-concepts/autotools/diagram.png b/general-concepts/autotools/diagram.png
deleted file mode 100644
index 5ee2ab8..0000000
--- a/general-concepts/autotools/diagram.png
+++ /dev/null
Binary files differ
diff --git a/general-concepts/cvs-to-rsync/diagram.png b/general-concepts/cvs-to-rsync/diagram.png
deleted file mode 100644
index ade7a52..0000000
--- a/general-concepts/cvs-to-rsync/diagram.png
+++ /dev/null
Binary files differ
diff --git a/general-concepts/ebuild-revisions/text.xml b/general-concepts/ebuild-revisions/text.xml
new file mode 100644
index 0000000..51c109f
--- /dev/null
+++ b/general-concepts/ebuild-revisions/text.xml
@@ -0,0 +1,35 @@
+<?xml version="1.0"?>
+<guide self="general-concepts/ebuild-revisions/">
+<chapter>
+<title>Ebuild Revisions</title>
+
+<body>
+<p>
+Ebuilds may have a Gentoo revision number associated with them. This is a
+<c>-rX</c> suffix, where <c>X</c> is an integer -- see `File Naming Rules`_. This
+component must only be used for Gentoo changes, not upstream releases. By
+default, <c>-r0</c> is implied and should not be specified manually.
+</p>
+
+<p>
+Ebuilds should have their <c>-rX</c> incremented whenever a change is made which
+will make a substantial difference to what gets installed by the package -- by
+substantial, we generally mean "something for which many users would want to
+upgrade". This is usually for bugfixes.
+</p>
+
+<p>
+Simple compile fixes do <b>not</b> warrant a revision bump; this is because they do
+not affect the installed package for users who already managed to compile it.
+Small documentation fixes are also usually not grounds for a new revision.
+</p>
+
+<p>
+When doing a revision bump, the usual rules about dropping to <c>~arch</c> apply.
+See `Keywording on Upgrades`_.
+</p>
+
+</body>
+</chapter>
+</guide>
+
diff --git a/general-concepts/emerge-and-ebuild/diagram.svg b/general-concepts/emerge-and-ebuild/diagram.svg
new file mode 100644
index 0000000..62bc8fd
--- /dev/null
+++ b/general-concepts/emerge-and-ebuild/diagram.svg
@@ -0,0 +1,55 @@
+<?xml version="1.0" standalone="no"?>
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN"
+ "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
+<svg viewBox="0 100 500 220" xmlns="http://www.w3.org/2000/svg" version="1.1">
+ <desc>Emerge and Ebuild</desc>
+ <rect x="-10" y="-10" width="1000" height="1000" fill="#eeeeee" id="background" />
+
+ <rect x="50" y="150" width="100" height="30"
+ fill="#ccffcc" stroke="black" stroke-width="2" />
+ <text style="text-anchor: middle;" x="100" y="170"># emerge foo</text>
+
+ <line x1="150" y1="165" x2="200" y2="165" stroke-width="2" stroke="black" />
+ <line x1="200" y1="165" x2="193" y2="160" stroke-width="2" stroke="black" />
+ <line x1="200" y1="165" x2="193" y2="170" stroke-width="2" stroke="black" />
+
+ <rect x="200" y="150" width="100" height="30"
+ fill="#ffffff" stroke="black" stroke-width="2" />
+ <text style="text-anchor: middle;" x="250" y="170">emerge</text>
+
+ <line x1="220" y1="180" x2="220" y2="250" stroke-width="2" stroke="black" />
+ <line x1="220" y1="250" x2="215" y2="243" stroke-width="2" stroke="black" />
+ <line x1="220" y1="250" x2="225" y2="243" stroke-width="2" stroke="black" />
+ <text style="text-anchor: right;" x="210" y="220">$PN, phases</text>
+
+ <line x1="280" y1="180" x2="280" y2="250" stroke-width="2" stroke="black" />
+ <line x1="280" y1="180" x2="275" y2="187" stroke-width="2" stroke="black" />
+ <line x1="280" y1="180" x2="285" y2="187" stroke-width="2" stroke="black" />
+ <text style="text-anchor: left;" x="290" y="220">Image in $D</text>
+
+ <rect x="200" y="250" width="100" height="30"
+ fill="#ffffff" stroke="black" stroke-width="2" />
+ <text style="text-anchor: middle;" x="250" y="270">ebuild.sh</text>
+
+ <rect x="50" y="250" width="100" height="30"
+ fill="#ccccff" stroke="black" stroke-width="2" />
+ <text style="text-anchor: middle;" x="100" y="270">foo-1.23.ebuild</text>
+
+ <line x1="150" y1="265" x2="200" y2="265" stroke-width="2" stroke="black" />
+ <line x1="200" y1="265" x2="193" y2="260" stroke-width="2" stroke="black" />
+ <line x1="200" y1="265" x2="193" y2="270" stroke-width="2" stroke="black" />
+
+ <line x1="300" y1="165" x2="350" y2="165" stroke-width="2" stroke="black" />
+ <line x1="350" y1="165" x2="343" y2="160" stroke-width="2" stroke="black" />
+ <line x1="350" y1="165" x2="343" y2="170" stroke-width="2" stroke="black" />
+
+ <ellipse cx="400" cy="165" rx="50" ry="20" stroke-width="2" stroke="black"
+ fill="#ffcccc" />
+ <text style="text-anchor: middle;" x="400" y="164">Installed image</text>
+ <text style="text-anchor: middle;" x="400" y="177">in $ROOT</text>
+
+</svg>
+
+<!-- vim: set ft=xml sw=4 sts=4 et : -->
+
+
diff --git a/general-concepts/emerge-and-ebuild/text.xml b/general-concepts/emerge-and-ebuild/text.xml
new file mode 100644
index 0000000..16bc056
--- /dev/null
+++ b/general-concepts/emerge-and-ebuild/text.xml
@@ -0,0 +1,23 @@
+<?xml version="1.0"?>
+<guide self="general-concepts/emerge-and-ebuild/">
+<chapter>
+<title>Emerge and Ebuild Relationships</title>
+
+<body>
+
+<figure short="How emerge, ebuild and foo.ebuild interact" link="diagram.png">
+</figure>
+
+<p>
+The <c>emerge</c> program is a high level wrapper for <c>ebuild.sh</c> that handles
+dependency tracking, safe installs and uninstalls and so on. <c>emerge</c> calls
+<c>ebuild.sh</c> during the build process, which in turn handles the ebuild file
+and any eclasses. The <c>${D}</c> to <c>${ROOT}</c> install is handled by <c>emerge</c>.
+</p>
+
+<todo>http://dev.gentoo.org/~g2boojum/portage.html</todo>
+
+</body>
+</chapter>
+</guide>
+
diff --git a/general-concepts/features/text.xml b/general-concepts/features/text.xml
new file mode 100644
index 0000000..8227ea6
--- /dev/null
+++ b/general-concepts/features/text.xml
@@ -0,0 +1,68 @@
+<?xml version="1.0"?>
+<guide self="general-concepts/features/">
+<chapter>
+<title>FEATURES</title>
+
+<body>
+<p>
+The <c>FEATURES</c> variable specifies options which affect how portage operates
+and how packages are compiled. It is **not** used for settings which have a
+substantial effect upon the resulting generated package.
+</p>
+
+<p>
+Relevant <c>FEATURES</c> for developers include:
+</p>
+
+<table>
+ <tr>
+ <th>Feature</th>
+ <th>Explanation</th>
+ </tr>
+ <tr>
+ <ti><c>autoaddcvs</c></ti>
+ <ti>Automatically runs a <c>cvs add</c> for certain files.</ti>
+ </tr>
+ <tr>
+ <ti><c>collision-protect</c></ti>
+ <ti>
+ Raise an error if an installing package attempts to overwrite a file which
+ is provided by a different package.
+ </ti>
+ </tr>
+ <tr>
+ <ti><c>cvs</c></ti>
+ <ti>Generate proper digests even when <c>SRC_URI</c> has conditional elements.</ti>
+ </tr>
+ <tr>
+ <ti><c>sandbox</c></ti>
+ <ti>Enable the sandbox.</ti>
+ </tr>
+ <tr>
+ <ti><c>sign</c></ti>
+ <ti>GPG sign manifest files.</ti>
+ </tr>
+ <tr>
+ <ti><c>strict</c></ti>
+ <ti>
+ Do some extra checks for potentially dangerous situations (eg missing
+ <c>Manifest</c> files).
+ </ti>
+ </tr>
+ <tr>
+ <ti><c>test</c></ti>
+ <ti>Enable the <c>src_test</c> phase.</ti>
+ </tr>
+ <tr>
+ <ti><c>userpriv</c></ti>
+ <ti>Drop to non-root privileges for certain phases.</ti>
+ </tr>
+ <tr>
+ <ti><c>usersandbox</c></ti>
+ <ti>Enables the sandbox even when running non-privileged.</ti>
+ </tr>
+</table>
+
+</body>
+</chapter>
+</guide>
diff --git a/general-concepts/filesystem/text.xml b/general-concepts/filesystem/text.xml
new file mode 100644
index 0000000..1f5cbb3
--- /dev/null
+++ b/general-concepts/filesystem/text.xml
@@ -0,0 +1,82 @@
+<?xml version="1.0"?>
+<guide self="general-concepts/filesystem/">
+<chapter>
+<title>Filesystem</title>
+
+<body>
+<p>
+The basic filesystem layout and purpose is as follows:
+</p>
+
+<ul>
+ <li><c>/bin</c>: Boot-critical applications</li>
+ <li><c>/etc</c>: System administrator controlled configuration files</li>
+ <li><c>/lib</c>: Boot-critical libraries</li>
+ <li><c>/opt</c>: Binary-only applications.</li>
+ <li><c>/sbin</c>: System administrator boot-critical applications</li>
+ <li><c>/tmp</c>: Temporary data</li>
+ <li><c>/usr</c>: General applications</li>
+ <ul>
+ <li><c>/usr/bin</c>: Applications</li>
+ <li><c>/usr/lib</c>: Libraries</li>
+ <li><c>/usr/local</c>: Non-portage applications. <b>Ebuilds must not install here</b>.</li>
+ <li><c>/usr/sbin</c>: Non-system-critical system administrator applications</li>
+ <li><c>/usr/share</c>: Architecture independent application data and documentation</li>
+ </ul>
+ <li><c>/var</c>: Program generated data</li>
+ <ul>
+ <li><c>/var/cache</c>: Long term data which can be regenerated</li>
+ <li><c>/var/lib</c>: General application generated data</li>
+ <li><c>/var/log</c>: Log files</li>
+ </ul>
+</ul>
+
+<p>
+Where possible, we prefer to put non-boot-critical applications in <c>/usr</c>
+rather than <c>/</c>. If a program is not needed in the boot process until after
+filesystems are mounted then it generally does not belong on <c>/</c>.
+</p>
+
+<p>
+Any binary which links against a library under <c>/usr</c> must itself go into
+<c>/usr</c> (or possibly <c>/opt</c>).
+</p>
+
+<p>
+The <c>/opt</c> top-level should only be used for binary-only applications.
+Binary-only applications must not be installed outside of <c>/opt</c>.
+</p>
+
+<p>
+The <c>/usr/local</c> heirarchy is for non-portage software. Ebuilds must not
+attempt to put anything in here.
+</p>
+
+<p>
+The <c>/usr/share</c> directory is for *architecture independent* application data
+which is not modified at runtime.
+</p>
+
+<p>
+Try to avoid installing unnecessary things into <c>/etc</c> -- every file in there
+is additional work for the system administrator. In particular, non-text files
+and files that are not intended for system administrator usage should be moved
+to <c>/usr/share</c>.
+</p>
+
+<section>
+<title>FHS</title>
+<body>
+
+<p>
+Gentoo does not consider the `Filesystem Hierarchy Standard
+http://www.pathname.com/fhs/`__ to be an authoritative standard, although much
+of our policy coincides with it.
+</p>
+
+</body>
+</section>
+
+</body>
+</chapter>
+</guide>
diff --git a/general-concepts/herds-and-projects/text.xml b/general-concepts/herds-and-projects/text.xml
new file mode 100644
index 0000000..c70754b
--- /dev/null
+++ b/general-concepts/herds-and-projects/text.xml
@@ -0,0 +1,34 @@
+<?xml version="1.0"?>
+<guide self="general-concepts/herds-and-projects/">
+<chapter>
+<title>Herds and Projects</title>
+
+<body>
+
+<p>
+A <i>herd</i> is a collection of developers who maintain a collection of related
+packages. A herd has an associated email address which can be used for bugzilla
+assignments. This email address is <b>not</b> always <c>herdname@gentoo.org</c> -- for
+example, because of the way Gentoo's email aliases are set up, the <c>cron</c> herd
+use <c>cron-bugs@gentoo.org</c> (aliases cannot match system usernames).
+</p>
+
+<p>
+A <i>project</i> is a group formed for handling a particular general area. A project
+may have herds associated with it.
+</p>
+
+<p>
+Sometimes herd and project names overlap -- for example, the <c>sparc</c> project
+has an associated <c>sparc</c> herd which maintains sparc-specific packages (such
+as the <c>silo</c> bootloader). This is <i>not</i> always the case.
+</p>
+
+<p>
+The <c>herdstat</c> tool can display useful information about herds.
+</p>
+
+</body>
+</chapter>
+</guide>
+
diff --git a/general-concepts/install-destinations/text.xml b/general-concepts/install-destinations/text.xml
new file mode 100644
index 0000000..dbe0492
--- /dev/null
+++ b/general-concepts/install-destinations/text.xml
@@ -0,0 +1,32 @@
+<?xml version="1.0"?>
+<guide self="general-concepts/install-destinations/">
+<chapter>
+<title>Install Destinations</title>
+
+<body>
+
+<p>
+When an ebuild runs the <c>src_install</c> phase, it installs an image of the
+package in question from <c>${S}</c> into <c>${D}</c>. Ebuilds must <i>not</i> attempt to
+perform any operation upon the live filesystem at this stage -- this will break
+binaries, and will (often) cause a sandbox violation notice.
+</p>
+
+<p>
+When installing, portage will install the image in <c>${D}</c> into <c>${ROOT}</c>. By
+default, <c>${ROOT}</c> points to <c>/</c>, although the user can alter this -- for
+example, the user may be building a minimal image for another system in a
+different location. If your package must operate on the live filesystem (for
+example, to create some cache files during <c>pkg_postinst</c>), you must ensure
+that you prefix any paths with <c>${ROOT}</c>.
+</p>
+
+<p>
+When inside <c>pkg_preinst</c>, the image to be installed can be accessed under
+<c>"${IMAGE}"</c>.
+</p>
+
+</body>
+</chapter>
+</guide>
+
diff --git a/general-concepts/mirrors/diagram.png b/general-concepts/mirrors/diagram.png
deleted file mode 100644
index ede32ea..0000000
--- a/general-concepts/mirrors/diagram.png
+++ /dev/null
Binary files differ
diff --git a/general-concepts/text.xml b/general-concepts/text.xml
index 178b327..66d2840 100644
--- a/general-concepts/text.xml
+++ b/general-concepts/text.xml
@@ -25,6 +25,12 @@ writing ebuilds or working with the portage tree.
<include href="dependencies/"/>
<include href="digest-and-manifest/"/>
<include href="distributed-building/"/>
+<include href="ebuild-revisions/"/>
+<include href="emerge-and-ebuild/"/>
+<include href="features/"/>
+<include href="filesystem/"/>
+<include href="herds-and-projects/"/>
+<include href="install-destinations/"/>
<include href="licenses/"/>
<include href="linguas/"/>
<include href="mirrors/"/>