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.
Posts are HTML formatted. Put <p> </p> tags around your paragraphs. Put <code> </code> tags around your code and data!
Titles consisting of a single word are discouraged, and in most cases are disallowed outright.
Read Where should I post X? if you're not absolutely sure you're posting in the right place.
Please read these before you post! —
Posts may use any of the Perl Monks Approved HTML tags:
- a, abbr, b, big, blockquote, br, caption, center, col, colgroup, dd, del, details, div, dl, dt, em, font, h1, h2, h3, h4, h5, h6, hr, i, ins, li, ol, p, pre, readmore, small, span, spoiler, strike, strong, sub, summary, sup, table, tbody, td, tfoot, th, thead, tr, tt, u, ul, wbr
You may need to use entities for some characters, as follows. (Exception: Within code tags, you can put the characters literally.)
| |
For: |
|
Use: |
| & | | & |
| < | | < |
| > | | > |
| [ | | [ |
| ] | | ] |
Link using PerlMonks shortcuts! What shortcuts can I use for linking?
See Writeup Formatting Tips and other pages linked from there for more info.