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

diff --git a/doc/config.docbook b/doc/config.docbook
new file mode 100644 (file)
index 0000000..118d98b
--- /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 (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 1ca868722e6aabb479f10b35815219b6885284c1..6b3f53e1f47ee0fdb1a74fe5e831c0151d8a7357 100644 (file)
--- 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>