"Fossies" - the Fresh Open Source Software Archive

Member "deheader-1.10/deheader.xml" (30 Jan 2023, 8662 Bytes) of package /linux/privat/deheader-1.10.tar.gz:

As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) XML source code syntax highlighting (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file. See also the latest Fossies "Diffs" side-by-side code changes report for "deheader.xml": 1.8_vs_1.10.

    1 <?xml version="1.0" encoding="ISO-8859-1"?>
    2 <!DOCTYPE refentry PUBLIC 
    3    "-//OASIS//DTD DocBook XML V4.1.2//EN"
    4    "docbook/docbookx.dtd">
    5 <refentry id='deheader.1'>
    6 <refmeta>
    7 <refentrytitle>deheader</refentrytitle>
    8 <manvolnum>1</manvolnum>
    9 <refmiscinfo class='date'>Dec 01 2010</refmiscinfo>
   10 <refmiscinfo class='productname'>deheader</refmiscinfo>
   11 <refmiscinfo class='source'>deheader</refmiscinfo>
   12 <refmiscinfo class='manual'>Development Tools</refmiscinfo>
   13 </refmeta>
   14 <refnamediv id='name'>
   15 <refname>deheader</refname>
   16 <refpurpose>report which includes in C or C++ compiles can be removed</refpurpose>
   17 </refnamediv>
   18 <refsynopsisdiv id='synopsis'>
   20 <cmdsynopsis>
   21   <command>deheader</command>
   22        <arg choice='opt'>-h </arg>
   23        <arg choice='opt'>-m <replaceable>command</replaceable></arg>
   24        <arg choice='opt'>-b <replaceable>builddir</replaceable></arg>
   25        <arg choice='opt'>-i <replaceable>pattern</replaceable></arg>
   26        <arg choice='opt'>-q </arg>
   27        <arg choice='opt'>-r </arg>
   28        <arg choice='opt'>-v </arg>
   29        <arg choice='opt'>-x <replaceable>pattern</replaceable></arg>
   30        <arg choice='opt'>-V </arg>
   31        <arg choice='opt'><replaceable>file-or-dir</replaceable></arg>
   32 </cmdsynopsis>
   33 </refsynopsisdiv>
   35 <refsect1 id='description'><title>DESCRIPTION</title>
   37 <para>This tool takes a list of C or C++ sourcefiles and generates a
   38 report on which #includes can be omitted from them; also, what
   39 standard inclusions may be required for portability. The test, for
   40 each foo.c or foo.cc or foo.cpp, is simply whether "rm foo.o; make
   41 foo.o" returns a zero status (but the build command may be
   42 overridden).</para>
   44 <para>Exception: Under cmake, foo.o is a phony target.  Therefore,
   45 when a "CMakeList.txt" is detected, "make clean" is done rather than
   46 "rm foo.o".</para>
   48 <para>Optionally, with the <option>-r</option> switch, the
   49 unneeded headers are removed from the sourcefiles.  Don't use
   50 this option unless you have your sourcefiles safely under version
   51 control and can revert!</para>
   53 <para>If a sourcefile argument is a directory, the report is generated
   54 on all source files beneath it.  Subdirectories beginning with a dot
   55 are assumed to be repository directories for version-control systems
   56 and ignored.  If no arguments are given, the program runs as if the
   57 name of the current directory had been passed to it.</para>
   59 <para>Inclusions within the scope of #if/#ifdef/#else/#endif
   60 directives are left alone, because trying to reason about potential
   61 combinations of -D and U options would be too complicated and prone to
   62 weird errors. One exception: headers protected only by S_SPLINT_S, the
   63 conditional for blocking scanning by the static analysis tool
   64 <citerefentry><refentrytitle>splint</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
   65 are scanned normally.</para>
   67 <para>The tool will also emit warnings about duplicate inclusions, and 
   68 inclusions required for portability but not present.</para>
   70 <para>It is recommended that you arrange to compile with options that
   71 will stop the compiler on warnings when using this tool; otherwise it
   72 will report headers that only declare prototypes and return types
   73 (and thus throw only warnings) as being not required.  Under gcc the
   74 compiler options to accomplish this are -Werror -Wfatal-errors.  If
   75 your makefile follows normal conventions, running with <command>-m
   76 "make CFLAGS='-Werror -Wfatal-errors' %s" </command> may do the right thing; you
   77 can check this by running with -v -v -v to see what compilation
   78 commands are actually emitted.</para>
   80 <para>On each test compile, the original sourcefile is moved to a name
   81 with an .orig suffix and restored on interrupt or after processing
   82 with its original timestamp, unless the <option>-r</option> option was
   83 given and headers removed.</para>
   85 <para> If the -b option is given, it tells the program that generated
   86 .o files live in a file tree parallel to the source tree but rooted
   87 at the specified argument. If the argument is a relative path, it is
   88 interpreted relative to the directory in which deheader is run.</para>
   90 <para>If the first test compilation from the top-level directory fails,
   91 deheader descends into the subdirectory of the source file and retries
   92 compiling inside there.</para>
   94 <para>At verbosity level 0, only messages indicating removable headers
   95 are issued.  At verbosity 1, test compilations are timed and progress
   96 indicated with a twirling-baton prompt. At verbosity level 2, you get
   97 verbose progress messages on the analysis.  At verbosity level 3, you
   98 see the output from the make and compilation commands.</para>
  100 <para>If the -q (--quiet) option flag was not set, the last line of the
  101 output will be a statistical summary.</para>
  103 <para>Running deheader will leave a lot of binaries in your directory
  104 that were compiled in ways possibly not invoked by your normal build
  105 process.  Running "make clean" afterwards (or the equivalent under
  106 whatever build system you are using) is strongly recommended.</para>
  107 </refsect1>
  109 <refsect1 id='options'><title>OPTIONS</title>
  110 <variablelist>
  111 <varlistentry>
  112 <term>-h</term>
  113 <listitem>
  114 <para>Display some help and exit.</para>
  115 </listitem>
  116 </varlistentry>
  117 <varlistentry>
  118 <term>-m</term>
  119 <listitem>
  120 <para>Set the build command used for test compiles. Defaults to 'make %s'.
  121 A %s in the build command is replaced with the make target. Targetless
  122 builders such as meson can be supported with, e.g. "-m 'ninja -C build'"</para>
  123 </listitem>
  124 </varlistentry>
  125 <varlistentry>
  126 <term>-b</term>
  127 <listitem>
  128 <para>Set the build directory for object files.</para>
  129 </listitem>
  130 </varlistentry>
  131 <varlistentry>
  132 <term>-i</term>
  133 <listitem>
  134 <para>Set a pattern for includes to be ignored. 
  135 Takes a Python regular expression.</para>
  136 </listitem>
  137 </varlistentry>
  138 <varlistentry>
  139 <term>-q</term>
  140 <listitem>
  141 <para>Suppress statistical summary.</para>
  142 </listitem>
  143 </varlistentry>
  144 <varlistentry>
  145 <term>-r</term>
  146 <listitem>
  147 <para>Remove header inclusions from sourcefiles where they are not required.</para>
  148 </listitem>
  149 </varlistentry>
  150 <varlistentry>
  151 <term>-v</term>
  152 <listitem>
  153 <para>Set verbosity.</para>
  154 </listitem>
  155 </varlistentry>
  156 <varlistentry>
  157 <term>-x</term>
  158 <listitem>
  159 <para>Exclude files with names matching the specified Python regexp.</para>
  160 </listitem>
  161 </varlistentry>
  162 <varlistentry>
  163 <term>-V</term>
  164 <listitem>
  165 <para>Show version of program and exit.</para>
  166 </listitem>
  167 </varlistentry>
  168 </variablelist>
  169 </refsect1>
  171 <refsect1 id='returns'><title>RETURN VALUES</title>
  172 <para>Returns 1 if unneeded includes were found, 0 otherwise. Thus,
  173 you can use it for pre-release sanity checking in Makefile.</para>
  174 </refsect1>
  176 <refsect1 id='bugs'><title>BUGS</title>
  178 <para>Very rarely, test-compiling after running with
  179 <option>-r</option> may show that this tool removed some headers that
  180 are actually required for your build. This can happen because
  181 <command>deheader</command> doesn't know about all the strange things
  182 your build system gets up to, and the problem of analyzing your build
  183 to understand them would be Turing-complete.  Simply revert the
  184 altered files and continue.</para>
  186 <para>Due to minor variations in system headers, it is possible your
  187 program may not port correctly to other Unix variants after being
  188 deheadered. This is normally not a problem with the portion of the API
  189 specified by POSIX and ANSI C, but may be for headers that are not
  190 standardized or only weakly standardized.  The sockets API
  191 (sys/select.h, sys/sockets.h, and friends such as sys/types.h and
  192 sys.stat.h) is perhaps the most serious trouble
  193 spot. <command>deheader</command> has an internal table of rules that
  194 heads off the most common problems by suppressing deletion of headers
  195 that are required for portability, but your mileage may vary.</para>
  197 <para>The dependency scanner does not ignore the text of comments.
  198 This, e.g, a reference to "log10" in a comment will produce a spurious
  199 warning that &lt;math.h&gt;  is required for portability.</para>
  201 <para>Sufficiently perverse C++ can silently invalidate the brute-force
  202 algorithm this tool uses. Example: if an overloaded function has
  203 different overloads from two different files, removing one may expose
  204 the other, changing runtime semantics without a compile-time warning.
  205 Similarly, removing a later file containing a template specialization
  206 may lead to undefined behavior from a template defined in an earlier
  207 file. Use this with caution near such features, and test carefully.</para>
  208 </refsect1>
  210 <refsect1 id='author'><title>AUTHOR</title>
  211 <para>Eric S. Raymond <email>esr@snark.thyrsus.com</email>; (home page at <ulink
  212 url='http://www.catb.org/~esr/'>http://www.catb.org/~esr/</ulink>).</para>
  213 </refsect1>
  214 </refentry>