-
Notifications
You must be signed in to change notification settings - Fork 4
/
deheader.xml
172 lines (153 loc) · 6.75 KB
/
deheader.xml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE refentry PUBLIC
"-//OASIS//DTD DocBook XML V4.1.2//EN"
"docbook/docbookx.dtd">
<refentry id='deheader.1'>
<refmeta>
<refentrytitle>deheader</refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo class='date'>Dec 01 2010</refmiscinfo>
<refmiscinfo class='productname'>deheader</refmiscinfo>
<refmiscinfo class='source'>deheader</refmiscinfo>
<refmiscinfo class='manual'>Development Tools</refmiscinfo>
</refmeta>
<refnamediv id='name'>
<refname>deheader</refname>
<refpurpose>report which includes in C or C++ compiles can be removed</refpurpose>
</refnamediv>
<refsynopsisdiv id='synopsis'>
<cmdsynopsis>
<command>deheader</command>
<arg choice='opt'>-h </arg>
<arg choice='opt'>-m <replaceable>command</replaceable></arg>
<arg choice='opt'>-i <replaceable>pattern</replaceable></arg>
<arg choice='opt'>-r </arg>
<arg choice='opt'>-v </arg>
<arg choice='opt'>-x <replaceable>pattern</replaceable></arg>
<arg choice='opt'>-V </arg>
<arg choice='opt'><replaceable>file-or-dir</replaceable></arg>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1 id='description'><title>DESCRIPTION</title>
<para>This tool takes a list of C or C++ sourcefiles and generates a
report on which #includes can be omitted from them; also, what
standard inclusions may be required for portability. The test, for
each foo.c or foo.cc or foo.cpp, is simply whether 'rm foo.o; make
foo.o' returns a zero status (but the build command may be
overridden). Optionally, with the <option>-r</option> switch, the
unneeded headers are removed from the sourcefiles.</para>
<para>If a sourcefile argument is a directory, the report is generated
on all source files beneath it. Subdirectories beginning with a dot
are assumed to be repository directories for version-control systems
and ignored. If no arguments are given, the program runs as if the
name of the current directory had been passed to it.</para>
<para>Inclusions within the scope of #if/#ifdef/#else/#endif
directives are left alone, because trying to reason about potential
combinations of -D and U options would be too complicated and prone to
weird errors. One exception: headers protected only by S_SPLINT_S, the
conditional for blocking scanning by the static analysis tool
<citerefentry><refentrytitle>splint</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
are scanned normally.</para>
<para>The tool will also emit warnings about duplicate inclusions, and
inclusions required for portability but not present.</para>
<para>It is recommended that you arrange to compile with options that
will stop the compiler on warnings when using this tool; otherwise it
will be report headers that only declare prototypes and return types
(and thus throw only warnings) as being not required. Under gcc the
compiler options to accomplish this are -Werror -Wfatal-errors. If
your makefile follows normal conventions, running with <command>-m
"make CFLAGS='-Werror -Wfatal-errors'" </command> may do the right thing; you
can check this by running with -v -v -v to see what compilation
commands are actually emitted.</para>
<para>On each test compile, the original sourcefile is moved to a name
with an .orig suffix and restored on interrupt or after processing
with its original timestamp, unless the <option>-r</option> option was
given and headers removed.</para>
<para>At verbosity level 0, only messages indicating removable headers
are issued. At verbosity 1, test compilations are timed and progess
indicated with a twirling-baton prompt. At verbosity level 2, you get
vebose progress messages on the analysis. At verbosity level 3, you
see the output from the make and compilation commands.</para>
<para>The last line of the output will be a statistical summary.</para>
<para>Running deheader will leave a lot of binaries in your directory that
were compiled in ways possibly not invoked by your normal build process.
Running "make clean" afterwards is strongly recommended.</para>
</refsect1>
<refsect1 id='options'><title>OPTIONS</title>
<variablelist>
<varlistentry>
<term>-h</term>
<listitem>
<para>Display some help and exit.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-m</term>
<listitem>
<para>Set the build command used for test compiles. Defaults to 'make'.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-i</term>
<listitem>
<para>Set a pattern for includes to be ignored.
Takes a Python regular expression.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-r</term>
<listitem>
<para>Remove header inclusions from sourcefiles where they are not required.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-v</term>
<listitem>
<para>Set verbosity.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-x</term>
<listitem>
<para>Exclude files with names matching the specified Python regexp.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-V</term>
<listitem>
<para>Show version of program and exit.</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 id='bugs'><title>BUGS</title>
<para>Test-compiling after running with <option>-r</option> will
sometimes show that this tool removed some headers that are actually
required for your build. This happens because
<command>deheader</command> doesn't know about all the strange things
your build system gets up to, and the problem of analyzing it to
understand them would be Turing-complete. Simply revert the altered
files and continue.</para>
<para>Due to minor variations in system headers, it is possible your
program may not port correctly to other Unix variants after being
deheadered. This is normally not a problem with the portion of the API
specified by POSIX and ANSI C, but may be for headers that are not
stndardized or only weakly standardized. The sockets API
(sys/select.h, sys/sockets.h, and friends such as sys/types.h and
sys.stat.h) is perhaps the most serious trouble
spot. <command>deheader</command> has an internal table of rules that
heads off the most common problems by suppressing deletion of headers
that are required for portability, but your mileage may vary.</para>
<para>Sufficiently perverse C++ can silently invalidate the simple
algorithm this tool uses. Example: if an overloaded function has
different overloads from two different files, removing one may expose
the other, changing runtime semantics without a compile-time warning.
Similarly, removing a later file containing a template specialization
may lead to undefined behavior from a template defined in an earlier
file. Use this with caution near such features, and test carefully.</para>
</refsect1>
<refsect1 id='author'><title>AUTHOR</title>
<para>Eric S. Raymond <email>[email protected]</email>; (home page at <ulink
url='http://www.catb.org/~esr/'>http://www.catb.org/~esr/</ulink>).</para>
</refsect1>
</refentry>