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.chg file 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.

ARGUMENTS

 None

OPTIONS

     -h - help message(exit)
     -c - The -c option will create, at the end of a bld run, a bld.chg file 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.

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 shared)) and, unlike 'make', uses
 SHA1 signatures(no dates) for building software and GNU cpp for automatic 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 change then nothing needs to,
 or will, be re-built.  bld is not hierarchical.  bld can descend recursively 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 construction 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 Bld 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 bld 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 targets
         bld.<project>.rm           # script - target and bld.<info|warn|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> targets
         <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 - script(s) to be run during target bld
             bld.sig.<project>.<target>    # file - signatures(SHA1) of 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 Bld.gv files

FEATURES AND ADVANTAGES

  1. Everything is done with SHA1 signatures.  No dates are used anywhere.  Signatures are a property of the
     file and not meta data from the system used for the build.  Any time issues, whether related to local
     clocks, networked host clocks or files touched by command activities 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 expense of signature calculation times 
     is small relative to the expense of programmer time.  An investigation of some other make alternatives
     e.g. scons, cook - will disclose that they too are using signatures - for exactly for the same reasons.
  2. bld is REALLY simple to use.  There are no arguments and no environment variables.  The entire bld is
     controlled from the Bld(and Bld.gv file) file.  Only a minimal knowledge of perl is needed - variable
     definitions and simple regular expressions.
  3. Automatic dependency checking - GNU cpp is used to find the header file dependencies.  Optionally,
     header file checking may be done for user header files only or for simultaneously both system header
     and user header files.  All header file dependency information associated with each source is saved
     to the bld.info file.
  4. There are no built in dependency rules.  The Bld file DIRS section specifications give what is to be
     built from what and the Bld file EVAL section gives how to assemble all the components for the target.
  5. bld is not hierarchical.  A single Bld file controls the construction of a single target(a target is an
     executable or library(static or shared)).  Complex multi-target projects 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>.<target>) encapsulates all the build
     information for all the source directories under bld.<project>/<version>.  All the built targets and
     build information files go into the Bld.<project>/<version>/<target> directory.  See "'make' and it's
     difficulties:" below for reasons why recursive make causes problems.
  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 the source.  A change in any of these will
     result in a re-build.  A change in the target signature will result in a re-build.  Optionally, the
     signatures of dynamic libraries may be tracked.  If a library signature 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 about 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, libraries, executable) are checked it is
     more difficult to insinuate an exploit into a source, object, library or executable during the build process.
 10. The capture of the full build process in the bld.info, bld.warn and bld.fatal files allows easy access to
     and saving of this information.  For multi-target projects with the target names appended to these files
     it allows quick investigation of the build process of many interrelated targets at the same time.
 11. Perl - since bld is all perl and since all warnings and fatals have the source line number associated with
     them, it is very easy to locate in the source code the exact location of an error and examine the context
     about which the error occurred and routine that the error was produced in.
 12. Time - programmer time; learning about, maintaining/debugging Makefiles and Makefile hierarchies, dependency
     checking integration and formulation of Makefile strategies, automatic Makefile generation with Autotools -
     these all dominate the programmer time and expense of 'make'.  bld only requires basic perl variables(in
     the Bld file EVAL section) and '[R] dir:regex:{cmds}' line specifications(in the Bld file DIRS section).
 13. The -c option will create, at the end of a bld run, a bld.chg file 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 GNU Build System contributes
         http://aegis.sourceforge.net/auug97.pdf
             an article "Recursive Make Considered Harmful" by Peter Miller 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-make.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 the 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 requirements:

        "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 then check for a configure.ac
    file and run 'autoconf' with no arguments or options.  This will generate 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 target 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 bld - 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 empty if bld is successful

