From d7b7e218bfe92516f525568a6c1c9e1a9eb241fe Mon Sep 17 00:00:00 2001 From: Boris Kolpackov Date: Fri, 5 Feb 2010 18:01:45 +0200 Subject: Start tracking build with git --- documentation/BUGS | 18 + documentation/CLEANUP | 2 + documentation/CONFIGURATION | 64 +++ documentation/DOC | 16 + documentation/FACILITIES | 16 + documentation/FEATURES | 5 + documentation/IDEAS | 156 +++++++ documentation/INSTALLATION | 5 + documentation/ISSUES | 72 ++++ documentation/MAKE | 31 ++ documentation/NOTES | 34 ++ documentation/OPTIMIZATION | 21 + documentation/PROBLEMS | 70 ++++ documentation/RELEASE | 7 + documentation/SHOWCASE | 85 ++++ documentation/STYLE | 23 ++ documentation/TARGETS | 30 ++ documentation/TODO | 9 + documentation/default.css | 160 ++++++++ documentation/index.xhtml | 970 ++++++++++++++++++++++++++++++++++++++++++++ 20 files changed, 1794 insertions(+) create mode 100644 documentation/BUGS create mode 100644 documentation/CLEANUP create mode 100644 documentation/CONFIGURATION create mode 100644 documentation/DOC create mode 100644 documentation/FACILITIES create mode 100644 documentation/FEATURES create mode 100644 documentation/IDEAS create mode 100644 documentation/INSTALLATION create mode 100644 documentation/ISSUES create mode 100644 documentation/MAKE create mode 100644 documentation/NOTES create mode 100644 documentation/OPTIMIZATION create mode 100644 documentation/PROBLEMS create mode 100644 documentation/RELEASE create mode 100644 documentation/SHOWCASE create mode 100644 documentation/STYLE create mode 100644 documentation/TARGETS create mode 100644 documentation/TODO create mode 100644 documentation/default.css create mode 100644 documentation/index.xhtml (limited to 'documentation') diff --git a/documentation/BUGS b/documentation/BUGS new file mode 100644 index 0000000..ec499ae --- /dev/null +++ b/documentation/BUGS @@ -0,0 +1,18 @@ +@@ Messages during configuration should be about 80 chars long. + Right now they are much shorter which makes it look really ugly. + +@@ some keywords (l:) are being framed + +%% Relative paths result in rebuilds. + +@% When configuring with -j N some strange warnings appear. Temporary + fix. Depends on GNU make bug #12229. + +%% Use src_root path as default value for out_root. + +@@ Intel C++ does not generate phony rule for non-existent headers. + +@@ It seems to me that in generated header prefix logic the dependency + patched by sed script and one produced by a subsequent run of the + compiler are different which triggers makefile reload. I wonder + why? \ No newline at end of file diff --git a/documentation/CLEANUP b/documentation/CLEANUP new file mode 100644 index 0000000..fc3e263 --- /dev/null +++ b/documentation/CLEANUP @@ -0,0 +1,2 @@ +%@ add project_name, add corresponding message to all configuration scripts + \ No newline at end of file diff --git a/documentation/CONFIGURATION b/documentation/CONFIGURATION new file mode 100644 index 0000000..feed13c --- /dev/null +++ b/documentation/CONFIGURATION @@ -0,0 +1,64 @@ + +@@ It would be nice if configuration happens only when it is + required. For example if I need to build something that + uses CORBA then only in this case happens configuration of + CORBA facilities. + + +@@ 'configure' should depend on 'clean' + + +@@ What if I change something in config file (let's say archive to shared) + and then say make - things will break. + + +@@ It would be nice if I could keep build/ outside of the project. This + is going to be very useful when multiple projects share the same + build system. + +@@ it would be nice to have a project_base which will be + $(root)/example/project. However, in normal most cases project will be + the same as root, right? Look at CCF. Some comments: + + Saying -I$(root) would be exactly what I need if its value would be + .../example/project. This, according to the concept of clusters, could + be achived if I make .../example/project a cluster (which is quite + natural thing to do). It would also be a good example of a cluster. + + +@@ Right now I have one global implicit rule for the project. In most + cases this is probably enough. But what if I want to use different + rules for different sub-projects (config clusters). For example two + parts of the same project could use different compilers or ORB or... + Probably the generic approach would be to provide sub-dir specific + rules. + +@@ concept of configuration clusters (no more src_root). + + +@@ Can I get rid of src_root and out_root (i.e. can they be /)? + + +@@ It would be nice if I could configure the same sub-system + (like CORBA) for dirrefent parts of the project differenty. + + +@@ Do I really need those configuration clusters? Is the structure + of CCF right? Or am I just trying to hide problems of wrong + structuring? Isn't it overcomplication? Even if not shouldn't + I postpone this until I gain more experience? + +--------------------- + +@@ Each project includes (in its root directory) copy of the build system. + +@@ The build system is configuration cluster. + +@@ Configuration cluster sets src/out_root. + +@@ Configuration cluster can inherit configuration from its parent. + +@@ Configuration cluster can override inherited values. + +@@ sub-projects in configuration cluster should not refer to anything + outside of this cluster. diff --git a/documentation/DOC b/documentation/DOC new file mode 100644 index 0000000..0ace1cf --- /dev/null +++ b/documentation/DOC @@ -0,0 +1,16 @@ +@@ Update to describe new option importing mechanism. Maybe even + include some general model of project building? + + +@@ Create style section and put STYLE file there. + + +@@ Describe canonical targets (from targets). + +@@ Currently I have no description of targtes (e.g., nobody knows about + disfigure). + +@@ Update documentation with the new output from examples. + +@@ Add News section to the index.xhtml + diff --git a/documentation/FACILITIES b/documentation/FACILITIES new file mode 100644 index 0000000..26492f4 --- /dev/null +++ b/documentation/FACILITIES @@ -0,0 +1,16 @@ + +@@ can I have different strategies for src/out? Would I be able + to come up with generic implicit rules that work for all cases? + +@@ optional facilities could go into pre-load. + +@@ from building point of view distinction on source and generated + files is not essential. + +@@ Common places for generated files (from multi-arch): + + - home (out == src) + + - parallel structure outside (out is set based on curdir?) + + - subdirs in source (potentially many) (out := src + something) diff --git a/documentation/FEATURES b/documentation/FEATURES new file mode 100644 index 0000000..1068025 --- /dev/null +++ b/documentation/FEATURES @@ -0,0 +1,5 @@ +@@ Allow multiple files in $(call load ). + +@! Extract compiler-specific include paths to create do-nothing rules + for headers. + diff --git a/documentation/IDEAS b/documentation/IDEAS new file mode 100644 index 0000000..649f375 --- /dev/null +++ b/documentation/IDEAS @@ -0,0 +1,156 @@ +@@ Need to create some show-case with some intermidiate compiler like + idl/lex/yacc. M4 comes to mind. + +%% Stages of building + + 1. configure/configuration + + 2. build/build + + 3a. test/testing + + 3b. install/installation + +@@ Maybe I should have a special function for inclusion from special + directories (like Build). + +@@ it would nice to have suffixes configurable + +@@ There could be a set of files to configure building environment (like + suffixes of files, names of utilities, etc). If I decide to ship + environment as standalon product I will have to somehow separate + those files (like putting in different directories). + +@@ It would make sense to split build system on subsystems like 'base' + 'c' 'cxx', 'corba/cxx' etc. + +%% Maybe I should pre-load some commonly used patterns. + +@@ Maybe makefiles that are not ment to be used interactively should + inherit their interactivity status from their includer. + +@@ Allow changing of options based on the category (plus all). This + can be done like this: + + %.o : %.cpp : cxx_options = $(cxx_cpp_flags) $(cxx_debug_flags) $(cxx_diagnostic_flags) + %.o : %.cpp : cxx_cpp_options := + %.o : %.cpp : cxx_debug_options := -g + %.o : %.cpp : cxx_diagnostic_options := -Wall + + This will allow the user to change only what he want without much + hassle. + +@! Can I make a dependecy of lib.l on lib.so? Should I? Or should I list + .so/.a in the pattern rule so it gets deleted? + +@@ It would be nice to have a custom message for phony targets that merely + depend on normal targets. For example if I could get a list of targets + that were updated I would have been able to print such a message. This + would probably require modifications to make. + + For default target of a dispatch makefile (better name?) I use directory + name which makes perfect sense. BTW, maybe I should call them directory + makefiles, or meta-makefiles, or stubs? + +@@ Since the build of multiple goals in the same target can be tricky I + may want to detect this and give a warning/error (this could be + configurable). + +@@ 'cxx' should depend on 'c'. 'cxx' can reuse ar facility from 'c'. + +@@ Make function extension framework. The idea is to use $(shell) to call + arbitrary executable/shell-script. The only problem is that I need a + way to build something before continuing to read makefile. Something + like .REQUIRE: target? When make sees this it stops reading makefile + and tries to build the target. If build succeeded make resumes to + read the makefile. If build failed make stops with an error. + + The other, more advanced, idea is to use dynamic loading of functions. + This way it will be alot faster. + + If included makefiles could be rebuilt on the spot (i.e. without + first reading the rest) then it would be a way. + +@@ Can I use linker script instead of my .l library descriptor (or together + with?). + +@@ There is a support for 'version script' in ld. I wonder what is that. + +@@ study linux kernel build system + +@! Maybe clean/disfigure target should include deletion of a directory + if (a) the build could potentially create it and (b) it is empty. + This way things will be cleaner and, after saying make clean in the + build directory, one gets just configuration. + +@@ I can ask user if he wants to override default .a/.so search paths + (for example to match the compiler). + + +@@ Multidir example probably belongs to c subsystem. + +@@ If I have build-as-you-need-them makefile inclusion scheme then if I + include makefiles in a proper order I can get rid of those + 'configuring blah-blah' messages. + +@@ I can be cool and make 'ls' in cxx to find present c++ compilers. This + way I will be able to distribute compiler-specific files separately. + +@@ It would be nice to have include function that includes a file + relatevely to the current's Makefile directory. + +@@ Maybe factor out cpp as a common facility in 'c'? Right now I duplicate + some support code in cxx/gnu and cxx/intel. + +@@ All this '.l' abstraction support belongs to 'c'. + +@@ In import/export stubs check for version compatibilities. Oohooo! + +@@ What if I save src_root somewhere in out_root? + +%% Need to try to use build with distcc. Works well. + +@@ I may want to store src_root someweher in out_root so that I don't + need to ask for it (will not work in all cases). + +@! It is probably a good idea to make each file responsible for + making sure its guts are included right number of times. + +@! With introduction of .NOT_DEFAULT I can factor out aliasing into + (per-project) bootstrap.make. Did in some projects - works well. + Need to do them in example. + +@@ foreach is a way to define local variable. + +@! use $(< file) instead of cat + +@! use last dir + relative path in messages + +@! what about using few-letters vars instead of cxx_obj (o) cxx_od (d)? + +@! How about uniform importing facility without any subsystems? For example + CORBA is a translator and a library at the same time - how to handle it? + + - can use whatever names in imported files. + + - will need importing from project build dir and from bld_root + +@! Need to think about hacker mode - passing config info via command line + with standard names like CXX CPPFLAGS LDFLAGS, etc. + +@! teach import stubs to not try include anything when cleaning/disfiguring? + +@@ local target that will rebuild only local object files? Or maybe set an + order of rebuilding local files first? + +@! Now since I have .DEFAULT_TARGET I can do save/restore thing for export + import. So there won't be a need to secure default target. Way too cool! + +%% Usually src_root and out_root are the same. I should suggest one + by default when asking user for it. + +@@ There are two situations where I can guess src_root from out_root: + first is when out_root == src_root (I can check for build/bootstrap.make + though bootstrap.make can be named differently). The other case is when + out_root already contains build project (I will need to kind of marker + that contains value of src_root; maybe build/configuratio-dynamic.make). diff --git a/documentation/INSTALLATION b/documentation/INSTALLATION new file mode 100644 index 0000000..24eebcf --- /dev/null +++ b/documentation/INSTALLATION @@ -0,0 +1,5 @@ +%% used install -d to create directories during installation. + +%@ splitting, completion, and cleanup + +%% terse messages for installation commands. diff --git a/documentation/ISSUES b/documentation/ISSUES new file mode 100644 index 0000000..e7b4263 --- /dev/null +++ b/documentation/ISSUES @@ -0,0 +1,72 @@ +@@ use shell && instead of multi-line rules since they don't consider + atomic (e.g. if something failed other files won't be deleted). Or + maybe not, think about it (and read the doc). + +@@ Some implicit rule should actually be two rules: one that looks + for the source under srd_root tree and the other under out_root. + Theoretically, any source could be just an intermidiate file generated + from something else (discovered while playing with idl). + +@@ Compensating rules: 'clean all' example. + +@@ Issues from "Multi-Architecture Builds Using GNU make": + + - big (bloated) makefiles + + - cannot say "make foo.o" + +@@ How can I integrate building of realpath utility in configuration + process? + +@@ Executing make from non-source directory is painful. Can I make it + easier? + +%% When shared library is linked with absolute path the loader is looking + for the library with the same path. See also -soname= and -rpath ls + options. + +@@ With multidir makefiles I loos the ability to say make where I am. + This is especially nasty when I edit a file and then say make. This + happens for example in CCF. The easy workaround is to say something + "make -C dir/to/test/driver". Once this is done life get very nice. + Actually I think this could be the best approach. + +@@ Variable inheritance doesn't play well with 'make foo.o'. + +@@ Configurations include absolute paths to imported libraries which + makes it hard to reuse them. In this light configurations on installed + libraries should not include any absolute paths. + +@@ Better name for project_name? build_name? + +@@ Repetition of paths in $(call message) is quite ugly. Anything I can do? + +@@ -MP conflicts with --no-implicit-phony. The new approach uses a special + terminal pattern rule to handle this. However headers without suffix + cannot be handled by this method. + +@! Delete-on-error does not cover .o.d files. I could specify it as a target + together with .o but then it will try to rebuild it. + +@! When you hide things from make (like .o.d or .l/.so) all sorts of bad things + happen. + +@@ What is a better term for development (not installed?) build? + +@@ /usr/bin/g++ is a link but extracted include paths have precise version in + them (e.g. 3.3.4). But then dependencies will trigger update, right? + +@! I am using some of the features of GNU find which are not available in SUS. + +@@ Since .l.cpp-options pattern does not have any prereqs then the file can + always be created (example: I misspelled file name). + +@@ Use abspath to prevent call-inclusion from -I dirs. + +@@ lib.cpp-options should be lib.cpp_options? + +@@ Use $@ in $$(dir $(out)/%). + +@! Need to make content of .l compiler-independant (rpath stuff). + +@@ export is now position-sensitive. diff --git a/documentation/MAKE b/documentation/MAKE new file mode 100644 index 0000000..50e073b --- /dev/null +++ b/documentation/MAKE @@ -0,0 +1,31 @@ + +@@ I was thinking about the way make handles inclusion of missing + makefile. The following strategy seems like a better choice: + if makefile is missing try to rebuild & read it immediately, + without parsing the rest of makefile and without reexecuting + make later. This approach has at least two benefits: + + + more efficient (no make re-execution) (this is not very + important in most cases, thoug) + + + more deterministic: if some of the code after (missing) + included makefile depends on some code from it (for + example a function) then things can break (example: + configuration of ORB). + + - sequential (cannot build makefile in parallel) + + +@! target/pattern-specific vpath + +@@ no `target is up to date' message when commnds are executed + but target is not changed. + +@@ %.o %.d and include + +%% implicit double expansion: now supports target/pattern variables + and $- + +%% create `examples' directory where I can put md5 and maybe hello. + +@! shortest stem diff --git a/documentation/NOTES b/documentation/NOTES new file mode 100644 index 0000000..7bed2c8 --- /dev/null +++ b/documentation/NOTES @@ -0,0 +1,34 @@ +@@ ?= is deferred + +@@ automatically-generated dependecies should include absolute paths + just like gcc does. Note that it only happens when you pass gcc + absolute paths in -I so I should watch out! + +@@ order-only dependencies allow for elegant creation of a directory + before build. + +@@ need to try generation of headers in out_dir. + +@@ maybe think about shared library versioning. This could be done + transparently at installation time. + +%% I should use some form of include function for -include for + consistency. + +@@ linker accepts -O options and can opimize. + +@@ use suffix (.make, .cxx) to specify file type - not as a mere + separator. Can I use '-' as separator? Should I use '_' as separator? + +@@ read lisp ASDF manual. + +@@ Use $(eval foo:=bar) in rule's command to set variable only if (and after) + the rule is in use. + +%% Files in import directory are called configuration. They are not quite + that. Maybe a better name would be stub? + +@@ For some (all? SUS?) platforms inclusion of .so in .l is redundant + because .so is already linked against them. + +@@ Need to continue cleaning if some files do not exist (rm -f ?). diff --git a/documentation/OPTIMIZATION b/documentation/OPTIMIZATION new file mode 100644 index 0000000..dfdb06d --- /dev/null +++ b/documentation/OPTIMIZATION @@ -0,0 +1,21 @@ +%% I should keep a separate list of files that are included-once which + should also cache the realpaths. + +@@ It would make sense to use $(call include-once,out_dir) in cxx/cxx-o.make + etc. + +@@ Need to check what is being framed. + +@@ I wonder how much it costs to have the second expansion in implicit rule? + +@@ Make executes each line in a separate shell. I wonder if using && is + more efficient? + +%% check make's default hash table size. + +@@ would using `makefile: ' tecknique to prevent make from trying to + match against pattern-rules help? + +@@ Look for redundant $(eval ) calls (like I had in include-*). + +@@ use head -n 1 instead of sed -e 1q diff --git a/documentation/PROBLEMS b/documentation/PROBLEMS new file mode 100644 index 0000000..a07fbda --- /dev/null +++ b/documentation/PROBLEMS @@ -0,0 +1,70 @@ +STRUCTURE + + +VARIABLES + +%% It would be nice to be able to include makefile in a way that + variables are restored. + +@% I definitely need some naming convention for "global" variables. + Since I include potentially unknown makefiles (like library + dependecies) I cannot predict what they do. This is another + argument for variable framing. + + Some ideas: + + - Variables that start and end with '%' are considered global + and system. Subsystems may define such vars if there is + a real need. (Currently defined names should be documented + here. Each subsystem should document names that it defines.) + Subsystem should prefix each such var with its name (e.g. cxx_). + + - Variables that contain '-' are considered 'functions' and not + framed. Generally subsystems should define those. The names + should be chosen carefully in order not to cause name clashes. + (Each subsystem should document names that it defines). + Subsystem should prefix each such function with its name + (e.g. cxx-). + + - Variables that appear in %frame_exclude% are not framed. General + rule is to add only special one-word functions (usually defined + by base subsystem) that are used often and thus having one-word + terse name is very important; for example 'include' or 'import' + + +%% After the inclusion of dependency makefiles I cannot use src_base + becasue it was reset by the included file. So I am forced to use + src_root now which will hurt especially sore when I include from + sub-directories. + + + +DEPENDENCIES : STRUCTURE + +@@ It would be nice to be able to chose dependency type project-wise + and on a by-makefile basis. This could be tricky, however. + +@@ Missing headers assumed generated with some inflexible logic (cur dir). + This can also vary among compilers (which is not something I would worry + too much as long as g++ works). Can I make it more reliable? Maybe capture + this (or essential) dependecies in a Makefile? + +@@ Can I specify dependencies in CORBA projects manually. Do I want to do + that? + +@@ Don't include dependecies when cleaning (configuring?). + + + +MISC + +@@ If I have generated idl files in src directory then build in some other + directory will fail or will use wrong headers. + +%% .NOT_DEFAULT: target in make? + +%@ configuration targets should not be parallel. try make -j 4 Maybe I can + detect that those files do not exist and disable parallelism for this + run. See .MUTEX bug (#3656). + +@@ relative paths and pattern matching does not work very well together diff --git a/documentation/RELEASE b/documentation/RELEASE new file mode 100644 index 0000000..fc216ed --- /dev/null +++ b/documentation/RELEASE @@ -0,0 +1,7 @@ +@@ add header to every file. + +@@ make sure all files conform to the STYLE. + +@@ remove empty directoris (left after disfigure) in examples/ + +@@ update copyright diff --git a/documentation/SHOWCASE b/documentation/SHOWCASE new file mode 100644 index 0000000..1a032f2 --- /dev/null +++ b/documentation/SHOWCASE @@ -0,0 +1,85 @@ +#@@ if a showcase complicated the initial example then it should +# be implemented as a separate example. + +%% build with nested directories from single Makefile + +%% generation of headers/sources from some other source with + automatically generated dependencies (IDL showcase) + +%% two executables in the same dir (though generally not recomended) + +%% selection of PIC by a target (target-specific variables + inheritance) (read the bug report about this feature). + +%% directory Makefiles (need a nice name for them) + +%@ configuration target + + - implemented disfigure only (for now). + + - not complete + + - need to implement configuration of installed dependencies. + +%@ installation target + + - prototype design + + - needs completion + +%@ test target + + - only in libhello + +%% generation of actual dependencies for C++/C + +@@ use of C & C++ compiler from the same Makefile + +@@ another C++/C compiler (Sun CC?) + +@@ cleaning after messy compilers (Sun CC?) + +@@ c subsystem + +@@ Quite mode. all answers defaulted. Error if something is wrong. + +@@ I need some way of programmatically supplying configuration + information (for example for debian package creation). Via + command line variables seems like a reasonable approach. Also + saving configuration seems like a good idea too (i.e. keeping + configuration around) but then I need to make sure there are + no absolute paths. + +%@ Installation process for the build system itself. + + - now installs only build system itself. + +%% What am I going to do with corba? Maybe package it as a separate + incomplete subsystem? + +@% All those "file not found" messages by make are quite nasty. I should + either fix make (preferable) or use -include. + + - using -include for now + +%% variable unsetting: do I still need it? Yes I do. + +@@ installation of examples + +@@ need to clean source code out of @@ + +@! target-specific vpath + +@! Can .INTERMIDIATE help me with .d problem? No! Also it seems + saying something like %.o %.d: %.cxx won't work either? Need + to check this. + +@! Need to run ranlib on certain platforms. Need to detect if I need to. + +@! .cpp-options: if add/remove .cpp-options prereqs the target file does not + get regenerated. Probably need to save list of prereqs and compare with it. + +@! shared library versioning + +@! Need to think on a general idea of state saving (like I do with + .cpp-options). Is there a cleaner way of doing this? diff --git a/documentation/STYLE b/documentation/STYLE new file mode 100644 index 0000000..32799f6 --- /dev/null +++ b/documentation/STYLE @@ -0,0 +1,23 @@ +@@ write "t: p" instead of "t : p" or "t :p" + +@@ write $(call f,a) instead of $(call f, a) or $(call f , a) + +@@ Use '-' to separate words in function names (e.g. foo-bar); + use 'define' to define functions. + +@@ Use '_' to separate words in variable names (e.g. foo_bar); + use := to assign value to a variable. Use '=' if you know + what you are doing. + +@@ Be careful with += in target-specific variables. + +@@ Action explicitly requested by the user (which should correspond + to verbs, e.g. install, clean, configure) should perform without + regards to up-to-dateness. + +@@ Use verbs for .PHONY targets. There is one notable exception:... + +@! maybe declare `__' variable prefix reserved? + +@@ Use directory name as a default phony target in directory makefiles. + (explain why). \ No newline at end of file diff --git a/documentation/TARGETS b/documentation/TARGETS new file mode 100644 index 0000000..ff5476f --- /dev/null +++ b/documentation/TARGETS @@ -0,0 +1,30 @@ + +# Configuration +# + +configuration +configure : disfigure +disfigure : clean + +# build +# + +build : configuration +clean + + +# test +# +test : build + + +# install +# +install : build +uninstall + + +# help +# + +help diff --git a/documentation/TODO b/documentation/TODO new file mode 100644 index 0000000..4aec2c6 --- /dev/null +++ b/documentation/TODO @@ -0,0 +1,9 @@ +!! Need to change include path in hello example. + +!! And change to #include <> + +!! Need to get rid of those header patterns or implement shortest stem. + +!! finish cxx-d.make + +@@ Add include-dep to examples. diff --git a/documentation/default.css b/documentation/default.css new file mode 100644 index 0000000..7242a94 --- /dev/null +++ b/documentation/default.css @@ -0,0 +1,160 @@ +body { + font-family : sans-serif; + font-weight : normal; + + color : black; + background : white; + + max-width : 42em; + padding : 2em 2em 2em 3em; + margin : 0 auto; +} + +h1, h2, h3, h4, h5, h6 { + font-family : sans-serif; + font-weight : 500; +} + +h1 { font-size : 170%; } +h2 { font-size : 145%; } +h3 { font-size : 125%; } +h4 { font-size : 110%; } +h5 { font-size : 106%; } +h6 { font-size : 100%; } + + +p.indent { + margin-left : 1.5em; +} + + +/* table of content */ +ul.toc li { + padding : .4em 0em 0em 0em; +} + + + +/* list of links */ +ul.menu { + list-style-type : none; +} + +ul.menu li { + padding-top : 0.3em; + padding-bottom : 0.3em; +} + + + +/* @@ I should probably use child selector here */ +/* list with multiline list-elements */ +ul.multiline li { + padding-top : 0.4em; + padding-bottom : 0.4em; +} + +ol.multiline li { + padding-top : 0.4em; + padding-bottom : 0.4em; +} + +dl.multiline dd { + padding-top : 0.4em; + padding-bottom : 0.4em; +} + +/* code */ + +code { + font-size : 114%; + font-family : monospace; +} + + +/* C++ code snippet */ +pre.cxx { + + margin-top : 0em; + margin-bottom : 2em; + + margin-left : 1em; +} + + + +/* make code snippet */ +pre.make { + + margin-top : 0em; + margin-bottom : 2em; + + margin-left : 1em; +} + + + +/* terminal output */ +pre.term { + + margin-top : 0em; + margin-bottom : 2em; + + margin-left : 1em; +} + + +/* Images */ +div.center { + text-align: center; +} + +/* Navigation. */ +#navigation { + margin-top: 1em; + border-bottom: 1px dashed #000000; +} + +#content { + margin-top: 2.5em; +} + + +/* Document info. */ +#docinfo { + margin-top: 4em; + border-top: 1px dashed #000000; + font-size: 70%; +} + +/* distribution terms */ +div.terms { + font-size : 114%; + font-family : monospace; +} + + + +/* Footnote */ + +#footnote { + margin-top: 2em; +} + +#footnote hr { + margin-left: 0; + margin-bottom: 1.5em; + width: 8em; + border-top: 1px solid #000000; + border-right: none; + border-bottom: none; + border-left: none; + +} + +#footnote p { + font-size: .91em; + text-indent: -0.8em; + padding-left: 0.8em; +} + diff --git a/documentation/index.xhtml b/documentation/index.xhtml new file mode 100644 index 0000000..afc655c --- /dev/null +++ b/documentation/index.xhtml @@ -0,0 +1,970 @@ + + + + + + + + + + + build/documentation + + + + + + + + + + + +
+ + + +

