NAME bld VERSION bld version 1.0.8 USAGE usage: bld [-hc] -h - help message(exit) -c - The -c option will create, at the end of a bld run, a bld.ch +g file with all files and their old/new signatures that have been added/deleted/change +d. Successive runs will append to this file with a time stamp. ARGUMENTS None OPTIONS -h - help message(exit) -c - The -c option will create, at the end of a bld run, a bld.ch +g file with all files and their old/new signatures that have been added/deleted/change +d. Successive runs will append to this file with a time stamp. ENVIRONMENT VARIABLES None RC CONFIGURATION FILES For defining perl variables in the Bld file EVAL section. Should be +valid perl code. Syntax errors will be reported. $ENV{HOME}/.bldrc - user bld run cmd file .bldrc - local bld run cmd file DESCRIPTION bld(1.0.8) is a simple flexible non-hierarchical program that builds +a single C/C++/Objective C /Objective C++/Assembler target(executable or library(static or share +d)) and, unlike 'make', uses SHA1 signatures(no dates) for building software and GNU cpp for autom +atic header file dependency checking. The operation of bld depends entirely on the construction +of the Bld(bld specification) and Bld.gv(bld global values) files. See the bld.README file. There + are no cmd line arguments. A bld.rm program is provided to clean up the main bld directory. Source or header files may be moved about, and if the files do not ch +ange then nothing needs to, or will, be re-built. bld is not hierarchical. bld can descend recu +rsively to pick up and build source, however, the specification for this is still in the Bld file +at the top of the source tree. The bld'ing of a single target uses the following: ~/bld directory files: bld # script - the bld perl script bld.rm # script - script to clean the bld directory bld.README # file - for first point of contact quick start Bld # file - the bld file which controls bld and the cons +truction of a target Bld.gv # file - the file of global values imported into the +Bld file (unusually used only for multi-target builds +) Bld.sig # file - the signature(SHA1) file created from the Bl +d file bld.info # file - information about the bld bld.warn # file - warnings from the bld bld.fatal # file - any fatal msg that ended the bld Complex multi-target projects are built with the use of(in the main b +ld directory): aux/bld.<project> # file - template copied to Bld.<project>/< +version> directories to bld multi-target projects aux/bld.<project>.rm # file - template copied to Bld.<project>/< +version> directories to clean multi-target projects Bld.<project>/<version> # directory - bld instructions for all + project targets bld.<project> # script - bld all or specific tar +gets bld.<project>.rm # script - target and bld.<info|wa +rn|fatal>.<target> file removal Bld.<project>.gv # file - project global values bld.<project>.install # script - target and file install bld.<project>.README # file - project documentation bld.<project>.targets # file - list of all <project> tar +gets <target> # directory - holds all the files +and scripts for the bld of a target Bld.<project>.<target> # file - the Bld file which + controls bld and the construction of a target Bld.<project>.<target>.script.<script name> # script - s +cript(s) to be run during target bld bld.sig.<project>.<target> # file - signatures(SHA1) o +f all source, headers, objects, cmds and target of the target bld bld.info.<project>.<target> # file - information about +the bld bld.warn.<project>.<target> # file - warnings from the +bld bld.fatal.<project>.<target> # file - any fatal msg that + ended the bld bld.<project>/<version> # directory - a source code version of + the project Current example projects: git - the git project http://git-scm.com/ example - misc examples intended to show how to create Bld and Bl +d.gv files FEATURES AND ADVANTAGES 1. Everything is done with SHA1 signatures. No dates are used anywh +ere. Signatures are a property of the file and not meta data from the system used for the build. Any t +ime issues, whether related to local clocks, networked host clocks or files touched by command activit +ies are eliminated. Modern signature algorithms are strongly randomized even for small file changes - +for the 160 bit SHA1 hash collisions are unlikely in the extreme. The Digest::SHA module is fast. The ex +pense of signature calculation times is small relative to the expense of programmer time. An investig +ation of some other make alternatives e.g. scons, cook - will disclose that they too are using signatur +es - for exactly for the same reasons. 2. bld is REALLY simple to use. There are no arguments and no envir +onment variables. The entire bld is controlled from the Bld(and Bld.gv file) file. Only a minimal kn +owledge of perl is needed - variable definitions and simple regular expressions. 3. Automatic dependency checking - GNU cpp is used to find the heade +r file dependencies. Optionally, header file checking may be done for user header files only or fo +r simultaneously both system header and user header files. All header file dependency information as +sociated with each source is saved to the bld.info file. 4. There are no built in dependency rules. The Bld file DIRS sectio +n specifications give what is to be built from what and the Bld file EVAL section gives how to assemb +le all the components for the target. 5. bld is not hierarchical. A single Bld file controls the construc +tion of a single target(a target is an executable or library(static or shared)). Complex multi-target p +rojects use one Bld.gv(global values) file and many Bld files - one to a target. The source directory +structure goes under bld.<project>/<version> and each target Bld file(Bld.<project>.<t +arget>) encapsulates all the build information for all the source directories under bld.<project>/<v +ersion>. All the built targets and build information files go into the Bld.<project>/<version>/<targ +et> directory. See "'make' and it's difficulties:" below for reasons why recursive make causes proble +ms. 6. Each source file will have three signatures associated with it - +one for the source file, one for the corresponding object file and one for the cmds use to re-build th +e source. A change in any of these will result in a re-build. A change in the target signature will resu +lt in a re-build. Optionally, the signatures of dynamic libraries may be tracked. If a library sig +nature changes the bld may warn or stop the re-build. If dynamic libraries are added or deleted from the + bld this can ignore/warn/fatal. 7. If any files in the bld have the same signature this is warned ab +out e.g. two header or source files of the same or different names. 8. Complex multi-target projects are built with a standard directory + setup and a standard set of scripts - see RC CONFIGURATION FILES and DESCRIPTION sections above. 9. Security - since the signatures of everything(source, objects, li +braries, executable) are checked it is more difficult to insinuate an exploit into a source, object, lib +rary or executable during the build process. 10. The capture of the full build process in the bld.info, bld.warn a +nd bld.fatal files allows easy access to and saving of this information. For multi-target projects with t +he target names appended to these files it allows quick investigation of the build process of many interr +elated targets at the same time. 11. Perl - since bld is all perl and since all warnings and fatals ha +ve the source line number associated with them, it is very easy to locate in the source code the exact loca +tion of an error and examine the context about which the error occurred and routine that the error was pro +duced in. 12. Time - programmer time; learning about, maintaining/debugging Mak +efiles and Makefile hierarchies, dependency checking integration and formulation of Makefile strategies, auto +matic Makefile generation with Autotools - these all dominate the programmer time and expense of 'make'. bl +d only requires basic perl variables(in the Bld file EVAL section) and '[R] dir:regex:{cmds}' line specif +ications(in the Bld file DIRS section). 13. The -c option will create, at the end of a bld run, a bld.chg fil +e with all files and their old/new signatures that have been added/deleted/changed. Successive runs + will append to this file with a time stamp. 14. 'make' and it's difficulties: http://www.scons.org/wiki/FromMakeToScons a detailed critique of make and some alternatives(Adrian +Neagu) http://freecode.com/articles/what-is-wrong-with-make What is Wrong with Make?(Adrian Neagu) http://www.scons.org/architecture/ a description of the scons architecture and in particular + the reasons for the use of signatures instead of dates ftp://ftp.gnu.org/old-gnu/Manuals/autoconf/html_mono/autoconf +.html#SEC3 a brief critique of make and how GNU automake from the GN +U Build System contributes http://aegis.sourceforge.net/auug97.pdf an article "Recursive Make Considered Harmful" by Peter M +iller from the Australian UNIX Users Group http://www.conifersystems.com/whitepapers/gnu-make/ an in depth critique of make http://www.conifersystems.com/whitepapers/gnu-make/ What's Wrong With GNU make? http://www.leosimons.com/2006/bettermake/what-is-a-better-mak +e.html What is a better make? http://www.leosimons.com/2006/a-better-make.html Building a better (make|ant|maven|...) DEPENDENCIES I use Fedora for development on an x86_64 architecture. Dnf is th +e package installation tool. Required for execution: experimental.pm(3pm) - for smartmatch and switch features cpp(1) - gnu cpp cmd is required for dependency determination ldd(1) - used for library dependency determination Do: cpan install cpanm cpanm experimental.pm Required for test: gcc(1)/g++(1) (http://gcc.gnu.org/) clang(1) (http://llvm.org/) Some variation might be required on(for git test): dnf install gcc.x86_64 dnf install gcc-c++.x86_64 dnf install clang.x86_64 dnf install zlib.x86_64 dnf install zlib-devel.x86_64 If ./configure generates the following msg about missing requireme +nts: "configure: error: Package requirements (foo) were not met: No package 'foo' found Consider adjusting the PKG_CONFIG_PATH environment variable if + you installed software in a non-standard prefix." Do: dnf install "pkgconfig(foo)" Also check: http://who-t.blogspot.com/2014/05/configure-fails-with +-no-package-foo.html If the downloaded project code does not have a configure script th +en check for a configure.ac file and run 'autoconf' with no arguments or options. This will g +enerate a configure script. QUICK START 1. Bld'ing the git project - http://www.git-scm.com/ a. cd Bld.git/git-2.9.2 # puts you into the git(git-2.9.2) project + directory b. ./bld.git --all # bld's all of the git targets and bld tar +get output files - the bld.info.git.<target>, the bld.warn.git.<target>, the bld.fatal.git.<target>, files c. ./bld.git.rm --all # cleans up everything 2. Bld'ing any single target a. cd bld # the main bld directory - cd here when you unpack + the bld.tar.xz file b. Install the source code in a sub-directory of the bld directory c. Create a Bld file - the Bld file entirely controls the target b +ld - see example below d. ./bld -h # the bld usage msg e. ./bld # do the bld f. ./bld.rm # clean up g. vi Bld.sig # examine the bld signature file h. vi bld.info # detailed info about the stages of the bld i. vi bld.warn # warning msgs from the bld j. vi bld.fatal # fatal msgs that terminated the bld - should be e +mpty if bld is successful Bld FILE FORMAT The Bld file(and Bld.gv) controls the entire target bld. The Bld fil +e is divided into three sections - Comments, EVAL and DIRS: ################################################## Comments - Add comments before the EVAL line EVAL # add perl variables to be used in the DIRS section 'dir' or {cmds} p +arts. six are mandatory. $PROJECT = "git"; $CC = "clang"; $INCDIR = "test/include"; # optional variables e.g. $CCOPT = "-O"; # mandatory defined variables # the target to build e.g. executable, libx.a, libx.so $bld="exec-c"; # cmd used in perl `` call to build $bld target - requires '$bld' +(target) and '$O'(object files) internally $bldcmd = "$CC $INCDIR -lm -o \$bld \$O"; # space separated list of directories to search for libraries $lib_dirs = "example/lib /usr/lib /lib /usr/local/lib"; # use system header files in dependency checking("system" or "nos +ystem") $opt_s = "system"; # inform about any files that will require re-building, but do no +t rebuild("rebuild" or "norebuild") $opt_r = "rebuild"; # do dependency checking on libraries("nolibcheck", "libcheck", " +warnlibcheck" or "fatallibcheck") $opt_lib = "fatallibcheck"; DIRS # '{cmds}' cmd blocks e.g. {ls;pwd;date;} # or # '[R] dir:regex:{cmds}' specifications e.g. bld.$PROJECT/git-2.9.2/: +^zlib\.c$:{gcc $INCDIR -o zlib.o $s} # see examples below in 'Bld FILE FORMAT AND EXAMPLES'. both 'dir' a +nd '{cmds}' fields below may have EVAL # defined variables interpolated into them. {cmds} [R] dir:regex:{cmds} {cmds} [R] dir:regex:{cmds} [R] dir:regex:{cmds} ... ... ################################################## The Bld file has three sections, a starting comments section to docum +ent the Bld, an EVAL section to define variables(and Bld.gv defined variables read in at t +he beginning of the EVAL section) for interpolation into DIRS section 'dir' and '{cmds}' +fields and a DIRS section that defines either {cmd} blocks or '[R] dir:regex:{cmds}' sp +ecifications. The entire EVAL section is eval{}'ed in bld. Any errors will terminate t +he run. There are six mandatory variables(see above). The {cmd} blocks just execute a g +roup of shell cmds. The '[R] dir:regex:{cmds}' specifications are used to build source, l +ocated in directories below the bld directory. These specifications are composed of three f +ields: [R] dir - a directory with possibly variables to be interpolated +and [R] if a recursive search for source is to be made. regex - a perl regular expression to match sources to be built +by the {cmds} field. if [R] is specified then this same regex will be applied t +o every directory recursively searched. the same {cmds} are applied to e +very source found. {cmds} - a group of cmds to construct all the source files selec +ted by the regex field. {cmds} will be executed successively for each source ma +tched. the cmds should have at least one '$s' variable specified. each of the + matched source files will be substituted for '$s'. Rebuilds will happen if: 1. a source file is new or has changed 2. the corresponding object file is missing or has changed 3. the command that is used to compile the source has changed 4. a dependent header file has been added/deleted or changed 5. the command to link the executable or build the library archiv +e has changed 6. the executable or library has changed or is missing The execution of bld will produce four files: Bld.sig The Bld.sig file, holds the source/object/header/executable/l +ibrary file names and corresponding signatures and build cmd signatures used to det +ermine if a source should be re-built. System header files and libraries may optionall +y be included. bld.info Contains detailed information about the the stages of the bui +ld. 1. date/time, OS version, compiler version, cpp version etc. 2. comments section of Bld file 3. EVAL section expansion of $bld, $bldcmd and $lib_dirs mand +atory variables($O is object files) 4. Bld file DIRS section specification lines with irrelevant +white space compressed out 5. R recursively expanded and numbered DIRS section specifica +tion lines 6. a. DIRS section specification lines b. variable interpolated(except for $s) specification +line cmd field c. matching compilation unit source file(s) d. source file header dependencies 7. EVAL section expansion of defined variables used in DIRS s +ection cmd fields 8. List of all build - System headers(full path) User headers(relative path) System libraries(full path) User libraries(relative path) Source files(relative path) Build target(bld directory) bld.warn Warnings about the build e.g. multiple copies of the same head +er files in different directories, multiple '$s' variables specified in DIRS line c +ommand field, same source file specified in more than one directory, EVAL de +fined variables not used in DIRS cmds. Each warning will include the package, + filename and source line etc. bld.fatal Fatals terminate the build e.g. Same source file \'$basename\' + specified in same directory, extra unused variable(s) in DIRS section etc. Thes +e files should be empty if everything built correctly. The six mandatory EVAL defined variables are: 1. $bld # the target to build e.g. executable, libx.a, libx.so $bld="exec-c"; 2. $bldcmd # cmd used in perl `` call to build $bld target - requires '$ +bld'(target) and '$O'(object files) internally $bldcmd = "$CC $INCDIR -lm -o \$bld \$O"; 3. $lib_dirs # space separated list of directories to search for libraries $lib_dirs = "example/lib /usr/lib /lib /usr/local/lib"; 4. $opt_s # use system header files in dependency checking("system" or +"nosystem") $opt_s = "system"; 5. $opt_r # inform about any files that will require re-building, but d +o not rebuild("rebuild" or "norebuild") $opt_r = "rebuild"; 6. $opt_lib # do dependency checking on libraries("nolibcheck", "libcheck +", "warnlibcheck" or "fatallibcheck") $opt_lib = "fatallibcheck"; The previous description material focused on the construction of a si +ngle target. This requires only the use of the bld program and Bld file. To bld complex multi-target + projects requires use of some standard directory structure conventions, several programs for bld'in +g targets and cleaning project directories and directory/file naming conventions. For example, usin +g git-2.9.2 and a <project> name of 'git': Bld.git/git-2.9.2 All of the target Bld files and bld run output files are here +. During development the initiation of target re-blds or full project re-blds are initiated from +here. bld.git/git-2.9.2 The git-2.9.2.tar.gz file is unzipped here 'make configure' a +nd/or ./configure is run against the git project source code. aux Template scripts for use in the Bld.git/git-2.9.2 directory. + The bld.<project> script is copied to Bld.git/git-2.9.2 as bld.git. The bld.<project>.rm is cop +ied to Bld.git/git-2.9.2 as bld.git.rm. No changes are required to the scripts code. aux/bld.git The bld.<project> file would be copied to Bld.git/git-2.9.2 a +s bld.git. There is no need to change the file; the file name is picked up internally. This is the + main project bld script. It is executed either with a sequence of target names or with '--al +l' for building all targets. Do 'perldoc bld.git' for the man page. aux/bld.git.rm The bld.<project>.rm file would be copied to Bld.git/git-2.9. +2 as bld.git.rm. There is no need to change the file; the file name is picked up internally. This script + is used to remove build files related to specific targets or clean files related to all targets. It i +s executed either with a sequence of target names or with '--all' for cleaning all targets. For example, + if test-wildmatch is used as a target then the following files will be removed: bld.fatal.git.test-wildmatch bld.info.git.test-wildmatch bld.warn.git.test-wildmatch Bld.sig.git.test-wildmatch test-wildmatch The target Bld file, Bld.git.test-wildmatch, will not be remo +ved. Do 'perldoc bld.git.rm' for the man page. bld.git.targets All the project targets go here, one to a line. The targets +will be built in order from top to bottom. Make sure than libraries that are required by subsequent targ +ets are built first. The file may have any number of blank or comment lines. bld.git.README The bld.git.README file provide getting started and contact i +nformation. bld.git.install For installing the project. This most likely will be a scrip +t to create an installable package. At present none are populated. bld.git.script.<script> These are scripts to call from the Bld files that do various +functions required for target construction. There may be any number of these. The git pro +ject did not require any. Bld.git.<target> The Bld file for a specific target. Bld.gv.git The project global values file. This file is imported at the + beginning of every project target Bld file. It has no structure. It contains defined variable +s that are common to all project Bld files e.g. $CC. Bld.sig.git.<target> bld.info.git.<target> bld.warn.git.<target> bld.fatal.git.<target> See above for a description of these files. See BUILDING MULTI-TARGET PROJECTS below for the detail steps in +building complex multi-target projects. Bld FILE FORMAT EXAMPLES Example Bld Files: Simplest(Bld.example/example/Bld.example.helloworld-c): The 'Hello World!' program with only the minimal required defi +nitions. Comments EVAL $CC = "gcc"; # mandatory defined variables # the target to build e.g. executable, libx.a, libx.so $bld="helloworld-c"; # cmd used in perl `` call to build $bld target - requires + '$bld'(target) and '$O'(object files) internally $bldcmd = "$CC -o \$bld \$O"; # space separated list of directories to search for librar +ies $lib_dirs = "/usr/lib /lib /usr/local/lib"; # use system header files in dependency checking("system" +or "nosystem") $opt_s = "system"; # inform about any files that will require re-building, bu +t do not rebuild("rebuild" or "norebuild") $opt_r = "rebuild"; # do dependency checking on libraries("nolibcheck", "libch +eck", "warnlibcheck" or "fatallibcheck") $opt_lib = "warnlibcheck"; DIRS bld.example/example : ^helloworld\.c$ : { $CC -c $s; } Complex(Bld.example/example/Bld.example.exec-c): A well commented example of all of the features of a Bld file. + The code routines are all just stubs designed to illustrate a Bld file. Comments EVAL # this section will define perl variables to be interpolated i +nto DIRS section cmd fields # the compiler $CC = "clang"; # mandatory defined variables # the target to build e.g. executable, libx.a, libx.so $bld="exec-c"; # cmd used in perl `` call to build $bld target - requires + '$bld'(target) and '$O'(object files) internally $bldcmd = "$CC -lm -o \$bld \$O"; # space separated list of directories to search for librar +ies $lib_dirs = "example/lib /usr/lib /lib /usr/local/lib"; # use system header files in dependency checking("system" +or "nosystem") $opt_s = "system"; # inform about any files that will require re-building, bu +t do not rebuild("rebuild" or "norebuild") $opt_r = "rebuild"; # do dependency checking on libraries("nolibcheck", "libch +eck", "warnlibcheck" or "fatallibcheck") $opt_lib = "fatallibcheck"; # some examples of variables that will be interpolated into DI +RS section cmd fields $INCLUDE = "-I bld.example/example/include"; $LSOPTIONS = "-l"; # "a" or "b" to conditionally compile main.c $COND = "a"; DIRS # this section will have either {cmds} cmd blocks or '[R] dir: +regex:{cmds}' specifications # example of use of conditional compilation bld.example/example/C : ^main\.c$ : { # can have comments here too if [ "$COND" == 'a' ]; then $CC -S $INCLUDE $s; fi if [ "$COND" == 'b' ]; then $CC -O4 -S $INCLUDE $s; fi } # example of execution of a bare block of cmds - '{' and '}' m +ay be on separate lines { ls $LSOPTIONS; } # the cmd field may be put on another line(s) and indented bld.example/example/C : ^g\.x\.C$ : { $CC -c $INCLUDE $s; } # all three fields - dir, regex and cmd - may be put on separa +te lines(even with extra blank lines). # directories may have embedded blanks('a b'). bld.example/example/C/a b : ^m\.c$ : {$CC -c $INCLUDE $s;} # example of regex field that captures multiple source files(h +.c and i.c) and example of a # cmd field with multiple cmds - white space is irrelevant(a c +hange should not cause a re-build) # example of cmd fields with multiple cmds(ls and $CC) bld.example/example/C : ^(h|i)\.c$ : { ls -l $s; $CC +-c $INCLUDE $s; } # example of assembler source # Note: the $CC compile produces .o output by changing the c t +o an o. # the as output needs to be specified by the -o option. bld.example/example/C : ^main\.s$ : {as -c -o main.o $s;} # are applied to all subdirectories of the specified dir field +(right after the 'R') R bld.example/example/C/y : ^.*\.c$ : {$CC -c $INCLUDE $s;} bld.example/example/C/x : ^t\.c$ : {$CC -c $INCLUDE $s;} bld.example/example/C/z : ^(w|w1)\.c$ : {$CC -c $INCLUDE +$s;} # cmd blocks may execute multiple cmds(ls and pwd) { ls -lfda; pwd; ls; } BUILDING SINGLE TARGETS (a target is an executable or library(static or shared)) 1. Construct the Bld file - see below for a Bld file example and s +ee the Bld.example directory for multiple examples. A Bld.gv file is not needed f +or a single target. Since there are no args to bld and no environment variables are + used, nothing else needs to be done. 2. Execute './bld'. This will rebuild the target and create/updat +e the Bld.sig signature file. The bld.info, bld.warn and bld.fatal files will be creat +ed. 3. Use './bld.rm' to clean the bld directory. BUILDING MULTI-TARGET PROJECTS (a target is an executable or library(static or shared)) 1. Pick a name for the project e.g. git, svn, systemd. 2. In the main bld directory(the location of the bld script) creat +e a bld.<project> directory. Create another directory, bld.<project>/<version>, +that describes the version of the code it will hold e.g. git-2.9.2. Any number of + these version directories may be created to maintain different versions of th +e code. Unpack the source code in the version directory e.g. bld.git/git-2.9.2/<gi +t-2.9.2 src code>. 3. Create a Bld.<project> directory. Create another directory, Bl +d.<project>/<version>, that describes the version of the code it will maintain e.g. gi +t-2.9.2. There should be one version directory for each version of the code be +ing maintained. The version directory will hold the following files: bld.<project> bld.<project>.install bld.<project>.README bld.<project>.rm bld.<project>.targets Bld.gv.<project> Any additional files for project development may be located her +e and will not be removed by bld.<project>.rm. 4. Create in the Bld.<project>/<version> directory a directory for + each target e.g. Bld.git/git-2.9.2/git. These target directories will hold: a. all of the Bld.<project>.<target> files that control the + construction of each project target(along with Bld.gv.<project>) b. all of the target bld output files: bld.info.<project>.<target>(information describing t +he bld) bld.warn.<project>.<target>(bld warning msgs) bld.fatal.<project>.<target>(bld fatal msgs) c. the script control files, bld.<project>.script.<script> +- scripts called by the Bld.<project>.<target> files d. the targets Any additional subdirectories for project development may be lo +cated here and will not be removed by bld.<project>.rm. 5. Create a Bld.<project>.<target> file for each project target. +These control the bld for each target. If there are variables that may be defined gl +obally over the entire project then set them in the Bld.gv.<project>(one per project) +file. The Bld.gv.<project> file will be included in each Bld.<project>.<t +arget> file before it is evaluated. All Bld.<project>.<target> files require six var +iables to be defined. These are: e.g. # mandatory defined variables # space separated list of directories to search for librari +es $lib_dirs = ""; # use system header files in dependency checking("system" o +r "nosystem") $opt_s = "nosystem"; # inform about any files that will require rebuilding, but +do not rebuild("rebuild" or "norebuild") $opt_r = "rebuild"; # do dependency checking on libraries("libcheck", "nolibche +ck", "warnlibcheck" or "fatallibcheck") $opt_lib = "nolibcheck"; # the target to built e.g. executable, libx.a, libx.so $bld="accelerometer"; # cmd used in perl `` call to build $bld target - requires +'$bld'(target) and '$O'(object files) internally $bldcmd = "$CC $LIBSLINKOPTS -o \$bld \$O -LBld.git/git-2.9 +.2 -ludev -lm -lrt -ldl"; The definition of these variables may be spread between the Bld +.<project>.<target> and the imported Bld.gv.<project> files. See the Bld FILE FORMAT section below for detailed inst +ructions on Bld file construction. 6. Create a bld.<project>.targets file with all of the project tar +get names, one to a line. e.g. # each line is a valid target argument to bld.<project> e.g +. './bld.<project> target' # and will build one(that named) library or executable. th +e order of target bld's # is important. if 'bld.<project> --all' is used to bld al +l targets then dependencies # must be built first, that is, libraries then executables. libxdiff.a libgit.a test-date ... The order is important; if an executable depends on a library t +hen build the library first. 7. Copy the 'aux/bld.<project>' and 'aux/bld.<project>.rm' files f +rom the aux directory to the source code directory and rename them for that particular proje +ct. These scripts use the <project> part of the script name for building output files. 8. Run the ./bld.<project> script with the --all option or one or +more target names from the bld.<project>.targets file. This will bld all targets or the s +elected targets. The: bld.info.<project>.<target>(information describing the bld) bld.warn.<project>.<target>(bld warning msgs) bld.fatal.<project>.<target>(bld fatal msgs) files will be created. Examine these for the results of each t +arget bld. All of the bld.fatal.<project>.<target> files should be empty if everythin +g bld's OK. 9. Run './bld.<project> --all' again to rebuild. If everything bu +ilt successfully the first time then this run will indicate that everything is up to date. 10. Use './bld.<project>.rm [--all] [target, target, ...]' to clea +n up. 11. Use './bld.<project>.install' as root to install the project. 12. Examine the ./bld.<project>.README for project specific inform +ation. 13. As an example, an edited run of 'tree Bld.git/git-2.9.2' after + a './bld.git --all': Bld.git/git-2.9.2/ ├── bld.git ├── bld.git.install ├── bld.git.README ├── bld.git.rm ├── bld.git.targets ├── Bld.gv.git ├── git │ ├── bld.fatal.git.git │ ├── Bld.git.git │ ├── bld.git.git.script.sc1 │ ├── bld.info.git.git │ ├── Bld.sig.git.git │ ├── bld.warn.git.git │ └── git ├── git-credential-cache │ ├── bld.fatal.git.git-credential-c +ache │ ├── Bld.git.git-credential-cache │ ├── bld.info.git.git-credential-ca +che │ ├── Bld.sig.git.git-credential-cac +he │ ├── bld.warn.git.git-credential-ca +che │ └── git-credential-cache ├── libgit.a │ ├── bld.fatal.git.libgit.a │ ├── Bld.git.libgit.a │ ├── bld.info.git.libgit.a │ ├── Bld.sig.git.libgit.a │ ├── bld.warn.git.libgit.a │ └── libgit.a ├── libvcs-svn.a │ ├── bld.fatal.git.libvcs-svn.a │ ├── Bld.git.libvcs-svn.a │ ├── bld.info.git.libvcs-svn.a │ ├── Bld.sig.git.libvcs-svn.a │ ├── bld.warn.git.libvcs-svn.a │ └── libvcs-svn.a ├── test-chmtime │ ├── bld.fatal.git.test-chmtime │ ├── Bld.git.test-chmtime │ ├── bld.info.git.test-chmtime │ ├── Bld.sig.git.test-chmtime │ ├── bld.warn.git.test-chmtime │ └── test-chmtime . . . NOTES 1. bld assumes that a source will build a derived file e.g. .o files + in the same directory and have the same root name as the source. a subsequent Bld file {} +block can rename and move the .o files. 2. bld assumes that all targets in multi-target bld's will be unique +ly named - all targets go into the same project directory(in <target> subdirectories) befor +e distribution for installation. installation can then rename and distribute target +s in any way desired. 3. Some projects(rarely) violate either or both of these target nami +ng or object file naming/location requirements, but reconstructing these projects w +ith bld should be relatively easy. 4. bld executes cmd fields({}) in the bld directory and then moves a +ll created files to the source directory. 5. A bld run may be ^C interrupted. When a normal uninterrupted run + is completed the Bld.sig file is rewritten using only those files that were includ +ed in the build. Thus, if files were added or deleted this would reflect in the ne +w Bld.sig file. If a run is interrupted, all files read in from the original Bld.sig f +ile and any new files already built are written out to the Bld.sig file. This ensures +that new files already built and old files not yet examined will not be re-built. This +may result in some entries in the Bld.sig file that no longer exist, but this will b +e corrected at the end of the next normally completed run. 6. The Bld.sig signature file is automatically created and updated. + It contains one line for each source, one line for each header file, optionally one li +ne for each library and one line for the executable. The header file lines and the execu +table line have two fields: the file name and its signature. The source lines have f +our fields: the file name, the signatures of the source file, the command use to build + the source, and the object file. The user can modify this file to force the re-build + of files by altering the signature or even by deleting a line, however, any modificati +on to a source or header file, or build command string will do the same thing. Removing t +he Bld.sig file will re-build the entire target. 7. A non C or C++ source will be re-built if its build command has b +een changed or the source file itself has been changed. The re-built output will be + put back in the directory where the source came from. The assumption is that it w +ill be a file that will then act as source for subsequent build steps e.g. a lex or yacc +that will produce a C file as output which will then later need to be compiled. Bld fi +le cmd({}) blocks can modify this. 8. When blocks of cmds({}) are executed by the perl `{ cmds } 2>&1`; + operator, error reporting is per ``; call. If you are executing multiple cmds an +d want more granular error reporting then break up the cmd block into multiple cmd blo +cks e.g {ls;pwd;} -> {ls;} {pwd;} or dir:regex:{ls;pwd;$CC -c $s;} -> {dir/ls;} {dir/p +wd;} dir:regex: {$CC -c $s;}. 9. All cmds must end with a ';'. If you miss this then you'll see m +sgs like - "sh: -c: line 1: syntax error: unexpected end of file". This includes the + compile and the $bldcmd string. 10. If you interrupt a bld(^C) you might get an object file left in t +he bld directory. The next time bld is run this will not be recognized as a new fil +e and mv'ed to the source file directory. Just remove these before a new bld run. 11. { cmds } are executed within `{ cmds } 2>&1`; and the return stdo +ut/stderr matched against strings stored in the @stderr_err_strs array. Any actual + error return not matched by one of these strings will be missed. New strings can +be added to @stderr_err_strs in the BGC.pm module. TODO 1. The git project needs work. I ran ./configure before each bld. I + used no options. How options affect the generated code and thus the Bld files is im +portant. Anyone willing to investigate configure options and how these options aff +ect the Bld files is welcome. 2. The bld.git.install scripts all need to be done. These scripts ne +ed to build the packages that 'dnf install <package>' would install or possibly pa +ckages tailored to other systems. I'd prefer to partner with someone knowledgeabl +e about the installation of git. 3. If you successfully bld a new project and wish to contribute the b +ld, please do so. I'm interested in how others construct/organize/document/debug pro +jects and their Bld files. CALL TREE Calls to imported functions from public CPAN modules are omitted. Ca +lls to some bld coded routines are omitted: opt_help() system_error_msg() warning() fatal() sourcesort() bld Bld_section_extract() init_blddotinfo() dirs_pro() cvt_dirs_to_array() expand_R_specification() accum_blddotinfo_output() var_sub() var_sub() var_sub() variable_match() var_sub() var_sub() var_sub() read_Blddotsig() var_sub() var_sub() src_pro() file_sig_calc() buildopt(); tgtextorfile(); hdr_depend() file_sig_calc() rebuild_src_bool() tgt_signature() rebuild_target_bool() file_sig_calc() file_sig_calc() rebuild_exec() file_sig_calc() file_sig_calc() multiple_sigs() sig_file_update() DIAGNOSTICS Diagnostics are either warnings(calling warning($msg)) or fatals(call +ing fatal($msg)). Warnings and fatals are exclusive; specific conditions cause warnings + and specific other conditions cause fatals. There is no overlap. Warnings are co +nditions that may be of interest e.g. same header file in multiple locations or multipl +e -c specifications in a source compilation cmd, but which should not impact the full bui +ld of the project. Fatals are conditions that either will necessarily force the terminat +ion of the build e.g. a source file compile failure, or that indicate the construction + of the Bld file has some instructions that are contradictory or missing necessary ele +ments e.g. same source file matched twice in Bld file DIRS section specifications. W +arnings are written to the bld.warn file only. Fatals are written identically to standar +d out and the bld.fatal file. Warnings all start with 'WARNING:' and fatals all st +art with 'FATAL:'. There are no other types of diagnostic msgs. FILES For defining perl variables in the Bld file EVAL section. Should be +valid perl code. Syntax errors will be reported. $ENV{HOME}/.bldrc - user bld run cmd file .bldrc - local bld run cmd file The bld'ing of a single target uses the following: ~/bld directory files: bld # script - the bld perl script bld.rm # script - script to clean the bld directory bld.README # file - for first point of contact quick start Bld # file - the bld file which controls bld and the cons +truction of a target Bld.gv # file - the file of global values imported into the +Bld file (unusually used only for multi-target builds +) Bld.sig # file - the signature(SHA1) file created from the Bl +d file bld.info # file - information about the bld bld.warn # file - warnings from the bld bld.fatal # file - any fatal msg that ended the bld Complex multi-target projects are built with the use of(in the main b +ld directory): aux/bld.<project> # file - template copied to Bld.<project>/< +version> directories to bld multi-target projects aux/bld.<project>.rm # file - template copied to Bld.<project>/< +version> directories to clean multi-target projects Bld.<project>/<version> # directory - bld instructions for all + project targets bld.<project> # script - bld all or specific tar +gets bld.<project>.rm # script - target and bld.<info|wa +rn|fatal>.<target> file removal Bld.<project>.gv # file - project global values bld.<project>.install # script - target and file install bld.<project>.README # file - project documentation bld.<project>.targets # file - list of all <project> tar +gets <target> # directory - holds all the files +and scripts for the bld of a target Bld.<project>.<target> # file - the Bld file which + controls bld and the construction of a target Bld.<project>.<target>.script.<script name> # script - s +cript(s) to be run during target bld bld.sig.<project>.<target> # file - signatures(SHA1) o +f all source, headers, objects, cmds and target of the target bld bld.info.<project>.<target> # file - information about +the bld bld.warn.<project>.<target> # file - warnings from the +bld bld.fatal.<project>.<target> # file - any fatal msg that + ended the bld bld.<project>/<version> # directory - a source code version of + the project INCOMPATIBILITIES None Known BUGS AND LIMITATIONS None Known SEE ALSO Do: perldoc 'bld.<project>' perldoc 'bld.<project>.rm' 'make' and it's difficulties - in FEATURES AND ADVANTAGES above GITHUB RELEASES https://github.com/rahogaboom/bld bld-1.0.8.tar.gz - changes related to: a. remove svn as an example. this allows grea +ter focus on multiple versions of git as the single example of a complex p +roject build. added git version 2.9.2. b. modify bld.<project> and bld.<project>.rm t +o work with all target files under the same target named directory. thi +s unclutters the project directory to hold only target directories a +nd the project build configuration and build executables. c. minor code changes. bld-1.0.7.tar.gz - changes related to: a. upgrade to perl 5.24.0 b. remove systemd as an example. ./configure +is complicated by many dependencies. c. update license to Boost d. remove Obj C and yacc/lex examples. requir +es dependencies. I wanted the examples to run with only gcc/g+ ++/clang more or less. bld-1.0.6.tar.gz - changes related to: a. fixes for two gcc warnings in the example c +ode(rdx and daa) b. use 'print STDERR' for all prints - more im +mediate output c. doc updates Why are there no releases beyond the latest three? For now, I on +ly intend to maintain and answer questions about the most recent releases. This may change in future. AUTHOR Richard A Hogaboom richard.hogaboom@gmail.com LICENSE and COPYRIGHT and (DISCLAIMER OF) WARRANTY Copyright Richard Allen Hogaboom 1997 - 2016. Distributed under the Boost Software License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) Boost Software License - Version 1.0 - August 17th, 2003 Permission is hereby granted, free of charge, to any person or organi +zation obtaining a copy of the software and accompanying documentation cover +ed by this license (the "Software") to use, reproduce, display, distribute, execute, and transmit the Software, and to prepare derivative works o +f the Software, and to permit third-parties to whom the Software is furnish +ed to do so, all subject to the following: The copyright notices in the Software and this entire statement, incl +uding the above license grant, this restriction and the following disclaime +r, must be included in all copies of the Software, in whole or in part, +and all derivative works of the Software, unless such copies or derivativ +e works are solely in the form of machine-executable object code genera +ted by a source language processor. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRE +SS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILI +TY, FITNESS FOR A PARTICULAR PURPOSE, TITLE AND NON-INFRINGEMENT. IN NO E +VENT SHALL THE COPYRIGHT HOLDERS OR ANYONE DISTRIBUTING THE SOFTWARE BE LI +ABLE FOR ANY DAMAGES OR OTHER LIABILITY, WHETHER IN CONTRACT, TORT OR OTHE +RWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR + OTHER DEALINGS IN THE SOFTWARE.
|
|---|