rulebase.default

# vim:set syntax=tcl:
# vi:se noet sw=4 ts=4:
#
# These are the built-in rules
#
# They can be replaced if necessary by creating rulebase.spec
# at the top level of your project.

# @synopsis:
#
# rulebase.default is the default tmake rulebase...
#
# The following environment variables are used if set:
#
## CC       - C compiler
## CXX      - C++ compiler
## ...

use getopt glob

proc rulebase-invoke {cmd} {
	switch -exact -- $cmd {
		prolog {
			tailcall rulebase-prolog
		}
		epilog {
			tailcall rulebase-epilog
		}
		init {
			tailcall rulebase-init
		}
		default {
			dputs m "Rulebase does not implement rulebase-invoke $cmd"
		}
	}
}

# ==================================================================
# Default variable settings and rules
# ==================================================================

proc rulebase-init {} {
	# If settings are loaded via Load, these should all be ignored
	# Thus we use define?
	define? CCACHE ""
	define? CC gcc
	define? CXX g++
	define? AR ar
	define? RANLIB ranlib
	define? STRIP strip
	define? STRIPFLAGS ""
	define? STRIPLIBFLAGS ""
	define? ARFLAGS cr
	define? CPPFLAGS ""
	define? CFLAGS ""
	define? CXXFLAGS ""
	define? LDFLAGS ""
	if {[iswin]} {
		define? EXEEXT .exe
	} else {
		define? EXEEXT ""
	}

	define? SH_CFLAGS ""
	define? SH_LDFLAGS ""
	define? SH_LINKFLAGS ""
	define? SH_SOEXT .so
	define? SHOBJ_CFLAGS ""
	define? SHOBJ_LDFLAGS ""
	define? LD_LIBRARY_PATH ""

	define? CC_FOR_BUILD gcc
	define? HOST_CFLAGS ""
	if {[iswin]} {
		define? HOST_EXEEXT .exe
	} else {
		define? HOST_EXEEXT ""
	}

	define? LEX flex
	define? LFLAGS ""
	define? YACC bison
	define? YFLAGS -y

	define? LOCAL_LIBS ""
	define? DESTDIR ""
	define? OBJCFLAGS ""
	define? INCPATHS ""

	# Default header pattern for C and C++ dynamic dependencies
	define? CHDRPATTERN {^[\t ]*#[\t ]*include[\t ]*[<\"]([^\">]*)[\">]}

	# Value to check for change (e.g. from environment)  to force Autosetup configure to rerun
	define? CONFIGURE_ENV ""

	# These are set by the project via CFlags, ObjectCFlags, LinkFlags, etc.
	define C_FLAGS ""
	define CXX_FLAGS ""
	define LD_FLAGS ""

	define PUBLISH publish

	define PROJLIBS ""
	define SYSLIBS ""
	define HOST_SYSLIBS ""
	define PRECOMPILED_HEADER ""

	# All globals variables for rulebase.default are kept in the $::tmakedrb array
	set ::tmakedrb {
		testruncount 0
		testpasscount 0
		testid 0
		setuptestenv 0
		objmap {}
		objrules {}
	}
}

# ==================================================================
# Help Overview
# ==================================================================
rule-overview {
This is rulebase.default, the default tmake rulebase. Note the following conventions:

File specifications for Install and Publish rules support the following forms:
  - Regular filenames
  - Renaming rules of the form: target=source
  - Glob patterns (e.g. *.png)

For rules that set variables/flags, those definitions apply to rules later in the file.
For example, when setting C_FLAGS with CFlags, those flags are used by subsequent
Object and Executable rules, but not earlier rules.

Note: Scope can be used to limit the lifetime of definitions.

The following global phony targets are created:

  all:       Builds the 'all' targets from all subdirectories
  test:      Runs the 'test' targets from all subdirectories
  clean:     Runs the 'clean' targets from all subdirectories
  distclean: Runs the 'distclean' targets from all subdirectories
  install:   Runs all install rules
  uninstall: Runs all uninstall rules

  Note that these global targets can be accessed from within a subdirectory
  by using a / prefix. e.g. /all

The following per-directory phony targets are created:
  all:       Builds executables and shared objects for the current directory
             (or libraries if there are no executables or shared objects)
  test:      Runs all tests for the current directory
  clean:     Removes all build products, including Clean targets, for the current directory
  distclean: Runs 'clean', and removes DistClean targets for the current directory,
             and removes all orphan objects
  install:   A convenience alias for /install
  uninstall: A convenience alias for /uninstall

Note that by default, Lib is an alias for ArchiveLib. This can be changed with:
  alias Lib SharedLib

Normally 'install' targets are built on-demand, but the following can be set
to build the install dependencies as part of the 'all' target in order to avoid
build during install when installing as root.

  define INSTALLDEPTARGET all
}

# ==================================================================
# BUILT-IN Object Rules
# ==================================================================

proc is-duplicate-obj-rule {obj src vars} {
	global tmakedrb

	# Build the info for the rule
	set info [list $src]
	foreach var $vars {
		lappend info $var [get-define $var]
	}

	if {[dict exists $tmakedrb objrules $obj]} {
		# Is it identical?
		dputs m "Ignoring identical duplicate object rule for $obj at [find-source-location]"

		set oldinfo [dict get $tmakedrb objrules $obj]
		if {$oldinfo ne $info} {
			build-error [warning-location "Error: Duplicate Object rule for $obj with different settings"]
		}
		return 1
	}

	dict set tmakedrb objrules $obj $info
	return 0
}

# @ObjectRule.<ext> object source
#
# Rule for creating 'object' from source file 'source' with the
# extentions 'ext'.
#
# The appropriate ObjectRule.<ext> is invoked from Object
# (and hence Objects, Executable and Lib) based on the extension.
#
# Note that 'object' and 'source' are fully qualified names, not local names.

rule ObjectRule.c {obj src} {
ObjectRule.c object source

Generates an object file from a C source file

Bound variables: CC, C_FLAGS (from CFlags, ObjectCFlags), INCPATHS (from IncludePaths)
Used variables:  CPPFLAGS, CFLAGS, CCACHE, CHDRPATTERN (for dynamic dependency generation)
                 PRECOMPILED_HEADER (see PrecompiledHeader)
} {
	if {![is-duplicate-obj-rule $obj $src {CC C_FLAGS INCPATHS}]} {
		# Capture the current value of CC, C_FLAGS and INCPATHS
		target $obj -inputs $src -msg {note Cc $targetname} -getvars CC C_FLAGS INCPATHS -do {
			run $CCACHE $CC $C_FLAGS $CFLAGS $CPPFLAGS -c $inputs -o $target
		} -dyndep {
			header-scan-regexp-recursive $INCPATHS "" $CHDRPATTERN
		} -depends [get-define PRECOMPILED_HEADER]
	}
	return $obj
}

rule ObjectRule.cpp {obj src} {
ObjectRule.cpp object source
(Also aliases ObjectRule.cc, ObjectRule.cxx, ObjectRule.C)

Generates an object file from a C++ source file

Bound variables: CXX, CXX_FLAGS (from C++Flags), INCPATHS (from IncludePaths)
Used variables:  CPPFLAGS, CXXFLAGS, CCACHE, CHDRPATTERN (for dynamic dependency generation),
                 PRECOMPILED_HEADER (see PrecompiledHeader)
} {
	if {![is-duplicate-obj-rule $obj $src {CXX CXX_FLAGS INCPATHS}]} {
		# Capture the current value of CXX, CXX_FLAGS and INCPATHS
		target $obj -inputs $src -msg {note C++ $targetname} -getvars CXX CXX_FLAGS INCPATHS -do {
			run $CCACHE $CXX $CXX_FLAGS $CXXFLAGS $CPPFLAGS -c $inputs -o $target
		} -dyndep {
			header-scan-regexp-recursive $INCPATHS "" $CHDRPATTERN
		} -depends [get-define PRECOMPILED_HEADER]
	}
	return $obj
}

# Why haven't we settled on a single extension?
alias ObjectRule.cc ObjectRule.cpp
alias ObjectRule.cxx ObjectRule.cpp
alias ObjectRule.C ObjectRule.cpp

rule Lex {args} {
Lex [--prefix=.lex] source.l

Generates .c and .h from a lexer source file
Note that $LEX must support --outfile and --header-file

Returns the (local) generated files.

Bound variables: LEX, LFLAGS
} {
	show-this-rule
	getopt {--prefix: src} args
	if {![exists prefix]} {
		set prefix .lex
	}
	set src [make-local $src]
	set base [file rootname $src]
	set targets [list $base$prefix.c $base$prefix.h]

	# Build the output files with lex/flex
	target $targets -inputs $src -msg {note Lex $targetname} -getvars LEX LFLAGS -do {
		run $LEX $LFLAGS --outfile=[lindex $target 0] --header-file=[lindex $target 1] $inputs
	}
	add-clean [make-local clean] $targets
	add-clean [make-local distclean] $targets
	make-unlocal {*}$targets
}

rule ObjectRule.l {obj src} {
ObjectRule.l object source

Uses the Lex rule to create an object from lexer source.
Note that the object name is ignored, and is instead derived from the source.
} {
	show-this-rule
	lassign [Lex [make-unlocal $src]] csrc hsrc
	Object [change-ext .o $csrc] $csrc
}

rule Yacc {args} {
Yacc [--prefix=.tab] source.y

Generates an object file from a yacc source file

Note that $YACC must support --output and --defines

Returns the (local) generated files.

Bound variables: YACC, YFLAGS
} {
	show-this-rule
	getopt {--prefix: src} args
	if {![exists prefix]} {
		set prefix .tab
	}
	set src [make-local $src]
	set base [file rootname $src]
	set targets [list $base$prefix.c $base$prefix.h]

	# Build the output files with yacc/bison
	target $targets -inputs $src -msg {note Yacc $targetname} -getvars YACC YFLAGS -do {
		run $YACC $YFLAGS --output=[lindex $target 0] --defines=[lindex $target 1] $inputs
	}
	add-clean [make-local clean] $targets
	add-clean [make-local distclean] $targets

	make-unlocal {*}$targets
}

rule ObjectRule.y {obj src} {
ObjectRule.y object source

Uses the Yacc rule to create an object from yacc source.
Note that the object name is ignored, and is instead derived from the source.
} {
	show-this-rule
	lassign [Yacc [make-unlocal $src]] csrc hsrc
	Object [change-ext .o $csrc] $csrc
}

# ==================================================================
# PROLOG/EPILOG HOOKS
# ==================================================================
proc rulebase-prolog {} {
	global tmakedrb

	show-this-rule [local-dir]

	# Local phony targets build from the current directory down
	if {[local-prefix] ne ""} {
		set parentprefix [make-prefix [file dirname [local-dir]]]
		foreach t {all clean distclean test} {
			set localtarget [make-local $t]
			target $localtarget -phony
			target $parentprefix$t -phony -depends $localtarget
		}
		Phony install install
		Phony uninstall uninstall
		clean-target [make-local clean] Clean
		clean-target [make-local distclean] DistClean
	}

	# Capture these variables
	foreach i {INCPATHS C_FLAGS CXX_FLAGS} {
		dict set tmakedrb $i [get-define $i]
	}

	# This can be removed with IncludePaths --reset
	IncludePaths .
}

proc rulebase-epilog {} {
	show-this-rule [local-dir]

	# Does subdir/all have any dependencies? If not, make it depend on subdir/libs (if that rule exists)
	set t [get-target-rule [make-local all]]
	if {[llength $t(depends)] == 0} {
		if {[is-rule? [make-local libs]]} {
			Depends all [make-local libs]
		}
	}

	# Ensure that even directories with no targets are removed
	Clean __dummy__
}

# ==================================================================
# UTILTY PROCS
# ==================================================================

# @target-alias target targetexe
#
# On some systems, executables are identified with an extension (e.g. .exe)
# For cross-platform compatibility, rules omit this extension and an alias is used
# to link to the actual filename.
#
# This command checks the rule name (e.g. abc) and the executable name (e.g. abc.exe)
# and if they are different, returns an appropriate target alias for the executable
# (e.g. -alias abc). Otherwise an empty list is returned.
#
proc target-alias {target targetexe} {
	if {$target ne $targetexe} {
		return [list -alias [make-local $target]]
	}
	return ""
}

# @publish-path dir
#
# Returns the path to the given 'publish' subdirectory,
# e.g. [publish-path include] returns something like objdir/.publish/include
#
proc publish-path {dir} {
	file-build [file-join [get-define PUBLISH] $dir]
}

# @publish-dir dir
#
# Returns the path to the given 'publish' subdirectory relative to the build directory
# e.g. [publish-dir include] returns something like .publish/include
#
proc publish-dir {dir} {
	file-join [get-define PUBLISH] $dir
}

# @publish-prefix dir
#
# Like publish-dir, but returns the value suitable to be used as a prefix
#
proc publish-prefix {dir} {
	make-prefix [publish-dir $dir]
}

# @publish-one-file dest src
#
# Creates a rule to publish $src as $dest (build relative name) by creating a hard link.
# e.g. publish-one-file include/header.h header.h
#
proc publish-one-file {args dest src} {
	#dputs m "publish-one-file dest=$dest, src=$src, realdest=[publish-dir $dest]"
	hard-link [publish-dir $dest] $src -msg {note Publish $targetname} {*}$args
}

# @publish-lib libname alias
#
# Creates a rule to publish an archive library, $libname, to the $PUBLISH/lib directory.
# $alias is the alias name of the library, e.g. <lib>blah
#
proc publish-lib {libname alias} {
	hard-link [publish-prefix lib]$libname [make-local $libname] -msg {note Publish $targetname} -alias $alias
}

# @make-shlib-symlinks first alias...
#
# Create symlinks such that each of the given aliase is a symlink to $first.
# All paths/names should be in the same directory
# The alias targets must not exist.
#
proc make-shlib-symlinks {first args} {
	foreach alias $args {
		file-link -sym $alias [file tail $first]
	}
}

# @publish-shared-lib names source alias
#
# Creates a rule to publish a shared library, $source, with the given names to the
# $PUBLISH/lib directory.
# This includes creating appropriate symlinks.
# $alias is the alias name of the library, e.g. <lib>blah
#
proc publish-shared-lib {names source alias} {
	set published [prefix [publish-prefix lib] {*}$names]

	target $published -inputs $source -msg {note Publish [lindex $targetname 0]} -do {
		file delete {*}$target
		file-link [lindex $target 0] $inputs
		make-shlib-symlinks {*}$target
	} -vars libname [lindex $names 0] -alias $alias
	add-clean [make-local clean] $published
	add-clean [make-local distclean] $published
}

# @install-shared-lib ?--striplib? dest names source flags
#
# Creates a rule to install a shared library, $source, to install directory $dest
# This includes creating appropriate symlinks.
# $flags are passed to install-file and should either be empty, or "striplib".
proc install-shared-lib {args} {
	getopt {--striplib dest names source} args

	set installed [prefix [make-prefix [get-define DESTDIR]$dest] $names]

	set installopts {}
	lappend installopts --bin
	if {$striplib} {
		lappend installopts "--strip=[get-define STRIP] [get-define STRIPLIBFLAGS]"
	}
	target $installed -nocache -rootok -inputs $source -msg {note Install $libname} -do {
		file delete {*}$target
		install-file {*}$installopts [lindex $target 0] $inputs
		make-shlib-symlinks {*}$target
	} -vars installopts $installopts libname [file-join $dest [lindex $names 0]]

	target install -depends {*}$installed
	add-clean uninstall $installed
}

# @make-local-or-abs filename
#
# If $filename is an absolute path, returns $filename
# Otherwise returns [make-local $filename]
proc make-local-or-abs {filename} {
	if {[string match /* $filename]} {
		return $filename
	}
	return [make-local $filename]
}

# @expand-filespec dir filelist keepdir
#
# Implements target renaming/globbing for Publish and Install
#
# $dir is the target directory
# $filelist is the file specification
# $keepdir is a boolean which indicates whether to keep the source dir in the target name
#
# The file specification may include:
# - Regular filenames
# - Renaming rules of the form: target=src
# - Glob patterns
#
# Returns a list of the form: target1 source1 target2 source2 ...
proc expand-filespec {dir filelist keepdir} {
	set result {}

	foreach spec $filelist {
		if {$spec eq ""} {
			continue
		}
		if {[string match *=* $spec]} {
			lassign [split $spec =] target src
			#dputs m "file renaming: dir=$dir, target=$target, src=$src => target=[file-join $dir $target] src=[make-local $src]"
			lappend result [file-join $dir $target] [make-local-or-abs $src]
			continue
		}
		if {[string match {*[{}*?]*} $spec]} {
			set srcs [Glob --all $spec]
		} else {
			set srcs $spec
		}
		foreach src $srcs {
			if {$keepdir} {
				#dputs m "keepdir: dir=$dir, src=$src => target=[file-join $dir $src] src=[make-local-or-abs $src]"
				lappend result [file-join $dir $src] [make-local-or-abs $src]
			} else {
				#dputs m "no keepdir: dir=$dir, src=$src => target=[file-join $dir [file tail $src]] src=[make-local-or-abs $src]"
				lappend result [file-join $dir [file tail $src]] [make-local-or-abs $src]
			}
		}
	}
	#puts "expand-filespec: $filelist => $result"
	return $result
}

# @expand-objects objs
#
# Expands a list of objects which may contain library aliases of the form <lib>$basename
# Each library alias is expanded into the list of objects for that library.
# (Note that SharedLib and ArchiveLib create an object list when creating libraries)
# Any non-aliases are left unchanged.
#
# Returns the expanded object list.
proc expand-objects {objs} {
	set result {}
	foreach obj $objs {
		if {[string match <lib>* $obj]} {
			if {![dict exists $::tmakedrb(objmap) $obj]} {
				build-error [warning-location "Error: Unable to find objects for unknown lib $obj"]
				return -code break
			}
			# XXX: How to guarantee that $SH_CFLAGS are set on these objects?
			# (Either directly via ObjectCFlags or with a top-level CFlags)
			#
			lappend result {*}[file-build-list [dict get $::tmakedrb(objmap) $obj]]
		} else {
			lappend result $obj
		}
	}
	return $result
}

# @load-config-file filename
#
# Reads a configuration file of the form:
#
## CONFIG_BOOL_VALUE=y (or m)
## CONFIG_STR_VALUE="string value"
## CONFIG_INT_VALUE=123
#
# Each matching value is loaded as a corresponding variable definition
# where if the value is "y", it is changed to "1", and if the value
# is a quoted string, the quotes are removed.
proc load-config-file {filename} {
	set n 0
	foreach line [split [readfile $filename] \n] {
		incr n
		set line [string trim $line]
		if {$line eq "" || [string match "#*" $line]} {
			continue
		}
		if {[regexp {^([^=:]*):?=(.*)} $line -> name value]} {
			set value [string trim $value]
			if {$value eq "y"} {
				set value 1
			} elseif {[string match {"*"} $value]} {
				set value [lindex $value 0]
			}
			dputs c "define $name $value"
			# Add source info here for tracking purposes
			define $name [info-source $value $filename $n]
		} else {
			user-notice purple "$filename:$n: Warning: Failed to parse $line"
		}
	}
	if {$n == 0} {
		user-notice purple "Warning: $filename contains no configuration"
	}
}

# @setup-test-env
#
# Prepares the environment for running tests.
# Given the (absolute path of) $PUBLISH/lib and the name of the LD_LIBRARY_PATH variable,
# appends the publish lib $LD_LIBRARY_PATH in the environment to allow published shared libraries to be loaded
# Also sets TMAKE_LIBPATH to the same value for script helpers on Mac OS X
# since DYLD_LIBRARY_PATH can't be passed to scripts
# (See https://forums.developer.apple.com/message/31148)
proc setup-test-env {publishlib ldlibpath} {
	setenv TMAKE_LIBPATH $publishlib
	if {$ldlibpath ne ""} {
		set path [getenv $ldlibpath ""]
		append-with-space path $publishlib $::tcl_platform(pathSeparator)
		setenv $ldlibpath $path
	}


}

# @get-test-id
#
# Returns a unique test id of the form 'test#nnn'
# Used to help identify Test targets since they don't have
# a natural target name.
proc get-test-id {} {
	return test#[incr ::tmakedrb(testid)]
}

# @run-test-command testcommand
#
# This is a helper for running test commands.
# It is used by the Test rule.
# The environment should first be set up with setup-test-env
# Then SRCDIR is exported to the environment
# stdout, stderr and errok are checked from the caller to determine
# how output/errors are handled/checked
proc run-test-command {testcommand} {
	upvar stdout stdout
	upvar stderr stderr
	upvar errok errok
	upvar SRCDIR SRCDIR

	set cmdline $testcommand

	set outfile {}

	foreach i {stdout stderr} redir {> 2>} {
		if {[exists $i]} {
			set outfile($i) [file tempfile]
			lappend testcommand ${redir}$outfile($i)
		}
	}

	if {![exists stdout]} {
		lappend testcommand >@stdout
	}

	# Get this value from the calling scope and set in the environment
	setenv SRCDIR $SRCDIR
	incr ::tmakedrb(testruncount)
	set rc [catch {
		vputs [string trim $testcommand]
		exec {*}$testcommand
	} msg opts]
	if {[exists errok]} {
		set rc 0
	}
	if {$rc == 0} {
		# Succeeded. Does the output match?
		foreach {i gotfile} $outfile {
			set expfile [set $i]
			set got [readfile $gotfile]
			set exp [readfile $expfile]
			if {$got ne $exp} {
				if {$rc == 0} {
					set rc 1
					pputs \n\t$cmdline\n
					set msg "\nError: Output does not match"
				}
				vputs "diff -u $expfile $gotfile"
				catch {
					exec diff -u $expfile $gotfile >@stdout
				}
			}
		}
	}

	# Delete output
	foreach file [dict values $outfile] {
		file delete -force $file
	}

	if {$rc == 0} {
		incr ::tmakedrb(testpasscount)
		return 0
	}
	build-error $msg
	return -code break
}

# @hard-link ?--copy? dest source ?target-args...?
#
# Creates a rule to link $dest to $source (or copy if --copy is specified)
# Additional arguments may be passed and are added to the target rule.
#
proc hard-link {args} {
	#show-this-rule

	getopt {dest source --copy args} args

	# XXX: If the platform doesn't support hard links,
	# consider falling back to soft links and then to file copy
	if {$copy || ![exists -command file-link]} {
		target $dest -inputs $source -do {
			file delete $target
			file copy $inputs $target
		} {*}$args
	} else {
		target $dest -inputs $source -do {
			file delete $target
			file-link $target $inputs
		} {*}$args
	}

	# Note that we can't use Clean here because $dest is already
	# a local name
	add-clean [make-local clean] $dest
	add-clean [make-local distclean] $dest
}

# @sym-link dest source ?target-args...?
#
# Creates a rule to link $dest to $source
# Additional arguments may be passed and are added to the target rule.
#
proc sym-link {args} {
	#show-this-rule

	getopt {dest linktarget args} args

	target $dest -symlink -vars linktarget $linktarget -do {
		file delete $target
		file-link -sym $target $linktarget
	} {*}$args

	# Note that we can't use Clean here because $dest is already
	# a local name
	add-clean [make-local clean] $dest
	add-clean [make-local distclean] $dest
}

# @install-file ?--strip=$STRIPCMD? ?--bin? target source
#
# Helper for installing files
# Copies the file from $source to $target, then performs zero or more actions
# depending upon the flags (which is a list)
#
#- --bin                 - make the target executable with chmodx-file
#- --strip=$STRIPCMD     - If specified, strips the target with the given strip command
#
proc install-file {args} {
	getopt {--strip: --bin target source} args

	vputs "Copy $source $target"
	# Delete the target first in case it is in use
	# XXX Should we instead copy to a tmp file and force rename?
	file delete $target
	file copy $source $target
	if {$bin} {
		chmodx-file $target
	}
	if {[exists strip]} {
		vputs "Strip $target"
		exec {*}$strip $target
	}
}

# @chmodx-file target
#
# Makes the given file executable with chmod +x
proc chmodx-file {target} {
	vputs "Chmod $target"
	exec chmod +x $target
}

# @remove-empty-directories filename-list
#
# Considers the set of directories containing each filename in the list.
# Removes any of those directories that are empty.
proc remove-empty-directories {files} {
	set dirs {}
	foreach file $files {
		while {1} {
			set dirname [file dirname $file]
			if {$dirname eq $file || $dirname eq "."} {
				break
			}
			dict set dirs [file dirname $file] 1
			set file $dirname
		}
	}
	if {[dict size $dirs]} {
		# Sort in reverse order so that abc/def/ghi is removed before abc/def
		#dputs m "file delete {*}[lsort -decreasing [dict keys $dirs]]"
		foreach dir [lsort -decreasing [dict keys $dirs]] {
			catch { file delete $dir }
		}
	}
}

# @clean-files filename-list ?msg?
#
# Helper to clean files (and any empty directories)
#
# Removes the list of files, and then any directories that contain those
# files which have become empty.
#
# If $msg is provided, it is printed via 'note', otherwise a default
# message is printed.
proc clean-files {files {msg {}}} {
	if {[llength $files]} {
		vputs "rm $files"
		if {$msg ne ""} {
			note "Clean [llength $files] $msg"
		}
		file delete {*}$files
		# Also need to remove any empty directories
		remove-empty-directories $files
	}
}

# @clean-target type msg ?args...?
#
# Create the phony clean target of the given type and message.
# The created target invokes clean-files
#
# Additional files can be added to the target with 'add-clean'
#
# If 'args' are specified, these are added to the target. e.g. -rootok
#
proc clean-target {type msg args} {
	target $type -phony -nofail -vars cleanfiles {} -msg "note $msg [local-dir]" {*}$args -do {
		clean-files $cleanfiles
	}
}

# @add-clean type filename-list
#
# Adds the given files to the list to be removed for the given type (target)
#
proc add-clean {type filelist} {
	# This could be done with Depends or target, but it is much
	# faster to simply append to the rule variable directly
	target-add-var $type cleanfiles [file-build-list $filelist]
}

# @add-src-clean type filename-list
#
# Like add-clean, except $filelist are in the source directory rather than the build directory
#
proc add-src-clean {type filelist} {
	target-add-var $type cleanfiles $filelist
}

# @find-project-bin binfile ?-chdir 0|1? ?-optional 0|1?
#
# Searches for the given binary file as follows:
#- If $binfile is a known target, the result is the target
#- If $binfile is of the form <bin>name, the result is the published binary
#- If the file exists in the local directory, the result is the file
#- Otherwise, if optional=1, the file is assumed to be an external binary
#- Otherwise an error is raised.
#
# The result is a list of two values: {dependency filename}
#
# The first value is a build dependency for the file. (Empty for an external binary)
# The second value is the path to the file suitable for executing it, taking
# into account the setting of 'chdir'.
proc find-project-bin {bin args} {
	set opts [list -chdir 0 -optional 0 {*}$args]

	set localbin [make-local $bin]

	if {[regexp {^<bin>(.*)} $bin -> basename]} {
		dputxs l {[find-source-location]: find-project-bin: $bin is a publish target}
		set publishbin [publish-prefix bin]$basename
		if {$opts(-chdir)} {
			# We will be running in [file-build [local-dir]],
			# while the executable to run is in [file-build $PUBLISH/bin]
			# So calculate a relative path
			set curdir [file-build [local-dir]]
			set builddir [publish-path bin]
			# It can't hurt to create the $PUBLISH/bin here and it makes relative-path always work
			file-mkdir -rootskip $builddir
			set reldir [relative-path $builddir $curdir]

			set result [list $bin $reldir/$basename]
		} else {
			set result [list $bin [file-build $publishbin]]
		}
	} elseif {[is-target? $localbin]} {
		dputxs l {[find-source-location]: find-project-bin: $localbin is a local target}
		if {$opts(-chdir)} {
			set result [list $localbin ./$bin]
		} else {
			# Note: Use [build-dir] here rather than [file-build] to retain ./
			#       if building in-tree
			set result [list $localbin [build-dir]/$localbin]
		}
	} elseif {[file exists $localbin]} {
		dputxs l {[find-source-location]: find-project-bin: $localbin exists as source}
		if {$opts(-chdir)} {
			# Need to adjust the interp to account for chdir
			set result [list $localbin [file-src-relative $localbin]]
		} else {
			set result [list $localbin $localbin]
		}
	} elseif {$opts(-optional)} {
		dputxs l {[find-source-location]: find-project-bin: $bin is assumed to be external}
		set result [list "" $bin]
	} else {
		# Not found
		build-error [warning-location "$bin is neither a local nor a published (<bin>) target"]
		set result [list "" ""]
	}
	dputxs l {[find-source-location]: find-project-bin returning $result}
	return $result
}

add-deferred-action {
	# Need to add $PUBLISH/include to the include paths
	IncludePaths --build [publish-dir include]
}

# Don't allow the same rule to be specified twice
# Avoids accidental merging of, e.g., Executable rules
proc check-dup-rule {rule} {
	if {[is-rule? $rule]} {
		set info [get-rule $rule]
		parse-error "A rule for $rule already exists at $info(source)"
	}
}

# ==================================================================
# HIGH LEVEL RULES
# ==================================================================

rule Executable {args} {
Executable --test --chdir --nobuild --publish --no|strip --nofork --install=<dir> target sources...

Builds an executable from one or more source files. For each source, the appropriate ObjectRule is used
to generate the object file, and these files are linked (along with any libraries) to create the executable.

Bound variables: CCLD (from Linker), LD_FLAGS (from LinkFlags), PROJLIBS and PROJDEPS (from UseLibs)
                 LOCAL_LIBS (from ArchiveLib), SYSLIBS (from UseSystemLibs)
Used variables: LDFLAGS

The following options are supported:
  --test              Marks the executable as a test (see Test)
  --nofork            With --test, uses Test --nofork
  --chdir             With --test, uses Test --chdir
  --nobuild           Don't make this executable dependent on phony 'all' (which is otherwise the default)
  --publish           Publishes the executable (see PublishBin)
  --install=<dir>     Install the executable to the given directory (see InstallFile)
  --strip[=full|dynamic|none]  Sets the strip type on installation. --strip means full. omitted means none. (see InstallFile)
} {
	add-default-opts args
	show-this-rule
	set strip none
	getopt {--test --chdir --nobuild --nofork --publish --strip:full --install: target args} args

	set localtarget [make-local $target]
	set targetexe $target[get-define EXEEXT]
	set localtargetexe $localtarget[get-define EXEEXT]

	# Flatten and glob inputs
	set objects [Objects [Glob --all [join $args]]]

	define? CCLD [get-define CC]

	check-dup-rule $localtargetexe

	# Capture the current value of CCLD, LD_FLAGS and SYSLIBS
	target $localtargetexe -inputs {*}$objects [get-define LOCAL_LIBS] -depends [get-define PROJDEPS] -msg {note Link $targetname} -do {
		run $CCLD $LD_FLAGS $LDFLAGS -o $target $inputs $PROJLIBS $SYSLIBS
	} -getvars CCLD LD_FLAGS PROJLIBS SYSLIBS {*}[target-alias $target $targetexe]
	Clean $targetexe

	if {$publish} {
		PublishBin $target
	}

	if {[info exists install]} {
		set opts --bin
		if {$strip ni {none full dynamic}} {
			build-error [warning-location "Unknown --strip option $strip"]
		}
		if {$strip eq "full"} {
			lappend opts --strip
		} elseif {$strip eq "dynamic"} {
			lappend opts --striplib
		}
		InstallFile {*}$opts [file-join $install $targetexe] $localtargetexe
	}
	if {$test} {
		set opts {}
		if {$chdir} {
			lappend opts --chdir
		}
		if {$nofork} {
			lappend opts --nofork
		}
		Test {*}$opts $target
	}
	if {!$nobuild} {
		Phony all $localtargetexe
	}
}

rule PublishBin {args} {
PublishBin ?--script? ?--copy? name ...

Publishes one or more executables (either binaries or scripts)
Unless --script is specified, the executable extension (e.g. .exe) is used.
If --copy is specified, the target is copied. Otherwise it is hard linked (if supported).

Note that 'name' can be 'target=src' to rename a file when published.
} {
	show-this-rule

	getopt {--script --copy args} args

	set destdir [publish-dir bin]

	if {$script} {
		set exe ""
	} else {
		set exe [get-define EXEEXT]
	}
	set opts {}
	if {$copy} {
		set opts --copy
	}

	set rules {}

	# XXX Currently does not support external sources
	foreach {dest src} [expand-filespec $destdir $args 0] {
		hard-link {*}$opts $dest$exe $src$exe -vars dest bin/$dest -msg {note Publish $targetname} -alias <bin>[file tail $dest]
		target $dest$exe -add -do {
			chmodx-file $target
		}
		lappend rules $dest$exe
	}
	return $rules
}

rule Publish {args} {
Publish ?--keepdir --hash? dir name...

Publishes one or more files to directory $PUBLISH/$dir

Accepts the following file names:
  - Regular filenames
  - Renaming rules of the form: target=src
  - Glob patterns (.e.g *.img)

Normally files are published directly into $PUBLISH/$dir, but if --keepdir is
specified, the relative source directory is kept and replicated under $PUBLISH/$dir

If --hash is specified, the publish target uses hash-based comparison rather
than time-based comparison (if 'UseHashes on' is set)

Note: Libraries and Binaries should not be published with this rule.
Rather Publishlib and PublishBin should be used.
} {
	show-this-rule
	getopt {--keepdir --hash dir args} args

	if {$dir eq "bin"} {
		user-notice purple [warning-location "Warning: Use PublishBin to publish binaries"]
	}
	if {$dir eq "lib" && [string match lib* $args]} {
		user-notice purple [warning-location "Warning: Use Lib --publish to publish libraries"]
	}
	set options {}
	if {$hash} {
		lappend options -hash
	}

	# XXX Does not support external sources
	foreach {dest src} [expand-filespec $dir $args $keepdir] {
		publish-one-file {*}$options $dest $src
	}
}

rule ArchiveLib {args} {
ArchiveLib ?--publish? ?--install=<dir>? basename sources...

Creates an archive library from the given sources. For each source, the appropriate ObjectRule is used
to generate the object file, and these files are combined with $AR and $RANLIB to create the archive library.

This library is added to LOCAL_LIBS so that subsequent Executable's are linked against it.

Used variables: AR, ARFLAGS, RANLIB

The following options are supported:
  --publish           Publishes the library (see PublishLib)
  --install=<dir>     Install the library to the given directory (see InstallFile)
} {
	show-this-rule
	getopt {--publish --install: basename args} args

	# Flatten and glob inputs
	set objects [Objects [Glob --all [join $args]]]

	set libname lib$basename.a
	set libalias <lib>$basename

	set locallibname [make-local $libname]

	check-dup-rule $locallibname

	target $locallibname -inputs {*}$objects -msg {note Ar $targetname} -do {
		file delete $target
		run $AR $ARFLAGS $target {*}[expand-objects $inputs]
		run $RANLIB $target
	}

	# Note: Libraries are not built by default, but are added to a local 'libs' rule
	Phony libs $locallibname
	Clean $libname
	define-append LOCAL_LIBS $locallibname

	if {[info exists install]} {
		InstallFile [file-join $install $libname] $locallibname
	}
	if {$publish} {
		publish-lib $libname $libalias

		# Used to make expand-objects work
		dict set ::tmakedrb(objmap) $libalias $objects
	}
}

rule SharedLib {args} {
SharedLib ?--publish? ?--strip=<type>? ?--version=<ver>? ?--soversion=<ver>? ?--install=<dir>? basename source...

Creates a shared library from the given sources. For each source, the appropriate ObjectRule is used
to generate the object file, and these files are linked (along with any libraries) to create the shared library.

Bound variables: CCLD (from Linker), PROJLIBS and PROJDEPS (from UseLibs), SYSLIBS (from UseSystemLibs)
Used variables: LD_FLAGS, LDFLAGS, SH_LDFLAGS, SH_SOEXT, SH_SOEXTVER, SH_SOPREFIX

The following options are supported:
  --publish              For compatibility. Note that shared libraries are always published. (see PublishLib)
  --install=<dir>        Install the shared library to the given directory (see InstallFile)
  --version=<ver>        A version for the shared library of the form n.n.n (1-3 parts)
  --soversion=<ver>      Override the soname version. Otherwise the first part of the version is used.
  --strip[=dynamic|none] Sets the strip type on installation. --strip means dynamic. omitted means none. (see InstallFile)
} {
	show-this-rule
	add-default-opts args
	set strip none
	getopt {--publish --strip:dynamic --version: --soversion: --install: basename args} args

	if {![info exists version]} {
		set version 0
	}
	set n 0
	foreach part [split $version .] {
		if {![string is integer -strict $part]} {
			set n -1
			break
		}
		incr n
	}
	if {$n < 0 || $n > 3} {
		build-error [warning-location "Not a valid shared library version number: $version"]
		return
	}

	# What names may our shared lib have?
	set nameinfo [list [get-define SH_SOEXTVER] $version %s [get-define SH_SOEXT]]
	set default_soversion $version
	if {$n > 1} {
		# If more that one part is given, the first one is the defaul soversion
		lassign [split $version .] default_soversion
		lappend nameinfo [get-define SH_SOEXTVER] $version
		lappend nameinfo [get-define SH_SOEXTVER] $default_soversion
	}

	set names {}
	set libname {}

	foreach {fmt version} $nameinfo {
		if {$fmt eq ""} {
			continue
		}
		set name lib$basename[format $fmt $version]
		if {$libname eq {}} {
			set libname $name
		}
		if {$name ni $names} {
			lappend names $name
		}
	}

	# Flatten and glob inputs
	set objects [Objects [Glob --all [join $args]]]

	set locallibname [make-local $libname]
	check-dup-rule $locallibname

	set srcs [join $args]
	set libalias <lib>$basename
	ObjectCFlags $srcs [get-define SH_CFLAGS]

	set setsoname {}
	if {[get-define SH_SOPREFIX ""] ne ""} {
		if {![info exists soversion]} {
			set soversion $default_soversion
		}
		set soname lib$basename[format [get-define SH_SOEXTVER] $soversion]
		if {[info exists install] && [get-define SH_SOFULLPATH] ne ""} {
			set fullsoname [file-join $install $soname]
		} else {
			set fullsoname $soname
		}
		set setsoname [get-define SH_SOPREFIX]$fullsoname
	}

	define? CCLD [get-define CC]

	# Note: Do not link against local archive libs (LOCAL_LIBS)
	# XXX: Here we use $LDFLAGS to capture any user-specified link flags (.e.g. -mbig-endian).
	#      Assume that these are required both for shared libs and for executables.
	#      Any shared-library-only flags are in $SH_LDFLAGS.
	#      LinkFlags/LD_FLAGS are also used here (we assume they are appropriate)

	target $locallibname -inputs {*}$objects -depends [get-define PROJDEPS] -msg {note SharedLib $targetname} -do {
		run $CCLD $LD_FLAGS $SH_LDFLAGS $LDFLAGS -o $target $setsoname {*}[expand-objects $inputs] $PROJLIBS $SYSLIBS
	} -getvars CCLD PROJLIBS SYSLIBS -vars setsoname $setsoname
	Clean $locallibname

	# Only the fully versioned name is built in the local dir
	Phony libs $locallibname
	Clean $libname

	# Note: --publish is dummy. Shared libs always need to be published to be used
	# The reason is that it gets difficult to manage LD_LIBRARY_PATH or equalivalent.
	# If shared libraries are always published, a single definition of LD_LIBRARY_PATH=$PUBLISH/lib
	# will work for all shared libs
	incr publish

	if {$publish} {
		# Publish along with the various symlinks and create an alias
		publish-shared-lib $names $locallibname $libalias

		# Used to make expand-objects work
		dict set ::tmakedrb(objmap) $libalias $objects

		# Local executables link against this library
		UseLibs $basename
	}
	if {[info exists install]} {
		if {$strip ni {none dynamic}} {
			build-error [warning-location "Unknown --strip option $strip"]
		}
		set opts {}
		if {$strip eq "dynamic"} {
			lappend opts --striplib
		}

		install-shared-lib {*}$opts $install $names $locallibname
	}
	return $libname
}

# If desired, this can be aliased to SharedLib in project.spec
alias Lib ArchiveLib

rule SharedObject {args} {
SharedObject ?--install=<dir>? ?--strip=<type>? target sources...

Builds a dynamically loadable shared object from the given sources.
For each source, the appropriate ObjectRule is used to generate the object file,
and these files are linked (along with any libraries) to create the loadable object.

Bound variables: CCLD (from Linker), SHOBJ_LDFLAGS (must be set appropriately),
                 PROJLIBS and PROJDEPS (from UseLibs), SYSLIBS (from UseSystemLibs)
Used variables:  LD_FLAGS, LDFLAGS, SHOBJ_CFLAGS (must be set appropriately)

Note that sources are marked to be built with SHOBJ_CFLAGS via ObjectCFlags.

The following options are supported:
  --install=<dir>        Install the shared object to the given directory (see InstallFile)
  --strip[=dynamic|none] Sets the strip type on installation. --strip means dynamic. omitted means none. (see InstallFile)
} {
	show-this-rule
	add-default-opts args

	set strip none
	getopt {--install: --strip:dynamic target args} args

	set srcs [join $args]

	define? CCLD [get-define CC]

	# Must build objects with -fpic, etc.
	ObjectCFlags $srcs [get-define SHOBJ_CFLAGS]

	set localtarget [make-local $target]
	check-dup-rule $localtarget

	target $localtarget -inputs {*}[Objects $srcs] -depends [get-define PROJDEPS] -msg {note SharedObject $targetname} -do {
		run $CCLD $LD_FLAGS $SHOBJ_LDFLAGS -o $target {*}[expand-objects $inputs] $PROJLIBS $SYSLIBS
	} -getvars CCLD LD_FLAGS PROJLIBS SYSLIBS
	Clean $target
	Phony all $localtarget

	if {[info exists install]} {
		set opts --bin
		if {$strip ni {none dynamic}} {
			build-error [warning-location "Unknown --strip option $strip"]
		}
		if {$strip eq "dynamic"} {
			lappend opts --striplib
		}
		InstallFile {*}$opts [file-join $install $target] $localtarget
	}
}

rule Objects {args} {
Objects source ...

Create an object file from each source file using the appropriate ObjectRule for each source.
Accepts object files (.o) and <lib> aliases in addition to source files and simply returns them.

Returns a list of (local) objects.

e.g.

  Objects file1.c file2.o file3.cc <lib>compat
} {
	show-this-rule
	set args [join $args]
	set objs {}
	foreach src $args {
		if {[string match <lib>* $src]} {
			lappend objs $src
		} else {
			lappend objs [Object [change-ext .o $src] $src]
		}
	}
	return $objs
}

rule Object {target src} {
Object obj src

Creates object 'obj' from source 'src' by using the appropriate ObjectRule, e.g. ObjectRule.c
for .c sources.
} {
	show-this-rule
	set ext [file ext $src]
	set obj [make-local $target]
	set src [make-local $src]
	if {$ext ne ".o"} {
		if {[info commands ObjectRule$ext] eq ""} {
			build-error [warning-location "Don't know how to build Object from $src"]
			return $obj
		} else {
			set obj [ObjectRule$ext $obj $src]
			Clean $target
		}
	}
	return $obj
}

rule ObjectCFlags {srcs args} {
ObjectCFlags {sources} ...

Like CFlags, but instead of adding C_FLAGS for all subsequent rules, adds
C_FLAGS only to the objects created from the given list of source files.

Can also be used to apply directly to object files. e.g.

  ObjectCFlags {file1.c file2.o file3.cc} -O0

Note that if used before the rule that creates the .o file, these flags will
come before CFlags from project.spec and build.spec, otherwise they
will come afterwards.
} {
	show-this-rule
	foreach src $srcs {
		set obj [change-ext .o $src]
		target [make-local $obj] -vars C_FLAGS [join $args]
	}
}

rule CFlags {args} {
CFlags ...

Add the given flags to C_FLAGS (used in all subsequent ObjectRule.c)
e.g.  CFlags -DABC=7

Note that to pass a string value, it generally sufficient to quote it normally:

  CFlags -DVERSION="v1.0"

However if the value may contain spaces, use quote-if-needed. eg.

  CFlags [quote-if-needed {-DVERSION="processor v1.0"}]
} {
	show-this-rule
	define-append C_FLAGS {*}$args
}

rule C++Flags {args} {
C++Flags ...

Add the given flags to CXX_FLAGS (used in all subsequent ObjectRule.cpp)

See CFlags
} {
	define-append CXX_FLAGS {*}$args
}

rule LinkFlags {args} {
LinkFlags ...

Add the given flags to LD_FLAGS (used in all subsequent Executable and SharedLib)
} {
	define-append LD_FLAGS {*}$args
}

rule Linker {linker} {
Linker prog

Defines the linker to use for subsequent Executable and SharedLib ($CCLD).
By default $CC is used. For C++ applications, it is typical to set:

  Linker $CXX
} {
	define CCLD $linker
}

rule UseLibs {args} {
UseLibs projlib ...

Identifies published project libraries from other directories that are required for
linking subsequent Executables, Shared Libraries and Shared Objects.

The libraries are both added as dependencies (via $PROJDEPS) and added to the link line
(via $PROJLIBS)

For non-project libraries (such as system libraries), see UseSystemLibs and LinkFlags
} {
	# Create/append to PROJLIBS (the link line)
	if {[get-define PROJLIBS] eq ""} {
		define PROJLIBS "-L[publish-path lib]"
	}
	define-append PROJLIBS [prefix -l $args]

	# Now the dependencies
	define-append PROJDEPS [prefix <lib> $args]
}

rule IncludePaths {args} {
IncludePaths ?--reset? ?--global? ?--build|--source? paths...

Arranges to search the given paths for header files.

The paths are added:
- to $INCPATHS for use by dynamic header dependency searching
- to CFlags ($C_FLAGS) as -I <path>
- to C++Flags ($CXX_FLAGS) as -I <path>

By default, the paths (relative to the current local directory) are
searched in both the source tree and the build tree, but this can
be changed by specifying --build or --source.

The following options are supported:
  --build         Search the paths only in the build tree
  --source        Search the paths only in the source tree
  --reset         INCPATHS, C_FLAGS, and CXX_FLAGS are reset to their default values,
                  before any IncludePaths invocations.
                  This can be useful to remove the implicit 'IncludePaths .'

  --global        Paths are considered to be from the top of the tree rather
                  than local (to the current dir) paths.

Note that normally only relative paths should be used, however adding an absolute
path (e.g. /usr/local/include) is possible, in which case the path is added as-is
and headers in that directory will then be included in dynamic dependency analysis.
} {
	show-this-rule

	getopt {--reset --build --source --global args} args

	if {$reset} {
		global tmakedrb
		# Reset INCPATHS, C_FLAGS and CXX_FLAGS to their defaults
		foreach i {INCPATHS C_FLAGS CXX_FLAGS} {
			define $i [dict get $tmakedrb $i]
		}
	}

	if {!$build && !$source} {
		# No options means both
		incr build
		incr source
	}

	if {$global} {
		set srcdir .
		set builddir [file-build .]
	} else {
		set srcdir [local-dir]
		set builddir [file-build [local-dir]]
	}

	foreach dir $args {
		set srcpath [file-join $srcdir $dir]
		set buildpath [file-join $builddir $dir]

		if {$srcpath in [get-define INCPATHS]} {
			dputs m "IncludePaths: Ignoring duplicate $srcpath"
			# Already have this one added, so ignore it
			continue
		}
		define-append INCPATHS $srcpath
		if {$source} {
			CFlags [prefix -I $srcpath]
			C++Flags [prefix -I $srcpath]
		}
		if {$build} {
			if {$source && $buildpath eq $srcpath} {
				# Normally buildpath would not equal srcpath, but
				# if an out-of-tree location is given (e.g. /usr/local/include)
				# then it will. No need to include twice.
			} else {
				CFlags [prefix -I $buildpath]
				C++Flags [prefix -I $buildpath]
			}
		}
	}
}

rule Load {args} {
Load ?--nocare? ?--config? filename

Reads a configuration file in one of two forms.
If --config is specified, the following form is expected:

  CONFIG_BOOL_VALUE=y (or m)
  CONFIG_STR_VALUE="string value"
  CONFIG_INT_VALUE=123

Otherwise a Tcl source file is expected to contain 'define' commands. e.g.

  define CONFIG_BOOL_VALUE
  define CONFIG_STR_VALUE "string value"
  define CONFIG_INT_VALUE 123

Unless --nocare is specified, the file must exist.

The symbols contained in the file are defined, and the file is marked
as a project dependency. This means that if the file changes, it is re-read.
It is possibly for the build to create/re-create this file, in which case the
parsing phase will be restarted.
} {
	show-this-rule

	getopt {--nocare --config filename} args

	# XXX: Should we allow loading an out-of-tree file?

	if {[is-target? $filename]} {
		set f [file-build $filename]
		dputs m "Load: $filename is a target => $f"
	} elseif {[file exists $filename]} {
		dputs m "Load: $filename is source"
		set f $filename
		lappend result $f
	} elseif {![is-cleaning?] && !$nocare} {
		build-fatal-error [warning-location "Error: Load $filename does not exist and is not a target"]
	}

	if {[info exists f] && [file exists $f]} {
		if {$config} {
			dputs m "load-config-file $f"
			load-config-file $f
		} else {
			dputs m "source $f"
			source $f
		}
		# If we find the file, we now care about it
		set nocare 0
	}
	add-project-file $filename $nocare
}

rule UseSystemLibs {args} {
UseSystemLibs ...

Adds system libraries to be used when linking subsequent Executables, Shared Libraries and Shared Objects
via the $SYSLIBS variable.
Typical usage is:

  UseSystemLibs -ldl -lm
} {
	define-append SYSLIBS {*}$args
}

rule PublishIncludes {args} {
PublishIncludes ?--keepdir? name ...

Shorthand for:

  Publish ?--keepdir? --hash include name ...
} {
	getopt {--keepdir args} args

	set options {}
	if {$keepdir} {
		lappend options --keepdir
	}
	Publish {*}$options --hash include {*}$args
}

rule PrecompiledHeader {header} {
PrecompiledHeader headerfile.h

Arranges for the given header file to be precompiled (to headerfile.gch) and included
when compiling subsequent C/C++ sources.

Note that this is a work-in-progress. It appears to work with gcc and clang.
} {
	show-this-rule

	set local [make-local $header]

	# Build the precompiled header
	ObjectRule.c $local.gch $local
	Clean $local.gch
	# Need to publish both of these to the same directory
	PublishIncludes $header $header.gch

	# Now add this as an included for for subsequent compilation
	# Should we be using -include $header or -include-pch?
	# Is the latter only a clang thing?
	CFlags -include $header
	#CFlags -include-pch [publish-path include]/$header.gch

	# And we need to make sources depend on this too
	define PRECOMPILED_HEADER [publish-dir include]/$header.gch
}

rule Test {args} {
Test --interp=<interp> --errok --chdir --quiet --nofork --stdout=<stdout.exp.file> --stderr=<stderr.exp.file> command args

Runs the given test command with the given arguments.

The following options are supported (all are optional):
  --interp  Built or external program required to run the test. Available as $interp
  --chdir   The test runs from the local (build) directory
  --stdout  A local file. The command output must exactly match the file for the test to pass
  --stderr  As per --stdout, but for the command stderr output.
  --quiet   Do not output a message with the test rule runs.
  --errok   Ignores the return code of the command. Normally a non-zero return code indicates failure.
  --nofork  The test is run in the foreground. Otherwise tests are always run as separate jobs.
} {
	show-this-rule

	getopt {--interp: --errok --chdir --quiet --nofork --stdout: --stderr: command args} args
	set testid [get-test-id]
	set depends {}
	set localcommand [make-local $command]

	set opts {}
	set deps {}
	set vars {}

	if {$chdir} {
		lappend opts -chdir
	}
	if {$nofork} {
		lappend opts -nofork
	} else {
		lappend opts -slow
	}
	if {$errok} {
		lappend vars errok 1
	}

	# If there is an interpreter, find it
	if {[info exists interp]} {
		lassign [find-project-bin $interp -chdir $chdir -optional 1] dep filename

		# In this case, the command is a script - find it
		lassign [find-project-bin $command -chdir $chdir -optional 0] cmddep scriptpath
		set testcommand [list $filename $scriptpath {*}$args]

		lappend deps {*}$dep {*}$cmddep
	} else {
		# Find the local or published command and add it to the command and deps
		lassign [find-project-bin $command -chdir $chdir -optional 0] dep filename

		set testcommand [list $filename {*}$args]
		lappend deps {*}$dep
	}

	lappend vars testcommand $testcommand

	if {!$quiet} {
		lappend opts -msg [list note Test $testcommand]
	}

	# set up srcpath to allow the test command/script to find resources
	if {$chdir} {
		# We are in objdir/... and we need to find [local-dir] from src
		set srcdir [file-src-relative [local-dir]]
	} else {
		set srcdir [local-dir]
	}
	lappend vars SRCDIR $srcdir

	foreach i {stdout stderr} {
		if {[info exists $i]} {
			set path [set $i]
			lappend deps [make-local $path]
			lappend vars $i [file-join $srcdir $path]
		}
	}

	lappend vars publishlib [file-join [get-define TOPBUILDDIR] [publish-dir lib]]

	target [make-local $testid] -phony -depends $deps -vars {*}$vars {*}$opts -do {
		setup-test-env $publishlib $LD_LIBRARY_PATH
		run-test-command $testcommand
	} -getvars LD_LIBRARY_PATH

	Phony test [make-local $testid]

	return $testid
}

rule CopyFile {dest source} {
CopyFile dest source

Copies the source file to the destination file
} {
	show-this-rule
	target [make-local $dest] -inputs [make-local $source] -msg [list note Copy $dest] -do {
		file delete $target
		file copy $inputs $target
	}
	Clean $dest
}

rule InstallSymlink {args} {
InstallSymlink dest linktarget

Installs a symlink pointing to the given (relative) target

Adds the rule to the global 'install' target and adds the symlink to the list of files
to be uninstalled with 'uninstall'
} {
	show-this-rule

	getopt {dest linktarget} args

	set destfile [get-define DESTDIR]$dest
	if {[is-target? $destfile]} {
		user-notice purple [warning-location "Warning: Duplicate install rule for $dest [make-source-location $destfile @]"]
		return
	}

	# Note that we pass variable $dest purely so we can show a nice path in the message
	sym-link $destfile $linktarget -nocache -rootok -vars dest "$dest -> $linktarget" -msg {note InstallLink $dest}

	target install -depends $destfile
	add-clean uninstall $destfile

	return $destfile
}


rule InstallFile {args} {
InstallFile ?--strip|--striplib? ?--nowarn? ?--bin? dest source

Installs the given source file to the destination (file) relative to $DESTDIR

The following options are supported:
  --bin               Make the target executable
  --strip             Strip the target with $STRIP $STRIPFLAGS
  --striplib          Strip the target with $STRIP $STRIPLIBFLAGS
  --nowarn            Don't warn on duplicate install rule

Adds the rule to the global 'install' target and adds the file the list of files
to be uninstalled with 'uninstall'

Note that the source can be an absolute path to install an external file.
} {
	show-this-rule

	getopt {--strip --striplib --bin --build --nowarn dest src} args

	#puts "InstallFile $dest $src"

	set destfile [get-define DESTDIR]$dest
	if {$strip && $striplib} {
		build-error "Only one of --strip and --striplib can be specified"
	}
	set installopts {}
	if {$strip} {
		lappend installopts "--strip=[get-define STRIP] [get-define STRIPFLAGS]"
	} elseif {$striplib} {
		lappend installopts "--strip=[get-define STRIP] [get-define STRIPLIBFLAGS]"
	}
	if {$bin} {
		lappend installopts --bin
	}

	if {[is-target? $destfile]} {
		if {!$nowarn} {
			user-notice purple [warning-location "Warning: Duplicate install rule for $dest [make-source-location $destfile @]"]
		}
		return
	}

	# Note that we pass variable $dest purely so we can show a nice path in the message
	if {[string match /* $src]} {
		target $destfile -nocache -rootok -vars dest $dest src $src installopts $installopts -msg {note Install $dest} -do {
			install-file {*}$installopts $target $src
		}
	} else {
		target $destfile -nocache -rootok -vars dest $dest installopts $installopts -inputs $src -msg {note Install $dest} -do {
			install-file {*}$installopts $target $inputs
		}
	}

	target install -depends $destfile
	# Should $src be built by default?
	set srcdep [get-define INSTALLDEPTARGET]
	if {$srcdep ne ""} {
		Depends $srcdep $src
	}

	# This file also needs to be uninstalled
	add-clean uninstall $destfile

	return $destfile
}

rule Install {args} {
Install ?--bin? ?--strip|--striplib? ?--keepdir? ?--nowarn? destdir file-spec...

A convenience wrapper around InstallFile to allow multiple files to be installed at once.
See InstallFile for more details.

Files are installed to (directory) 'destdir'.  'file-spec...' is a
list of file specifications for files to be installed. See 'File
specifications' above.

The following options are supported:
  --bin               Pass --bin to InstallFile
  --nowarn            Pass --nowarn to InstallFile
  --strip|--striplib  Pass --strip or --striplib to InstallFile
  --keepdir           Pass --keepdir to InstallFile
} {
	show-this-rule

	getopt {--bin --strip --striplib --keepdir --nowarn destdir args} args
	set args [join $args]
	set opts {}
	if {$bin} {
		lappend opts --bin
	}
	if {$strip} {
		lappend opts --strip
	}
	if {$striplib} {
		lappend opts --striplib
	}
	if {$nowarn} {
		lappend opts --nowarn
	}

	set srcs {}
	foreach {dest src} [expand-filespec $destdir $args $keepdir] {
		lappend srcs $src
		InstallFile {*}$opts $dest $src
	}
	return $srcs
}

rule Clean {args} {
Clean ?--source? target ...

Adds the given targets to the list of files to be removed on 'tmake clean'

The following options are supported:
  --source       The file is relative to the source directory instead of the build directory
} {
	# DistClean also cleans these files
	DistClean {*}$args

	getopt {--src --source args} args

	set args [join $args]

	if {$source || $src} {
		add-src-clean [make-local clean] $args
	} else {
		add-clean [make-local clean] [make-local {*}$args]
	}
}

rule DistClean {args} {
DistClean ?--source? target ...

Adds the given targets to the list of files to be removed on 'tmake distclean'

The following options are supported:
  --source       The file is relative to the source directory instead of the build directory
} {
	getopt {--source --src args} args

	set args [join $args]

	if {$src} {
		user-notice purple [warning-location "Warning: DistClean --src is deprecated, use --source instead"]
	}
	if {$source || $src} {
		add-src-clean [make-local distclean] $args
	} else {
		add-clean [make-local distclean] [make-local {*}$args]
	}
}

rule Generate {args} {
Generate ?--interp=<interp>? ?--chdir? target generator inputs rules target-args...

A general purpose rule to create a target via a generator (program or script).

The arguments are as follows:
  --interp    Optional built or external program required to run the generator. Available as $interp
  --chdir     If specified, the generator runs from the local directory
  target      The target to generator. May be a list of one or more targets. Available as $target
  generator   The generator program or script. May be a local built target, a published built target
              (in which case the <bin> prefix is used), empty for none, or an external command (if none of the above).
              Unless empty, this is available as $script
  inputs      Local files that are inputs to the generator. Available as $inputs
  rules       A -do script that generates the target
  target-args Additional arguments to 'target'

The following is an example of a local, built generator.

  Executable mkindex mkindex.c
  Generate page_index.h mkindex *.c {
    run $script $inputs >$target
  }

If 'mkindex' were created in another directory and published with 'Executable --publish'
or 'PublishBin', we would use the following:

  Generate page_index.h <bin>mkindex *.c {
    run $script $inputs >$target
  }

If 'mkindex.rb' were a script that used a locally built version of 'ruby' to run, we would use:

  Generate --interp=<bin>ruby page_index.h mkindex.rb *.c {
    run $interp $script -o $target $inputs
  }

} {
	# XXX: Would be nice if script and inputs were optional
	getopt {--interp: --chdir target script inputs rules args} args

	set localtarget [make-local {*}$target]

	set opts {}
	if {[info exists interp]} {
		lassign [find-project-bin $interp -chdir $chdir] dep filename
		lappend opts -depends $dep -vars interp $filename
	}
	if {$script ne ""} {
		lassign [find-project-bin $script -chdir $chdir -optional 1] dep filename
		lappend opts -depends $dep -vars script $filename
	}
	if {$chdir} {
		lappend args -chdir
	}
	target $localtarget -inputs {*}[make-local {*}$inputs] {*}$opts -do $rules -msg {note Generate $targetname} {*}$args
	Clean $target
	return $localtarget
}

rule Depends {target args} {
Depends target target-args...

Creates a local target with the given additional target arguments.

e.g.

  Depends b.txt -inputs [make-local b.in] -do {
    cat $inputs >$target
  }
} {
	target [make-local {*}$target] -depends {*}$args
}

rule Phony {target args} {
Phony target target-args...

Creates a Phony, local target with the given additional target arguments.

See Depends
} {
	show-this-rule
	target [make-local {*}$target] -phony -depends {*}$args
}

proc LocalMakefile {name} {
	user-notice purple [warning-location "Warning: LocalMakefile is deprecated and ignored"]
}

rule DefaultOptions {rule args} {
DefaultOptions <command> options...

e.g. DefaultOptions Executable --strip
e.g. DefaultOptions SharedObject --strip=dynamic

Allows default options to be supplied for commands.
Note that currently only Executable, SharedObject and SharedLib support DefaultOptions
} {
	set-default-opts $rule $args
}

rule DefaultTarget {name} {
DefaultTarget target

Sets the default (local) target.
i.e. when tmake is invoked with no options.
The default is 'all'
} {
	show-this-rule
	set-default-target $name
}

rule HostLibs {args} {
HostLibs ...

Like UseSystemLibs, but for host builds with HostExecutable.
Adds the given arguments to HOST_SYSLIBS
} {
	define-append HOST_SYSLIBS {*}$args
}

rule HostExecutable {target args} {
HostExecutable target sources ...

A very simple version of Executable for building host (as opposed to target) applications.

Bound variables: HOST_CFLAGS, HOST_SYSLIBS (from HostLibs)
Used variables: CC_FOR_BUILD (defaults to gcc)

Note: HostExecutable and HostLibs are stopgaps until separate build contexts are fully supported
} {
	set localtarget [make-local $target]

	set localtargetexe $localtarget[get-define HOST_EXEEXT]
	set targetexe $target[get-define HOST_EXEEXT]

	target $localtargetexe -inputs {*}[make-local {*}$args] -msg {note HostExecutable $targetname} -getvars HOST_CFLAGS HOST_SYSLIBS -do {
		run $CC_FOR_BUILD $HOST_CFLAGS -o $target $inputs $HOST_SYSLIBS
	} -dyndep {
		header-scan-regexp-recursive $local "" $CHDRPATTERN
	} {*}[target-alias $target $targetexe]

	set desttargetexe [file-join [publish-dir bin] $targetexe]
	hard-link $desttargetexe $localtargetexe -vars dest bin/$target -msg {note Publish $targetname} -alias <bin>[file tail $target]
	target $desttargetexe -add -do {
		chmodx-file $target
	}
	Clean $targetexe

	return $localtarget
}

rule ExternalBuild {user_spec} {
ExternalBuild build-specification

Simplifies integration of a project with it's own build system.

Supports configure, build, clean and distclean targets.

build-specification is a dictionary containing some or all of the following entries:

  configure          - Name of the configure script, or "" if none. [default: configure]
  configure_opts     - Additional options to configure [default: none]
  configure_targets  - Targets generated by 'configure' [default: none]
  build              - Command to build [default: make]
  build_opts         - Additional options to build [default: none]
  build_targets      - Non-library targets generated by 'make' [default: none]
  lib_targets        - Archive library targets generated by 'make', as a list of: libname filename ... [default: none]
  clean              - Command to clean [default: make clean]
  distclean          - Command to distclean [default: make distclean]

Notes:
- The build is done "out of tree", and configure must accept --host and --build
- CONFIGURE_HOST and CONFIGURE_BUILD must be defined
- Currently shared libaries are not supported
- Header files, binaries etc. should be published and installed as normal
- The only dependencies for the external project are:
  - The completion of the configure and build commands
  - The existence of the configure and build targets
  - The commands used to configure and build
- configure_opts and build_opts are expanded at build time, so they may include, e.g. [get-define]
} {
	# Set up the default behaviour
	set spec {
		configure {configure}
		configure_opts {}
		build {make}
		build_opts {}
		clean {make clean}
		distclean {make distclean}
		configure_targets {}
		build_targets {}
		lib_targets {}
	}
	foreach {k v} $user_spec {
		if {$k eq "#"} {
			continue
		}
		if {![exists spec($k)]} {
			user-error "ExternalBuild doesn't recognise $k=$v"
		}
		set spec($k) $v
	}

	# --- configure ----
	if {$spec(configure) ne ""} {
		lassign [find-project-bin $spec(configure) -chdir 1] script_dep script_filename
		set configure_targets [list .configure {*}$spec(configure_targets)]

		set configure_opts [list --host=[get-define CONFIGURE_HOST] --build=[get-define CONFIGURE_BUILD] {*}[subst $spec(configure_opts)]]

		Depends $configure_targets [make-local $spec(configure)] -msg [list note External [make-local configure]] -do {
			run $script_filename $configure_opts
			writefile .configure "done"
		} -vars script_filename $script_filename configure_opts $configure_opts -chdir

		# Assume .distclean can only run if configured
		Phony .distclean -do {
			if {[file exists .configure]} {
				run $cmd
			}
		} -vars cmd $spec(distclean) -chdir
		Depends distclean [make-local .distclean]
		DistClean .configure
	} else {
		# Create a dummy configure step
		Depends .configure -do {
			writefile $target "done"
		}
		DistClean .configure
	}

	# --- build ----
	set build_targets [list .build {*}$spec(build_targets)]
	foreach {basename lib} $spec(lib_targets) {
		lappend build_targets $lib
	}
	set build_opts [subst $spec(build_opts)]

	Depends $build_targets [make-local .configure] -msg [list note External [make-local build]] -do {
		run $cmd $build_opts
		writefile .build "done"
	} -vars cmd $spec(build) build_opts $build_opts -chdir

	# Assume .clean can only run if configured
	Phony .clean -do {
		if {[file exists .configure]} {
			run $cmd
		}
	} -vars cmd $spec(clean) -chdir
	Depends clean [make-local .clean]
	Clean .built

	# --- libs ----
	foreach {basename lib} $spec(lib_targets) {
		set libname [file tail $lib]
		set libalias <lib>$basename
		set liblocal [make-local $lib]

		Phony libs $liblocal

		# Can't use publish-lib here because the lib may be in a subdir
		hard-link [publish-prefix lib]$libname $liblocal -msg {note Publish $targetname} -alias $libalias
		#publish-lib $libname $libalias
	}

	# XXX support for shared libs ...
}

rule Configure {args} {
Configure ?--configure=configscript? ?--output=filename? ?--logfile=logfile? {targets} {inputs} {do rules} ...

Runs an autoconf-compatible ./configure (defaults to "configure") to produce the given
targets. The given inputs (if any) are added as dependencies.
Runs the "do" rules, with the $configure variable set to the name of the configure script.

Additional 'target' arguments may be appended.

Typical usage for autoconf is:

  Configure --output=config.out --logfile=config.log include/config.h {} {
    run $configure >config.out
  }

The following options are supported:
  --output=filename    The output from the configure command is assumed to be written to 'filename',
                       and it is displayed if the configure fails.
  --logfile=filename   'Distclean --source $logfile' is added to delete the logfile on distclean.
} {
	getopt {--output: --logfile: --configure: targets inputs rules args} args

	if {![info exists configure]} {
		set configure "configure"
	}
	set inputs [make-local $configure {*}$inputs]
	set opts {}

	if {[info exists output]} {
		lappend opts -onerror "puts \[readfile \$build/$output\]"
		Clean $output
	}
	if {[info exists logfile]} {
		DistClean --source $logfile
	}

	Depends $targets $inputs -msg {note Configure $targetname} -fatal -vars configure $configure -do $rules {*}$opts {*}$args
	DistClean $targets
}

rule Autosetup {args} {
Autosetup ?--verbose? {targets} ...

Runs an autosetup-compatible configure to produce settings.conf plus the additional given targets.

Be sure to add something similar to the following to your auto.def file:

  use tmake
  ...
  make-tmake-settings [get-env BUILDDIR objdir]/settings.conf {[A-Z]*} *dir lib_*

The following options are supported:
  --verbose  Normally output is sent to config.out and only shown on error,
             but --verbose causes the output to be sent directly to stdout instead.

Bound variables: CONFIGURE_ENV is checked for changes to force configure to rerun
Used variables: AUTOREMAKE is the configure command to run
} {
	getopt {--verbose targets args} args

	set opts {}
	set redirect {}

	# We use [set redirect] in the -do to avoid rebuilding settings.conf
	# if just the verbosity setting changes
	if {$verbose || $::tmake(verbose)} {
		set redirect ">@stdout 2>@stderr"
	} else {
		set redirect >[file-build config.out]
		lappend opts --output=config.out
	}

	set alltargets [list settings.conf {*}$targets]

	# If not configured, configure with default options (or options to --configure)
	# Note that it is expected that configure will normally be run
	# separately. This is just a convenience.
	# project.spec can redefine AUTOREMAKE if required
	define? AUTOREMAKE ./configure

	# Create the rule
	Depends $alltargets

	# Now load the settings
	Load settings.conf

	# Note that we use exec here instead of run to avoid misinterpetation
	# of AUTOREMAKE arguments, that will often contain spaces
	Configure {*}$opts --logfile=config.log $alltargets auto.def {
		# $CONFIGURE_ENV
		vputs $AUTOREMAKE
		exec {*}$AUTOREMAKE {*}[set redirect]
	} -getvars CONFIGURE_ENV -nofork -vars redirect $redirect {*}$args
}

# ==================================================================
# Built-in targets
# ==================================================================

clean-target clean Clean
clean-target distclean DistClean
clean-target uninstall Uninstall -rootok

Phony all
Phony libs
Phony install all
Phony test

Depends clean clean-orphans
Depends distclean clean-orphans

DistClean .makecache

# Invoked manually
Phony clean-orphans -do {
	do-delete-orphans [get-orphan-targets]
	# Now remove the trash
	if {[file exists .trash]} {
		note Clean .trash
		file delete -force .trash
	}
}

# @delete-orphan-files files ...
#
# This callback is invoked to delete orphans
# This version replaces the builtin version.
# Instead of deleting files immediately, orphans are moved into
# the .trash directory. This directory is only removed via the
# 'clean', 'distclean' or 'clean-orphans' targets.
proc delete-orphan-files {args} {
	# XXX can't create .trash if it doesn't exist and we are root 
	file-mkdir -rooterr .trash
	foreach file $args {
		if {[file-type $file] in {file link}} {
			set trashfile .trash/[string map {/ _} $file]
			# Can't simple use file rename -force in case the files are hard links
			file delete $trashfile
			file rename $file $trashfile
		}
	}
}