Ebuild Revisions

From 296c57d3e177875dea9fc69cdc21d25befabce01 Mon Sep 17 00:00:00 2001 From: Mark Loeser Date: Mon, 27 Feb 2006 15:51:45 +0000 Subject: 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 --- Makefile | 6 ++ general-concepts/autotools/diagram.png | Bin 41702 -> 0 bytes general-concepts/cvs-to-rsync/diagram.png | Bin 32324 -> 0 bytes general-concepts/ebuild-revisions/text.xml | 35 +++++++++++ general-concepts/emerge-and-ebuild/diagram.svg | 55 +++++++++++++++++ general-concepts/emerge-and-ebuild/text.xml | 23 +++++++ general-concepts/features/text.xml | 68 ++++++++++++++++++++ general-concepts/filesystem/text.xml | 82 +++++++++++++++++++++++++ general-concepts/herds-and-projects/text.xml | 34 ++++++++++ general-concepts/install-destinations/text.xml | 32 ++++++++++ general-concepts/mirrors/diagram.png | Bin 31779 -> 0 bytes general-concepts/text.xml | 6 ++ 12 files changed, 341 insertions(+) delete mode 100644 general-concepts/autotools/diagram.png delete mode 100644 general-concepts/cvs-to-rsync/diagram.png create mode 100644 general-concepts/ebuild-revisions/text.xml create mode 100644 general-concepts/emerge-and-ebuild/diagram.svg create mode 100644 general-concepts/emerge-and-ebuild/text.xml create mode 100644 general-concepts/features/text.xml create mode 100644 general-concepts/filesystem/text.xml create mode 100644 general-concepts/herds-and-projects/text.xml create mode 100644 general-concepts/install-destinations/text.xml delete mode 100644 general-concepts/mirrors/diagram.png 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 Binary files a/general-concepts/autotools/diagram.png and /dev/null 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 Binary files a/general-concepts/cvs-to-rsync/diagram.png and /dev/null 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 @@ + + + +Ebuild Revisions + + +

+Ebuilds may have a Gentoo revision number associated with them. This is a +-rX suffix, where X is an integer -- see `File Naming Rules`_. This +component must only be used for Gentoo changes, not upstream releases. By +default, -r0 is implied and should not be specified manually. +

+ +

+Ebuilds should have their -rX 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. +

+ +

+Simple compile fixes do not 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. +

+ +

+When doing a revision bump, the usual rules about dropping to ~arch apply. +See `Keywording on Upgrades`_. +

+ + + + + 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 @@ + + + + + + + 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 @@ + + + +Emerge and Ebuild Relationships + + + +

+ + +

+The emerge program is a high level wrapper for ebuild.sh that handles +dependency tracking, safe installs and uninstalls and so on. emerge calls +ebuild.sh during the build process, which in turn handles the ebuild file +and any eclasses. The ${D} to ${ROOT} install is handled by emerge. +

+ +http://dev.gentoo.org/~g2boojum/portage.html + + + + + 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 @@ + + + +FEATURES + + +

+The FEATURES 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. +

+ +

+Relevant FEATURES for developers include: +

+ + + + + + + + autoaddcvs + Automatically runs a cvs add for certain files. + + + collision-protect + + Raise an error if an installing package attempts to overwrite a file which + is provided by a different package. + + + + cvs + Generate proper digests even when SRC_URI has conditional elements. + + + sandbox + Enable the sandbox. + + + sign + GPG sign manifest files. + + + strict + + Do some extra checks for potentially dangerous situations (eg missing + Manifest files). + + + + test + Enable the src_test phase. + + + userpriv + Drop to non-root privileges for certain phases. + + + usersandbox + Enables the sandbox even when running non-privileged. + +

Feature	Explanation

+ + + + 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 @@ + + + +Filesystem + + +

+The basic filesystem layout and purpose is as follows: +

+ +

/bin: Boot-critical applications
/etc: System administrator controlled configuration files
/lib: Boot-critical libraries
/opt: Binary-only applications.
/sbin: System administrator boot-critical applications
/tmp: Temporary data
/usr: General applications

/usr/bin: Applications
/usr/lib: Libraries
/usr/local: Non-portage applications. Ebuilds must not install here.
/usr/sbin: Non-system-critical system administrator applications
/usr/share: Architecture independent application data and documentation

/var: Program generated data

/var/cache: Long term data which can be regenerated
/var/lib: General application generated data
/var/log: Log files

+ +

+Where possible, we prefer to put non-boot-critical applications in /usr +rather than /. If a program is not needed in the boot process until after +filesystems are mounted then it generally does not belong on /. +

+ +

+Any binary which links against a library under /usr must itself go into +/usr (or possibly /opt). +

+ +

+The /opt top-level should only be used for binary-only applications. +Binary-only applications must not be installed outside of /opt. +

+ +

+The /usr/local heirarchy is for non-portage software. Ebuilds must not +attempt to put anything in here. +

+ +

+The /usr/share directory is for *architecture independent* application data +which is not modified at runtime. +

+ +

+Try to avoid installing unnecessary things into /etc -- 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 /usr/share. +

+ +

+FHS + + +

+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. +

+ + +

+ + + + 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 @@ + + + +Herds and Projects + + + +

+A herd 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 not always herdname@gentoo.org -- for +example, because of the way Gentoo's email aliases are set up, the cron herd +use cron-bugs@gentoo.org (aliases cannot match system usernames). +

+ +

+A project is a group formed for handling a particular general area. A project +may have herds associated with it. +

+ +

+Sometimes herd and project names overlap -- for example, the sparc project +has an associated sparc herd which maintains sparc-specific packages (such +as the silo bootloader). This is not always the case. +

+ +

+The herdstat tool can display useful information about herds. +

+ + + + + 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 @@ + + + +Install Destinations + + + +

+When an ebuild runs the src_install phase, it installs an image of the +package in question from ${S} into ${D}. Ebuilds must not attempt to +perform any operation upon the live filesystem at this stage -- this will break +binaries, and will (often) cause a sandbox violation notice. +

+ +

+When installing, portage will install the image in ${D} into ${ROOT}. By +default, ${ROOT} points to /, 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 pkg_postinst), you must ensure +that you prefix any paths with ${ROOT}. +

+ +

+When inside pkg_preinst, the image to be installed can be accessed under +"${IMAGE}". +

+ + + + + diff --git a/general-concepts/mirrors/diagram.png b/general-concepts/mirrors/diagram.png deleted file mode 100644 index ede32ea..0000000 Binary files a/general-concepts/mirrors/diagram.png and /dev/null 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. + + + + + + -- cgit v1.2.3-65-gdbad