.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "SHTOOL-SCPP.TMP 1"
.TH SHTOOL-SCPP.TMP 1 "shtool 2.0.8" "18-Jul-2008" "GNU Portable Shell Tool"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
shtool\-scpp \- GNU shtool C source file pre\-processor
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
\&\fBshtool scpp\fR
[\fB\-v\fR|\fB\-\-verbose\fR]
[\fB\-p\fR|\fB\-\-preserve\fR]
[\fB\-f\fR|\fB\-\-filter\fR \fIfilter\fR]
[\fB\-o\fR|\fB\-\-output\fR \fIofile\fR]
[\fB\-t\fR|\fB\-\-template\fR \fItfile\fR]
[\fB\-M\fR|\fB\-\-mark\fR \fImark\fR]
[\fB\-D\fR|\fB\-\-define\fR \fIdname\fR]
[\fB\-C\fR|\fB\-\-class\fR \fIcname\fR]
\&\fIfile\fR [\fIfile\fR ...]
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This command is an additional \s-1ANSI C\s0 source file pre-processor for sharing
\&\fBcpp\fR\|(1) code segments, internal variables and internal functions. The intention
for this comes from writing libraries in \s-1ANSI C.\s0 Here a common shared internal
header file is usually used for sharing information between the library
source files.
.PP
The operation is to parse special constructs in \fIfile\fRs, generate a few
things out of these constructs and insert them at position \fImark\fR in \fItfile\fR
by writing the output to \fIofile\fR. Additionally the \fIfile\fRs are never touched
or modified. Instead the constructs are removed later by the \fBcpp\fR\|(1) phase of
the build process. The only prerequisite is that every \fIfile\fR has a
``\f(CW\*(C`#include "\*(C'\fR\fIofile\fR\f(CW\*(C`"\*(C'\fR'' at the top.
.PP
This command provides the following features: First it avoids namespace
pollution and reduces prototyping efforts for internal symbols by recognizing
functions and variables which are defined with the storage class identifier
``\fIcname\fR''.  For instance if \fIcname\fR is ``intern'', a function ``\f(CW\*(C`intern
void *foobar(int quux)\*(C'\fR'' in one of the \fIfile\fRs is translated into both a
``\f(CW\*(C`#define foobar _\|_foobar\*(C'\fR'' and a ``\f(CW\*(C`extern void *foobar(int quux);\*(C'\fR'' in
\&\fIofile\fR. Additionally a global ``\f(CW\*(C`#define\*(C'\fR \fIcname\fR \f(CW\*(C`/**/\*(C'\fR'' is also
created in \fIofile\fR to let the compiler silently ignore this additional
storage class identifier.
.PP
Second, the library source files usually want to share \f(CW\*(C`typedef\*(C'\fRs,
\&\f(CW\*(C`#define\*(C'\fRs, etc.  over the source file boundaries. To achieve this one can
either place this stuff manually into \fItfile\fR or use the second feature of
\&\fBscpp\fR: All code in \fIfile\fRs encapsulated with ``\f(CW\*(C`#if \*(C'\fR\fIdname\fR ...
\&\f(CW\*(C`#endif\*(C'\fR'' is automatically copied to \fIofile\fR. Additionally a global
``\f(CW\*(C`#define\*(C'\fR \fIdname\fR \f(CW0\fR'' is also created in \fIofile\fR to let the compiler
silently skip this parts (because it was already found in the header).
.SH "OPTIONS"
.IX Header "OPTIONS"
The following command line options are available.
.IP "\fB\-v\fR, \fB\-\-verbose\fR" 4
.IX Item "-v, --verbose"
Display some processing information.
.IP "\fB\-p\fR, \fB\-\-preserve\fR" 4
.IX Item "-p, --preserve"
Preserves \fIofile\fR independent of the generated ``#line'' lines. This is
useful for Makefiles if the real contents of \fIofile\fR will not change,
just line numbers. Default is to overwrite.
.IP "\fB\-f\fR, \fB\-\-filter\fR \fIfilter\fR" 4
.IX Item "-f, --filter filter"
Apply one or more pre-processing \fBsed\fR\|(1) \fIfilter\fR commands (usually of
type ``\f(CW\*(C`s/.../.../\*(C'\fR'') to each input file before their input is parsed.
This option can occur multiple times.
.IP "\fB\-o\fR, \fB\-\-output\fR \fIofile\fR" 4
.IX Item "-o, --output ofile"
Output file name. Default is \f(CW\*(C`lib.h\*(C'\fR.
.IP "\fB\-t\fR, \fB\-\-template\fR \fItfile\fR" 4
.IX Item "-t, --template tfile"
Template file name. Default is \f(CW\*(C`lib.h.in\*(C'\fR.
.IP "\fB\-M\fR, \fB\-\-mark\fR \fImark\fR" 4
.IX Item "-M, --mark mark"
Mark to be replaced by generated constructs. Default is \f(CW\*(C`%%MARK%%\*(C'\fR.
.IP "\fB\-D\fR, \fB\-\-define\fR \fIdname\fR" 4
.IX Item "-D, --define dname"
\&\s-1FIXME.\s0 Default is \f(CW\*(C`cpp\*(C'\fR.
.IP "\fB\-C\fR, \fB\-\-class\fR \fIcname\fR" 4
.IX Item "-C, --class cname"
\&\s-1FIXME.\s0 Default is \f(CW\*(C`intern\*(C'\fR.
.SH "EXAMPLE"
.IX Header "EXAMPLE"
.Vb 5
\& #   Makefile
\& SRCS=foo_bar.c foo_quux.c
\& foo_p.h: foo_p.h.in
\&      shtool scpp \-o foo_p.h \-t foo_p.h.in \e
\&                  \-M %%MARK%% \-D cpp \-C intern $(SRCS)
\&
\& /* foo_p.h.in */
\& #ifndef FOO_P_H
\& #define FOO_P_H
\& %%MARK%%
\& #endif /* FOO_P_H */
\&
\& /* foo_bar.c */
\& #include "foo_p.h"
\& #if cpp
\& #define OURS_INIT 4711
\& #endif
\& intern int ours;
\& static int myone = 0815;
\& intern int bar(void)
\& {
\&     ours += myone;
\& }
\&
\& /* foo_quux.c */
\& #include "foo_p.h"
\& int main(int argc, char *argv[])
\& {
\&     int i;
\&     ours = OURS_INIT
\&     for (i = 0; i < 10; i++) {
\&         bar();
\&         printf("ours now %d\en", ours);
\&     }
\&     return 0;
\& }
.Ve
.SH "HISTORY"
.IX Header "HISTORY"
The \fB\s-1GNU\s0 shtool\fR \fBscpp\fR command was originally written by Ralf S.
Engelschall <rse@engelschall.com> in 1999 for \fB\s-1GNU\s0 shtool\fR.
Its was prompted by the need to have a pre-processing facility
in the \fB\s-1GNU\s0 pth\fR project.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBshtool\fR\|(1), \fBcpp\fR\|(1).