Bld FILE FORMAT

 The Bld file(and Bld.gv) controls the entire target bld.  The Bld file 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} parts.  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 "nosystem")
     $opt_s = "system";

     # inform about any files that will require re-building, but do not 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' and '{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 document the Bld, an EVAL
 section to define variables(and Bld.gv defined variables read in at the 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}' specifications.  The
 entire EVAL section is eval{}'ed in bld.  Any errors will terminate the run.  There are
 six mandatory variables(see above). The {cmd} blocks just execute a group of shell cmds.
 The '[R] dir:regex:{cmds}' specifications are used to build source, located in directories
 below the bld directory. These specifications are composed of three fields:

     [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 to every directory
               recursively searched.  the same {cmds} are applied to every source found.

     {cmds}  - a group of cmds to construct all the source files selected by the regex field.
               {cmds} will be executed successively for each source matched.  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 archive 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/library file names and
         corresponding signatures and build cmd signatures used to determine if a source should
         be re-built.  System header files and libraries may optionally be included.

     bld.info
         Contains detailed information about the the stages of the build.

         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 mandatory 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 specification 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 section 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 header files in different
        directories,  multiple '$s' variables specified in DIRS line command field,
        same source file specified in more than one directory, EVAL defined 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.  These 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 do 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 single 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'ing targets and cleaning project
 directories and directory/file naming conventions.  For example, using 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' and/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 copied 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 as 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 '--all' 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 is 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 removed. 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 targets 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 information.

     bld.git.install
         For installing the project.  This most likely will be a script 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 project 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 variables 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 definitions.

        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 libraries
            $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, but do not rebuild("rebuild" or "norebuild")
            $opt_r = "rebuild";

            # do dependency checking on libraries("nolibcheck", "libcheck", "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 into 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 libraries
            $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, but do not rebuild("rebuild" or "norebuild")
            $opt_r = "rebuild";

            # do dependency checking on libraries("nolibcheck", "libcheck", "warnlibcheck" or "fatallibcheck")
            $opt_lib = "fatallibcheck";

        # some examples of variables that will be interpolated into DIRS 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 '}' may 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 separate 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 change 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 to 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 see the Bld.example
       directory for multiple examples.  A Bld.gv file is not needed for 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/update the Bld.sig signature
       file.  The bld.info, bld.warn and bld.fatal files will be created.

    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) create 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 the code.  Unpack the
       source code in the version directory e.g. bld.git/git-2.9.2/<git-2.9.2 src code>.

    3. Create a Bld.<project> directory.  Create another directory, Bld.<project>/<version>,
       that describes the version of the code it will maintain e.g. git-2.9.2.  There
       should be one version directory for each version of the code being 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 here 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 the 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 located 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 globally 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>.<target> file before it
       is evaluated.  All Bld.<project>.<target> files require six variables to be defined.
       These are:

       e.g.
       # mandatory defined variables

           # space separated list of directories to search for libraries
           $lib_dirs = ""; 

           # use system header files in dependency checking("system" or "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", "nolibcheck", "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 instructions on Bld file construction.


    6. Create a bld.<project>.targets file with all of the project target 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.  the order of target bld's
           # is important.  if 'bld.<project> --all' is used to bld all 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 then build the library first.

    7. Copy the 'aux/bld.<project>' and 'aux/bld.<project>.rm' files from the aux directory to the
       source code directory and rename them for that particular project.  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 selected 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 target bld.  All of the
       bld.fatal.<project>.<target> files should be empty if everything bld's OK.

    9. Run './bld.<project> --all' again to rebuild.  If everything built successfully the first
       time then this run will indicate that everything is up to date.

    10. Use './bld.<project>.rm [--all] [target, target, ...]' to clean up.

    11. Use './bld.<project>.install' as root to install the project.

    12. Examine the ./bld.<project>.README for project specific information.

    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/
        &#9500;&#9472;&#9472; bld.git
        &#9500;&#9472;&#9472; bld.git.install
        &#9500;&#9472;&#9472; bld.git.README
        &#9500;&#9472;&#9472; bld.git.rm
        &#9500;&#9472;&#9472; bld.git.targets
        &#9500;&#9472;&#9472; Bld.gv.git
        &#9500;&#9472;&#9472; git
        &#9474;   &#9500;&#9472;&#9472; bld.fatal.git.git
        &#9474;   &#9500;&#9472;&#9472; Bld.git.git
        &#9474;   &#9500;&#9472;&#9472; bld.git.git.script.sc1
        &#9474;   &#9500;&#9472;&#9472; bld.info.git.git
        &#9474;   &#9500;&#9472;&#9472; Bld.sig.git.git
        &#9474;   &#9500;&#9472;&#9472; bld.warn.git.git
        &#9474;   &#9492;&#9472;&#9472; git
        &#9500;&#9472;&#9472; git-credential-cache
        &#9474;   &#9500;&#9472;&#9472; bld.fatal.git.git-credential-cache
        &#9474;   &#9500;&#9472;&#9472; Bld.git.git-credential-cache
        &#9474;   &#9500;&#9472;&#9472; bld.info.git.git-credential-cache
        &#9474;   &#9500;&#9472;&#9472; Bld.sig.git.git-credential-cache
        &#9474;   &#9500;&#9472;&#9472; bld.warn.git.git-credential-cache
        &#9474;   &#9492;&#9472;&#9472; git-credential-cache
        &#9500;&#9472;&#9472; libgit.a
        &#9474;   &#9500;&#9472;&#9472; bld.fatal.git.libgit.a
        &#9474;   &#9500;&#9472;&#9472; Bld.git.libgit.a
        &#9474;   &#9500;&#9472;&#9472; bld.info.git.libgit.a
        &#9474;   &#9500;&#9472;&#9472; Bld.sig.git.libgit.a
        &#9474;   &#9500;&#9472;&#9472; bld.warn.git.libgit.a
        &#9474;   &#9492;&#9472;&#9472; libgit.a
        &#9500;&#9472;&#9472; libvcs-svn.a
        &#9474;   &#9500;&#9472;&#9472; bld.fatal.git.libvcs-svn.a
        &#9474;   &#9500;&#9472;&#9472; Bld.git.libvcs-svn.a
        &#9474;   &#9500;&#9472;&#9472; bld.info.git.libvcs-svn.a
        &#9474;   &#9500;&#9472;&#9472; Bld.sig.git.libvcs-svn.a
        &#9474;   &#9500;&#9472;&#9472; bld.warn.git.libvcs-svn.a
        &#9474;   &#9492;&#9472;&#9472; libvcs-svn.a
        &#9500;&#9472;&#9472; test-chmtime
        &#9474;   &#9500;&#9472;&#9472; bld.fatal.git.test-chmtime
        &#9474;   &#9500;&#9472;&#9472; Bld.git.test-chmtime
        &#9474;   &#9500;&#9472;&#9472; bld.info.git.test-chmtime
        &#9474;   &#9500;&#9472;&#9472; Bld.sig.git.test-chmtime
        &#9474;   &#9500;&#9472;&#9472; bld.warn.git.test-chmtime
        &#9474;   &#9492;&#9472;&#9472; 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 uniquely named - all targets go
     into the same project directory(in <target> subdirectories) before distribution for
     installation.  installation can then rename and distribute targets in any way desired.

  3. Some projects(rarely) violate either or both of these target naming or object file
     naming/location requirements, but reconstructing these projects with bld should be
     relatively easy.

  4. bld executes cmd fields({}) in the bld directory and then moves all 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 included in the build.
     Thus, if files were added or deleted this would reflect in the new Bld.sig file.  If a
     run is interrupted, all files read in from the original Bld.sig file 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 be 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 line for each library and
     one line for the executable.  The header file lines and the executable line have two
     fields: the file name and its signature.  The source lines have four 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 modification to a source or header
     file, or build command string will do the same thing.  Removing the 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 been 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 will 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 file 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 and want more granular
     error reporting then break up the cmd block into multiple cmd blocks e.g {ls;pwd;} ->
     {ls;} {pwd;} or dir:regex:{ls;pwd;$CC -c $s;} -> {dir/ls;} {dir/pwd;} dir:regex:
     {$CC -c $s;}.

  9. All cmds must end with a ';'.  If you miss this then you'll see msgs 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 the bld directory.
     The next time bld is run this will not be recognized as a new file 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 stdout/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 important.  Anyone
    willing to investigate configure options and how these options affect the Bld files
    is welcome.

 2. The bld.git.install scripts all need to be done.  These scripts need to build the
    packages that 'dnf install <package>' would install or possibly packages tailored
    to other systems.  I'd prefer to partner with someone knowledgeable about the
    installation of git.

 3. If you successfully bld a new project and wish to contribute the bld, please do so.
    I'm interested in how others construct/organize/document/debug projects and their
    Bld files.

