icmbuild(1) A generic, easy configurable, program maintenance script

SYNOPSIS

icmbuild [-h] [-c] args

DESCRIPTION

The icmbuild script is a generic script that can be used to do program maintenance using icmake(1).

Icmbuild requires that the file icmconf is available in the directory where program maintenance is requested.

Icmbuild assumes that your sources exist in and below the current working directory. The file icmconf in icmake(1)'s distribution provides an example of an icmconf file that can be used by icmbuild. In that example icmconf file it is assumed that C++ sources are maintained, but program maintenance for, e.g., C sources can easily be configured.

Icmbuild() compiles all sources in each of the subdirectories named in the file CLASSES, and then compiles all sources in the current working directory.

The compiled sources result in object modules which may be kept in a library, against which the main-object module is linked. It is also possible to specify additional libraries against which the program must be linked.

If a library is constructed it is kept up to date by icmbuild. When a source is successfully compiled its new object module will replace the old one that is found in the library. At that point the object files are no longer required and are removed by icmbuild.

KICK-STARTING ICMBUILD

To use icmbuild do as follows:

  • Install icmbuild in your path;
  • copy icmconf (and probably the file CLASSES) to your project's base directory (i.e., the directory in which and where below the project's sources are found);
  • Modify the #defines in the file icmconf to taste;
  • Enter the names of subdirectories containing sources on separate lines in the file CLASSES
  • Note that the order of the classes mentioned in CLASSES is relevant. New class (subdirectory) names can always be added, but reordering the lines in the CLASSES file should be avoided. If reordering is necessary, then first run the command icmbuild clean to remove all files thus far created by icmbuild. Recompilation is necessary as the names of the object files contain class order-numbers for identification. These class-order numbers prevent file-name collisions (e.g., two classes might use a file data.cc) and thus replacement of a file x.o from class A by file x.o from class B is prevented;
  • Now simply run 
                icmbuild -h
    from the project's base directory and let the help-info tell you what your options are. See the next section for the modes of operation.

OPTIONS

Icmbuild recognizes two options, at most one should be specified:

  • -h: Provide a short usage overview.
  • -c: Clear the screen (using tput clear) before starting the compilation process

Following the optional -c icmbuild() the following arguments may be passed to icmbuild:

  • clean
    clean up remnants of previous activities
  • library
    build the library (static and optionally the dynamic library)
  • program
    build the binary program
  • program strip
    build the stripped binary program
  • install program path install the constructed program in the specified path (to be used after issuing icmbuild program)
  • install static path install the constructed static library in the specified path (to be used after issuing icmbuild library)
  • install shared path install the constructed shared library in the specified path (to be used after issuing icmbuild library) After adding a line to icmconf containing 
        #define DEFCOM "program"
    icmbuild by default uses the argument program. After adding 
        #define DEFCOM "strip"
    icmbuild by default uses the argument strip. After adding 
        #define DEFCOM "library"
    icmbuild by default uses the argument library.

DEFCOM is ignored when an explicit operational mode is passed to icmbuild.

FILES

The mentioned paths are sugestive only and may be installation dependent:

  • /usr/share/icmake/icmconf Example of a icmbuild configuration file;
  • /usr/share/icmake/CLASSES Example of a icmbuild CLASSES file.

EXAMPLES

Here is an example of the configuration file icmconf for a concrete program, using the library libbobcat1 as an additional library: 

    // Inspect the following #defines. Change them to taste. If you don't
    // need a particular option, change its value into an empty string
    // For more information about this file: 'man 7 icmconf'
// MAINTENANCE RELATED DEFINES THAT ARE OFTEN ADAPTED:
// ===================================================
    // Uncomment to clear the screen starting the compilation
//#define CLS
    // Uncomment to construct a library. Optionally use another name (don't
    // use lib or an extension like .a)
//#define LIBRARY           "modules"
    // The source containing main():
#define MAIN                "main.cc"
    // The pattern locating sources in a directory:
#define SOURCES             "*.cc"
    //  The extension of object modules:
#define OBJ_EXT             ".o"
    // Uncomment to construct a shared library 
