The build-web project

The build-web project contains all scripts, make file rules and documentation for build-web. It is organized as follows:

build-web project configuration

Configuration choices for a Web Project are recorded in the Makefile and directory mapping scripts dirmap-dev.pl and dirmap-prod.pl which live under the project directory.

The Source Web Directory for the build-web project was chosen to be /build-web-srce/. This follows an unofficial convention in build-web projects in general, that the Source Web Directory name is chosen to be the project directory name with -srce appended. This convention helps reduce the possibility that unwanted changes can occur during directory mapping. The Source Web Directory is used when authoring content in order to refer back to the top level of the web project. In general, all SSI's should use paths which begin at the Source Web Directory.

Development builds are intended to be use by developers while testing content which is under development. They do not need to be created with the exact same directory structure as the production version of a project. Production builds are intended to have exactly the same directory structure as the final production version. This difference between Development and Production allows multiple Development versions of Web Projects to be hosted on a single web server each in it's own directory even though the production version of each of the projects expects to live on the root directory of the Web Server.

By convention, the Development version of the directory mapping script for a project is named dirmap-dev.pl while the Production version of the directory mapping script is named dirmap-prod.pl

The Development Destination Web Directory for the build-web project was chosen to be /dev/build-web/ and this is reflected in the dirmap-dev.pl directory mapping script for Development builds. dirmap-dev.pl is a Perl hash to perform directory mapping from the Source Web Directory /build-web-srce/to the Destination Web Directory /dev/build-web/ for Development builds.

The Production Destination Web Directory for the build-web project was chosen to be /build-web/ and is reflected in the dirmap-prod.pl directory mapping script for Production builds. dirmap-prod.pl is a Perl hash to perform directory mapping from the Source Web Directory /build-web-srce/ to the Destination Web Directory /build-web/ for Production builds.

build-web/Makefile

The build-web/Makefile is used to build and clean the build-web project. rules.mak defines various make variables and default rules for making build web sites.

rules.mak creates a number of variables for use in the Makefile which can be overridden by environment variables of the same name or by setting new values in the Makefile itself. 

ifndef BUILD_WEB
$(error you must set BUILD_WEB to point to $(PWD) before doing make)
endif

# default variable and rules
include $(BUILD_WEB_DIR)/bin/rules.mak

SRCEWEBDIR         = /build-web-srce
SSIPROCESS = off

#
# rules
# =====

clean: clean-main 

all:    main

Makefile requires that the environment variable BUILD_WEB be set to the name of the directory containing the build-web project. It then loads rules.mak from that location. The name of the Source Web Directory is customized by setting the SRCEWEBDIR makefile variable, the handling of Server Side includes (SSIPROCESS) is set to not replace the Server Side include with the contents of the included file. All other settings remain at their default values.

Note that main and clean-main are Make targets which are defined in rules.mak. These rules build and clean the web project respectively. It is also possible to include child projects although that will be discussed later.

build-web/dirmap-dev.pl

The dirmap-dev.pl script defines a Perl hash which will be used by the directory mapping code to replace all instances of the hash key ( the string on the left inside of the quotes) with the hash value (the string on the right side). Note that additional directory maps are included besides the one for the Source Web Directory. /xbProjects-srce/ is a separate build-web project which provides a number of reusable javascripts. It could have been included as a child project however since it is used by many scripts in my sites, the reference to xbProjects uses a separate mapping. Note also the use of the '/home-srce/' directory name. This is a convention I use to allow projects to redefine the home pages of child projects.

This file is required by the build-web.pl script. As such it is necessary to end the file with the 1; so that it is successfully included in build-web.pl. 

# build-web dirmap-dev.pl
$::WEBDIRMAP{'/build-web-srce/'} = '/dev/build-web/';
$::WEBDIRMAP{'/xbProjects-srce/'} = '/dev/lib/js/';
$::WEBDIRMAP{'/home-srce/'} = '/dev/build-web/';
1;

build-web/dirmap-prod.pl

# build-web dirmap-prod.pl
$::WEBDIRMAP{'/build-web-srce/'} = '/build-web/';
$::WEBDIRMAP{'/xbProjects-srce/'} = '/lib/js/';
$::WEBDIRMAP{'/home-srce/'} = '/build-web/';
1;

Building the build-web Project

To build the build-web project, do a make in the project directory. By default, a simple make will build the Development version of the site and place the output in the Physical Destination Directory which is build-web/dest-dev. This location can be customized either by editing the Makefile or by creating a symbolic link from build-web/dest-dev to whatever location you wish. Typically, I do a soft link into my web server's document tree which matches the Destination Web Directory name. You can also create the output inside the web project directory and then create a virtual directory in your web server to point to it.

To build the production version of build-web, perform a make BUILDTYPE=prod in the project directory. This will build the Production version of the site in the build-web/dest-prod directory. Again, you are free to customize this location in the same way as described for the Development version.

Build Web Home