GNU Web HowTo

This is step-by-step guideline, how to enable GNU Build System for Web/PHP applications. You can replay all examples on demo.tgz package is distributed with GNU Web. You should find a copy in prefix/share/gnuweb/demo.tgz, where prefix is the installation prefix during configuration either /usr/local or /usr.

1. Create a new project

We would create an empty project and underlying folder structure.

   mkdir web-php-demo
   mkdir web-php-demo/src
   mkdir web-php-demo/tsrc
   mkdir web-php-demo/js
   mkdir web-php-demo/css

We are recommending to maintain the following high-level folder structure for your projects

src

your source code

tsrc

unit test, demos, etc.

js

javascripts

css

stylesheets

2. General settings

You have to create a additional files into root folder of your project (web-php-demo)

• configure.ac, use the template below for simple PHP-based web application

   AC_INIT([web-php-demo], [0.0], [xxx])
   AM_INIT_AUTOMAKE
   #
   # check for programs, configure runtime, PHP and W3C
   ACX_PREFIX
   ACX_PHP
   ACX_W3C
   #
   # defines Makefile rules
   AMX_PHP
   AMX_W3C
   AMX_TARBALL
   #
   # check for libraries
   ACX_CHECK_PHP_LIB([libxyz.php], [], [AC_MSG_NOTICE('Install libxyz.php')])
   ACX_CHECK_JS_LIB([libxyz.js],   [], [AC_MSG_NOTICE('Install libxyz.js')])
   #
   # optional features 
   ACX_FEATURE([fea])
   #
   # output configuration
   AM_CONFIG_HEADER(config.h)
   AC_OUTPUT(         \
        Makefile      \
        js/Makefile   \
        css/Makefile  \
        src/Makefile  \
        tsrc/Makefile \
   )
   ACX_DONE

• root Makefile.am

   SUBDIRS = data doc src tsrc
   #includes additional rules from aminclude.am
   @INC_AMINCLUDE@

• Files NEWS, README, AUTHORS, Changelog to distribute all additional information on your package. They are required by autotools.

3. Makefile.am for PHP scripts

You have to create Makefile.am into web-php-demo/src

   # 
   # This example application: consist of library and UI template
   # 
   
   # library source files
   SRC  = lib-php-demo/demo1.php
   SRC += lib-php-demo/demo2.php
   # source files that implements optional feature
   if HAVE_FEA
   SRC += lib-php-demo/fea.php
   endif
   
   # target library and its component installed into ${libphpdir}
   libphp_SCRIPTS = libphpdemo.php
   nobase_libphp_SCRIPTS = $(SRC)
   
   #bin script is a template in this example
   bin_SCRIPTS = $(PACKAGE).php
   #index.php  executes application from httpd context
   www_SCRIPTS = index.php
   
   CLEANFILES = libphpdemo.php index.php
   EXTRA_DIST = $(SRC)
   
   #includes additional rules from aminclude.am
   @INC_AMINCLUDE@

• libphp_SCRIPTS is automake constructions, "Variables that end with _SCRIPTS are special variables that list of non-native scripts that the resulting Makefile should build." The libphp part tells that the resulting programs should be installed in libphpdir.
• $(SRC) defines all source files that are required to assemble library. One of current limitation is one library per Makefile.
• if HAVE_FEA ... endif includes files into library if FEA is configured, variable HAVE_FEA is automatically managed by ACX_FEATURE([fea]) macro.
• @INC_AMINCLUDE@ is automatically replaced by include $(top_builddir)/aminclude.am. This script contains rules to build libphpdemo.php and index.php.

4. Makefile.am for Javascript

You have to create Makefile.am into web-php-demo/js

   # library source files
   SRC  = demo1.js
   SRC += demo2.js
   # source files that implements optional feature
   if HAVE_FEA
   SRC += fea.js
   endif
   
   #target libraries
   LIB  = libdemo.yc.js libdemo.nc.js
   libjs_SCRIPTS = $(LIB)
   static_DATA   = $(LIB)
   CLEANFILES = $(LIB)
   EXTRA_DIST = $(SRC)
   
   #includes additional rules
   @INC_AMINCLUDE@

• In this example we install javascript both to libjsdir and staticdir
• Javascript libraries a assembled in non-compressed (.nc.js) version and compressed (.yc.js)

5. Makefile.am for Stylesheet

You have to create Makefile.am into web-php-demo/css

   # common stylesheet
   SRC  = demo1.css
   SRC += demo2.css
   # optional stylesheet
   if HAVE_FEA
   SRC += fea.css
   endif
   
   #targets
   CSS  =  libdemo.nc.css libdemo.yc.css
   
   static_DATA = $(CSS)
   CLEANFILES  = $(CSS)
   EXTRA_DIST  = $(SRC)
   
   @INC_AMINCLUDE@

6. Configure package

In the root folder of your project (web-php-demo)

   autoreconf -i
   ./configure

By default everything would be installed under /usr/local

   libphpdir:	 /usr/local/lib/php
   wwwdir:	 /usr/local/var/www
   staticdir:	 /usr/local/var/www/static
   libjsdir:	 /usr/local/lib/js

Adjust configuration according you httpd setup

   ./configure wwwdir=/var/www staticdir=/var/www/static

7. Build and Install package

   make
   make install