1SHTOOL-SCPP.TMP(1)          GNU Portable Shell Tool         SHTOOL-SCPP.TMP(1)
2
3
4

NAME

6       shtool scpp - GNU shtool C source file pre-processor
7

SYNOPSIS

9       shtool scpp [-v|--verbose] [-p|--preserve] [-f|--filter filter]
10       [-o|--output ofile] [-t|--template tfile] [-M|--mark mark] [-D|--define
11       dname] [-C|--class cname] file [file ...]
12

DESCRIPTION

14       This command is an additional ANSI C source file pre-processor for
15       sharing cpp(1) code segments, internal variables and internal
16       functions. The intention for this comes from writing libraries in ANSI
17       C. Here a common shared internal header file is usually used for
18       sharing information between the library source files.
19
20       The operation is to parse special constructs in files, generate a few
21       things out of these constructs and insert them at position mark in
22       tfile by writing the output to ofile. Additionally the files are never
23       touched or modified. Instead the constructs are removed later by the
24       cpp(1) phase of the build process. The only prerequisite is that every
25       file has a ``"#include ""ofile"""'' at the top.
26
27       This command provides the following features: First it avoids namespace
28       pollution and reduces prototyping efforts for internal symbols by
29       recognizing functions and variables which are defined with the storage
30       class identifier ``cname''.  For instance if cname is ``intern'', a
31       function ``"intern void *foobar(int quux)"'' in one of the files is
32       translated into both a ``"#define foobar __foobar"'' and a ``"extern
33       void *foobar(int quux);"'' in ofile. Additionally a global ``"#define"
34       cname "/**/"'' is also created in ofile to let the compiler silently
35       ignore this additional storage class identifier.
36
37       Second, the library source files usually want to share "typedef"s,
38       "#define"s, etc.  over the source file boundaries. To achieve this one
39       can either place this stuff manually into tfile or use the second
40       feature of scpp: All code in files encapsulated with ``"#if "dname ...
41       "#endif"'' is automatically copied to ofile. Additionally a global
42       ``"#define" dname 0'' is also created in ofile to let the compiler
43       silently skip this parts (because it was already found in the header).
44

OPTIONS

46       The following command line options are available.
47
48       -v, --verbose
49           Display some processing information.
50
51       -p, --preserve
52           Preserves ofile independent of the generated ``#line'' lines. This
53           is useful for Makefiles if the real contents of ofile will not
54           change, just line numbers. Default is to overwrite.
55
56       -f, --filter filter
57           Apply one or more pre-processing sed(1) filter commands (usually of
58           type ``"s/.../.../"'') to each input file before their input is
59           parsed.  This option can occur multiple times.
60
61       -o, --output ofile
62           Output file name. Default is "lib.h".
63
64       -t, --template tfile
65           Template file name. Default is "lib.h.in".
66
67       -M, --mark mark
68           Mark to be replaced by generated constructs. Default is "%%MARK%%".
69
70       -D, --define dname
71           FIXME. Default is "cpp".
72
73       -C, --class cname
74           FIXME. Default is "intern".
75

EXAMPLE

77        #   Makefile
78        SRCS=foo_bar.c foo_quux.c
79        foo_p.h: foo_p.h.in
80             shtool scpp -o foo_p.h -t foo_p.h.in \
81                         -M %%MARK%% -D cpp -C intern $(SRCS)
82
83        /* foo_p.h.in */
84        #ifndef FOO_P_H
85        #define FOO_P_H
86        %%MARK%%
87        #endif /* FOO_P_H */
88
89        /* foo_bar.c */
90        #include "foo_p.h"
91        #if cpp
92        #define OURS_INIT 4711
93        #endif
94        intern int ours;
95        static int myone = 0815;
96        intern int bar(void)
97        {
98            ours += myone;
99        }
100
101        /* foo_quux.c */
102        #include "foo_p.h"
103        int main(int argc, char *argv[])
104        {
105            int i;
106            ours = OURS_INIT
107            for (i = 0; i < 10; i++) {
108                bar();
109                printf("ours now %d\n", ours);
110            }
111            return 0;
112        }
113

HISTORY

115       The GNU shtool scpp command was originally written by Ralf S.
116       Engelschall <rse@engelschall.com> in 1999 for GNU shtool.  Its was
117       prompted by the need to have a pre-processing facility in the GNU pth
118       project.
119

SEE ALSO

121       shtool(1), cpp(1).
122
123
124
12518-Jul-2008                      shtool 2.0.8               SHTOOL-SCPP.TMP(1)
Impressum