\section{eisbuild}

\newcommand{\eisbuildexample}[1]{\emph{Example:} #1}

\subsection{What is eisbuild?}
  You can use eisbuild to make it easier to build and maintain eisfair-packages.
  eisbuild is something like the debhelper-tools from Debian, for those who know
  Debian. It uses a \jump{EISBUILDCONTROLFILE}{control-file} which has a similar
  style like the debhelper-tools (the syntax of those
  \jump{EISBUILDCONTROLFILE}{control-files} is described below).

\subsection{Why to use eisbuild?}
  eisbuild can be used to make it easier to...
  \begin{itemize}
    \item{... build new or maintain packages}
    \item{... write the deinstall-script}
    \item{... hold the .info-file actual and refresh it automatically}
  \end{itemize}

\subsection{History}
  I wrote eisbuild because of the need of a tool which can make it easier
  to build a eisfair-package. The first version (not published) was a complex
  makefile. To define a new package, it was needed to write a include-file for
  the makefile. Then after some weeks i rewrote everything as a shell-script and
  introduced the control- and rules-files. There were also some other improvments
  like a easier user-interface and the autoconf/automake-installation.

\subsection{Where to get eisbuild?}
  You can download eisbuild at \url{http://www.hansmi.ch/eisbuild/}.

\subsection{Installation}
  eisbuild can be installed with the following commands:
  \begin {verbatim}
    tar xvzf eisbuild-x.x.x.tar.gz
    cd eisbuild-x.x.x
    ./configure
    make
    make install
  \end{verbatim}

\subsection{How to use it?}
  To make a new eisfair-package, you've to write the
  \jump{EISBUILDCONTROLFILE}{control-file}, the
  \jump{EISBUILDRULESFILE}{rules-file(s)} and to create the
  \jump{EISBUILDADDITIONALFILESFOLDER}{additional\_files}-folder.

\subsubsection{Commandline-Options}
  You've to call eisbuild with:
  \begin {verbatim}
    eisbuild [options1] <action> [options2]
  \end{verbatim}
  Where [options1] is one of:
  \begin {verbatim}
    --help                general help
    --debug               enable debugmode
    --controlfile=<file>  name of the controlfile
  \end{verbatim}
  The <action> defines what eisbuild should do. It can be one of:
  \begin {verbatim}
    unpack                unpack the sources
    distclean             remove the source-directories
    clean                 executes the target "clean" in all rule-files
    build                 compile the sources if it's needed
    pack                  pack the binaries and scripts together
  \end{verbatim}
  The allowed options for [options2] are:
  \begin {verbatim}
    Action "build":
      --forcebuild  do a build even if it's not really needed
    Action "pack":
      --to-bz2      pack to a .tar.bz2-archive instead of a .tar.gz-archive
    Other actions:
      no options available
  \end{verbatim}

\marklabel{EISBUILDCONTROLFILE}{\subsubsection{The control-file}}
  This file includes the relevant informations about the package. It's
  the most relevant file for the build-process because it includes
  all definitions.
  
  \subsubsection{Common}
    This file has the syntax
    \begin {verbatim}
      Tag1: value
      Tag2: value
    \end{verbatim}
    The tags and values are case-sensitive!

  \subsubsection{Tags}
    \begin{description}
      \config{Package}{Package}{EISBUILDTAGPACKAGE}
        Describe the package-name. The only allowed chars
        here are [A-z0-9] and \_.

        \eisbuildexample{Package: xml-tools}

      \config{Short}{Short}{EISBUILDTAGSHORT}
        A short description of what the package does. (approx. 60 chars)

        \eisbuildexample{Short: xmlclitools and libxml2}

      \config{Section}{Section}{EISBUILDTAGSECTION}
        One of the following values:
        \begin{itemize}
          \item admin - admin-tools to install and configure
          \item utils - sed, grep, links and co - everything that helps on the console
          \item comm - serial interface 
          \item devel - gcc and co
          \item game - gameproxies etc
          \item interpreter - perl, ruby, python and co.
          \item lib - zlib, openssl and co
          \item net - everything around the network
          \item news - everything around news
          \item mail - everything around mail
          \item misc - everything other
          \item web - everything around the web
        \end{itemize}

        \eisbuildexample{Section: utils}

      \config{Version}{Version}{EISBUILDTAGVERSION}
        This is the actual package-version. (needs to be changed for a new
        release; planed to be updated automatically). Only numeric values are
        allowed in the version!

        \eisbuildexample{Version: 1.0.1} 
	
      \config{Date}{Date}{EISBUILDTAGDATE}
        Release date of the package. (needs to be changed for a new release;
        planed to be updated automatically)

        \eisbuildexample{Date: 2002/11/02}

      \config{Author}{Author}{EISBUILDTAGAUTHOR}
        The author of the package. A control-file can have more than one
        author.

        \eisbuildexample{Author: Michael Hanselmann, {\flq}hansmi@eisfair.org{\frq}}

      \config{Status}{Status}{EISBUILDTAGSTATUS}
        The status of the package. This is one of stable, testing or unstable.

        \eisbuildexample{Status: stable}

      \config{AdditionalFiles}{AdditionalFiles}{EISBUILDTAGADDITIONALFILES}
       You can specify the folder for additional files here. It is by default on
        ``additional\_files'' and shouldn't be changed if you don't really need it.

        \eisbuildexample{AdditionalFiles: additional\_files}

      \config{Source}{Source}{EISBUILDTAGSOURCE}
        The URL of the sourcecode. Because you can
        include more than one source-package into one eisfair-packge, it's possible
        to define more than one Source-tag in the control-file.

        \eisbuildexample{Source: http://robur.slu.se/jensl/xmlclitools/}

      \config{Require}{Require}{EISBUILDTAGREQUIRE}
        If a package needs another package, then you can specifiy it here. Mostly
        this will be the base-package. Here it's also possible to specify more than
        one Require-tag in the control-file.

        \eisbuildexample{Require: base-1.0.2}

      \config{Description}{Description}{EISBUILDTAGDESCRIPTION}
        The desciption of the package. Because the most descriptions are long, this
        tag can be used more than one times in the control-file.

        \eisbuildexample{Description: These package include the xmlclitools which can be\\}
        \eisbuildexample{Description: used to read XML-Files and the libxml2 which is used\\}
        \eisbuildexample{Description: by serveral programs.}

      \config{Sourcecode\_N}{Sourcecode\_N}{EISBUILDTAGSOURCECODEN}
        The number of sourcecode-archives which should be compiled in.

        \eisbuildexample{Sourcecode\_N: 1}

      \config{Sourcecode\_x\_Filename}{Sourcecode\_x\_Filename}{EISBUILDTAGSOURCECODEFILENAME}
        This is the sourcecode-archive.

        \eisbuildexample{Sourcecode\_x\_Filename: xmlclitools-1.41.tar.gz}

      \config{Sourcecode\_x\_Directory}{Sourcecode\_x\_Directory}{EISBUILDTAGSOURCECODEDIRECTORY}
        The sourcecode-archive'll be unpacked into this directory. This can
        vary from package to package!

        \eisbuildexample{Sourcecode\_x\_Directory: xmlclitools}

        Many times it's something like:

        \eisbuildexample{Sourcecode\_x\_Directory: package-x.x.x}

        Please read in the Makefile of the sourcecode to get
        the right variable!

      \config{Sourcecode\_x\_Rulesfile}{Sourcecode\_x\_Rulesfile}{EISBUILDTAGSOURCECODERULESFILE}
        Defines which file includes the build-rules. See also
        ``\jump{EISBUILDRULESFILE}{The rules-file}''

    \end{description}

  \marklabel{EISBUILDRULESFILE}{\subsubsection{The rules-file}}
    The rules-file is a file with the Makefile-syntax and has some
    build-rules in it. To make a successfull build of a eisfair-package,
    you've to write the following rules:
    \begin{description}
      \config{build}{build}{EISBUILDRULESBUILD}
        This is the main rule. Normally you have to run ``configure'' and ``make'' here.

        \eisbuildexample{./configure --disable-debug --prefix=/usr\\}
        \eisbuildexample{\$(MAKE)}

      \config{install}{install}{EISBUILDRULESINSTALL}
        In this rule, you've to install the source into the \$(INSTALLDIR)-directory.
        This can mostly be done with:

        \eisbuildexample{\$(MAKE) DESTDIR=\$(INSTALLDIR) install}

      \config{clean}{clean}{EISBUILDRULESCLEAN}
        This rule is to clean the source.

        \eisbuildexample{\$(MAKE) clean}

      \config{patch}{patch}{EISBUILDRULESPATCH}
        You can apply patches or similar things here.

        \eisbuildexample{patch -p0 \flq ../extended-functions.patch}

    \end{description}
    Please also read the GNU make documentation (\url{http://www.gnu.org/manual/make/index.html})
    for writing the rules-files.

  \marklabel{EISBUILDADDITIONALFILESFOLDER}{\subsubsection{The ``additional\_files''-folder}}
    If you want to add some more things that they are included in the
    sources of the packages, you can copy it into this folder. As
    an example, you can copy the install.sh-file into this folder.
    (the path then would be additional\_files/tmp/install.sh)

\marklabel{EISBUILDAUTHOR}{\subsection{The author}}
  eisbuild is written by Michael Hanselmann, \email{hansmi-AT-eisfair-DOT-org}
  and released under the terms of the GNU GPL License.

  \begin {verbatim}
  This program is free software; you can redistribute it and/or modify
  it under the terms of the GNU General Public License as published by
  the Free Software Foundation; either version 2 of the License, or (at
  your option) any later version.

  This program is distributed in the hope that it will be useful, but
  WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  General Public License for more details.

  You should have received a copy of the GNU General Public License
  along with this program; if not, write to the Free Software
  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
  USA
  \end{verbatim}