Introduction

+ +

I hear you saying: "Yeah, yeah, another marvelous make +replacement with built-in support for various compilers, automatic +dependency scanning, parallel and distributed builds, and XML instead of +makefiles!" On the contrary, build is a software build system +that is implemented on top of GNU make. It defines extensible framework for +translators, delegates most of its tasks to existing tools, and uses GNU +make syntax for makefiles. Build was designed with the following +tasks in mind:

+ + + +

As distribution of software in source code is being replaced by +precompiled package distributions, greater emphasis was placed on +development-time conveniences. Some of the features of build +include:

+ + + +

To understand leaf makefiles in this manual you will need basic +knowledge of how make works. However, inside, build +uses some of the more advanced features of GNU make including

+ + + +

If you find usage of some of the make techniques obscure +in this text you can always consult with the +GNU make +manual.

+ + +

Fundamentals

+ +

Build defines a framework in terms of which user makefiles +are written. Below is the list of fundamental concepts.

+ +
+
Project
+
is a separately distributable collection of source files. A more +intuitive way of defining a project would be to say it's what you +normally assign a version number to (e.g., libhello-0.0.1) +and package as a tar ball (e.g., libhello-0.0.1.tar.gz). +A reasonably complex project usually has a hierarchy of sub-directories +under its root directory.
+ +
Component
+
is part of a project for which you would normally write a +makefile. For example our libhello could consist of +two components: the library itself and a test driver.
+ +
Source root
+
is a root directory of a project. For example, if we unpack our +libhello-0.0.1.tar.gz to /tmp and end up with +a directory /tmp/libhello-0.0.1 then that would be this +project's source root.
+ +
Source base
+
is a directory of a component in a project. Continuing our example, +if our libhello project had a subdirectory test +then the source base of the test component would be +/tmp/libhello-0.0.1/test. By definition, any source base +is a sub-directory of a source root for any particular project.
+ +
Out root
+
is a root directory of a project's build (or output) hierarchy. This +directory signifies where generated files for the project will be placed. +For example, if we decide to build libhello in +/tmp/libhello-i686-pc-linux-gnu then that would be one of the +possible out roots.
+ +
Out base
+
is a build (or output) directory of a component in a project. +If we continue our example, the out base for the test +component would be /tmp/libhello-i686-pc-linux-gnu/test.
+
+ +

