[XEN PATCH v4 07/18] build: Introduce documentation for xen Makefiles

[Anthony PERARD <anthony.perard@xxxxxxxxxx>]

This start explainning the variables that can be used in the many
Makefiles in xen/.

Most of the document copies and modifies text from Linux v5.4 document
linux.git/Documentation/kbuild/makefiles.rst. Modification are mostly
to avoid mentioning kbuild. Thus I've added the SPDX tag which was
only in index.rst in linux.git.

Signed-off-by: Anthony PERARD <anthony.perard@xxxxxxxxxx>
---

Notes:
    v4:
    - new patch

 docs/misc/xen-makefiles/makefiles.rst | 87 +++++++++++++++++++++++++++
 xen/Rules.mk                          |  4 ++
 2 files changed, 91 insertions(+)
 create mode 100644 docs/misc/xen-makefiles/makefiles.rst

diff --git a/docs/misc/xen-makefiles/makefiles.rst 
b/docs/misc/xen-makefiles/makefiles.rst
new file mode 100644
index 000000000000..a86e3a612d61
--- /dev/null
+++ b/docs/misc/xen-makefiles/makefiles.rst
@@ -0,0 +1,87 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+=============
+Xen Makefiles
+=============
+
+Documentation for the build system of Xen, found in xen.git/xen/.
+
+Makefile files
+==============
+
+Description of the syntax that can be used in most Makefiles named
+'Makefile'. ('xen/Makefile' isn't part of the description.)
+
+'Makefile's are consumed by 'Rules.mk' when building.
+
+Goal definitions
+----------------
+
+       Goal definitions are the main part (heart) of the Makefile.
+       These lines define the files to be built, any special compilation
+       options, and any subdirectories to be entered recursively.
+
+       The most simple makefile contains one line:
+
+       Example::
+
+               obj-y += foo.o
+
+       This tells the build system that there is one object in that
+       directory, named foo.o. foo.o will be built from foo.c or foo.S.
+
+       The following pattern is often used to have object selected
+       depending on the configuration:
+
+       Example::
+
+               obj-$(CONFIG_FOO) += foo.o
+
+       $(CONFIG_FOO) can evaluates to y.
+       If CONFIG_FOO is not y, then the file will not be compiled nor linked.
+
+Descending down in directories
+------------------------------
+
+       A Makefile is only responsible for building objects in its own
+       directory. Files in subdirectories should be taken care of by
+       Makefiles in these subdirs. The build system will automatically
+       invoke make recursively in subdirectories, provided you let it know of
+       them.
+
+       To do so, obj-y is used.
+       acpi lives in a separate directory, and the Makefile present in
+       drivers/ tells the build system to descend down using the following
+       assignment.
+
+       Example::
+
+               #drivers/Makefile
+               obj-$(CONFIG_ACPI) += acpi/
+
+       If CONFIG_ACPI is set to 'y'
+       the corresponding obj- variable will be set, and the build system
+       will descend down in the apci directory.
+       The build system only uses this information to decide that it needs
+       to visit the directory, it is the Makefile in the subdirectory that
+       specifies what is modular and what is built-in.
+
+       It is good practice to use a `CONFIG_` variable when assigning directory
+       names. This allows the build system to totally skip the directory if the
+       corresponding `CONFIG_` option is 'y'.
+
+Compilation flags
+-----------------
+
+    CFLAGS-y and AFLAGS-y
+       These two flags apply only to the makefile in which they
+       are assigned. They are used for all the normal cc, as and ld
+       invocations happening during a recursive build.
+
+       $(CFLAGS-y) is necessary because the top Makefile owns the
+       variable $(XEN_CFLAGS) and uses it for compilation flags for the
+       entire tree. And the variable $(CFLAGS) is modified by Config.mk
+       which evaluated in every subdirs.
+
+       CFLAGS-y specifies options for compiling with $(CC).
+       AFLAGS-y specifies assembler options.
diff --git a/xen/Rules.mk b/xen/Rules.mk
index 0def40a00a09..7f28c3bc6c13 100644
--- a/xen/Rules.mk
+++ b/xen/Rules.mk
@@ -1,3 +1,7 @@
+#
+# See docs/misc/xen-makefiles/makefiles.rst on variables that can be used in
+# Makefile and are consumed by Rules.mk
+#
 
 -include $(BASEDIR)/include/config/auto.conf
 
-- 
Anthony PERARD