michael@0: INTRODUCTION
michael@0: 
michael@0: make.py (and the pymake modules that support it) are an implementation of the make tool
michael@0: which are mostly compatible with makefiles written for GNU make.
michael@0: 
michael@0: PURPOSE
michael@0: 
michael@0: The Mozilla project inspired this tool with several goals:
michael@0: 
michael@0: * Improve build speeds, especially on Windows. This can be done by reducing the total number
michael@0:   of processes that are launched, especially MSYS shell processes which are expensive.
michael@0: 
michael@0: * Allow writing some complicated build logic directly in Python instead of in shell.
michael@0: 
michael@0: * Allow computing dependencies for special targets, such as members within ZIP files.
michael@0: 
michael@0: * Enable experiments with build system. By writing a makefile parser, we can experiment
michael@0:   with converting in-tree makefiles to another build system, such as SCons, waf, ant, ...insert
michael@0:   your favorite build tool here. Or we could experiment along the lines of makepp, keeping
michael@0:   our existing makefiles, but change the engine to build a global dependency graph.
michael@0: 
michael@0: KNOWN INCOMPATIBILITIES
michael@0: 
michael@0: * Order-only prerequisites are not yet supported
michael@0: 
michael@0: * Secondary expansion is not yet supported.
michael@0: 
michael@0: * Target-specific variables behave differently than in GNU make: in pymake, the target-specific
michael@0:   variable only applies to the specific target that is mentioned, and does not apply recursively
michael@0:   to all dependencies which are remade. This is an intentional change: the behavior of GNU make
michael@0:   is neither deterministic nor intuitive.
michael@0: 
michael@0: * $(eval) is only supported during the parse phase. Any attempt to recursively expand
michael@0:   an $(eval) function during command execution will fail. This is an intentional incompatibility.
michael@0: 
michael@0: * There is a subtle difference in execution order that can cause unexpected changes in the
michael@0:   following circumstance:
michael@0: ** A file `foo.c` exists on the VPATH
michael@0: ** A rule for `foo.c` exists with a dependency on `tool` and no commands
michael@0: ** `tool` is remade for some other reason earlier in the file
michael@0:   In this case, pymake resets the VPATH of `foo.c`, while GNU make does not. This shouldn't
michael@0:   happen in the real world, since a target found on the VPATH without commands is silly. But
michael@0:   mozilla/js/src happens to have a rule, which I'm patching.
michael@0: 
michael@0: * pymake does not implement any of the builtin implicit rules or the related variables. Mozilla
michael@0:   only cares because pymake doesn't implicitly define $(RM), which I'm also fixing in the Mozilla
michael@0:   code.
michael@0: 
michael@0: ISSUES
michael@0: 
michael@0: * Speed is a problem.
michael@0: 
michael@0: FUTURE WORK
michael@0: 
michael@0: * implement a new type of command which is implemented in python. This would allow us
michael@0: to replace the current `nsinstall` binary (and execution costs for the shell and binary) with an
michael@0: in-process python solution.
michael@0: 
michael@0: AUTHOR
michael@0: 
michael@0: Initial code was written by Benjamin Smedberg <benjamin@smedbergs.us>. For future releases see
michael@0: http://benjamin.smedbergs.us/pymake/
michael@0: 
michael@0: See the LICENSE file for license information (MIT license)