The Perl script
build-web.pl is the
heart of build-web. See the build-web.pl manpage
for more details.
Depending upon the options with which it is started,
build-web.pl performs the following
actions:
Makefiles with the name Makefile.pre will be
executed in the Source Physical Directory tree before any
other processing and can produce new files or directories which will be
copied to the Destination Physcical Directory tree.
If the Destination Directories do not exist, they are created.
The following Source Directories are not copied
The following Source Files are not copied:
Files which exist in the Destination Directories but not
in the Source Directories are deleted from the Destination
Directories unless the noclean argument is passed to the
build-web.pl script.
Source Files are processed according to their type:
HTML Files (identified by their file extension of .html or .htm) are written to the Destination Physical Directory after application of the appropriate templates, Directory Remapping and the replacement of all Server Side Includes (SSI) with the contents of the included files.
template.html (full template including navigation) and template-nomenu.html (template wihthout full navigation) are special HTML files located in the Source Physical Directory.
By default, all HTML files will be wrapped in the template.html template. This may be overridden in each directory by listing the filename on distinct lines in either the NOMENU or NOWRAP text files in each directory.
Any file listed in the NOMENU file will be wrapped with the template-nomenu.html file, while any file listed in the NOWRAP file will not be wrapped in a template at all. However, all HTML Files will have their references to directories remapped according to the DIRMAP.pl program.
Each Template file uses special strings which are replaced by the corresponding parts of the HTML file being wrapped:
Server Side includes in HTML Files, including the template files,
may be replaced by the contents of the included files. The included files must
reside in the Source Physical Directory tree and are not copied to the
Destination Directories as long as their file name ends in -incl.html.
The Server Side includes may be
either file or virtual, but typically virtual is the most
useful.
Text Files (identified by the file extensions .xml, .txt, .css, .js) are written to the Destination Physical Directory after Directory Remapping.
Binary Files (any file not an HTML file or a Text file) are copied written to the Destination Physical Directory without change.
Source Files are copied if their modification times are
different from the modification times of the existing
Destination files. If a template.html,
template-nomenu.html have been modified since
the last build, each HTML file is automatically rebuilt.
If a NOWRAP or NOMENU file is modified since the last build, each HTML file listed in the NOWRAP or NOMENU file is rebuilt. However, if a file name is removed from NOWRAP or NOMENU files, there is no guarantee that the file will be rebuilt in the destination.
Note that changes in any included files will not be detected and will not result in the HTML files being rebuilt which include the included file. You must either clean the Destination Physical Directory or manually delete the files from the Destination Physical Directory you need to be rebuilt.
Directory Mapping is performed by the specified "dirmap.pl" Perl script. The script specifies the remapping of the Source Web Directory names in the Source Physical Directory into the Destination Web Directory names in the Destination Physical Directory.
"dirmap.pl", which can be named anything, consists of a single Hash which specifies the old=>new directory remapping as in:
$WEBDIRMAP{'/fromdir/'} = '/todir/';
Note that $WEBDIRMAP must contain at least a mapping for
the Source Web Directory to the new Destination Web directory. $WEBDIRMAP
may contain any number of additional directory mappings. These can be used when
building a Destination Web from more than one separate build-web project.
Possible Enhancment: Allow ability to specify files which are not processed by the directory remapping. This has great performance implications regarding hosting raw data such as the Cross Brower XML Data documents or external systems such as DOCBOOK which will never require directory remapping.
Makefiles with the name "Makefile.post" will be executed in the Destination Physical Directory tree after all files are processed and copied and can be used to post process output files generated during the build. For example, zip files of the final versions of files in the Destination Physical Directory tree can be created using post Makefiles.
| Build Web Home |