CALL TREE

 Calls to imported functions from public CPAN modules are omitted.  Calls 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(calling fatal($msg)).
 Warnings and fatals are exclusive; specific conditions cause warnings and specific
 other conditions cause fatals.  There is no overlap.  Warnings are conditions that may
 be of interest e.g. same header file in multiple locations or multiple -c specifications
 in a source compilation cmd, but which should not impact the full build of the project.
 Fatals are conditions that either will necessarily force the termination 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 elements e.g. same
 source file matched twice in Bld file DIRS section specifications.  Warnings are written
 to the bld.warn file only.  Fatals are written identically to standard out and the
 bld.fatal file.  Warnings all start with 'WARNING:' and fatals all start 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 construction 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 Bld 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 bld 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 targets
         bld.<project>.rm           # script - target and bld.<info|warn|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> targets
         <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 - script(s) to be run during target bld
             bld.sig.<project>.<target>    # file - signatures(SHA1) of 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 greater focus on multiple versions
                           of git as the single example of a complex project build.  added git
                           version 2.9.2.
                        b. modify bld.<project> and bld.<project>.rm to work with all target files
                           under the same target named directory.  this unclutters the project
                           directory to hold only target directories and 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.  requires 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 code(rdx and daa)
                        b. use 'print STDERR' for all prints - more immediate output
                        c. doc updates

     Why are there no releases beyond the latest three?  For now, I only 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 organization
 obtaining a copy of the software and accompanying documentation covered by
 this license (the "Software") to use, reproduce, display, distribute,
 execute, and transmit the Software, and to prepare derivative works of the
 Software, and to permit third-parties to whom the Software is furnished to
 do so, all subject to the following:

 The copyright notices in the Software and this entire statement, including
 the above license grant, this restriction and the following disclaimer,
 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 derivative
 works are solely in the form of machine-executable object code generated by
 a source language processor.

 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 FITNESS FOR A PARTICULAR PURPOSE, TITLE AND NON-INFRINGEMENT. IN NO EVENT
 SHALL THE COPYRIGHT HOLDERS OR ANYONE DISTRIBUTING THE SOFTWARE BE LIABLE
 FOR ANY DAMAGES OR OTHER LIABILITY, WHETHER IN CONTRACT, TORT OR OTHERWISE,
 ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
 DEALINGS IN THE SOFTWARE.