The build runtime defines four make variables that +correspond to the last four definitions:

+ +
+src_root
+src_base
+out_root
+out_base
+
+ +

Below is an example of how you could use some of them.

+ +
+driver := $(out_base)/driver
+
+$(driver): $(out_base)/driver.o $(out_root)/libhello/libhello.so
+
+ +

Additionally, the build framework defines three more +variables:

+ +
+bld_root
+scf_root := $(src_root)/build
+dcf_root := $(out_root)/build
+
+ +

bld_root is a root directory of the build runtime. +Normally you would use it to include one of the build's files.

+ +

scf_root stands for static configuration root and +points to a directory where project's static configuration is kept. +dcf_root stands for dynamic configuration root and +points to a directory where project's dynamic configuration is kept. +We will talk more about those two variables later.

+ +

Also note that having src_root the same as +out_root is perfectly valid and indicates that we +are building in a source directory.

+ +

First Example

+ +

Now we are ready to examine our first simple example. We +will skip one-file C-based "hello world", however, because it +is not very practical and there is not much room for improvement. +Rather we will start from a libhello library, a test +driver for it and a hello program that uses the library. +To make our example even more realistic the libhello +library and the hello program are two separate projects. +And, did I mention, they are written in C++. See +examples/cxx/hello.

+ +