//#define SHARED
    // If the constructed shared library requires additional libraries then
    // specify these here. E.g., if a library /usr/lib/special/libspecial.so
    // is required then specify  "-L/usr/lib/special -lspecial" 
    // Predefined paths (e.g., /lib, /usr/lib) do not have to be specified
#define SHAREDREQ           ""
    // Directory to contain temporary results
#define TMP_DIR             "tmp"
    // Uncomment to use the ALL facility and a class dependency setup in the
    // CLASSES file. When a directory contains a file ALL (optionally rename
    // this filename by providing an alternative name) then all its sources
    // and all sources of all classes depending on it are also compiled.  
    // Class dependencies are indicated by the class name (as the first
    // word on a line) optionally followed by additional class names, which
    // are the classes directly depending on the line's first class name.
//#define USE_ALL             "a"
    // should commands be echoed (ON) or not (OFF) ?
#define USE_ECHO              ON
    //  Use the VERSION file
#define USE_VERSION
    // When DEFCOM "program" is specified './icmbuild' is shorthand for 
    // './icmbuild program'
    // When DEFCOM "library" is specified './icmbuild' is shorthand for 
    // './icmbuild library'
    // The icmstart script may add a DEFCOM specification to this file.
//#define DEFCOM "program"
//#define DEFCOM "library"
// COMPILATION AND LINKING RELATED DEFINES
// =======================================
    // The compiler to use. Define CC instead if a C compiler should be used.
#define CXX            "g++"
//#define CC            "gcc"
    // The compiler options to use. Define CFLAGS instead if a C compiler is
    // used. 
    // To suppress colored error messages add option -fdiagnostics-color=never
    // To add debug-code to object files add option  -g
#define CXXFLAGS        " --std=c++14 -Wall -O2"
//#define CFLAGS        " -Wall -g -O2"
    // The extension of internal header files. See PRECOMP below
#define IH              ".ih"
    // Uncomment to generate precompiled headers. When activated internal
    // header files are precompiled when they are more recent than their 
    // precompiled versions. PRECOMP requires IH
//#define PRECOMP "-x c++-header"
    // Uncomment to relink the binary, even when no sources were changed 
//#define REFRESH
    // Options passed to the linker:
#define LDFLAGS         ""
// LIBRARIES REQUIRED BY THE CONSTRUCTED PROGRAM OR LIBRARY:
// =========================================================
    // any additional libraries the program may need:
#define ADD_LIBRARIES       ""
    // additional paths (other than the standard paths) to locate additional
    // libraries:
#define ADD_LIBRARY_PATHS   ""
// DEFINES RELATED TO USING A PARSER GENERATOR
// ===========================================
    // The subdirectory containing the parser's specification file
    // If this directive is REMOVED, then all parser-related #defines
    // can also be removed from icmconf.
#define PARSER_DIR          ""
    // What is the program generating a parser?
#define PARSGEN             "bisonc++"
    // Flags to pass to PARSGEN:
#define PARSFLAGS           "-V"
    // What is the top-level (or only) grammar specification file?
#define PARSSPEC            "grammar"
    // Optionally use patterns to specify additional grammar specification 
    // files. These files are (in)directly included by PARSSPEC. Specify
    // patterns relative to PARSER_DIR
//#define PARSFILES           ""
    // The source file generated by the parser generator
#define PARSOUT             "parse.cc"
// DEFINES RELATED TO USING A SCANNER GENERATOR
// ============================================
    // The subdirectory containing the scanner's specification file
    // If this directive is REMOVED, then all scanner-related #defines
    // can also be removed from icmconf.
#define SCANNER_DIR         ""  
    // What is the program generating the lexical scanner?
#define SCANGEN             "flexc++"
    // Flags to provide SCANGEN with:
#define SCANFLAGS           ""
    // Name of the lexical scanner specification file
#define SCANSPEC            "lexer"
    
    // Optionally use patterns to specify additional scanner specification 
    // files. These files are (in)directly included by SCANSPEC. Specify
    // patterns relative to SCANNER_DIR
//#define SCANFILES            ""
    // The source file generated by the lexical scanner
#define SCANOUT             "lex.cc"

BUGS

None reported

COPYRIGHT

This is free software, distributed under the terms of the GNU General Public License (GPL).

AUTHOR

Frank B. Brokken ([email protected]).

SEE ALSO

LAST SEARCHED