Add some documentation for ebuild phases and pre/post phase

hooks that can be defined via bashrc.

svn path=/main/trunk/; revision=8876

diff --git a/doc/config.docbook b/doc/config.docbook
index 39c560080c4e9f5950bd2c4a41912d37ed8fd2c5..88009dfc6f65c8a3c73906231ccbec3442e98e3a 100644 (file)
--- a/doc/config.docbook
+++ b/doc/config.docbook
@@ -1,4 +1,5 @@
 <part id='config'>
 <title>Configuration</title>
+&config_bashrc;
 &config_set;
 </part>

diff --git a/doc/config/bashrc.docbook b/doc/config/bashrc.docbook
new file mode 100644 (file)
index 0000000..2f06262
--- /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 (file)
index 0000000..d37e6d5
--- /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 (file)
index 0000000..5466f99
--- /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 (file)
index 0000000..5c7f049
--- /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 ac1061310131bc0947a49347a2b6b9a27f51f9aa..5417bb73e7ee5cb22f18d58a835e352e247b6af0 100644 (file)
--- a/doc/portage.docbook
+++ b/doc/portage.docbook
@@ -7,8 +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">
        <!ENTITY config_set SYSTEM "config/sets.docbook">
 ]>
 
@@ -30,6 +34,7 @@
 </bookinfo>
 
 &config;
+&package;
 &qa;
 
 </book>