Every directory in a Pictools source tree should have a Makefile of at least two lines:

include ${PICTOOLS}/MakeVars
include ${PICTOOLS}/MakeTargets

Additional variables can be set between the two lines. Additional build targets can be defined after MakeTargets. See the examples Makefiles below. A Makefile is essential for pictures group directories. In other directories, most files are uploaded when saved by a web page builder like DreamWeaver. Having a Makefile will implement a few additional functions like make clean and rebuilding the entire tree. To support tree operations, each parent directory needs a line

SUBDIRS = subdirectories-list-space-separated

Then the whole tree or a subtree can be rebuilt and uploaded with a simple "make uploadall".

Targets

MakeTargets defines installation targets. Target build puts items in the staging area, creating or copying them as necessary. Target upload copies from the staging area to the server. To cause other items to be built, they must be named in one of the lists COPYFILES, BUILDTOSTAGE, or BUILDONLY. See MakeVars.

For the gory details of all targets defined, see MakeTargets. The default target is build. Corresponding to build and upload, MakeVarsdefines buildall and uploadall to operate first on the local directory and then on each directory listed in SUBDIRS.

Properties and the Environment

See MakeVars for variables that can be set or modified in Makefiles, usually between the includes. See also properties.php.

Makefiles, programs, and scripts (csh, sh, PHP, and JavaScript) all depend on shell environment variables and Pictools properties. Environment variables are available in all contexts. Pictools variables must be fetched in each context where needed. The various ways to define Pictools properties, and their precedence are listed in propcon. At one time, Pictools properties were exported by MakeVars so they were available to programs and scripts called from recipes. This approach led to a few situations where the passed value was inappropriate. After numerous tries at a good policy, the most draconian was adopted. Pictools properties are not propagated in Makefiles. Each subordinate Makefile, program, or script must fetch the properties for itself.

Too draconian. So I devised an exception. When a property is defined with the pragma "#! export" it will be exported by Make. (Pragmas are described in propcon.) For instance the version.number and build.number properties in /pictools/Pictools.properties are both so marked. Thus they are available as genhtml expands INSTALL.html. (See the sample Makefile for pictools below).

Size

Most Makefiles are quite small, two or three lines will do: To illustrate, I ran a histogram of the sizes of all the Makefiles in PhysPics:

# lines	# Makefiles
1-3	130
4-6	32
7-9	34
10-12	7
13-15	7
More	5

The Makefiles with 4, 5, or 6 lines are often just the three usual lines plus a few comment lines. When I looked closer, most of the bigger Makefiles are obsolete. Many oddball directories don't have Makefiles; their files are edited and copied to the server by DreamWeaver. Files in /Java are uploaded by ant scripts in Java source directories.

Running make

To upload the pages for a directory, open a shell window, change file to the directory and enter the command

make uploadall

This builds and uploads all files in the current directory and all directories listed in its SUBDIRS variable. For directories with a captions file, xxx.cap, MakeTargets automatically builds the picture subdirectories and scales and uploads the pictures.

See MakeTargets for defined targets other than uploadall.

Example Makefiles

Example: physpics top-level.  This Makefile has SUBDIRS and needs to upload a couple of unusual files:

include $(PICTOOLS)/MakeVars
SUBDIRS = pictools images annals
COPYFILES = .htaccess favicon.ico
include $(PICTOOLS)/MakeTargets

Example with compilation. If a directory needs a C compilation for, say, tool.exe

include $(PICTOOLS)/MakeVars
BUILDONLY = tool.exe
include $(PICTOOLS)/MakeTargets

tool.exe : tool.c aLib.c aLib.h
   cc -c $@ @<

Example setting THUMBSCOL. The numer of thumbnails per row defaults to five. If you want some other number, set the THUMBSCOL variable.

include $(PICTOOLS)/MakeVars
THHUMBSCOL = 4
include $(PICTOOLS)/MakeTargets

(THUMBSCOL can be set for each individal segment by making the same assignment just after the file: line within a .cap file.)

Example: pictools. This is a somewhat-simplified version of the Makefile in the /Pictools directory. In addition to the usual install behaviors, it builds and installs INSTALL.html and the compressed tar file pictools.tgz.

The first line invokes a small sub-Makefile which ensures that soon-to-be-used tools are compiled. t preprocesses INSTALL.html to expand properties like PICTOOLS.VERSION and then creates/uploads a tar file. The tar file installs for a site; the -C options ensure that untarring will put files in the right place.

# Ensure that propcon et al. have been compiled
$(info $(shell $(MAKE) -C $(PICTOOLS) -f MakeHelpers))

include $(PICTOOLS)/MakeVars

# define additional files to be built and installed 
COPYFILES = propcon.c src.c src.h strtbl.c strtbl.h
#define files to be built, but not installed
BUILDTOSTAGE = pictools.tgz INSTALL.html

# define parameters to the rule to build the tar file
TAR_SRCS = images library pictools scripts Templates 
TAR_DEPENDS = ${TAR_SRCS:%=%/*} $(STAGE)INSTALL.html
TAR_EXCLUDES = _notes *~ Thumbs.db *.exe \
            Pictools.csh Pictools.mkinc 
_EXC = ${TAR_EXCLUDES:%=--exclude "%"}

include $(PICTOOLS)/MakeTargets

#pre-process INSTALL.html to expand macros
$(STAGE)/INSTALL.html: INSTALL.html Pictools.properties
    genhtml -o $@  INSTALL.html

#create the tar file
$(STAGE)/pictools.tgz: $(TAR_DEPENDS)
	tar cfz $@  $(_EXC) -C $(STAGE) INSTALL.html \
            -C $(SRCROOT) $(TAR_SRCS)