[XEN PATCH v5 05/16] build: Introduce documentation for xen Makefiles

From: Anthony PERARD <anthony.perard@citrix.com>
To: <xen-devel@lists.xenproject.org>
Cc: Stefano Stabellini <sstabellini@kernel.org>,
	Julien Grall <julien@xen.org>, Wei Liu <wl@xen.org>,
	Andrew Cooper <andrew.cooper3@citrix.com>,
	Ian Jackson <ian.jackson@eu.citrix.com>,
	George Dunlap <george.dunlap@citrix.com>,
	Jan Beulich <jbeulich@suse.com>,
	Anthony PERARD <anthony.perard@citrix.com>
Subject: [XEN PATCH v5 05/16] build: Introduce documentation for xen Makefiles
Date: Tue, 21 Apr 2020 17:11:57 +0100	[thread overview]
Message-ID: <20200421161208.2429539-6-anthony.perard@citrix.com> (raw)
In-Reply-To: <20200421161208.2429539-1-anthony.perard@citrix.com>

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@citrix.com>
Acked-by: Jan Beulich <jbeulich@suse.com>
---

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 8e4b9e3a4a82..9d1e1ebf5e44 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


