WebMake Documentation (version 1.2)

WebMake Operation

When you run WebMake, it'll first search for a file ending with .wmk in the current directory, then in the parent directory, and so on 'til it hits the root directory.

Alternatively if you use the -R switch, it'll search relative to the filename specified on the command-line; this is very handy if you're calling WebMake from a macro in your editor or IDE, as it means you don't even have to be running the editor in the same working directory as the files you're working on.

Anyway, once it finds the WebMake file, it reads the file and parses it. Contents and media statements will cause it to search directories or other data sources for content (directly includable files and text blocks) or media (static content that can be linked to or otherwise referred to with a href). Include statements will cause it to directly include a block of code from another file.

Finally, once the WebMake file has been parsed, the list of out files will have been read. Each of these is roughly equivalent to a target in traditional UNIX make(1) terminology.

If a target has been specified on the command line, that file will be made; otherwise, all the out files named in the WebMake file will be made.

Dependencies And Other Optimisations

"Making" the target is not the end of it -- strictly speaking, the target may or may not be updated. WebMake tracks the dependencies of each file, and if these have not changed, the file will not be rebuilt.

That's the first optimisation. However it doesn't always work; if some of the file's text is generated by, or depends on text that contains dynamic Perl code, WebMake will always have to rebuild the file.

To avoid continually "churning" the file, regenerating it every time WebMake is run, a comparison step takes place. Before the file is written to disk, WebMake compares the file in memory with the file on disk; if there are no changes, the on-disk file will not be modified in any way. This means tools like rsync(1), rdist(1) or even make(1) itself will work fine with a WebMake site.

All of these optimisations can be overridden by using the -F (freshen) command-line switch; this will force output whether or not the files have changed.

Ensuring A Seamless Transition

A very large (or very complicated) WebMake site can take a while to update. To avoid broken links while updating the site, WebMake generates all output into temporary files called filename.new; once all the output has been generated, these are renamed into place. This minimises the time during which there may be inconsistencies in the site.

Caching

Since WebMake uses dependencies to avoid rebuilding the entire site every time, it needs to cache metadata and dependency information somewhere.

Currently this data is stored in a file called filename/cache.db, where filename is a sanitised version of the WebMake file's name, in the .webmake subdirectory of your home directory.

WebMake Documentation (version 1.2)