1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/build/pymake/README Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,64 @@
1.4 +INTRODUCTION
1.5 +
1.6 +make.py (and the pymake modules that support it) are an implementation of the make tool
1.7 +which are mostly compatible with makefiles written for GNU make.
1.8 +
1.9 +PURPOSE
1.10 +
1.11 +The Mozilla project inspired this tool with several goals:
1.12 +
1.13 +* Improve build speeds, especially on Windows. This can be done by reducing the total number
1.14 + of processes that are launched, especially MSYS shell processes which are expensive.
1.15 +
1.16 +* Allow writing some complicated build logic directly in Python instead of in shell.
1.17 +
1.18 +* Allow computing dependencies for special targets, such as members within ZIP files.
1.19 +
1.20 +* Enable experiments with build system. By writing a makefile parser, we can experiment
1.21 + with converting in-tree makefiles to another build system, such as SCons, waf, ant, ...insert
1.22 + your favorite build tool here. Or we could experiment along the lines of makepp, keeping
1.23 + our existing makefiles, but change the engine to build a global dependency graph.
1.24 +
1.25 +KNOWN INCOMPATIBILITIES
1.26 +
1.27 +* Order-only prerequisites are not yet supported
1.28 +
1.29 +* Secondary expansion is not yet supported.
1.30 +
1.31 +* Target-specific variables behave differently than in GNU make: in pymake, the target-specific
1.32 + variable only applies to the specific target that is mentioned, and does not apply recursively
1.33 + to all dependencies which are remade. This is an intentional change: the behavior of GNU make
1.34 + is neither deterministic nor intuitive.
1.35 +
1.36 +* $(eval) is only supported during the parse phase. Any attempt to recursively expand
1.37 + an $(eval) function during command execution will fail. This is an intentional incompatibility.
1.38 +
1.39 +* There is a subtle difference in execution order that can cause unexpected changes in the
1.40 + following circumstance:
1.41 +** A file `foo.c` exists on the VPATH
1.42 +** A rule for `foo.c` exists with a dependency on `tool` and no commands
1.43 +** `tool` is remade for some other reason earlier in the file
1.44 + In this case, pymake resets the VPATH of `foo.c`, while GNU make does not. This shouldn't
1.45 + happen in the real world, since a target found on the VPATH without commands is silly. But
1.46 + mozilla/js/src happens to have a rule, which I'm patching.
1.47 +
1.48 +* pymake does not implement any of the builtin implicit rules or the related variables. Mozilla
1.49 + only cares because pymake doesn't implicitly define $(RM), which I'm also fixing in the Mozilla
1.50 + code.
1.51 +
1.52 +ISSUES
1.53 +
1.54 +* Speed is a problem.
1.55 +
1.56 +FUTURE WORK
1.57 +
1.58 +* implement a new type of command which is implemented in python. This would allow us
1.59 +to replace the current `nsinstall` binary (and execution costs for the shell and binary) with an
1.60 +in-process python solution.
1.61 +
1.62 +AUTHOR
1.63 +
1.64 +Initial code was written by Benjamin Smedberg <benjamin@smedbergs.us>. For future releases see
1.65 +http://benjamin.smedbergs.us/pymake/
1.66 +
1.67 +See the LICENSE file for license information (MIT license)
