includefile(release.yo)

htmlbodyopt(text)(#27408B)
htmlbodyopt(bgcolor)(#FFFAF0)
whenhtml(mailto(Frank B. Brokken: f.b.brokken@rug.nl))

DEFINEMACRO(sop)(3)(\
    it() bf(-ARG1) ARG2 nl()ARG3\
)

DEFINEMACRO(itt)(1)(\
    it()tt(ARG1)\
)

DEFINEMACRO(itb)(1)(\
    it()bf(ARG1)nl()\
)

DELETEMACRO(tt)
DEFINEMACRO(tt)(1)(em(ARG1))

COMMENT( man-request, section, date, distribution file, general name)
manpage(icmstart.rc)(7)(_CurYrs_)(icmake._CurVers_)
        (icmstart resource file)

COMMENT( man-request, larger title )
manpagename(icmstart.rc)(The icmstart(1) resource file)

manpagedescription()

The bf(icmstart.rc) file specifies files to be installed by bf(icmstart)(1).

A default bf(icmstart.rc) is found in tt(/etc/icmake/icmstart.rc), but if 
tt($HOME/.icmake/icmstart.rc) exists then the latter file is used by
bf(icmstart)(1). tt($HOME/.icmake/icmstart.rc) in turn is overruled by
specifying a tt(-c) option when invoking bf(icmstart)(1).

The default resource file contains the following specifications, preparing for
the construction of a bf(C++) program using bf(icmbuild)(1):
        verb(
    CLASSES
    icmconf
    P  main.cc 
    P  main.ih 
    Pb usage.cc
    Pb version.cc
    P ? scanner 
    P ? parser  
        )
The tt(icmstart.rc) file may contain:
    itemization(
    it() empty lines, which are ignored;
    it() lines beginning with a hash-character (tt(#)), also ignored;
    it() an optional installation mode followed by a source-destination
        specification. 
    )

manpagesection(INSTALLATION MODE)

    An installation mode consists of a combination of:
    itemization(
    it() either a tt(P) (don't install with tt(icmstart xxx library)) or an
        tt(L) (don't install with tt(icmstart xxx program));

    it() a tt(D), indicating that the source must also be installed by
        default, i.e., if neither `program' or `library' was specified as
        second argument;

    it() a tt(b), indicating that the file must em(not) be installed if the
        tt(-b) (basic installation) option was specified when calling
        tt(icmstart);

    it() Following the optional tt( P, L, D,) or tt(b) character a space
        delimited optional tt(?) may be specified. If specified the
        installation of the file or directory must be confirmed by the user.
    )

manpagesection(SOURCE-DESTINATION SPECIFICATIONS)

    The following source-destination specifications can be used in an
tt(icmstart.rc) file (using tt(skeletons) below to refer to tt(icmstart's)
skeleton files directory):
    itemization(
    it() tt(source)nl() 
       a file named tt(source) must exist in tt(skeletons). It is installed in
        the destination directory tt(`dest') that's specified when calling
        bf(icmstart)(1). Example: 
 verb(
    CLASSES     
 )
       tt(skeletons/CLASSES) is installed as tt(dest/CLASSES);

    it() tt(pathspec)nl()
       if `pathspec' does not begin with a slash it must exist in
        tt(skeletons).  It is installed as `pathspec' in the destination
        directory specified when calling bf(icmstart)(1). Example:
 verb(
    dir/file
 )
       tt(skeletons/file) is installed as tt(dest/dir/file);

    it() tt(/pathspec) or tt(~/pathspec)nl()
       the tt(~)-character is expanded to the user's home directory. The
        pathspec's final element is installed in the destination directory
        specified when calling bf(icmstart)(1). Example:
 verb(
    ~/.icmake/file
 )
       tt($HOME/.icmake/file) is installed as tt(dest/file)
    )

    When the above source specifications are followed by a destination
specification tt(destspec) (a file or non-absolute directory specification)
then the source specification is installed as tt(dest/destspec) below the
destination directory specified when calling bf(icmstart)(1). Examples:
        verb(
    CLASSES CLASSES             # skeletons/CLASSES is installed as 
                                #   dest/CLASSES
    dir/file dir/file           # skeletons/dir/file is installed as
                                #   dest/dir/file
    ~/.icmake/file .icmake/file # $HOME/.icmake/file is installed as 
                                #   dest/.icmake/file
        )
    Icmstart converts destination specifications to absolute paths. If these
absolute paths do not begin with tt(dest's) absolute path then an error
message is displayed and bf(icmstart) ends.

manpagesection(FINE-TUNING ICMCONF)

The default tt(icmconf) file contains tt(#defines) which are used when a
project uses a parser (by default generated by bf(bisonc++)(1)) and/or a
scanner (by default generated by bf(flexc++)(1)). All those tt(#defines) are
commented out in the default tt(icmconf) file. They are:
 verb(
    #define PARSER_DIR          ""
    #define PARSGEN             "bisonc++"
    #define PARSFLAGS           "-V"
    #define PARSSPEC            "grammar"
    #define PARSFILES           ""
    #define PARSOUT             "parse.cc"
    
    #define SCANNER_DIR         ""  
    #define SCANGEN             "flexc++"
    #define SCANFLAGS           ""
    #define SCANSPEC            "lexer"
    #define SCANFILES            ""
    #define SCANOUT             "lex.cc"
 )

However, the tt(icmstart.rc) file can be modified so that these tt(#defines)
are omitted from the project's tt(icmconf) file unless a parser and/or scanner
is actually used by the project. For this:
    itemization(
    it() copy the files in tt(/usr/share/icmake) to tt(~/.icmake);

    it() if the program uses a parser then define the file
        tt(~/.icmake/parser/icmconf) containing 
 verb(
    #define PARSER_DIR          "parser"
    #define PARSGEN             "bisonc++"
    #define PARSFLAGS           "-V"
    #define PARSSPEC            "grammar"
    #define PARSFILES           ""
    #define PARSOUT             "parse.cc"
 )
       (here `tt(parser)' is the name of the directory containing the parser's
        implementation; optionally another directory name can be
        specified); nl()
        Remove the parser-defines from tt(~/.icmake/icmconf);nl()
        In tt(~/.icmake/icmconf/icmstart.rc) replace the parser-directory
        specification, like
 verb(
    ? parser    parser
 )
       by
 verb(
    ? ~/.icmake/parser    parser
 )

    it() if the program uses a scanner then define the file
        tt(~/.icmake/scanner/icmconf) containing 
 verb(
    #define SCANNER_DIR         "scanner"  
    #define SCANGEN             "flexc++"
    #define SCANFLAGS           ""
    #define SCANSPEC            "lexer"
    #define SCANFILES            ""
    #define SCANOUT             "lex.cc"
 )
       (here `tt(scanner)' is the name of the directory containing the
        scanner's implementation; optionally another directory name can be
        specified);n()
       Remove the scanner-defines from tt(~/.icmake/icmconf);nl()
       In tt(~/.icmake/icmconf/icmstart.rc) replace the scanner-directory
        specification, like
 verb(
    ? scanner    scanner
 )
       by
 verb(
    ? ~/.icmake/scanner    scanner
 )
    )

    In general: tt(icmconf #defines) can be redefined by removing them from
tt(~/.icmake/icmconf), specifying their redefinitions in tt(icmconf) files in
subdirectories of tt(~/.icmake/icmconf).

manpagefiles()
    The mentioned paths are sugestive only and may be installation dependent:
    itemization(
    it() bf(/usr/share/icmake/icmconf):
        example of an bf(icmbuild) configuration file;
    it() bf(/usr/share/icmake/CLASSES):
        example of an bf(icmbuild) tt(CLASSES) file;
    it() bf(/usr/share/icmake/icmstart.rc):
        default skeleton resource file.
    )

manpageseealso()
    bf(bisonc++)(1), bf(flexc++)(1), bf(icmake)(1), bf(icmbuild)(1),
    bf(icmconf)(7), bf(icmstart)(1) 

manpagebugs()
    None reported

includefile(trailer.inc)





