Add some documentation for ebuild phases and pre/post phase

hooks that can be defined via bashrc. (trunk r8876)

svn path=/main/branches/2.1.2/; revision=8879

6 files changed, 84 insertions, 0 deletions

diff --git a/doc/config.docbook b/doc/config.docbook
new file mode 100644
index 000000000..118d98b55
--- /dev/null
+++ b/doc/config.docbook
@@ -0,0 +1,4 @@
+<part id='config'>
+<title>Configuration</title>
+&config_bashrc;
+</part>
diff --git a/doc/config/bashrc.docbook b/doc/config/bashrc.docbook
new file mode 100644
index 000000000..2f0626215
--- /dev/null
+++ b/doc/config/bashrc.docbook
@@ -0,0 +1,22 @@
+<chapter id='config-bashrc'>
+	<title>Bashrc Configuration</title>
+	<sect1 id='config-bashrc-locations'>
+		<title>bashrc locations</title>
+		<para>
+		If a bashrc file is located at <filename>/etc/portage/bashrc</filename>
+		then it will be sourced before an ebuild is executed.
+		</para>
+	</sect1>
+	<sect1 id='config-bashrc-ebuild-phase-hooks'>
+		<title>Ebuild Phase Hooks</title>
+		<para>
+		A phase hook function name begins with a pre_ or post_
+		prefix to indicate that it will be called before or after
+		one of the <link linkend='package-ebuild-phases'>ebuild phases</link>.
+		The prefix is followed by the name of the ebuild function that the hook
+		will be associated with. For example, a hook named pre_src_compile
+		will be called before src_compile, and a hook named post_src_compile
+		will be called after src_compile.
+		</para>
+	</sect1>
+</chapter>
diff --git a/doc/package.docbook b/doc/package.docbook
new file mode 100644
index 000000000..d37e6d525
--- /dev/null
+++ b/doc/package.docbook
@@ -0,0 +1,4 @@
+<part id='package'>
+<title>Package Formats</title>
+&package_ebuild;
+</part>
diff --git a/doc/package/ebuild.docbook b/doc/package/ebuild.docbook
new file mode 100644
index 000000000..5466f99db
--- /dev/null
+++ b/doc/package/ebuild.docbook
@@ -0,0 +1,4 @@
+<chapter id='package-ebuild'>
+<title>Ebuild</title>
+&package_ebuild_phases;
+</chapter>
diff --git a/doc/package/ebuild/phases.docbook b/doc/package/ebuild/phases.docbook
new file mode 100644
index 000000000..5c7f04969
--- /dev/null
+++ b/doc/package/ebuild/phases.docbook
@@ -0,0 +1,43 @@
+<sect1 id='package-ebuild-phases'>
+	<title>Ebuild Phases</title>
+	<para>
+	Ebuild execution is divided into a series of phases. In order
+	to implement a phase, an ebuild defines a function to serve as
+	an entry point for execution of that phase.
+	This design is similar to the template method pattern that
+	is commonly used in object oriented programming languages. An ebuild
+	can inherit or override a template method from an eclass.
+	</para>
+	<para>
+	The function names for the ebuild phases, listed in order of execution:
+	<itemizedlist>
+	<listitem>
+		pkg_setup
+	</listitem>
+	<listitem>
+		src_unpack
+	</listitem>
+	<listitem>
+		src_compile
+	</listitem>
+	<listitem>
+		src_test
+	</listitem>
+	<listitem>
+		src_install
+	</listitem>
+	<listitem>
+		pkg_preinst
+	</listitem>
+	<listitem>
+		pkg_postinst
+	</listitem>
+	<listitem>
+		pkg_prerm
+	</listitem>
+	<listitem>
+		pkg_postrm
+	</listitem>
+	</itemizedlist>
+	</para>
+</sect1>
diff --git a/doc/portage.docbook b/doc/portage.docbook
index 1ca868722..6b3f53e1f 100644
--- a/doc/portage.docbook
+++ b/doc/portage.docbook
@@ -7,7 +7,12 @@
 
 	<!ENTITY project "portage">
 
+	<!ENTITY package SYSTEM "package.docbook">
+	<!ENTITY package_ebuild SYSTEM "package/ebuild.docbook">
+	<!ENTITY package_ebuild_phases SYSTEM "package/ebuild/phases.docbook">
 	<!ENTITY qa SYSTEM "qa.docbook">
+	<!ENTITY config SYSTEM "config.docbook">
+	<!ENTITY config_bashrc SYSTEM "config/bashrc.docbook">
 ]>
 
 <book id="portage" lang="en">
@@ -27,6 +32,8 @@
  &date;
 </bookinfo>
 
+&config;
+&package;
 &qa;
 
 </book>