.TH "icmstart" "1" "1992\-2018" "icmake\&.9\&.02\&.07\&.tar\&.gz" "starts icmbuild program maintenance"

.PP 
.SH "NAME"
icmstart \- A startup script for icmbuild program maintenance
.PP 
.SH "SYNOPSIS"
\fBicmstart\fP \fI[Options]\fP top\-dir [program|library]
.PP 
.SH "DESCRIPTION"

.PP 
Although \fIicmake\fP\-scripts can be written from scratch for handling program
maintenance, often the required actions are highly comparable\&. This
observation resulted in the construction of two \fIicmake\fP\-tools:
\fBicmstart\fP(1), initializing a directory for program development and
\fBicmbuild\fP(1), handling the actual program maintenance\&. Both come predefined
with \fIicmake\(cq\&s\fP distribution, to initialize and maintain \fBC++\fP programs
(or, after minimal adaptation, \fBC\fP) programs)\&. They can also easily be
tailored to other programming languages\&. The \fIicmstart\fP script and
\fIicmbuild\fP program can directly be called: \fIicmstart\fP is an \fIicmake\fP
script, for which the command\-shell calls \fIicmake\fP; \fIicmbuild\fP is a small
\fBC\fP program that calls \fIicmake\fP to process the \fIicmbuild\fP script in
(commonly) \fI/usr/lib/icmake\fP\&.  
.PP 
This man\-page covers the \fBicmstart\fP script; refer to the \fBicmbuild\fP(1)
man\-page for information about how \fIicmbuild\fP can be used\&.
.PP 
The \fBicmstart\fP script is a generic script that can be used to initialize a
directory with a basic set of files that are commonly used when developing a
\fBC++\fP or \fBC\fP program\&. 
.PP 
\fBIcmstart\fP creates an initial directory (here named `\fItop\-dir\fP\(cq\&) and
installs the files \fICLASSES, VERSION\fP and \fIicmconf\fP below \fItop\-dir\fP\&. A
second argument `\fIprogram\fP\(cq\& or `\fIlibrary\fP\(cq\& may be specified as the default
mode of operation of the \fBicmbuild\fP(1) script, usually resulting in the
addition of additional skeleton source files\&. If the predefined set of files
doesn\(cq\&t fit your needs, then the default set can easily be tailored to your
needs\&. The default set of skeleton files is listed in the file
\fI/etc/icmake/icmstart\&.rc\fP\&. Refer to the \fBicmstart\&.rc\fP(7) man\-page for
information about how this file is structured and how it can be adapted\&.
.PP 
After changing to the directory created by \fBicmstart\fP \fBicmbuild\fP(1)
may be used for program maintenance\&.
.PP 
.SH "OPTIONS"

.PP 
\fIIcmstart\fP supports the following options, which (when specified)
must be \fIicmstart\(cq\&s\fP first arguments:
.IP o 
\fI\-b\fP
.br 
Basic installation: the files VERSION, usage\&.cc and version\&.cc are not
installed, and the #define USE_VERSION entry in icmconf is commented
out\&.
.IP o 
\fI\-c confpath\fP
.br 
Use the configuration files (\fIicmstart\&.rc, AUTHOR,
YEARS\fP and \fIVERSION\fP) if found in `confpath\(cq\& rather than in
\fI~/\&.icmake\fP and/or \fI/etc/icmake/\fP\&. Once a file is found it is used
allowing partial overrides of the default files provided by
\fBicmake\fP(1)\&.
.IP o 
\fI\-d\fP
.br 
Do not execute any commands, but show the commands that would have been
executed on the standard output\&.
.IP o 
\fI\-I\fP
.br 
Do not install files\&. 
.IP o 
\fI\-r\fP 
Unconditionally replace existing files\&. If \fI\-r\fP is not provided
\fBicmstart\fP will ask the user to confirm that an existing file must
be overwritten\&. If a skeleton specification refers to a directory, the
full directory and its subdirectories will be replaced\&.
.IP o 
\fI\-s skeleton\-path\fP 
.br 
By default skeleton files are listed in the skeleton resource file
\fI/usr/share/icmake/icmstart\&.rc\fP\&. Alternatively, the skeleton
resource file may be specified by the \fIICM\fP environment variable,
which \-in turn\- may be overruled by the path specified with the \fI\-s\fP
option\&. The skeleton path may be specified as a full file\-path or as a
directory, in which case the skeleton resource file is assumed to be
\fIicmstart\&.rc\fP (see below at \fBSKELETON FILES\fP)\&.
Since \fBicmstart\fP uses \fIcp\fP to install files, \fIcp\fP must be
available when \fBicmstart\fP should install skeleton files\&.
.PP 
.SH "SKELETON FILES"

.PP 
Skeleton resource files may contain comment (empty lines and lines beginning
with the hash\-mark (\fI#\fP)) which is ignored, and should otherwise contain
specifications of resource \fBs\fP to install\&.
.PP 
The default resource specification file is \fI/etc/icmake/icmstart\&.rc\fP,
containing:
.nf 

    CLASSES
    icmconf
    P main\&.cc 
    P main\&.ih 
    P usage\&.cc
    P version\&.cc
    P ? scanner 
    P ? parser  
        
.fi 
This file is overruled by \fI~/\&.icmake/icmstart\&.rc\fP\&. The \fI~/\&.icmake\fP
directory (called `configuration directory\(cq\& below) can be prepared using the
following system command:
.nf 

    cp \-r /etc/icmake ~/\&.icmake
        
.fi 
This directory can be provided with skeleton files\&. Default skeleton files
are commonly found in \fI/usr/share/icmake\fP, and could be copied to the
configuration directory and referred to by the configuration directory\(cq\&s file
\fIicmstart\&.rc\fP\&.  See \fBicmstart\&.rc\fP(7) for details about how skeleton files
can be referred to \fIicmstart\&.rc\fP\&.
.PP 
.SH "CONFIGURATION FILES"

.PP 
The configuration directory\(cq\&s files \fIicmstart\&.rc, AUTHOR, YEARS\fP and
\fIVERSION\fP are recognized as skeleton files and are, if available, processed
by \fIicmstart\fP\&.
.PP 
If the \fI\-c\fP option was specified configuration files found in the path
specified at this option are used\&. If not specified or if a file isn\(cq\&t
found then the path \fI~/icmake\fP is inspected\&. If a configuration file isn\(cq\&t
found in \fI~/icmake\fP either, configuration files in \fI/etc/icmake\fP are used\&.
.PP 
Configuration files are optional; if absent  \fIicmstart\fP can still be used,
but in normal cases at least \fIicmstart\&.rc\fP is provided\&.
.PP 
In addition to \fIicstart\&.rc\fP consider defining the files \fIAUTHOR, VERSION,\fP
and \fIYEARS\fP in the configuration directory:
.IP o 
If the file \fIAUTHOR\fP exists it should have one line, defining the
author of the program\&. E\&.g\&.,
.nf 

    #define AUTHOR \(dq\&Frank B\&. Brokken <f\&.b\&.brokken@rug\&.nl>\(dq\&
        
.fi 
If it does not exist \fIicmstart\fP uses the default \fI#define AUTHOR \(dq\&\(dq\&\fP\&. 
.IP 
.IP o 
If the file \fIVERSION\fP exists it should have one line, defining the
program\(cq\&s version\&. E\&.g\&.,
.nf 

    #define VERSION \(dq\&1\&.00\&.00\(dq\&
        
.fi 
If it does not exist \fIicmstart\fP uses the default 
\fI#define VERSION \(dq\&0\&.00\&.00\(dq\&\fP\&.
.IP 
.IP o 
If the file \fIYEARS\fP exists it should have one line, defining the
program\(cq\&s initial release year or range of release years\&. E\&.g\&.,
.nf 

    #define YEARS \(dq\&2016\(dq\&
        
.fi 
or a range of years can be defined:
.nf 

    #define YEARS \(dq\&1992\-2016\(dq\&
        
.fi 
If it does not exist \fIicmstart\fP uses the default 
\fI#define YEARS \(dq\&yyyy\(dq\&\fP where \fIyyyy\fP is the current year\&.

.PP 
The \fIAUTHOR, VERSION,\fP and \fIYEARS\fP definitions are concatenated to one
file, called \fIVERSION\fP, which is installed in the top\-level directory\&.
.PP 
If the file \fIicmstart\&.rc\fP does not exist (or is empty) \fIicmstart\fP
merely installs the top\-level directory, \fIicmconf\fP and \fIVERSION\fP\&.
.PP 
.SH "FILES"
The mentioned paths are sugestive only and may be installation dependent:
.IP o 
\fB/usr/share/icmake/icmconf\fP
Example of a \fBicmbuild\fP configuration file;
.IP o 
\fB/usr/share/icmake/CLASSES\fP
Example of a \fBicmbuild\fP \fICLASSES\fP file\&.
.IP o 
\fB/etc/icmake/icmstart\&.rc\fP
Default skeleton resource file\&.

.PP 
.SH "SEE ALSO"
\fBicmake\fP(1), \fBicmbuild\fP(1), \fBicmconf\fP(7), \fBicmstart\&.rc\fP(7)\&.
.PP 
.SH "BUGS"
Path names containing blanks are not supported\&.
.PP 
.SH "COPYRIGHT"
This is free software, distributed under the terms of the 
GNU General Public License (GPL)\&.
.PP 
.SH "AUTHOR"
Frank B\&. Brokken (\fBf\&.b\&.brokken@rug\&.nl\fP)\&.
.PP