Clean up doc, readdress gentoo bug #322759

author: Anthony G. Basile <blueness@gentoo.org> 2012-06-27 20:37:22 -0400
committer: Anthony G. Basile <blueness@gentoo.org> 2012-06-27 20:37:22 -0400
commit: 94f241acb9a3998c1ea41fe74a44091b1dff72eb (patch)
tree: 99331de324ce870386146ecfef3c438901585291 /doc
parent: Remove examples (diff)
download: webapp-config-94f241acb9a3998c1ea41fe74a44091b1dff72eb.tar.gz
webapp-config-94f241acb9a3998c1ea41fe74a44091b1dff72eb.tar.bz2
webapp-config-94f241acb9a3998c1ea41fe74a44091b1dff72eb.zip
3 files changed, 2 insertions, 569 deletions
diff --git a/doc/Makefile b/doc/Makefile
index aaace8a..4dc8e44 100644
--- a/doc/Makefile
+++ b/doc/Makefile
@@ -14,8 +14,8 @@
 #
 # ========================================================================
 
-MAN_PAGES = webapp-config.8 webapp-config.5 webapp.eclass.5
-HTML_PAGES = webapp-config.8.html webapp-config.5.html webapp.eclass.5.html
+MAN_PAGES = webapp-config.8 webapp-config.5 webapp-eclass.5
+HTML_PAGES = webapp-config.8.html webapp-config.5.html webapp-eclass.5.html
 
 TMPFILE=./webapp-config.man
 
