Commit 09b5d726 authored by Reiner Herrmann's avatar Reiner Herrmann

Imported Upstream version 1.1

parent 471c3291
BSD LICENSE
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.
Neither name of the this project nor the names of its contributors
may be used to endorse or promote products derived from this software
without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR
CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
#
# makefile for `deheader'
#
VERS=$(shell sed <deheader -n -e '/version\s*=\s*"\(.*\)"/s//\1/p')
SOURCES = README COPYING NEWS deheader deheader.xml deheader.1 Makefile control deheader-logo.png
all: deheader.1
deheader.1: deheader.xml
xmlto man deheader.xml
deheader.html: deheader.xml
xmlto html-nochunks deheader.xml
clean:
rm -f *~ *.1 *.html test/*.o test/*~ MANIFEST
check: regress
regress:
cd test; make --quiet regress
makeregress:
cd test; make --quiet makeregress
PYLINTOPTS = --rcfile=/dev/null --reports=n \
--msg-template="{path}:{line}: [{msg_id}({symbol}), {obj}] {msg}" \
--dummy-variables-rgx='^_'
SUPPRESSIONS = --disable="C0103,C0111,C0301,C0302,C0323,C1001,R0903,R0912,R0913,R0914,R0915,W0110,W0141,W0611,W0621"
pylint:
@pylint $(PYLINTOPTS) $(SUPPRESSIONS) deheader
version:
@echo $(VERS)
deheader-$(VERS).tar.gz: $(SOURCES)
@ls $(SOURCES) | sed s:^:deheader-$(VERS)/: >MANIFEST
@(cd ..; ln -s deheader deheader-$(VERS))
(cd ..; tar -czf deheader/deheader-$(VERS).tar.gz `cat deheader/MANIFEST`)
@ls -l deheader-$(VERS).tar.gz
@(cd ..; rm deheader-$(VERS))
dist: deheader-$(VERS).tar.gz
release: deheader-$(VERS).tar.gz deheader.html
shipper version=$(VERS) | sh -e -x
deheader project news
1.1 @ 2015-01-26
Allow --version on the command line. Fix up the regression tests.
1.0 @ 2014-06-03
Added --quiet option.
0.8 @ 2013-09-14
Minor documentation fixes.
0.7 @ 2013-01-22
Accept .cc as an extension as well as .cpp.
0.6 @ 2011-02-10
Add the return-status macros from sys/wait.h to the portability list.
0.5 @ 2010-12-22
Source is now checked against all SuS portability requirements.
There is an option to exclude files by pattern.
0.4 @ 2010-12-20
Script now removes generated objects.
Duplicate inclusions are now detected.
Absence of some headers required for portability is now detected.
0.3 @ 2010-12-09
Add a dependencies table to head off common cross-platform problems.
0.2 @ 2010-12-02
Make the last line of output a statistical summary.
Document some limitations.
0.1 @ 2010-12-01
Initial release.
deheader
deheader analyzes C and C++ files to determine which header enclusions can be
removed while still allowing them to compile. This may result in substantial
improvements in compilation time, especially on large C++ projects; it also
sometimes exposes dependencies and cohesions of which developers were unaware.
Eric S. Raymond
December 2010
# This is not a real Debian control file
# It's project metadata for the shipper tool
Package: deheader
Description: find (optionally remove) unneeded includes in C or C++ sourcefiles.
deheader analyzes C and C++ files to determine which header inclusions can be
removed while still allowing them to compile. This may result in substantial
improvements in compilation time, especially on large C++ projects; it also
sometimes exposes dependencies and cohesions of which developers were unaware.
XBS-Destinations: freecode
Homepage: http://www.catb.org/~esr/deheader
XBS-HTML-Target: index.html
Gitorious-URL: https://gitorious.org/deheader
OpenHub-URL: https://www.ohloh.net/p/deheader/
XBS-Logo: deheader-logo.png
XBS-Freecode-Tags: development tools, optimization, C, C++
XBS-VC-Tag-Template: %(version)s
XBS-Validate: make check
This diff is collapsed.
'\" t
.\" Title: deheader
.\" Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL Stylesheets v1.78.1 <http://docbook.sf.net/>
.\" Date: 01/26/2015
.\" Manual: Development Tools
.\" Source: deheader
.\" Language: English
.\"
.TH "DEHEADER" "1" "01/26/2015" "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] [\-q] [\-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)\&.
.PP
Optionally, with the
\fB\-r\fR
switch, the unneeded headers are removed from the sourcefiles\&. Don\*(Aqt use this option unless you have your sourcefiles safely under version control and can revert!
.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 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 verbose progress messages on the analysis\&. At verbosity level 3, you see the output from the make and compilation commands\&.
.PP
If the \-q (\-\-quiet) option flag was not set, 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 (or the equivalent under whatever build system you are using) 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
\-q
.RS 4
Suppress statistical summary\&.
.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
Very rarely, test\-compiling after running with
\fB\-r\fR
may show that this tool removed some headers that are actually required for your build\&. This can happen because
\fBdeheader\fR
doesn\*(Aqt know about all the strange things your build system gets up to, and the problem of analyzing your build 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 standardized 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 brute\-force 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[])\&.
<?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'>-q </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).</para>
<para>Optionally, with the <option>-r</option> switch, the
unneeded headers are removed from the sourcefiles. Don't use
this option unless you have your sourcefiles safely under version
control and can revert!</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 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
verbose progress messages on the analysis. At verbosity level 3, you
see the output from the make and compilation commands.</para>
<para>If the -q (--quiet) option flag was not set, 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 (or the equivalent under
whatever build system you are using) 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>-q</term>
<listitem>
<para>Suppress statistical summary.</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>Very rarely, test-compiling after running with
<option>-r</option> may show that this tool removed some headers that
are actually required for your build. This can happen because
<command>deheader</command> doesn't know about all the strange things
your build system gets up to, and the problem of analyzing your build
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
standardized 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 brute-force
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>esr@snark.thyrsus.com</email>; (home page at <ulink
url='http://www.catb.org/~esr/'>http://www.catb.org/~esr/</ulink>).</para>
</refsect1>
</refentry>
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment