-
Notifications
You must be signed in to change notification settings - Fork 4
/
deheader.1
114 lines (114 loc) · 6.23 KB
/
deheader.1
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
'\" t
.\" Title: deheader
.\" Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL Stylesheets v1.76.1 <http://docbook.sf.net/>
.\" Date: 01/22/2013
.\" Manual: Development Tools
.\" Source: deheader
.\" Language: English
.\"
.TH "DEHEADER" "1" "01/22/2013" "deheader" "Development Tools"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
deheader \- report which includes in C or C++ compiles can be removed
.SH "SYNOPSIS"
.HP \w'\fBdeheader\fR\ 'u
\fBdeheader\fR [\-h] [\-m\ \fIcommand\fR] [\-i\ \fIpattern\fR] [\-r] [\-v] [\-x\ \fIpattern\fR] [\-V] [\fIfile\-or\-dir\fR]
.SH "DESCRIPTION"
.PP
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 \*(Aqrm foo\&.o; make foo\&.o\*(Aq returns a zero status (but the build command may be overridden)\&. Optionally, with the
\fB\-r\fR
switch, the unneeded headers are removed from the sourcefiles\&.
.PP
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\&.
.PP
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
\fBsplint\fR(1), are scanned normally\&.
.PP
The tool will also emit warnings about duplicate inclusions, and inclusions required for portability but not present\&.
.PP
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
\fB\-m "make CFLAGS=\*(Aq\-Werror \-Wfatal\-errors\*(Aq" \fR
may do the right thing; you can check this by running with \-v \-v \-v to see what compilation commands are actually emitted\&.
.PP
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
\fB\-r\fR
option was given and headers removed\&.
.PP
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\&.
.PP
The last line of the output will be a statistical summary\&.
.PP
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\&.
.SH "OPTIONS"
.PP
\-h
.RS 4
Display some help and exit\&.
.RE
.PP
\-m
.RS 4
Set the build command used for test compiles\&. Defaults to \*(Aqmake\*(Aq\&.
.RE
.PP
\-i
.RS 4
Set a pattern for includes to be ignored\&. Takes a Python regular expression\&.
.RE
.PP
\-r
.RS 4
Remove header inclusions from sourcefiles where they are not required\&.
.RE
.PP
\-v
.RS 4
Set verbosity\&.
.RE
.PP
\-x
.RS 4
Exclude files with names matching the specified Python regexp\&.
.RE
.PP
\-V
.RS 4
Show version of program and exit\&.
.RE
.SH "BUGS"
.PP
Test\-compiling after running with
\fB\-r\fR
will sometimes show that this tool removed some headers that are actually required for your build\&. This happens because
\fBdeheader\fR
doesn\*(Aqt 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\&.
.PP
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\&.
\fBdeheader\fR
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\&.
.PP
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\&.
.SH "AUTHOR"
.PP
Eric S\&. Raymond
esr@snark\&.thyrsus\&.com; (home page at
\m[blue]\fBhttp://www\&.catb\&.org/~esr/\fR\m[])\&.