Invocation

+ +

Let's first get some user experience without looking into makefiles. +Suppose we unpacked build source into /tmp/build-0.1.12. +First let's try to build libhello:

+ +
+$ cd /tmp/build-0.1.12/examples/cxx/hello/libhello
+$ make
+
+
+configuring 'libhello'
+
+
+
+Please select the C++ compiler you would like to use:
+
+(1) GNU C++ (g++)
+(2) Intel C++ (icc)
+
+[1]: 1
+
+Would you like the C++ compiler to optimize generated code?
+
+[y]: y
+
+Would you like the C++ compiler to generate debug information?
+
+[y]: y
+
+
+configuring 'libhello'
+
+
+
+Please select the default library type:
+
+(1) archive
+(2) shared object
+
+[2]: 2
+
+
+configuring 'libhello'
+
+
+
+Please enter the g++ binary you would like to use, for example 'g++-3.4',
+'/usr/local/bin/g++' or 'distcc g++'. You can use path auto-completion.
+
+[g++]: g++
+
+Please select the optimization level you would like to use:
+
+(1) -O1 [Tries to reduce code size and execution time, without
+         performing any optimizations that take a great deal of
+         compilation time.]
+(2) -O2 [Performs nearly all supported optimizations that do not
+         involve a space-speed tradeoff.]
+(3) -O3 [Optimize even more.]
+(4) -Os [Optimize for size.]
+
+[2]: 2
+c++ /tmp/build-0.1.12/examples/cxx/hello/libhello/libhello/hello.cxx
+ld  /tmp/build-0.1.12/examples/cxx/hello/libhello/libhello/hello.l
+c++ /tmp/build-0.1.12/examples/cxx/hello/libhello/test/driver.cxx
+ld  /tmp/build-0.1.12/examples/cxx/hello/libhello/test/driver
+
+ +