diff --git a/doc/webapp.eclass.5.xml b/doc/webapp-eclass.5.xml
index f310f56..f310f56 100644
--- a/doc/webapp.eclass.5.xml
+++ b/doc/webapp-eclass.5.xml
diff --git a/doc/webapp-eclass.xml b/doc/webapp-eclass.xml
deleted file mode 100644
index 569b353..0000000
--- a/doc/webapp-eclass.xml
+++ /dev/null
@@ -1,567 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
-<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/proj/en/webapps/webapp-eclass.xml,v 1.3 2006/01/19 16:43:24 rl03 Exp $ -->
-
-<guide link="/proj/en/webapps/webapp-eclass.xml" lang="en">
-<title>webapp.eclass Documentation</title>
-
-<author title="Author">
-  <mail link="rl03@gentoo.org">Renat Lumpau</mail>
-</author>
-
-<abstract>
-The goal of this guide is to teach the reader how to create and maintain ebuilds
-for web applications. It presents an overview of the webapp.eclass and then
-discusses three ebuilds of increasing complexity and functionality.
-</abstract>
-
-<!-- The content of this document is licensed under the CC-BY-SA license -->
-<!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
-<license/>
-
-<version>1.0</version>
-<date>2006-01-17</date>
-
-<chapter>
-<title>Introduction</title>
-<section>
-<title>Background</title>
-<body>
-
-<p>
-<c>webapp.eclass</c> and <c>webapp-config</c> provide a standardized way to
-maintain web applications on Gentoo. Server administrators can use the
-<c>webapp-config</c> utility to install, upgrade, and remove software.
-<c>webapp-config</c> relies on a package manager such as Portage to prepare
-the application for installation into multiple virtual hosts. On Gentoo, this
-is done by an ebuild that uses <c>webapp.eclass</c>.
-</p>
-
-<p>
-The goal of this guide is to teach the reader how to create and maintain
-ebuilds for web applications. It presents an overview of the
-<c>webapp.eclass</c> and then discusses three ebuilds of increasing complexity
-and functionality. Using the <c>webapp-config</c> utility is beyond the scope
-of this guide and is documented in <c>man 8 webapp-config</c>.
-</p>
-
-</body>
-</section>
-<section>
-<title>Prerequisites</title>
-<body>
-
-<p>
-This guide assumes a basic familiarity with Portage and the ebuild format. Both
-are well-documented; the reader is encouraged to consult the <uri
-link="/proj/en/devrel/handbook/handbook.xml">official ebuild HOWTO</uri> and
-the unofficial <uri
-link="http://dev.gentoo.org/~plasmaroo/devmanual/">devmanual</uri>.
-</p>
-
-<p>
-<c>webapp-config</c> is under active development. Be sure to install the latest
-version; as of the time of this writing, it is 1.50.7. You can follow the
-development process on our <uri
-link="http://www.vhost-tools.org/">website</uri>.
-</p>
-
-</body>
-</section>
-<section>
-<title>A standardized approach to installing web applications</title>
-<body>
-
-<p>
-Gentoo has developed a standardized way of handling web applications. It is
-outlined in <uri link="/proj/en/glep/glep-0011.html">GLEP 11</uri> and
-discussed in detail in <c>man 5 webapp.eclass</c>. The reader is urged to
-familiarize himself with these documents before proceeding. The manpage also
-outlines the filesystem locations into which the eclass and
-<c>webapp-config</c> install files; advanced users and developers should take
-note.
-</p>
-
-<p>
-The <c>webapp.eclass</c> is located in the usual place in the Portage tree. By
-default, it will be found in <path>/usr/portage/eclass/webapp.eclass</path>. By
-definition, the source code is the ultimate documentation and should be
-consulted whenever something does not perform as expected or further
-clarification is required.
-</p>
-</body>
-</section>
-</chapter>
-
-<chapter>
-<title>Writing Ebuilds</title>
-<section>
-<title>Beginner: www-apps/gallery-2.0.2</title>
-<body>
-
-<p>
-Many web applications require no compilation and are installed by copying their
-files to a directory to be served by a httpd server such as Apache. The
-<c>webapp.eclass</c> simplifies this task by preparing the necessary set of
-directories.
-</p>
-
-<p>
-Let's take a look at a simple ebuild for <uri
-link="http://sources.gentoo.org/viewcvs.py/gentoo-x86/www-apps/gallery">www-apps/gallery-2.0.2</uri>.
-To use any of the functions in the eclass, the ebuild must first inherit it:
-</p>
-
-<pre caption="Inheriting the eclass">
-inherit webapp.eclass
-</pre>
-
-<p>
-The ebuild then sets several standard variables, such as <c>DESCRIPTION</c>,
-<c>IUSE</c>, <c>RDEPEND</c>, and <c>S</c>. The first important note is that
-ebuilds that use the <c>webapp.eclass</c> do not typically set the <c>SLOT</c>
-variable (the rationale for this is described in the manpage). <uri
-link="#doc_chap2_sect3">Section 2.3</uri> will explain how <c>SLOT</c> can be
-set when it is truly needed, but for now we will let the eclass handle it.
-</p>
-
-<note>
-Unless explicitly overridden, the eclass sets <c>SLOT="${PVR}"</c>. One
-important downside of this behavior is that security revision bumps are no
-longer possible. This is unfortunate and will be changed soon.
-</note>
-
-<p>
-<path>www-apps/gallery-2.0.2</path> does not require patching or compiling, so
-the ebuild does not call <c>src_unpack</c> or <c>src_compile</c>; installation
-is handled in <c>src_install</c>. The first thing <c>src_install</c> does is
-call a special helper function that sets up the required directory structure:
-</p>
-
-<pre caption="Setting up src_install">
-src_install() {
-  webapp_src_preinst
-</pre>
-
-<p>
-This function is required of all ebuilds that use the <c>webapp.eclass</c> and
-override the default <c>src_install</c>.
-</p>
-
-<p>
-Having set up the environment, the ebuild installs the web application:
-</p>
-
-<pre caption="Installing">
-cp -R * ${D}/${MY_HTDOCSDIR}
-</pre>
-
-<p>
-<c>${MY_HTDOCSDIR}</c> is one of the variables exported by
-<c>webapp_src_preinst</c>. Files placed there will be copied into the right
-directory under the webserver's document root by <c>webapp-config</c>. For a
-full list of variables exported by the eclass, please see the manpage.
-</p>
-
-<p>
-Next, the ebuild marks a file in <c>${FILESDIR}</c> as a file containing
-instructions to be displayed by <c>webapp-config</c> after the application has
-been installed:
-</p>
-
-<pre caption="Post-install instructions">
-webapp_postinst_txt en ${FILESDIR}/postinstall-en2.txt
-</pre>
-
-<note>
-A careful reader will observe that it is customary for other ebuilds to display
-instructions to the user in <c>pkg_postinst</c>. Ebuilds that inherit
-<c>webapp.eclass</c> may still do so, but the ebuild author should understand
-the important difference in usage. More often than not, post-install
-instructions include information specific to a virtual host, such as locations
-of a particular configuration file or a URL to access the web application
-remotely. This information is not available to Portage and cannot be included
-in <c>pkg_postinst</c>. Instead, it should be included in a post-install file
-and installed using <c>webapp_postinstall_txt</c>.
-</note>
-
-<p>
-Let's examine a typical post-install file:
-</p>
-
-<pre caption="Post-install file">
-  0. Create a new MySQL database:
-  mysqladmin create geeklog
-
-  1. Edit ${VHOST_ROOT}/${PN}-${PVR}/config.php and set database settings.
-
-  2. Login on
-  http://${VHOST_HOSTNAME}/${VHOST_APPDIR}/admin/install/install.php
-  and follow the directions.
-
-  3. Don't forget to delete the admin/install directory when you're done!
-</pre>
-
-<p>
-Post-install instruction files are plain text files. They can contain
-bash-style variables (e.g., <c>${PN}</c>) that will be expanded at display
-time. The <c>webapp-config</c> utility responsible for displaying the file
-exports a number of variables that allow for the customization of instructions.
-Consult the manpage for a list of available variables.
-</p>
-
-<p>
-Finally, the ebuild calls another mandatory helper function:
-</p>
-
-<pre caption="webapp_src_install">
-webapp_src_install
-</pre>
-
-<p>
-<c>webapp_src_install</c> is responsible for setting the right permissions on
-installed files.
-</p>
-
-<p>
-There are several best practices for writing simple ebuilds:
-</p>
-
-<ul>
-  <li>
-    Don't copy unneeded files. Some packages include <path>.svn</path> or
-    <path>CVS</path> directories or <path>Makefiles</path>; those should be
-    removed prior to installation. Note that the <path>LICENSE</path> file is
-    sometimes needed by the application and should not be removed.
-  </li>
-  <li>
-    Ensure that consecutive calls to all ebuild functions succeed. For
-    instance, don't remove files outside of <c>src_unpack</c>. If you must,
-    remove files from <c>${D}</c> rather than <c>${S}</c>.
-  </li>
-  <li>
-    For portability purposes, don't use GNU-only extensions such as <c>cp
-    -a</c>. They will break on non-GNU userlands such as Gentoo/FreeBSD.
-  </li>
-</ul>
-
-</body>
-</section>
-<section>
-<title>Intermediate: www-apps/tikiwiki-1.9.2</title>
-<body>
-
-<p>
-Many web applications have a more complicated installation procedure. Let's
-look at how <uri
-link="http://sources.gentoo.org/viewcvs.py/gentoo-x86/www-apps/tikiwiki">www-apps/tikiwiki-1.9.2</uri>
-handles one such package. After inheriting the eclass, the ebuild specifies a
-number of required and optional dependencies.
-</p>
-
-<pre caption="Specifying Dependencies">
-RDEPEND="virtual/php
-  mysql? ( >=dev-db/mysql-4 )
-  postgres? ( dev-db/postgresql )
-  graphviz? ( media-gfx/graphviz )
-"
-</pre>
-
-<p>
-Many web-applications written in PHP require that the PHP binary have certain
-capabilities built-in; common requirements include support for sessions and a
-specific database engine. This is typically accomplished by using the
-<c>depend.php</c> eclass; unfortunately, the author is not aware of any existing
-documentation for that eclass. The reader is referred to the eclass itself for
-further information and encouraged to consult relevant ebuilds in Portage.
-</p>
-
-<warn>
-If the package requires specific Perl modules, all dependencies must have
-ebuilds available. Relying on CPAN is not acceptable.
-</warn>
-
-<p>
-A common mistake with specifying dependencies for web applications is to
-unconditionally <c>RDEPEND</c> on a database engine such as MySQL or
-PostgreSQL.  Many, if not all, web applications are able to connect to a remote
-database server. Thus, a local database should not be a requirement; the right
-syntax for dealing with this is:
-</p>
-
-<pre caption="Database Dependencies">
-mysql? ( >=dev-db/mysql-4 )
-</pre>
-
-<note>
-It is currently not possible to depend on a generic webserver. Instead, you
-must explicitly specify the webserver (e.g., <path>net-www/apache</path>). This
-is inconvenient and has been reported in <uri
-link="http://bugs.gentoo.org/show_bug.cgi?id=11007">bug #11007</uri>; we hope
-that this issue will be resolved soon.
-</note>
-
-<p>
-<path>www-apps/tikiwiki</path> does not use <c>depend.php</c> and instead uses
-<c>pkg_setup</c> to print a warning:
-</p>
-
-<pre caption="pkg_setup()">
-pkg_setup () {
-  webapp_pkg_setup
-  einfo "Make sure your PHP is compiled with mysql or postgres support"
-  einfo "If you need PDF generation, make sure your PHP is emerged with xml2"
-}
-</pre>
-
-<p>
-Note the use of a mandatory helper function <c>webapp_pkg_setup</c>.
-</p>
-
-<p>
-Many web applications require write access to certain files. The eclass
-provides a helper function that marks a file as server-owned; at install time,
-<c>webapp-config</c> will ensure that it has the right owner and permissions:
-</p>
-
-<pre caption="webapp_serverowned">
-webapp_serverowned ${MY_HTDOCSDIR}/tiki-install.php
-</pre>
-
-<p>
-<c>webapp_serverowned</c> takes an optional <c>-R</c> flag to recurse into
-subdirectories. This flag has been added recently and not many ebuilds take
-advantage of it. Please consult the manpage for more information.
-</p>
-
-<p>
-Practically all web applications use configuration files to store settings.
-Such files should not be placed into <path>/etc</path> (figuring out the
-rationale is left as an exercise for the reader). To avoid losing important
-configuration information, the eclass provides another helper function that
-will instruct <c>webapp-config</c> not to overwrite an existing file. The
-administrator can use familiar tools such as <c>etc-update</c> or
-<c>dispatch-conf</c> to manage such files.
-</p>
-
-<pre caption="webapp_configfile">
-webapp_configfile ${MY_HTDOCSDIR}/config.php
-</pre>
-
-<p>
-Note that it is currently not possible to mark a file as both server-owned and
-config-protected. This has been fixed in an upcoming version of
-<c>webapp-config</c>. For now, there is a workaround described in <uri
-link="#doc_chap2_sect3">Section 2.3</uri>.
-</p>
-
-<p>
-To ease upgrades of web applications, the eclass provides a helper function
-that displays instructions when an existing installation is being upgraded:
-</p>
-
-<pre caption="Post-upgrade file">
-webapp_postupgrade_txt en ${FILESDIR}/postupgrade-en.txt
-</pre>
-
-<p>
-Even though no ebuilds in Portage currently take advantage this functionality,
-the reader is encouraged to use it in his ebuilds.
-</p>
-
-<p>
-The ebuild calls the familiar helper function to complete the installation.
-Note an important consequence of using <c>webapp_src_install</c> to set the
-correct file permissions: any manual adjustments to file permissions and
-ownership via <c>fowners</c> and <c>fperms</c> must occur <e>after</e>
-<c>webapp_src_install</c> is called.
-</p>
-
-<pre caption="Adjusting permissions">
-webapp_src_install
-fperms 0644 /etc/zm.conf
-</pre>
-
-<p>
-The tikiwiki ebuild displays some brief notes using <c>pkg_postinst</c>. Note
-the use of another helper function:
-</p>
-
-<pre caption="pkg_postinst">
-pkg_postinst() {
-  einfo "To setup a MySQL database, run:"
-  einfo "\"emerge --config =${PF}\""
-  einfo "If you are using PostgreSQL, consult your documentation"
-  webapp_pkg_postinst
-}
-</pre>
-
-<p>
-Strictly speaking, <c>webapp_pkg_postinst</c> is not mandatory. It is
-responsible for automatically calling <c>webapp-config</c> when the
-<c>vhosts</c> USE flag is unset. In rare instances it may be desirable to
-override this behavior; please consult <path>www-apps/otrs</path> for an
-example.
-</p>
-
-</body>
-</section>
-<section>
-<title>Advanced: www-apps/moinmoin-1.5.0</title>
-<body>
-
-<p>
-This section presents an overview of more advanced installation tasks provided
-by the <c>webapp.eclass</c>. An example of this functionality is <uri
-link="http://sources.gentoo.org/viewcvs.py/gentoo-x86/www-apps/moinmoin">www-apps/moinmoin-1.5.0</uri>.
-</p>
-
-<p>
-<c>moinmoin</c> is a wiki engine written in Python that uses <c>distutils</c>
-to install itself. Thus, it requires <c>SLOT="0"</c> to avoid collisions.
-Ebuilds that inherit <c>webapp.eclass</c> must set
-<c>WEBAPP_MANUAL_SLOT="yes"</c> to override the default <c>SLOT</c>ting
-behavior:
-</p>
-
-<pre caption="Setting SLOT">
-SLOT="0"
-WEBAPP_MANUAL_SLOT="yes"
-</pre>
-
-<note>
-The <c>yes</c> in <c>WEBAPP_MANUAL_SLOT="yes"</c> is case-sensitive.
-</note>
-
-<p>
-<c>moinmoin</c> installs files that should not be served by the webserver. The
-ebuild places such files in <c>${MY_HOSTROOTDIR}/${PF}</c>.
-</p>
-
-<pre caption="Installing into dodir ${MY_HOSTROOTDIR}/${PF}">
-dodir ${MY_HOSTROOTDIR}/${PF}
-cp -r data underlay config/wikiconfig.py ${D}/${MY_HOSTROOTDIR}/${PF}
-</pre>
-
-<p>
-A best practice for installing any application via Portage is to ensure it
-operates out of the proverbial box with sensible defaults. The eclass
-implements a helper function to aid with configuring the application after it
-has been installed by <c>webapp-config</c>.
-</p>
-
-<pre caption="webapp_hook_script">
-webapp_hook_script ${FILESDIR}/reconfig-2
-</pre>
-
-<p>
-The reconfig hook is a script, typically written in bash, that is invoked by
-<c>webapp-config</c> after installation and before removal.
-</p>
-
-<pre caption="Reconfig hook">
-#!/bin/bash
-
-die() {
-  echo "#####"
-  echo $1
-  echo "#####"
-  exit 1
-}
-
-if [ $1 = "install" ]; then
-  sed -e "s|/path/to/wikiconfig|${VHOST_ROOT}/${PN}-${PVR}|g" \
-    -i ${MY_INSTALLDIR}/moin.cgi || die "sed failed"
-  sed -e "s|\./data/|${VHOST_ROOT}/${PN}-${PVR}/data|
-    s|\./underlay/|${VHOST_ROOT}/${PN}-${PVR}/underlay|" \
-    -i ${VHOST_ROOT}/${PN}-${PVR}/wikiconfig.py || die "sed failed"
-
-elif [ $1 = "clean" ]; then
-  echo $1
-fi
-</pre>
-
-<p>
-The reconfig hook can use the same variables as the postinstall file. It is
-typically used to edit configuration files to set file locations that may
-differ from the default values. As of <c>webapp-config-1.50</c>, reconfig hooks
-are run in a sandbox to minimize risk; please consult the manpage for more
-details.
-</p>
-
-<p>
-There are several best practices for using reconfig hooks:
-</p>
-
-<ul>
-  <li>Die with an error message if the script failed</li>
-  <li>
-    Be careful about removing files when called with <c>clean</c>. Don't remove
-    configuration files or any other files that may have been locally
-    modified.
-  </li>
-  <li>
-    To mark a file as both config-protected and server-owned, use
-    <c>webapp_configfile</c> from the ebuild and use the reconfig hook to mark
-    it as server-owned:
-  </li>
-</ul>
-
-<pre caption="Using the reconfig hook to mark files as server-owned">
-chown ${VHOST_SERVER_UID}:${VHOST_SERVER_GID} ${MY_INSTALLDIR}/Settings.php
-</pre>
-
-<p>
-The eclass provides several other functions that are rarely used. The most
-notable is <c>webapp_sqlscript</c>, which marks a file as an SQL create script.
-In its current state, this function is only moderately useful.
-</p>
-
-</body>
-</section>
-</chapter>
-
-<chapter>
-<title>Additional Best Practices</title>
-<section>
-<title>Apache</title>
-<body>
-
-<ul>
-  <li>
-    Be careful when installing apache configuration files. If you place a
-    misconfigured Apache configuration file into
-    <path>/etc/apache{2}/vhosts.d</path>, the server will fail on next restart.
-    Is is better to either install the file elsewhere and let the administrator
-    customize it, or comment out the contents to avoid failure.
-  </li>
-</ul>
-
-</body>
-</section>
-</chapter>
-
-<chapter>
-<title>Next Steps</title>
-<section>
-<title>Obtaining More Information</title>
-<body>
-
-<p>
-Additional examples can be found in the <path>www-apps</path> category of the
-Portage tree. Developers and users should also consult the <uri
-link="http://svn.gnqs.org/projects/gentoo-webapps-overlay">web-apps
-overlay</uri> for even more examples and software packages.
-</p>
-
-<p>
-If you have a question that is not answered in this document, please feel free
-to contact the <uri
-link="http://svn.gnqs.org/projects/gentoo-webapps-overlay/wiki/Contributors">web-apps
-herd</uri> or ask on <uri link="irc://freenode/gentoo-web">IRC</uri>.
-</p>
-
-</body>
-</section>
-</chapter>
-</guide>
author	Anthony G. Basile <blueness@gentoo.org>	2012-06-27 20:37:22 -0400
committer	Anthony G. Basile <blueness@gentoo.org>	2012-06-27 20:37:22 -0400
commit	94f241acb9a3998c1ea41fe74a44091b1dff72eb (patch)
tree	99331de324ce870386146ecfef3c438901585291 /doc
parent	Remove examples (diff)
download	webapp-config-94f241acb9a3998c1ea41fe74a44091b1dff72eb.tar.gz webapp-config-94f241acb9a3998c1ea41fe74a44091b1dff72eb.tar.bz2 webapp-config-94f241acb9a3998c1ea41fe74a44091b1dff72eb.zip