diff options
| -rw-r--r-- | Makefile | 6 | ||||
| -rw-r--r-- | general-concepts/autotools/diagram.png | bin | 41702 -> 0 bytes | |||
| -rw-r--r-- | general-concepts/cvs-to-rsync/diagram.png | bin | 32324 -> 0 bytes | |||
| -rw-r--r-- | general-concepts/ebuild-revisions/text.xml | 35 | ||||
| -rw-r--r-- | general-concepts/emerge-and-ebuild/diagram.svg | 55 | ||||
| -rw-r--r-- | general-concepts/emerge-and-ebuild/text.xml | 23 | ||||
| -rw-r--r-- | general-concepts/features/text.xml | 68 | ||||
| -rw-r--r-- | general-concepts/filesystem/text.xml | 82 | ||||
| -rw-r--r-- | general-concepts/herds-and-projects/text.xml | 34 | ||||
| -rw-r--r-- | general-concepts/install-destinations/text.xml | 32 | ||||
| -rw-r--r-- | general-concepts/mirrors/diagram.png | bin | 31779 -> 0 bytes | |||
| -rw-r--r-- | general-concepts/text.xml | 6 |
12 files changed, 341 insertions, 0 deletions
@@ -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 Binary files differdeleted file mode 100644 index 5ee2ab8..0000000 --- a/general-concepts/autotools/diagram.png +++ /dev/null diff --git a/general-concepts/cvs-to-rsync/diagram.png b/general-concepts/cvs-to-rsync/diagram.png Binary files differdeleted file mode 100644 index ade7a52..0000000 --- a/general-concepts/cvs-to-rsync/diagram.png +++ /dev/null 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 Binary files differdeleted file mode 100644 index ede32ea..0000000 --- a/general-concepts/mirrors/diagram.png +++ /dev/null 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/"/> |