Here we were presented with a bunch of configuration questions. +If you have g++ in your default path you can just keep +hitting enter to select defaults. If you would like to see real commands +that are being executed (useful when something goes wrong) you can +say make verbose=1.

+ +

From the messages above we can deduce that we have built the +libhello library (hello.l) and the test driver +for it (test/driver). So far so good. Now let's try to build +the hello program:

+ +
+$ cd /tmp/build-0.1.12/examples/cxx/hello/hello
+$ make
+
+ +

Again you will be asked a bunch of questions you have already seen, +except these two:

+ +
+Configuring external dependency on 'libhello' for 'hello driver'.
+
+
+Would you like to configure dependency on the installed
+version as opposed to the development build?
+
+[y]: n
+
+Please enter the out_root for 'libhello'.
+
+[]: ../libhello
+
+Please enter the src_root for 'libhello'.
+
+[]: ../libhello
+
+ +

The hello program depends on libhello. Since +they are distributed as separate projects hello needs to +know where to look for libhello. That's why user intervention +is required. The first question is whether we would like to use an installed +version of libhello as opposed to the not installed build. +Since we haven't installed libhello the answer is +no. The next two questions determine where the +out_root of the build and the src_root of the source +code are. Since we built libhello in its source directory both +become /tmp/build-0.1.12/examples/cxx/hello/libhello or +../libhello if we are in +/tmp/build-0.1.12/examples/cxx/hello/hello. After answering +those questions you will see something like this:

