Where does the name Waf come from?

The name 'Waf' was the shortest and easily typed name that we found at the time (2005). There is no particular meaning.

Where is the license?

It is right here and is included in every waf file.

Where are the examples?

Two classes of examples are provided in the Waf distribution:

  1. Supported examples in the folder demos
  2. Work in progress examples in the folder playground

Examples of large projects can be found in this list

Why does touch-ing a file not force a rebuild?

By default, Waf hashes the file contents, so the files will be rebuilt when the actual file contents change

Why hashing files at all? Hashing files is inefficient

In general, the python hashing function (md5-based) is rarely a problem. The bottlenecks are usually elsewhere, for example in the amount of memory consumed by the python process. The hashing function can be changed though; a tool illustrates how to compute hashes only when the file timestamps have changed

How to force rebuilds when system headers change?

This is quite slow and ineffective in general but if you really want this:

   from waflib.Tools import c_preproc
   c_preproc.go_absolute=True # enable system folders
   c_preproc.standard_includes.append('/opt/include') # additional system folders 

Alternatively the tools gccdeps or msvcdeps can provide faster dependency calculation.

How to speed up dependency calculation? (boost libraries)

The tools gccdeps, msvcdeps or c_dumbpreproc are not completely portable or accurate but they may help.

Why do my builds run so often?

Run the build with 'waf -v' to see the warnings/errors (if the same files are produced, force a particular 'idx' value), then use the why tool to display the causes. Leaving stale files in the source directory can be a source of problems, so keep your source directory tidy.

Another potential source of rebuilds can be the excessive use of unordered collections (sets or dicts) in older Python versions.

How to create pkg-config files?

See substitution examples

Why does foo.cpp yield a file named foo.cpp.number.o?

This is to prevent collisions that would lead to unnecessary rebuilds. The index can easily be forced to a specific value if necessary: bld(..., idx=566)

Why is the index above per-wscript file and not global for an entire project?

This is to save resources: if the index were global, then adding or changing a target would force a rebuild of the entire project. This behaviour can be overridden if necessary.



Last update: July 2025