Makefile: generate descriptions on-the-fly

Checking in the generated descriptions files makes few things simpler,
but causes pain for pull requests: (1) PRs that touch descriptions
_always_ conflict, (2) PRs are large and harder to review,
(3) people sometimes forget to add auto-generated files.

The proposed way does not require us to hardcode lots of dependencies
in the Makefile (which is nice) and seem to work.
Let's see how it works.

The main contributor-visible consequence is that the auto-generated
files do not need to be checked-in now.

Credit for figuring the Makefile magic goes to @melver.

Fixes #1291

2 files changed, 7 insertions, 11 deletions

diff --git a/docs/contributing.md b/docs/contributing.md
index a701e6682..9e3a14dd3 100644
--- a/docs/contributing.md
+++ b/docs/contributing.md
@@ -30,10 +30,9 @@ Also:
 (where `NNN` is issue number). This will auto-close the issue. If you need to mention
 an issue without closing it, add `Update #NNN`.
 - The pull request text is mostly irrelevant.
-- Run `make presubmit` and ensure that it passes before sending a PR. It may require some additional packages to be installed (try `sudo make install_prerequisites`).
-- _All_ generated files (`*.const`, `*.go`, `*.h`) are checked-in with the
-`*.txt` changes in the same commit. Namely, `make generate` must not produce
-_any_ diff in the tree.
+- Run `make presubmit` and ensure that it passes before sending a PR.
+  It may require some additional packages to be installed (try `sudo make install_prerequisites`).
+- `*.const` files are checked-in with the `*.txt` changes in the same commit.
 - Rebase your pull request onto the master branch before submitting.
 - If you're asked to add some fixes to your pull requested, please squash the new commits with the old ones.
 
diff --git a/docs/syscall_descriptions.md b/docs/syscall_descriptions.md
index 7cf715250..7e46fa2d8 100644
--- a/docs/syscall_descriptions.md
+++ b/docs/syscall_descriptions.md
@@ -76,17 +76,15 @@ so if `make extract` complains about missing header files or constants undefined
 try to use the latest [linux-next](https://git.kernel.org/pub/scm/linux/kernel/git/next/linux-next.git/log/)
 tree (or if it happens to be broken at the moment, try a slightly older linux-next tree).\
 _Note_: `make extract` overwrites `.config` in `$KSRC` and `mrproper`'s it.
+_Note_: `*.const` files are checked-in with the `*.txt` changes in the same commit.
 
 Then `make generate` updates generated code and `make` rebuilds binaries.\
 Note: `make generate` does not require any kernel sources, native compilers, etc
 and is pure text processing.
-Note: `make generate` also updates the SYZ_REVISION under executor/defs.h, which
+Note: `make generate` also updates the SYZ_REVISION under `executor/defs.h`, which
 is required for machine check while running syz-manager. This should be taken care
 of especially if you are trying to rebase with your own change on syscall description.
 
-Note: _all_ generated files (`*.const`, `*.go`, `*.h`) are checked-in with the
-`*.txt` changes in the same commit.
-
 Note: `make extract` extracts constants for all architectures which requires
 installed cross-compilers. If you get errors about missing compilers/libraries,
 try `sudo make install_prerequisites` or install equivalent package for your distro.
@@ -121,9 +119,8 @@ The second step is translation of descriptions into Go code using
 [pkg/ast](/pkg/ast/) and [pkg/compiler](/pkg/compiler/)).
 This step uses syscall descriptions and the const files generated during the first step
 and produces instantiations of `Syscall` and `Type` types defined in [prog/types.go](/prog/types.go).
-Here is an [example](/sys/akaros/gen/amd64.go) of the compiler output for Akaros.
-This step also generates some minimal syscall metadata for C++ code in
-[executor/syscalls.h](/executor/syscalls.h).
+You can see an example of the compiler output for Akaros in `sys/akaros/gen/amd64.go`.
+This step also generates some minimal syscall metadata for C++ code in `executor/syscalls.h`.
 
 ## Non-mainline subsystems