+ +
+c++ /tmp/build-0.1.12/examples/cxx/hello/hello/hello.cxx
+ld  /tmp/build-0.1.12/examples/cxx/hello/hello/hello
+
+ +

And that's it.

+ +

One of the nice features of build is that you can have several +builds in separate directories all from the same source base. Suppose we +would like to build an -O3-optimized statically-linked version +of hello without debug information:

+ +
+$ mkdir /tmp/hello-i686-pc-linux-gnu
+$ cd /tmp/hello-i686-pc-linux-gnu
+$ make -f ../build-0.1.12/examples/cxx/hello/hello/makefile
+
+
+configuring 'hello driver'
+
+
+
+Please select the C++ compiler you would like to use:
+
+(1) GNU C++ (g++)
+(2) Intel C++ (icc)
+
+[1]: 1
+
+Would you like the C++ compiler to optimize generated code?
+
+[y]: y
+
+Would you like the C++ compiler to generate debug information?
+
+[y]: n
+
+
+Configuring external dependency on 'libhello' for 'hello driver'.
+
+
+
+Would you like to configure dependency on the installed
+version as opposed to the development build?
+
+[y]: n
+
+Please enter the out_root for 'libhello'.
+
+[]: /tmp/libhello-i686-pc-linux-gnu
+
+Please enter the src_root for 'libhello'.
+
+[]: ../build-0.1.12/examples/cxx/hello/libhello
+
+
+configuring 'hello driver'
+
+
+
+Please enter the g++ binary you would like to use, for example 'g++-3.4',
+'/usr/local/bin/g++' or 'distcc g++'. You can use path auto-completion.
+
+[g++]: g++
+
+Please select the optimization level you would like to use:
+
+(1) -O1 [Tries to reduce code size and execution time, without
+         performing any optimizations that take a great deal of
+         compilation time.]
+(2) -O2 [Performs nearly all supported optimizations that do not
+         involve a space-speed tradeoff.]
+(3) -O3 [Optimize even more.]
+(4) -Os [Optimize for size.]
+
+[2]: 3
+
+
+configuring 'libhello'
+
+
+
+Please select the C++ compiler you would like to use:
+
+(1) GNU C++ (g++)
+(2) Intel C++ (icc)
+
+[1]: 1
+
+Would you like the C++ compiler to optimize generated code?
+
+[y]: y
+
+Would you like the C++ compiler to generate debug information?
+
+[y]: n
+
+
+configuring 'libhello'
+
+
+
+Please select the default library type:
+
+(1) archive
+(2) shared object
+
+[2]: 1
+
+
+configuring 'libhello'
+
+
+
+Please enter the g++ binary you would like to use, for example 'g++-3.4',
+'/usr/local/bin/g++' or 'distcc g++'. You can use path auto-completion.
+
+[g++]: g++
+
+Please select the optimization level you would like to use:
+
+(1) -O1 [Tries to reduce code size and execution time, without
+         performing any optimizations that take a great deal of
+         compilation time.]
+(2) -O2 [Performs nearly all supported optimizations that do not
+         involve a space-speed tradeoff.]
+(3) -O3 [Optimize even more.]
+(4) -Os [Optimize for size.]
+
+[2]: 3
+c++ /tmp/build-0.1.12/examples/cxx/hello/hello/hello.cxx
+c++ /tmp/build-0.1.12/examples/cxx/hello/libhello/libhello/hello.cxx
+ar  /tmp/libhello-i686-pc-linux-gnu/libhello/hello.l
+ld  /tmp/hello-i686-pc-linux-gnu/hello
+
+ +

Makefiles

+ +

Now let's take a look at the makefiles. We will start from the +makefile for libhello (hello/libhello/libhello/makefile). +Note, that I removed support for install target for now.

+ +
+include $(dir $(lastword $(MAKEFILE_LIST)))../build/bootstrap.make
+
+cxx_tun   := hello.cxx
+cxx_obj   := $(addprefix $(out_base)/,$(cxx_tun:.cxx=.o))
+cxx_od    := $(cxx_obj:.o=.o.d)
+
+hello.l             := $(out_base)/hello.l
+hello.l.cpp-options := $(out_base)/hello.l.cpp-options
+
+clean     := $(out_base)/.clean
+
+
+# Build.
+#
+$(hello.l): $(cxx_obj)
+
+$(cxx_obj): $(hello.l.cpp-options)
+
+$(hello.l.cpp-options): value := -I$(src_root)
+
+$(call -include,$(cxx_od))
+
+
+# Clean.
+#
+.PHONY: $(clean)
+
+$(clean): $(hello.l).clean \
+          $(addsuffix .clean,$(cxx_obj)) \
+          $(hello.l.cpp-options).clean
+
+
+# Aliases.
+#
+ifdef %interactive%
+
+.PHONY: clean
+
+clean: $(clean)
+
+endif
+
+
+# How to.
+#
+$(call include,$(bld_root)/cxx/o-l.make)
+$(call include,$(bld_root)/cxx/cxx-o.make)
+
+ +

