[Phpgroupware-cvs] CVS: packages/doc README.txt,NONE,1.1

[Luca - De Whiskey's - De Vitis <address@hidden>]

Update of /cvsroot/phpgroupware/packages/doc
In directory subversions:/tmp/cvs-serv10903/packages/doc

Added Files:
        README.txt 
Log Message:
- Added basic documentation file.


--- NEW FILE ---
Packages module for phpGroupWare
--------------------------------

0. Contents
===========

    1. Get phpgroupware.
        1.1. Running `do'.
    2. The `do' targets.
        2.1. The `build' target.
            2.1.1. Building by module name.
            2.1.2. Building by package format.
                2.1.2.1. The orig.tar.gz format.
        2.2. The `compile' target.
        2.3. The `release' target.
        2.4. The `install' target.
        2.5. The `lint' target.
        2.6. The `clean' target.
        2.7. The `core' target.
    3. The `do' variables.
        3.1. Configuring from the command line.
        3.2. Configuring from file.
    4. NOTE

1. Get phpgroupware.
====================

    First of all you have to get all the latest phpGroupWare modules cvs
    snapshot. for example Try:

    prompt$ cd /some/directory
    prompt$ CVSROOT=:pserver:address@hidden:/cvsroot/phpgroupware
    prompt$ CVS_RSH=ssh
    prompt$ cvs login
    prompt$ cvs get all packages

    1.1. Running `do'.
    ==================
        The `do' command is a auto executable Makefile. To run it, you have to
        change directory to the same directory as you were when you got the
        latest cvs snapshot; then, you can simply type the following command.

        prompt$ ./packages/do

2. The `do' targets.
====================

    The `do' command, is meant to build phpgroupware packages, in as many
    format as possible. It does not only build the packages: it can releas
    them under a specified common directory (grouping packages by format), or
    apply configurable checks to test the source packages integrity. `do' is
    also capable of directly installing the source under a specified
    directory, so that it can be ready to use.

    2.1. The `build' target.
    ========================

        The default target is `build' which builds all the configured packages
                format for each phpGroupWare module, simply typing:

        prompt$ ./packages/do

        All the packages names reports either the current date in a "%Y%m%d"
        format, or the version specified by the release tag. Each target
        specified can only be achived if all the requisites are met
        (automatically checked).

        2.1.1. Building by module name.
        ===============================

            You can buld each module separately, simply passing one or more
            modules names as argument:

            prompt$ ./packages/do skel
            prompt$ ./packages/do setup phpgwapi

        2.1.2. Building by package format.
        ==================================

            Alternatively, you can build all the modules in one or more
            package format, simply specify them as argument:

            prompt$ ./packages/do tar.gz
            prompt$ ./packages/do deb tar.bz2 rpm

            2.1.2.1. The orig.tar.gz format.
            ================================

            The orig.tar.gz format, is an utility format needed to build
            official Debian packages.

    2.2. The `compile' target.
    ==========================

        The `compile target is responsible of the compiling of the sgml files
        into useful backends formats: txt, html, rtf and eventually ps.
        By now this target is not required, sou you have to manually pass it
        to the `do' commandi before anything else:

        prompt$ ./packages/do compile build

    2.3. The `release' target.
    ==========================

        The `release' target is responsible of installing the builded packages
        in a specified directory, simply typing:

        prompt$ ./packages/do release

        The `RELEASE_DIRECTORY' make variable decides where the packages will
        be installed.

    2.4. The `install' target.
    ==========================

        The `install' target installs the the source code, along with the
        compiled sgml documents, in a specified directory. The result is a
        ready to use phpGroupWare, up to date. To make it happen, type:

        prompt$ ./packages/do install

        The `INSTALL_DIRECTORY' make variable decides where the source will
        be installed.

    2.5. The `lint' target.
    =======================

        The `lint' target apply a list of extensible checks to each source
        module, to test if they comply specified set of rules. To start
        checking, type:

        prompt$ ./packages/do lint

    2.6. The `clean' target.
    ========================

        The `clean' target clean the the source modules from all the file
        genearated so far. To clean all, simply type:

        prompt$ ./packages/do clean

    2.7. The `core' target.
    =======================

    The `core' target is an utility target (needed by `build') used to build
    the core set of phpGroupWare modules under the usual phpgroupware
    directory in a single package. It builds a tar.gz and tar.bz2 format.

3. The `do' variables.
======================

    The `do' command provides some configurable variable under
    ./packages/conf . The are:

        PACKAGES = tar.gz tar.bz2 deb rpm tgz slp
        BUILD_DIRECTORY = packages/.build
        RELEASE_DIRECTORY = /home/ftp/phpgroupware
        INSTALL_DIRECTORY = /var/www

    You can olso safely overwrite the MODULES variable. The MODULES variable
    is not listed above, because it is automatically generated. Overwriting
    it, will cause `do' not to generate it.

    3.1. Configuring from the command line.
    =======================================

        The best way to configure the `do' command is by passing the variable
        from the command line:

        prompt$ ./packages/do 'MODULES = mail nntp'

        The above command make `do' build only the mail and the nntp
        modules. You can overwrite more than one variable:

        promtp$ ./packages/do 'MODULES = polls forum' 'PACKAGES = tar.gz rpm'

        The above command build only tar.gz and rpm packages for the poll and
        forum modules.

    3.2. Configuring from file.
    ===========================

        It is obviously possible, to overwrite the variable from the
        ./packages/conf file its self.

4. NOTE
=======

    (1) By now it's only possible to build tar.gz and tar.bz2 package for all
        the modules. The only module that provides the capability of building
        the other formats is the skel module.

    (2) There are some excluded modules by default:

        - felamimail
        - squirrelmail
        - syncml-server

        The first two are because i still don't know how to cleanly package
        them for debian: it was simplier to exclude them in any case.
        The later is because of a packaging name problem: i choosed to use
        functions instead of mappings for name manipulation for their
        quickness and extensibility, and excluding syncml-server was the less
        worst thing.
        You can generate tar.gz and tar.bz2 for the above mentioned package in
        any case:

        prompt$ ./packages/do felamimail squirrelmail syncml-server \
            'PACKAGES = tar.gz tar.bz2'