From e71e06389076009ab03e00153403c05a5dfaef25 Mon Sep 17 00:00:00 2001 From: Cyrill Gorcunov Date: Mon, 15 Feb 2016 15:26:51 +0300 Subject: [PATCH] build: Drop docs about old build engine No longer valid. Signed-off-by: Cyrill Gorcunov Signed-off-by: Pavel Emelyanov --- Documentation/Makefile.build.txt | 199 ------------------------------- 1 file changed, 199 deletions(-) delete mode 100644 Documentation/Makefile.build.txt diff --git a/Documentation/Makefile.build.txt b/Documentation/Makefile.build.txt deleted file mode 100644 index 60fca7e8d..000000000 --- a/Documentation/Makefile.build.txt +++ /dev/null @@ -1,199 +0,0 @@ -Makefile.build(1) -================= -:doctype: manpage -:man source: CRtools -:man version: 0.0.2 -:man manual: CRtools Manual - -NAME ----- -Makefile.build - a bunch of helpers for simplified Makefiles - - -SYNOPSIS --------- -'make' -f scripts/Makefile.build obj= - - -DESCRIPTION ------------ - -This is main build helpers script we use. Basically the idea is to minimize hand -work and describe Makefiles with somewhat simplified grammar. - -The script may work in two modes - - - *Default mode* - - - *Target mode* - -Following keywords are reserved and must not be used for anything else -- -'targets', 'deps', 'all-obj', 'incdeps', 'obj-y', 'obj-e', 'asm-y', 'asm-e', -'file', 'libs-e', '-obj-y', '-obj-e', '-asm-y', '-asm-e', -'-obj-y-cflags', '-obj-e-cflags', '-asm-y-asmflags', '-asm-e-asmflags', -'-libs-e'. Where '' is a prefix of the target, will be explained below. -That said, do not use such names for other purposes as stated here. - -OBJ= ----- - -Parameter *obj=* states for passing directory where simplified Makefile lays in. -Note the directory name must not end up with a slash, it is mandatory. - -In your simplifiled Makefile you still can refer to it as '$(obj)' variable. If -you need an ending slash, just type it explicitly as '$(obj)/'. - -DEFAULT MODE ------------- - -In *default* mode the script builds '$(obj)/built-in.o' relocatable file. To use -*default* mode do not ever mention '-' and 'targets' variables in a Makefile. -This done for simplicity, otherwise more complex logic will be needed in the -script which slows down built procedure. - -Thus in *default* mode the following variables may and should be referred - -obj-y:: - Source code C file. Typically refered as *obj-y += 'some-file.o'*. - This implies you have real 'some-file.c' in '$(obj)' directory. - -obj-x:: - Same as 'obj-y' but the output files have the suffix $(xsuffix). - This is used when building shared source file for both pie and crtools - The posfix '-x' came from word 'extra'. - -obj-e:: - Same as 'obj-y' but implies that source code file lays in directory - other than '$(obj)'. The postfix '-e' came from word 'external'. - -obj-ext-src-y:: - Same as 'obj-y' but implies that source code file lays in directory - other than '$(obj)', while compiled object file pushed into '$(obj)' directory. - Consider using this variable if you need to compile same source file with - different flags. - -asm-y:: - Source code S file. Same as 'obj-y' but for assembly language. - -asm-e:: - Same as 'obj-e' but for assembly language. - -lib-e:: - Some extarnal library the 'built-in.o' should link with. - -lib-so:: - Tells the make engine to build a shared library. - -incdeps:: - A flag which tells the script to generate dependency (that named '*.d' - files) for source code C files. To turn this functionality on just - type 'incdeps := y' somewhere in your Makefile. - -cleanup-y:: - List of files to be cleaned up when 'clean' target is called. - -For example a simplified Makefile may look like - - obj-y += file1.o - obj-y += file2.o - obj-y += file3.o - - ifneq ($(MAKECMDGOALS),clean) - incdeps := y - endif - -TARGET MODE ------------ - -In *target* mode the script builds all targets declared in a Makefile. Thus the -final built relocatable files will have a name as '.built-in.o', where '' -is a name of a target (I will continue using '' to refer the target name). -The following variables may be used for *target* mode. - -targets:: - This one defines a target name to built. - --obj-y:: - Same as 'obj-y' but per target. - --obj-y-cflags:: - Additional compiler flags for this target and object files - in '-obj-y'. - --obj-e:: - Same as 'obj-e' but per target. - --obj-e-cflags:: - Additional compiler flags for this target and object files - in '-obj-e'. - --asm-y:: - Same as 'asm-y' but per target. - --asm-y-asmflags:: - Additional compiler flags for this target and object files - in '-asm-y'. - --asm-e:: - Same as 'asm-e' but per target. - --asm-e-asmflags:: - Additional compiler flags for this target and object files - in '-asm-e'. - --libs-e:: - Same as 'libs-e' but per-target. - -There might be a situation where we have several targets and each of them need -some object file to be linked in. In this case we need to use variables from -*default* mode. Better to explain with example. - -Lets say we need to built two targets 'one' and 'two' (thus 'one.built-in.o' and -'two.built-in.o' relocatable files will be generated). For 'one' we need to use -files 'a.o', 'b.o', and for 'two' we need to use 'c.o' and 'd.o'. But both -targets need functionality from file 'e.o'. To force the script share the 'e.o' -we describe it as plain 'obj-y'. - - targets += one - targets += two - - one-obj-y += a.o - one-obj-y += b.o - - two-obj-y += c.o - two-obj-y += d.o - - obj-y += e.o - -The script will compile all files and link 'one.built-in.o' from files 'one-obj-y' -plus 'obj-y'. The same applies to the target 'two' ('obj-y' file will be linked -in as well). - -Thus if you refer variables from *default* mode but have 'targets' defined, the -script will treat such variables as a sign to share the productions at moment -when targets get linked. - -INVISIBLE RULES ---------------- - -If the script is used for build procedure then a couple of additional rules are -generated on the fly. Better to explain with example again. - -Lets say we have a Makefile with the following contents - - obj-y += file.o - -where $(obj) is a directory named 'dir'. So once we use the script we can -generate the following files. - -make dir/file.o:: - To compile the file. - -make dir/file.s:: - To generate assembly file from C file. - -make dir/file.d:: - To generate dependency file. - -make dir/file.i:: - To generate C file with preprocessor only.