Let's examine this file line-by-line:

+ +
+include $(dir $(lastword $(MAKEFILE_LIST)))../build/bootstrap.make
+
+ +

Every leaf makefile (i.e., one written to build a component) starts from a +line that looks like this. Its sole purpose is to bootstrap the build system. +In our case $(dir $(lastword ...)) will expand to something +like

+ +
+include .../hello/libhello/libhello/../build/bootstrap.make
+
+ +

Let's take a look at libhello/build/bootstrap.make:

+ +
+project_name := libhello
+include $(dir $(lastword $(MAKEFILE_LIST))).../build/bootstrap.make
+
+ +

The first line just initializes project_name with the name +of the project. The second line includes the real bootstrap.make. +See Bootstrapping section for more information on +various ways of bootstrapping the build runtime.

+ +

What does bootstrap.make do? Besides other things (which are +explained as we encounter them) it sets all those *_root and +*_base variables.

+ +

Let's go back to our libhello/makefile. The first line +should be clear by now so let's move on:

+ +
+cxx_tun   := hello.cxx
+cxx_obj   := $(addprefix $(out_base)/,$(cxx_tun:.cxx=.o))
+cxx_od    := $(cxx_obj:.o=.o.d)
+
+ +

This should be pretty straightforward: cxx_tun contains +a list of translation units, cxx_obj contains a list of +object files that will be produced from those translation units, and +cxx_od contains a list of automatically generated dependency +files for those translation units. After expansion these variables could +contain the following values (note, in this example out_root +is the same as src_root):

+ +
+cxx_tun   := hello.cxx
+cxx_obj   := .../hello/libhello/libhello/hello.o
+cxx_od    := .../hello/libhello/libhello/hello.o.d
+
+ +

Next chunk:

+ +
+hello.l             := $(out_base)/hello.l
+hello.l.cpp-options := $(out_base)/hello.l.cpp-options
+
+clean     := $(out_base)/.clean
+
+ +

hello.l and clean are two variables that +store names of targets. You are probably wondering what the heck +is hello.l? This is a library abstraction the build system +provides to deal (besides other things) with archives/shared objects +uniformly. A user who builds your project can specify what type of +library they want without any additional effort from you. I encourage +you to take a look inside hello.l.

+ +

hello.l.cpp-options is a bit trickier. +$(out_base)/hello.l.cpp-options keeps C preprocessor options +that are required to compile library files as well as any piece of code +that uses it. Hopefully, it will become clear once you see the rest of +the makefile.

+ +

Let's move on:

+ +
+# Build.
+#
+$(hello.l): $(cxx_obj)
+
+$(cxx_obj): $(hello.l.cpp-options)
+
+$(hello.l.cpp-options): value := -I$(src_root)
+
+$(call -include,$(cxx_od))
+
+ +

The first line tells us that hello.l is built from object +files listed in cxx_obj. The second line establishes dependency +of object files on C preprocessor options - in order to build an object file +we will need C++ source file and C preprocessor options - quite logical. The +third line sets target-specific variable value for +hello.l.cpp-options: that's how hello.l.cpp-options +gets its content. You may be wondering why do we need to add this +-I$(src_root). The first line of hello.cxx + should clear things up:

+ +
+#include "libhello/hello.hxx"
+
+ +

And finally the fourth line includes auto-generated dependency +information for each object file. You can think of +$(call -include ) as being equivalent to -include +directive for now.

+ + +

Next chunk:

+ +
+.PHONY: $(clean)
+
+$(clean): $(hello.l).clean \
+          $(addsuffix .clean,$(cxx_obj)) \
+          $(hello.l.cpp-options).clean
+
+ +

Let's concentrate on the last line. There we are essentially saying that +cleaning libhello consists of cleaning the library, object +files and C preprocessor options. How does this work? It is done using +pattern rules. Part of the build system that defines how to build say +%.l also defines how to clean after it: %.l.clean. +You may want to look into build/cxx/gnu/o-l.make for details.

+ +

Moving on:

+ +
+# Aliases.
+#
+ifdef %interactive%
+
+.PHONY: clean
+
+clean: $(clean)
+
+endif
+
+ +

In this part we are creating a short alias (clean) +for its long equivalent ($(out_base)/.clean). +%interactive% is a system variable defined by +the framework. It is initialized only if current makefile is +used in interactive mode as opposed to being included.

+ +

And finally:

+ +
+# How to.
+#
+$(call include,$(bld_root)/cxx/o-l.make)
+$(call include,$(bld_root)/cxx/cxx-o.make)
+
+ +

In this makefile fragment we are including parts of the build +system that actually know how to build. As you might have +noticed, all the code that we have examined up until now was dealing +with what to build. o-l.make defines a pattern +rule to build libraries from object files. cxx-o.make +defines a pattern rule to build object files from C++ translation units.

+ +

And this concludes our examination of the makefile for +libhello. Next is the test driver( +hello/libhello/test/makefile):

+ +
+include $(dir $(lastword $(MAKEFILE_LIST)))../build/bootstrap.make
+
+cxx_tun := driver.cxx
+cxx_obj := $(addprefix $(out_base)/,$(cxx_tun:.cxx=.o))
+cxx_od  := $(cxx_obj:.o=.o.d)
+
+hello.l             := $(out_root)/libhello/hello.l
+hello.l.cpp-options := $(out_root)/libhello/hello.l.cpp-options
+
+driver  := $(out_base)/driver.e
+clean   := $(out_base)/.clean
+test    := $(out_base)/.test
+
+
+# Build.
+#
+$(driver): $(cxx_obj) $(hello.l)
+
+$(cxx_obj): $(hello.l.cpp-options)
+
+$(call -include,$(cxx_od))
+
+
+# Test.
+#
+.PHONY: $(test)
+
+$(test): $(driver)
+	$<
+
+
+# Clean.
+#
+.PHONY: $(clean)
+
+$(clean): $(driver).clean $(addsuffix .clean,$(cxx_obj))
+
+
+# Aliases.
+#
+ifdef %interactive%
+
+.PHONY: clean test
+
+test: $(test)
+clean: $(clean)
+
+endif
+
+
+# How to.
+#
+$(call include,$(bld_root)/cxx/o-e.make)
+$(call include,$(bld_root)/cxx/cxx-o.make)
+
+
+# Load build information.
+#
+$(call load,$(src_root)/libhello/makefile)
+
+ +

