explain patching of older versions

Waf is also intended to be compiled into a binary for project-local use.
A change in Python breaks these binaries when they are created from a
waf version before 2.0.7. Thus, an explanation on how to recompile and
patch these enables maintainers unable to upgrade to the latest waf
right away to still build their projects.

1 files changed, 22 insertions, 0 deletions

diff --git a/building-waf.md b/building-waf.md
index e78e2f3d9d99..082c062e70c8 100644
--- a/building-waf.md
+++ b/building-waf.md
@@ -14,3 +14,25 @@ waf configure build --make-waf --tools=''
 The last line allows you to choose tools to include.
 
 After this process, there should be a `waf` binary ready in the current working directory.
+
+
+## Building an older version for current Python
+
+Especially after version 2 introduced API-breaking changes, some projects may have become incompatible and require older waf versions to build. Fortunately, they mostly stay available online and can be retrieved directly in binary form with a command like
+
+```bash
+wget -O waf http://ftp.waf.io/pub/release/waf-1.2.3
+chmod 755 waf
+```
+
+Unfortunately, a change in language library makes these impossible to run on Python version 3.7 or up. However, by applying the necessary change that made waf 2.0.7 compatible to newer Python versions, a compatible binary can still be built. The patch should apply even on older versions. This can be achieved through a build process similar to the one described above, extended with the download of an older waf version and patch.
+
+```bash
+wget 'https://waf.io/waf-1.8.22.tar.bz2'
+wget 'https://gitlab.com/ita1024/waf/commit/facdc0b173d933073832c768ec1917c553cb369c.patch'
+tar xjf waf-*.tar.bz2
+rm waf-*.tar.bz2
+cd waf-*
+patch -p1 -i ../*.patch
+./waf-light configure build --make-waf --tools=''
+```