Skip to content
Browse files

Update to the latest version of pake

  • Loading branch information...
1 parent 5575587 commit d0c83c74d26cbf4f010addd028c14db2556a005c @twpayne twpayne committed
Showing with 131 additions and 8 deletions.
  1. +131 −8
@@ -71,14 +71,31 @@ def __str__(self):
return 'duplicate target %r' % (,)
+class UnknownTargetError(PakeError):
+ def __init__(self, name):
+ = name
+ def __str__(self):
+ return 'unknown target %r' % (,)
class Target(object):
+ """Target is the core object of pake. It includes all of the target's name
+ (which may or may not correspond to a real file in the filesystem, see the
+ comments in virtual and TargetCollection below), the action to be performed
+ when this target is to be rebuilt, its dependencies, and various other
+ metadata."""
def __init__(self, name, action=None, clean=True, dependencies=(),
- makedirs=True, phony=False, precious=False):
+ help=None, help_group=None, makedirs=True, phony=False,
+ precious=False): = name
self.action = action
self._clean = clean
self.dependencies = list(flatten(dependencies))
+ = help
+ self.help_group = help_group
self._makedirs = makedirs
self.phony = phony
self.precious = precious
@@ -184,17 +201,26 @@ def newer(self, *args):
if targets.get(arg).timestamp > self.timestamp]
def output(self, *args, **kwargs):
+ """output runs the command passed to it, saving the output of the
+ command to the contents of the target. For example:
+ @target('ofile')
+ def ofile(t):
+ t.output('echo', '123')
+ After this target's action is executed, ofile will contain the string
+ "123"."""
args = flatten_expand_list(args)' '.join(args))
output = check_output(args, **kwargs)
- with open(, 'w') as f:
+ with open(, 'wb') as f:
except subprocess.CalledProcessError as e:
def rm_rf(self, *args):
+ """rm_rf recursively deletes the files and/or directories passed to
+ it."""
args = flatten_expand_list(args)
for arg in args:'rm -rf %s', arg)
@@ -211,6 +237,15 @@ def run(self, *args, **kwargs):
def tempdir(self):
+ """tempdir creates a temporary directory, changes to it, and runs the
+ nested block of code. However the nested block of code exits, tempdir
+ will delete the temporary directory permanently, before pake exits. For
+ example:
+ with t.tempdir():
+ # copy various files to $PWD (the temporary directory)
+ # zip up the contents of $PWD, or copy them somewhere else
+ However the above code exits (e.g. copy error or zip error), the
+ temporary directory will be cleaned up."""
tempdir = tempfile.mkdtemp()'mkdir -p %s', tempdir)
@@ -220,20 +255,32 @@ def tempdir(self):
shutil.rmtree(tempdir, ignore_errors=True)
def touch(self):
+ """touch updates the timestamp of the target. If the target already
+ exists as a file in the filesystem its timestamp is updated, otherwise
+ a new file is created with the current timestamp."""
if os.path.exists(
os.utime(, None)
- with open(, 'w'):
+ with open(, 'wb'):
class TargetCollection(object):
+ """TargetCollection implements a namespace for looking up build targets.
+ TargetCollection will first look for rules that match exactly, and then
+ - if no match is found - search through a list of regular expression-based
+ rules. As soon as a regular expression match is found, that rule is added
+ to the list of rules that match exactly. Typically, an invocation of pake
+ will only create a single TargetCollection."""
def __init__(self):
self.default = None
self.targets = {}
def add(self, target):
+ """add adds a concrete target to self, raising an error if the target
+ already exists. If target is the first target to be added, it becomes
+ the default for this TargetCollection."""
if in self.targets:
raise DuplicateTargetError(target)
self.targets[] = target
@@ -241,6 +288,11 @@ def add(self, target):
self.default = target
def get(self, name):
+ """get searches for a target. If it already exists, it is returned.
+ Otherwise, get searches through the defined rules, trying to find a
+ rule that matches. If it finds a matching rule, a concrete target is
+ instantiated, cached, and returned. If no match is found, a virtual
+ precious target is instantiated and returned."""
if name in self.targets:
return self.targets[name]
target = None
@@ -252,28 +304,74 @@ def get(self, name):
raise AmbiguousRuleError(name)
target = f(name, match)
if target is None:
- target = Target(name, precious=True)
+ if os.path.exists(name):
+ target = Target(name, precious=True)
+ else:
+ raise UnknownTargetError(name)
self.targets[name] = target
return target
+ def format_epilog(self, formatter):
+ helps_by_help_group = collections.defaultdict(dict)
+ max_name_len = 0
+ for name in sorted(self.targets):
+ target = self.targets[name]
+ if is not None:
+ helps_by_help_group[target.help_group][name] =
+ max_name_len = max(max_name_len, len(name))
+ lines = []
+ lines.append('Targets:\n')
+ format = ' %%-%ds %%s\n' % (max_name_len,)
+ for help_group in sorted(helps_by_help_group.keys()):
+ helps = helps_by_help_group[help_group]
+ if help_group is not None:
+ lines.append('%s targets:\n' % (help_group,))
+ for name in sorted(helps.keys()):
+ lines.append(format % (name, helps[name]))
+ return ''.join(lines)
class VariableCollection(object):
+ """VariableCollection implements an object with properties where the first
+ set of a property wins, and all further sets are ignored. For example:
+ vc = VariableCollection()
+ vc.FOO = 1 # First set of the property FOO
+ vc.FOO = 2 # Further sets of the property FOO are ignored, and do
+ # not raise an error. After this statement, vc.FOO is
+ # still 1.
+ print vc.FOO # Prints "1" """
def __init__(self, **kwargs):
for key, value in kwargs.iteritems():
setattr(self, key, value)
def __setattr__(self, key, value):
+ """Only set an attribute if it has not already been set. First to set
+ the value is the winner."""
if not hasattr(self, key):
object.__setattr__(self, key, value)
+# targets is the single TargetCollection instance created for this invokation
+# of pake
targets = TargetCollection()
+# rules is a dict of regular expressions to @rules where dynamically created
+# rules are registered.
rules = {}
+# variables is the global set of substitution variables, where the first setter
+# takes priority. The priority order is:
+# 1. Environment variables
+# 2. Command line arguments
+# 3. Internal Python settings in
variables = VariableCollection(**os.environ)
def flatten(*args):
+ """flatten takes a variable number of arguments, each of which may or may
+ be not be a collection.Iterable, and yields the elements of each in
+ depth-first order. In short, it flattens nested iterables into a single
+ collection. For example, flatten(1, [2, (3, 4), 5], 6) yields 1, 2, 3, 4,
+ 5, 6."""
for arg in args:
if (isinstance(arg, collections.Iterable) and
not isinstance(arg, basestring)):
@@ -284,17 +382,21 @@ def flatten(*args):
def flatten_expand_list(*args):
+ """flatten_expand_list applies flatten, treats each element as a string,
+ and formats each string according to the global value of variables."""
return list(arg % vars(variables) for arg in flatten(args))
def ifind(*paths):
+ """ifind is an iterative version of os.walk, yielding all walked paths and
+ normalizing paths to use forward slashes."""
for path in paths:
for dirpath, dirnames, names in os.walk(path):
for name in names:
- if sys.platform == 'win32':
- yield '/'.join(dirpath.split('\\') + [name])
- else:
+ if os.sep == '/':
yield os.path.join(dirpath, name)
+ else:
+ yield '/'.join(dirpath.split(os.sep) + [name])
def main(argv=sys.argv):
@@ -310,6 +412,7 @@ def main(argv=sys.argv):
option_parser.add_option('-v', '--verbose',
action='count', dest='logging_level')
+ option_parser.format_epilog = targets.format_epilog
options, args = option_parser.parse_args(argv[1:])
logging.basicConfig(format='%(asctime)s %(name)s: %(message)s',
level=logging.INFO - 10 * options.logging_level)
@@ -343,6 +446,11 @@ def main(argv=sys.argv):
def output(*args):
+ """output captures the output of a single command. It is typically used to
+ set variables that only need to be set once. For example:
+ UNAME_A = output('uname', '-a')
+ If you need to capture the output of a command in a target, you should use
+ t.output."""
args = flatten_expand_list(args)
logger.debug(' '.join(args))
return check_output(args)
@@ -355,6 +463,14 @@ def f(targetmaker):
def target(name, *dependencies, **kwargs):
+ """The @target decorator describes the action needed to build a single
+ target file when its dependencies are out of date. For example:
+ @target('hello', 'hello.c')
+ def hello(t):
+'gcc', '-o',, t.dependencies)
+ # the above line will run gcc -o hello hello.c
+ See the documentation for Target to see the properties provide by the
+ target t."""
def f(action):
target = Target(name, action=action, dependencies=dependencies,
@@ -363,6 +479,12 @@ def f(action):
def virtual(name, *dependencies, **kwargs):
+ """virtual targets are metatargets. They do not correspond to any real
+ file in the filesystem, even if a file with the same name already exists.
+ Virtual targets can be thought of as only existing for the duration of the
+ build. Their up-to-dateness or otherwise is independent of any existence
+ or up-to-dateness of any actual file in the filesystem. Typically they are
+ used to group actions such as "all", "build", or "test"."""
target = Target(name, dependencies=dependencies, clean=False, phony=True,
@@ -370,7 +492,8 @@ def virtual(name, *dependencies, **kwargs):
def which(program):
"""Returns the full path of a given argument or `None`.
- See:"""
+ See:
def is_exe(fpath):
return os.path.isfile(fpath) and os.access(fpath, os.X_OK)
fpath, fname = os.path.split(program)

0 comments on commit d0c83c7

Please sign in to comment.
Something went wrong with that request. Please try again.