Do you see anything unknown or strange in this makefile? I hope you don't. +Just to re-iterate, I will remove everything we definitely saw and leave +only what's new:

+ +
+hello.l             := $(out_root)/libhello/hello.l
+hello.l.cpp-options := $(out_root)/libhello/hello.l.cpp-options
+
+
+# Build.
+#
+$(driver): $(cxx_obj) $(hello.l)
+
+$(cxx_obj): $(hello.l.cpp-options)
+
+
+# Load build information.
+#
+$(call load,$(src_root)/libhello/makefile)
+
+ +

All of what's left deals in one way or the other with linking +to libhello. The first two lines define variables that +hold paths to the library and C preprocessor options (since we are in +the same project we know what those paths are relative to +out_root/src_root). The third line declares that +driver consists of object files and should be linked with +libhello. The next line says that we need C preprocessor options +to build object files, just like we did for libhello. And finally +the last line: what does the load function do? The +load function loads rules and dependency information from the +makefile specified. Note that it doesn't make variable definitions from that +makefile available (or, even worse, override ones we set) - only dependencies +and rules. The major benefit of doing this is in having complete dependency +information along with the rules in case something gets out of date. If, for +example, we change something in libhello and then execute +make in test, make will be able to +detect that libhello is out of date and will re-build it before +building the test driver.

+ +

Now let's take a look at the makefile from the hello program +(hello/hello/makefile). Remember that it is a separate project +(I removed support for install target again):

+ + +
+include $(dir $(lastword $(MAKEFILE_LIST)))build/bootstrap.make
+
+cxx_tun   := hello.cxx
+cxx_obj   := $(addprefix $(out_base)/,$(cxx_tun:.cxx=.o))
+cxx_od    := $(cxx_obj:.o=.o.d)
+
+hello.e   := $(out_base)/hello.e
+clean     := $(out_base)/.clean
+
+# Secure default target.
+#
+$(hello.e):
+
+
+# Import information about libhello.
+#
+$(call import,libhello,l: hello.l,cpp-options: hello.l.cpp-options)
+
+
+# Build.
+#
+$(hello.e): $(cxx_obj) $(hello.l)
+
+$(cxx_obj): $(hello.l.cpp-options)
+
+$(call -include,$(cxx_od))
+
+
+# Clean.
+#
+.PHONY: $(clean)
+
+$(clean): $(hello.e).clean $(addsuffix .clean,$(cxx_obj))
+
+
+# Aliases.
+#
+ifdef %interactive%
+
+.PHONY: clean
+
+clean: $(clean)
+
+endif
+
+
+# How to.
+#
+$(call include,$(bld_root)/cxx/o-e.make)
+$(call include,$(bld_root)/cxx/cxx-o.make)
+
+ +

Again I will remove all the parts that we are familiar with leaving +only what's new:

+ +
+# Secure default target.
+#
+$(hello.e):
+
+
+# Import information about libhello.
+#
+$(call import,libhello,l: hello.l,cpp-options: hello.l.cpp-options)
+
+ +

Let's see what's going on here. I will start from the call to +the import function. It is similar to the load +function with a few exceptions. First of all, since we are importing +build information from a separate project we don't know where to look +for its parts; this will require dynamic configuration. Secondly, we +have no way to figure out where hello.l and +hello.l.cpp-options are. Thus we have +`l: hello.l' and `cpp-options: hello.l.cpp-options' +which essentially means "initialize variable hello.l with +the library path and variable hello.l.cpp-options with +the C preprocessor options file path".

+ +

One side effect of the call to import function is the +potential loss of the default target. Thus, the first line.

+ +

The inter-project dependency importing architecture is probably +the most complicated part of the build system. It will be described +in a separate section.

+ +

This concludes our step-by-step examination. It was not trivial +but neither is building real software.

+ +

Inter-Project Dependencies

+ +

To be completed.

+ + +

Administrivia

+ + +

License

+ +

The build runtime (makefiles, scripts, etc.) is distributed under +the terms of the GNU General +Public License, version 2. Build documentation is distributed +under the terms of the GNU +Free Documentation License, version 1.2.

+ +

In particular, this means that any makefile, script, etc., that +includes, calls, or otherwise links to the build runtime must +be covered by a GPL-compatible license, should you decide to distribute +them.

+ + +

Bootstrapping

+ +

There are two ways to use the build system: your project can embed +all necessary files or you can require the build runtime to be +installed. The first approach allows you to make your project self-content, +modulo other external dependencies it might have. The disadvantage of this +approach manifests itself when your project participates in a build with +inter-project dependencies established: your project and the rest of the +build could use different (and potentially incompatible) versions of the +runtime. There is no such problem with the second approach.

+ +

My advice is to go with the installed build unless you have +a compelling reason to do otherwise.

+ +

When you go with the embedded runtime you can copy all necessary files +to your project's build/ directory. When you use external +build your build/bootstrap.make might look something +like this:

+ +
+project_name := libhello
+include build-0.1/bootstrap.make
+
+ +

How will make find build-0.1/bootstrap.make? +There are two ways this can happen: you have the runtime installed (e.g., +into /usr/local/include) where make will look +for it by default or you can tell make where to look using +-I option in the command line or by setting +MAKEFLAGS environment variable.

+ +

Versioning

+ +

Build uses a three-digit versioning scheme: X.Y.Z. +X is a generation number; it is incremented when a completely +new design is implemented. Y is an interface version; two +build runtimes with different Y have incompatible +interfaces even though the ideology is the same (if ideology changes +X will most likely be incremented). Additionally, odd +Y indicates that it's a development release (similar to +the linux kernel). Finally, Z signifies a release number. +Releases with the same X.Y have the same interface.

+ +

To allow co-existence of several versions of build on the +same system, the X.Y pair is made part of the path (e.g., +/usr/include/build-0.1) thus when you bootstrap the runtime +(in a project-specific bootstrap.make) you specify interface +version:

+ +
+include build-0.1/bootstrap.make
+
+
+ + +
+

Copyright © 2004-2010 Code Synthesis Tools CC.

+ +
+Permission is granted to copy, distribute and/or modify this document under +the terms of the GNU Free +Documentation License, version 1.2; with no Invariant Sections, no +Front-Cover Texts and no Back-Cover Texts. +
+
+ + + -- cgit v1.1