ceph/src/boost/tools/boostdep/doc/html/index.html

   1 <html>
   2 <head>
   3 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
   4 <title>Boostdep</title>
   5 <link rel="stylesheet" href="../../../../doc/src/boostbook.css" type="text/css">
   6 <meta name="generator" content="DocBook XSL Stylesheets V1.78.1">
   7 <link rel="home" href="index.html" title="Boostdep">
   8 </head>
   9 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
  10 <table cellpadding="2" width="100%"><tr>
  11 <td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../boost.png"></td>
  12 <td align="center"><a href="../../../../index.html">Home</a></td>
  13 <td align="center"><a href="../../../../libs/libraries.htm">Libraries</a></td>
  14 <td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
  15 <td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
  16 <td align="center"><a href="../../../../more/index.htm">More</a></td>
  17 </tr></table>
  18 <hr>
  19 <div class="spirit-nav"></div>
  20 <div class="article">
  21 <div class="titlepage">
  22 <div>
  23 <div><h2 class="title">
  24 <a name="boostdep"></a>Boostdep</h2></div>
  25 <div><p class="copyright">Copyright &#169; 2014-2016 Peter Dimov</p></div>
  26 <div><div class="legalnotice">
  27 <a name="boostdep.legal"></a><p>
  28         Distributed under the <a href="http://boost.org/LICENSE_1_0.txt" target="_top">Boost
  29         Software License, Version 1.0</a>.
  30       </p>
  31 </div></div>
  32 </div>
  33 <hr>
  34 </div>
  35 <div class="toc">
  36 <p><b>Table of Contents</b></p>
  37 <dl class="toc">
  38 <dt><span class="section"><a href="index.html#boostdep.introduction">Introduction</a></span></dt>
  39 <dd><dl>
  40 <dt><span class="section"><a href="index.html#boostdep.introduction.modular_boost">Modular Boost</a></span></dt>
  41 <dt><span class="section"><a href="index.html#boostdep.introduction.building_boostdep">Building Boostdep</a></span></dt>
  42 <dt><span class="section"><a href="index.html#boostdep.introduction.running_boostdep">Running Boostdep</a></span></dt>
  43 </dl></dd>
  44 <dt><span class="section"><a href="index.html#boostdep.usage">Usage</a></span></dt>
  45 <dd><dl>
  46 <dt><span class="section"><a href="index.html#boostdep.usage.simple_queries">Simple Queries</a></span></dt>
  47 <dt><span class="section"><a href="index.html#boostdep.usage.html_reports">HTML reports</a></span></dt>
  48 </dl></dd>
  49 <dt><span class="section"><a href="index.html#boostdep.reference">Reference</a></span></dt>
  50 <dd><dl>
  51 <dt><span class="section"><a href="index.html#boostdep.reference.list_modules">--list-modules</a></span></dt>
  52 <dt><span class="section"><a href="index.html#boostdep.reference.list_buildable">--list-buildable</a></span></dt>
  53 <dt><span class="section"><a href="index.html#boostdep.reference.list_dependencies">--list-dependencies</a></span></dt>
  54 <dt><span class="section"><a href="index.html#boostdep.reference.module_overview">--module-overview</a></span></dt>
  55 <dt><span class="section"><a href="index.html#boostdep.reference.module_levels">--module-levels</a></span></dt>
  56 <dt><span class="section"><a href="index.html#boostdep.reference.module_weights">--module-weights</a></span></dt>
  57 <dt><span class="section"><a href="index.html#boostdep.reference.primary">--primary</a></span></dt>
  58 <dt><span class="section"><a href="index.html#boostdep.reference.secondary">--secondary</a></span></dt>
  59 <dt><span class="section"><a href="index.html#boostdep.reference.reverse">--reverse</a></span></dt>
  60 <dt><span class="section"><a href="index.html#boostdep.reference.subset">--subset</a></span></dt>
  61 <dt><span class="section"><a href="index.html#boostdep.reference.header">--header</a></span></dt>
  62 <dt><span class="section"><a href="index.html#boostdep.reference.track_sources">--track-sources</a></span></dt>
  63 <dt><span class="section"><a href="index.html#boostdep.reference.title">--title</a></span></dt>
  64 <dt><span class="section"><a href="index.html#boostdep.reference.footer">--footer</a></span></dt>
  65 <dt><span class="section"><a href="index.html#boostdep.reference.html">--html</a></span></dt>
  66 </dl></dd>
  67 </dl>
  68 </div>
  69 <div class="section">
  70 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
  71 <a name="boostdep.introduction"></a><a class="link" href="index.html#boostdep.introduction" title="Introduction">Introduction</a>
  72 </h2></div></div></div>
  73 <div class="toc"><dl class="toc">
  74 <dt><span class="section"><a href="index.html#boostdep.introduction.modular_boost">Modular Boost</a></span></dt>
  75 <dt><span class="section"><a href="index.html#boostdep.introduction.building_boostdep">Building Boostdep</a></span></dt>
  76 <dt><span class="section"><a href="index.html#boostdep.introduction.running_boostdep">Running Boostdep</a></span></dt>
  77 </dl></div>
  78 <p>
  79       <span class="emphasis"><em>Boostdep</em></span> is a tool for generating Boost dependency reports.
  80       It scans the header or source files of the Boost libraries for <code class="computeroutput"><span class="preprocessor">#include</span></code> directives, builds a dependency
  81       graph from this information and outputs its findings in plain text or HTML.
  82     </p>
  83 <div class="section">
  84 <div class="titlepage"><div><div><h3 class="title">
  85 <a name="boostdep.introduction.modular_boost"></a><a class="link" href="index.html#boostdep.introduction.modular_boost" title="Modular Boost">Modular Boost</a>
  86 </h3></div></div></div>
  87 <p>
  88         <span class="emphasis"><em>Boostdep</em></span> requires the so-called "modular Boost"
  89         directory structure.
  90       </p>
  91 <p>
  92         If you already have a <a href="https://svn.boost.org/trac/boost/wiki/ModularBoost" target="_top">modular
  93         Boost installation</a>, you can skip this section. Otherwise, read on.
  94       </p>
  95 <p>
  96         Boost libraries reside in subdirectories under the <code class="literal">libs</code>
  97         directory. For example, the contents of the Boost.Filesystem library are
  98         in <code class="literal">libs/filesystem</code>. This includes the build scripts (in
  99         <code class="literal">libs/filesystem/build</code>), the source files (in <code class="literal">libs/filesystem/src</code>),
 100         the tests (in <code class="literal">libs/filesystem/test</code>), the documentation
 101         (in <code class="literal">libs/filesystem/doc</code>), and so on.
 102       </p>
 103 <p>
 104         In the past, when Boost used SVN as its version control system, the header
 105         files were an exception. The header files of all libraries resided in the
 106         <code class="literal">boost</code> subdirectory, and it wasn't possible to accurately
 107         determine which header belonged to which library.
 108       </p>
 109 <p>
 110         When Boost moved to Git for version control, header files were moved to their
 111         corresponding libraries, into an <code class="literal">include</code> subdirectory.
 112         The header files of Boost.Filesystem are now in <code class="literal">libs/filesystem/include</code>.
 113       </p>
 114 <p>
 115         For compatibility, <code class="literal">boost</code> is now a "virtual"
 116         directory, containing links to the headers. It's maintained automatically
 117         by Boost.Build. (The command <code class="literal">b2 headers</code> creates or recreates
 118         the contents of the <code class="literal">boost</code> directory.)
 119       </p>
 120 <p>
 121         This new structure allows <span class="emphasis"><em>Boostdep</em></span> to determine that,
 122         when faced with an <code class="computeroutput"><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">filesystem</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span></code>
 123         directive, that this header is part of Boost.Filesystem, and that therefore,
 124         the current library being scanned depends on Boost.Filesystem.
 125       </p>
 126 <p>
 127         Unfortunately, Boost releases do not have this structure. For backward compatibility,
 128         they have an old-style <code class="literal">boost</code> directory containing all
 129         header files, whereas the per-library <code class="literal">include</code> subdirectories
 130         are missing. Therefore, <span class="emphasis"><em>Boostdep</em></span> will not work with
 131         a downloaded Boost release.
 132       </p>
 133 <p>
 134         To use <span class="emphasis"><em>Boostdep</em></span>, you will have to clone the Boost Git
 135         repository instead. To do that, execute the following command:
 136       </p>
 137 <pre class="programlisting">git clone https://github.com/boostorg/boost.git boost
 138 </pre>
 139 <p>
 140         This will download the Boost "superproject" (the master project,
 141         without any libraries) and place it into the subdirectory <code class="literal">boost</code>
 142         of the current directory. To override the directory name, pass it as a second
 143         argument instead of <code class="literal">boost</code>:
 144       </p>
 145 <pre class="programlisting">git clone https://github.com/boostorg/boost.git <span class="emphasis"><em>mydir</em></span>
 146 </pre>
 147 <p>
 148         You can now <code class="literal">cd</code> into the newly created directory with
 149       </p>
 150 <pre class="programlisting">cd <span class="emphasis"><em>mydir</em></span>
 151 </pre>
 152 <p>
 153         This directory is called the "Boost root". All of the commands
 154         below assume that it is the current directory.
 155       </p>
 156 <p>
 157         The above <code class="literal">git clone</code> commands download the default branch
 158         of the Boost Git repository, which is <code class="literal">master</code>. This is
 159         the current more-or-less stable version of Boost.
 160       </p>
 161 <p>
 162         To verify this, issue the command
 163       </p>
 164 <pre class="programlisting">git status
 165 </pre>
 166 <p>
 167         from the Boost root. This will output
 168       </p>
 169 <pre class="programlisting"># On branch master
 170 nothing to commit, working directory clean
 171 </pre>
 172 <p>
 173         To download a specific release instead, such as 1.58.0, issue the following
 174         command after <code class="literal">git clone</code>, from the Boost root:
 175       </p>
 176 <pre class="programlisting">git checkout boost-1.58.0
 177 </pre>
 178 <p>
 179         <code class="literal">git status</code> will now say
 180       </p>
 181 <pre class="programlisting"># HEAD detached at boost-1.58.0
 182 nothing to commit, working directory clean
 183 </pre>
 184 <p>
 185         Then, download all the libraries:
 186       </p>
 187 <pre class="programlisting">git submodule update --init
 188 </pre>
 189 <p>
 190         This step will take a while.
 191       </p>
 192 <p>
 193         If all goes well, you will now have the complete contents of Boost's latest
 194         <code class="literal">master</code> branch (if you didn't <code class="literal">checkout</code>
 195         a specific release by name) or the corresponding Boost release (if you did).
 196       </p>
 197 <p>
 198         You can switch between the <code class="literal">master</code> branch, the <code class="literal">develop</code>
 199         (unstable) branch, and a release, by issuing the following commands:
 200       </p>
 201 <div class="blockquote"><blockquote class="blockquote"><p>
 202           For the <code class="literal">master</code> branch:
 203         </p></blockquote></div>
 204 <pre class="programlisting">git checkout master
 205 git pull
 206 git submodule update --init
 207 </pre>
 208 <div class="blockquote"><blockquote class="blockquote"><p>
 209           (<code class="literal">git pull</code> updates your local copy of the <code class="literal">master</code>
 210           branch from the server, in case it has changed since your initial checkout.)
 211         </p></blockquote></div>
 212 <div class="blockquote"><blockquote class="blockquote"><p>
 213           For the <code class="literal">develop</code> branch:
 214         </p></blockquote></div>
 215 <pre class="programlisting">git checkout develop
 216 git pull
 217 git submodule update --init
 218 </pre>
 219 <div class="blockquote"><blockquote class="blockquote"><p>
 220           For the <code class="literal">boost-1.58.0</code> release:
 221         </p></blockquote></div>
 222 <pre class="programlisting">git checkout boost-1.58.0
 223 git submodule update --init
 224 </pre>
 225 <div class="blockquote"><blockquote class="blockquote"><p>
 226           For the <code class="literal">boost-1.57.0</code> release:
 227         </p></blockquote></div>
 228 <pre class="programlisting">git checkout boost-1.57.0
 229 git submodule update --init
 230 </pre>
 231 <p>
 232         Note that, while the initial <code class="literal">git submodule update</code> is quite
 233         slow, as it needs to download all the libraries, the subsequent invocations
 234         are a lot faster.
 235       </p>
 236 <p>
 237         Also note that if a new Boost library (<code class="literal">libs/convert</code>, for
 238         example) is present in, say, <code class="literal">master</code>, and you have it checked
 239         out, when you later switch to <code class="literal">boost-1.58.0</code>, where this
 240         library doesn't exist, Git will not delete <code class="literal">libs/convert</code>.
 241         In this case, <code class="literal">git status</code> will output
 242       </p>
 243 <pre class="programlisting"># HEAD detached at boost-1.58.0
 244 # Untracked files:
 245 #   (use "git add &lt;file&gt;..." to include in what will be committed)
 246 #
 247 #       libs/convert/
 248 nothing added to commit but untracked files present (use "git add" to track)
 249 </pre>
 250 <p>
 251         and you will have to remove <code class="literal">libs/convert</code> by hand.
 252       </p>
 253 <p>
 254         Once you have the Boost contents which you want to analyze for dependencies,
 255         proceed with the next step, building <span class="emphasis"><em>Boostdep</em></span>.
 256       </p>
 257 </div>
 258 <div class="section">
 259 <div class="titlepage"><div><div><h3 class="title">
 260 <a name="boostdep.introduction.building_boostdep"></a><a class="link" href="index.html#boostdep.introduction.building_boostdep" title="Building Boostdep">Building Boostdep</a>
 261 </h3></div></div></div>
 262 <p>
 263         To build <span class="emphasis"><em>Boostdep</em></span>, issue the following command from
 264         the Boost root:
 265       </p>
 266 <pre class="programlisting">b2 tools/boostdep/build//install
 267 </pre>
 268 <p>
 269         This will build <span class="emphasis"><em>Boostdep</em></span> from source using the default
 270         "toolset" (a Boost.Build term meaning "compiler") and
 271         if successful, place it into the <code class="literal">dist/bin</code> subdirectory.
 272         The command assumes that <code class="literal">b2</code> (the Boost.Build executable)
 273         is somewhere in your path. If you don't have <code class="literal">b2</code>, execute
 274       </p>
 275 <pre class="programlisting">.\bootstrap
 276 </pre>
 277 <p>
 278         under Windows or
 279       </p>
 280 <pre class="programlisting">./bootstrap.sh
 281 </pre>
 282 <p>
 283         under Unix-like systems, which should build <code class="literal">b2</code> and place
 284         it into the current directory. You can then use <code class="literal">./b2</code> instead
 285         of <code class="literal">b2</code>.
 286       </p>
 287 </div>
 288 <div class="section">
 289 <div class="titlepage"><div><div><h3 class="title">
 290 <a name="boostdep.introduction.running_boostdep"></a><a class="link" href="index.html#boostdep.introduction.running_boostdep" title="Running Boostdep">Running Boostdep</a>
 291 </h3></div></div></div>
 292 <p>
 293         Once you have built <span class="emphasis"><em>Boostdep</em></span>, execute it with the following
 294         command:
 295       </p>
 296 <pre class="programlisting">dist/bin/boostdep
 297 </pre>
 298 <p>
 299         or
 300       </p>
 301 <pre class="programlisting">dist\bin\boostdep
 302 </pre>
 303 <p>
 304         on Windows. The commands below are given as using <code class="literal">dist/bin/boostdep</code>;
 305         if you're using Windows, use <code class="literal">dist\bin\boostdep</code> instead.
 306       </p>
 307 <p>
 308         This will print out the following help message:
 309       </p>
 310 <pre class="programlisting">Usage:
 311
 312     boostdep --list-modules
 313     boostdep --list-buildable
 314     boostdep [--track-sources] --list-dependencies
 315
 316     boostdep [options] --module-overview
 317     boostdep [options] --module-levels
 318     boostdep [options] --module-weights
 319
 320     boostdep [options] [--primary] &lt;module&gt;
 321     boostdep [options] --secondary &lt;module&gt;
 322     boostdep [options] --reverse &lt;module&gt;
 323     boostdep [options] --subset &lt;module&gt;
 324     boostdep [options] [--header] &lt;header&gt;
 325
 326     [options]: [--track-sources] [--title &lt;title&gt;] [--footer &lt;footer&gt;] [--html]
 327 </pre>
 328 <p>
 329         (The 1.58.0 version of <span class="emphasis"><em>Boostdep</em></span> has an unfortunate bug
 330         that causes the above output to be truncated after <code class="literal">boostdep --list-modules</code>.
 331         The rest of the functionality is intact though, so you can still use it as
 332         described.)
 333       </p>
 334 </div>
 335 </div>
 336 <div class="section">
 337 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
 338 <a name="boostdep.usage"></a><a class="link" href="index.html#boostdep.usage" title="Usage">Usage</a>
 339 </h2></div></div></div>
 340 <div class="toc"><dl class="toc">
 341 <dt><span class="section"><a href="index.html#boostdep.usage.simple_queries">Simple Queries</a></span></dt>
 342 <dt><span class="section"><a href="index.html#boostdep.usage.html_reports">HTML reports</a></span></dt>
 343 </dl></div>
 344 <div class="section">
 345 <div class="titlepage"><div><div><h3 class="title">
 346 <a name="boostdep.usage.simple_queries"></a><a class="link" href="index.html#boostdep.usage.simple_queries" title="Simple Queries">Simple Queries</a>
 347 </h3></div></div></div>
 348 <p>
 349         To list the dependencies of a specific library, use the command
 350       </p>
 351 <pre class="programlisting">dist/bin/boostdep <span class="emphasis"><em>library</em></span>
 352 </pre>
 353 <p>
 354         For Boost.Filesystem, for example, type
 355       </p>
 356 <pre class="programlisting">dist/bin/boostdep filesystem
 357 </pre>
 358 <p>
 359         This will print out something similar to the following:
 360       </p>
 361 <pre class="programlisting">Primary dependencies for filesystem:
 362
 363 assert:
 364     &lt;boost/assert.hpp&gt;
 365         from &lt;boost/filesystem/operations.hpp&gt;
 366         from &lt;boost/filesystem/path_traits.hpp&gt;
 367
 368 config:
 369     &lt;boost/config.hpp&gt;
 370         from &lt;boost/filesystem/config.hpp&gt;
 371         from &lt;boost/filesystem/convenience.hpp&gt;
 372         from &lt;boost/filesystem/fstream.hpp&gt;
 373         from &lt;boost/filesystem/operations.hpp&gt;
 374         from &lt;boost/filesystem/path.hpp&gt;
 375         from &lt;boost/filesystem/path_traits.hpp&gt;
 376     <span class="emphasis"><em>...</em></span>
 377
 378 functional:
 379     &lt;boost/functional/hash_fwd.hpp&gt;
 380         from &lt;boost/filesystem/path.hpp&gt;
 381
 382 io:
 383     &lt;boost/io/detail/quoted_manip.hpp&gt;
 384         from &lt;boost/filesystem/path.hpp&gt;
 385
 386 iterator:
 387     &lt;boost/iterator/iterator_facade.hpp&gt;
 388         from &lt;boost/filesystem/path.hpp&gt;
 389     <span class="emphasis"><em>...</em></span>
 390 </pre>
 391 <p>
 392         This lists the immediate dependencies of Boost.Filesystem. <code class="literal">assert:</code>
 393         is the library, <code class="literal">&lt;boost/assert.hpp&gt;</code> is the file that
 394         is being included, and <code class="literal">from &lt;boost/filesystem/config.hpp&gt;</code>
 395         shows where <code class="literal">&lt;boost/assert.hpp&gt;</code> is being included.
 396       </p>
 397 <p>
 398         <span class="emphasis"><em>Boostdep</em></span> names libraries (or modules) after their directory
 399         name. The <code class="literal">libs/filesystem</code> directory, for example, is the
 400         <code class="literal">filesystem</code> module. The <code class="literal">libs/numeric/conversion</code>
 401         directory is the <code class="literal">numeric~conversion</code> module, according
 402         to the <span class="emphasis"><em>Boostdep</em></span> naming convention.
 403       </p>
 404 <p>
 405         The reason forward slashes are replaced with tildes is that <code class="literal">numeric~conversion</code>
 406         is a valid file name, which makes generating HTML reports a bit easier.
 407       </p>
 408 <p>
 409         To see where a given header resides and who includes it, type
 410       </p>
 411 <pre class="programlisting">dist/bin/boostdep <span class="emphasis"><em>header</em></span>
 412 </pre>
 413 <p>
 414         For <code class="literal">boost/filesystem.hpp</code>, for example, type
 415       </p>
 416 <pre class="programlisting">dist/bin/boostdep boost/filesystem.hpp
 417 </pre>
 418 <p>
 419         This will print something along the lines of
 420       </p>
 421 <pre class="programlisting">Inclusion report for &lt;boost/filesystem.hpp&gt; (in module filesystem):
 422
 423     from spirit:
 424         &lt;boost/spirit/home/x3/support/utility/testing.hpp&gt;
 425 </pre>
 426 <p>
 427         What this tells you is that <code class="literal">boost/filesystem.hpp</code> is part
 428         of Boost.Filesystem and is only included once, from <code class="literal">&lt;boost/spirit/home/x3/support/utility/testing.hpp&gt;</code>.
 429         Other headers, such as <code class="literal">boost/shared_ptr.hpp</code>, are more
 430         widely used, as you can see if you try
 431       </p>
 432 <pre class="programlisting">dist/bin/boostdep boost/shared_ptr.hpp
 433 </pre>
 434 <p>
 435         To print the reverse dependencies of a library, use
 436       </p>
 437 <pre class="programlisting">dist/bin/boostdep --reverse <span class="emphasis"><em>library</em></span>
 438 </pre>
 439 <p>
 440         For example,
 441       </p>
 442 <pre class="programlisting">dist/bin/boostdep --reverse filesystem
 443 </pre>
 444 <p>
 445         will list which libraries depend on Boost.Filesystem:
 446       </p>
 447 <pre class="programlisting">Reverse dependencies for filesystem:
 448
 449 graph_parallel:
 450     &lt;boost/filesystem/operations.hpp&gt;
 451         from &lt;boost/graph/distributed/adjlist/serialization.hpp&gt;
 452     &lt;boost/filesystem/path.hpp&gt;
 453         from &lt;boost/graph/distributed/adjlist/serialization.hpp&gt;
 454
 455 log:
 456     &lt;boost/filesystem/config.hpp&gt;
 457         from &lt;boost/log/detail/config.hpp&gt;
 458     &lt;boost/filesystem/path.hpp&gt;
 459         from &lt;boost/log/sinks/event_log_backend.hpp&gt;
 460         from &lt;boost/log/sinks/text_file_backend.hpp&gt;
 461         from &lt;boost/log/sinks/text_multifile_backend.hpp&gt;
 462
 463 spirit:
 464     &lt;boost/filesystem.hpp&gt;
 465         from &lt;boost/spirit/home/x3/support/utility/testing.hpp&gt;
 466     &lt;boost/filesystem/fstream.hpp&gt;
 467         from &lt;boost/spirit/home/x3/support/utility/testing.hpp&gt;
 468     &lt;boost/filesystem/path.hpp&gt;
 469         from &lt;boost/spirit/home/x3/support/utility/error_reporting.hpp&gt;
 470
 471 wave:
 472     &lt;boost/filesystem/operations.hpp&gt;
 473         from &lt;boost/wave/util/cpp_include_paths.hpp&gt;
 474         from &lt;boost/wave/util/cpp_iterator.hpp&gt;
 475         from &lt;boost/wave/util/filesystem_compatibility.hpp&gt;
 476     &lt;boost/filesystem/path.hpp&gt;
 477         from &lt;boost/wave/cpp_context.hpp&gt;
 478         from &lt;boost/wave/util/cpp_include_paths.hpp&gt;
 479         from &lt;boost/wave/util/cpp_iterator.hpp&gt;
 480         from &lt;boost/wave/util/cpp_macromap.hpp&gt;
 481         from &lt;boost/wave/util/filesystem_compatibility.hpp&gt;
 482 </pre>
 483 </div>
 484 <div class="section">
 485 <div class="titlepage"><div><div><h3 class="title">
 486 <a name="boostdep.usage.html_reports"></a><a class="link" href="index.html#boostdep.usage.html_reports" title="HTML reports">HTML reports</a>
 487 </h3></div></div></div>
 488 <p>
 489         The primary purpose of <span class="emphasis"><em>Boostdep</em></span> is to generate HTML
 490         dependency reports. In the typical case, two types of reports are generated:
 491         overviews that contain information for all modules, and per-module ones that
 492         list information for a specific library.
 493       </p>
 494 <p>
 495         <span class="emphasis"><em>Boostdep</em></span> can generate three types of the first kind
 496         of report: module overview, module levels and module weights. To generate
 497         a module overview, use the command
 498       </p>
 499 <pre class="programlisting">dist/bin/boostdep --html --module-overview &gt; module-overview.html
 500 </pre>
 501 <p>
 502         For a module level report, use
 503       </p>
 504 <pre class="programlisting">dist/bin/boostdep --html --module-levels &gt; module-levels.html
 505 </pre>
 506 <p>
 507         For a module weight report, use
 508       </p>
 509 <pre class="programlisting">dist/bin/boostdep --html --module-weights &gt; module-weights.html
 510 </pre>
 511 <p>
 512         In these reports, module names such as <span class="emphasis"><em>module</em></span> are HTML
 513         links to <code class="literal"><span class="emphasis"><em>module</em></span>.html</code>.
 514       </p>
 515 <p>
 516         To make these links work as expected, you can generate HTML reports for each
 517         module as follows:
 518       </p>
 519 <pre class="programlisting">dist/bin/boostdep --title "Dependency Report for <span class="emphasis"><em>module</em></span>" --html --primary <span class="emphasis"><em>module</em></span> --secondary <span class="emphasis"><em>module</em></span> --reverse <span class="emphasis"><em>module</em></span> &gt; <span class="emphasis"><em>module</em></span>.html
 520 </pre>
 521 <p>
 522         This step can be automated if you generate a module list first with
 523       </p>
 524 <pre class="programlisting">dist/bin/boostdep --list-modules &gt; list-modules.txt
 525 </pre>
 526 <p>
 527         that will contain one module name per line, and then use a script to issue
 528         the previous command for each module name.
 529       </p>
 530 <p>
 531         For more information about the <span class="emphasis"><em>Boostdep</em></span> options and
 532         commands, see the <a class="link" href="index.html#boostdep.reference" title="Reference">Reference</a> section.
 533       </p>
 534 <p>
 535         For an example of a report generation script, see the file <code class="literal">tools/boostdep/examples/report.bat</code>.
 536         This is a Windows batch file, but translating it to a Unix-style shell script
 537         should be straightforward.
 538       </p>
 539 <p>
 540         For convenience, the contents of <code class="literal">tools/boostdep/examples/report.bat</code>
 541         are given below:
 542       </p>
 543 <pre class="programlisting">SET BOOSTDEP=dist\bin\boostdep.exe
 544
 545 FOR /f %%i IN ('git rev-parse HEAD') DO @SET REV=%%i
 546
 547 FOR /f %%i IN ('git rev-parse --short HEAD') DO @SET SHREV=%%i
 548
 549 FOR /f %%i IN ('git rev-parse --abbrev-ref HEAD') DO @SET BRANCH=%%i
 550
 551 SET FOOTER=Generated on %DATE% %TIME% from revision %REV% on branch '%BRANCH%'
 552
 553 SET OUTDIR=..\report-%BRANCH%-%SHREV%
 554
 555 mkdir %OUTDIR%
 556
 557 %BOOSTDEP% --list-modules &gt; %OUTDIR%\list-modules.txt
 558
 559 %BOOSTDEP% --footer "%FOOTER%" --html --module-overview &gt; %OUTDIR%\module-overview.html
 560 %BOOSTDEP% --footer "%FOOTER%" --html --module-levels &gt; %OUTDIR%\module-levels.html
 561 %BOOSTDEP% --footer "%FOOTER%" --html --module-weights &gt; %OUTDIR%\module-weights.html
 562
 563 FOR /f %%i IN (%OUTDIR%\list-modules.txt) DO %BOOSTDEP% --title "Dependency Report for %%i" --footer "%FOOTER%" --html --primary %%i --secondary %%i --reverse %%i &gt; %OUTDIR%%%i.html
 564 </pre>
 565 </div>
 566 </div>
 567 <div class="section">
 568 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
 569 <a name="boostdep.reference"></a><a class="link" href="index.html#boostdep.reference" title="Reference">Reference</a>
 570 </h2></div></div></div>
 571 <div class="toc"><dl class="toc">
 572 <dt><span class="section"><a href="index.html#boostdep.reference.list_modules">--list-modules</a></span></dt>
 573 <dt><span class="section"><a href="index.html#boostdep.reference.list_buildable">--list-buildable</a></span></dt>
 574 <dt><span class="section"><a href="index.html#boostdep.reference.list_dependencies">--list-dependencies</a></span></dt>
 575 <dt><span class="section"><a href="index.html#boostdep.reference.module_overview">--module-overview</a></span></dt>
 576 <dt><span class="section"><a href="index.html#boostdep.reference.module_levels">--module-levels</a></span></dt>
 577 <dt><span class="section"><a href="index.html#boostdep.reference.module_weights">--module-weights</a></span></dt>
 578 <dt><span class="section"><a href="index.html#boostdep.reference.primary">--primary</a></span></dt>
 579 <dt><span class="section"><a href="index.html#boostdep.reference.secondary">--secondary</a></span></dt>
 580 <dt><span class="section"><a href="index.html#boostdep.reference.reverse">--reverse</a></span></dt>
 581 <dt><span class="section"><a href="index.html#boostdep.reference.subset">--subset</a></span></dt>
 582 <dt><span class="section"><a href="index.html#boostdep.reference.header">--header</a></span></dt>
 583 <dt><span class="section"><a href="index.html#boostdep.reference.track_sources">--track-sources</a></span></dt>
 584 <dt><span class="section"><a href="index.html#boostdep.reference.title">--title</a></span></dt>
 585 <dt><span class="section"><a href="index.html#boostdep.reference.footer">--footer</a></span></dt>
 586 <dt><span class="section"><a href="index.html#boostdep.reference.html">--html</a></span></dt>
 587 </dl></div>
 588 <div class="section">
 589 <div class="titlepage"><div><div><h3 class="title">
 590 <a name="boostdep.reference.list_modules"></a><a class="link" href="index.html#boostdep.reference.list_modules" title="--list-modules">--list-modules</a>
 591 </h3></div></div></div>
 592 <p>
 593         <code class="literal">boostdep --list-modules</code> prints the module list. <span class="emphasis"><em>Boostdep</em></span>
 594         considers a subdirectory of <code class="literal">libs</code> a module if it contains
 595         an <code class="literal">include</code> subdirectory.
 596       </p>
 597 <p>
 598         This command is typically used from scripts which then use the list to execute
 599         a command for each module.
 600       </p>
 601 </div>
 602 <div class="section">
 603 <div class="titlepage"><div><div><h3 class="title">
 604 <a name="boostdep.reference.list_buildable"></a><a class="link" href="index.html#boostdep.reference.list_buildable" title="--list-buildable">--list-buildable</a>
 605 </h3></div></div></div>
 606 <p>
 607         <code class="literal">boostdep --list-buildable</code> prints a list of the modules
 608         that require building. <span class="emphasis"><em>Boostdep</em></span> considers a module to
 609         require building if it contains subdirectories named <code class="literal">build</code>
 610         and <code class="literal">src</code>.
 611       </p>
 612 <p>
 613         This command is typically used from scripts.
 614       </p>
 615 </div>
 616 <div class="section">
 617 <div class="titlepage"><div><div><h3 class="title">
 618 <a name="boostdep.reference.list_dependencies"></a><a class="link" href="index.html#boostdep.reference.list_dependencies" title="--list-dependencies">--list-dependencies</a>
 619 </h3></div></div></div>
 620 <p>
 621         <code class="literal">boostdep --list-dependencies</code> prints a module list in which
 622         each line is of the form
 623       </p>
 624 <pre class="programlisting">module -&gt; dependency1 dependency2 <span class="emphasis"><em>...</em></span>
 625 </pre>
 626 <p>
 627         By default, only the <code class="literal">include</code> directory is scanned for
 628         <code class="computeroutput"><span class="preprocessor">#include</span></code> directives. If
 629         the option <code class="literal">--track-sources</code> is given, the <code class="literal">src</code>
 630         directory is also scanned.
 631       </p>
 632 <p>
 633         This command is typically used from scripts. The output is virtually identical
 634         to <code class="literal">--module-overview</code> in plain text, but slightly more
 635         machine-friendly.
 636       </p>
 637 </div>
 638 <div class="section">
 639 <div class="titlepage"><div><div><h3 class="title">
 640 <a name="boostdep.reference.module_overview"></a><a class="link" href="index.html#boostdep.reference.module_overview" title="--module-overview">--module-overview</a>
 641 </h3></div></div></div>
 642 <p>
 643         <code class="literal">boostdep --module-overview</code> generates a module overview,
 644         in plain text or HTML. The plain text output is of the form
 645       </p>
 646 <pre class="programlisting">Module Overview:
 647
 648 accumulators -&gt; array assert circular_buffer concept_check config core fusion iterator mpl numeric~conversion numeric~ublas parameter preprocessor range static_assert throw_exception tuple type_traits typeof
 649 algorithm -&gt; array assert bind concept_check config core exception function iterator mpl range regex static_assert tuple type_traits unordered
 650 align -&gt; assert config core static_assert throw_exception
 651 </pre>
 652 <p>
 653         whereas the HTML output is similar to
 654       </p>
 655 <div class="blockquote"><blockquote class="blockquote">
 656 <p>
 657           <span class="bold"><strong>Module Overview</strong></span>
 658         </p>
 659 <p>
 660           <span class="bold"><strong><span class="emphasis"><em>accumulators</em></span></strong></span>
 661         </p>
 662 <p>
 663           &#8674; array assert circular_buffer concept_check config core fusion
 664           iterator mpl numeric~conversion numeric~ublas parameter preprocessor range
 665           static_assert throw_exception tuple type_traits typeof
 666         </p>
 667 </blockquote></div>
 668 <p>
 669         where <span class="emphasis"><em>accumulators</em></span> is a link to <code class="literal">accumulators.html</code>.
 670       </p>
 671 <p>
 672         As before, if <code class="literal">--track-sources</code> is given, the <code class="literal">src</code>
 673         subdirectory is scanned for <code class="computeroutput"><span class="preprocessor">#include</span></code>
 674         directives.
 675       </p>
 676 <p>
 677         HTML output is enabled by the <code class="literal">--html</code> option. The <code class="literal">--title</code>
 678         and <code class="literal">--footer</code> options set the HTML <code class="literal">&lt;title&gt;</code>
 679         and the page footer and need to precede <code class="literal">--html</code>, like in
 680         the following example:
 681       </p>
 682 <pre class="programlisting">dist/bin/boostdep --title "Module Overview" --footer "Generated on 21.05.2015 20:53:11" --html --module-overview &gt; module-overview.html
 683 </pre>
 684 </div>
 685 <div class="section">
 686 <div class="titlepage"><div><div><h3 class="title">
 687 <a name="boostdep.reference.module_levels"></a><a class="link" href="index.html#boostdep.reference.module_levels" title="--module-levels">--module-levels</a>
 688 </h3></div></div></div>
 689 <p>
 690         <code class="literal">boostdep --module-levels</code> generates a report that groups
 691         modules by level. Levels are determined in such a way so that a module of
 692         level <code class="literal">N</code> never depends on modules of levels greater than
 693         <code class="literal">N</code>, and in the absence of cyclic dependencies, doesn't
 694         depend on other modules of level <code class="literal">N</code>. It takes the same
 695         options as <code class="literal">--module-overview</code>.
 696       </p>
 697 <pre class="programlisting">dist/bin/boostdep --title "Module Levels" --footer "Generated on 21.05.2015 20:53:11" --html --module-levels &gt; module-levels.html
 698 </pre>
 699 </div>
 700 <div class="section">
 701 <div class="titlepage"><div><div><h3 class="title">
 702 <a name="boostdep.reference.module_weights"></a><a class="link" href="index.html#boostdep.reference.module_weights" title="--module-weights">--module-weights</a>
 703 </h3></div></div></div>
 704 <p>
 705         <code class="literal">boostdep --module-weights</code> generates a report that lists
 706         modules by weight. A module weight is the total number of its dependencies.
 707         This includes the indirect dependencies.
 708       </p>
 709 <p>
 710         <code class="literal">--module-weights</code> takes the same options as <code class="literal">--module-overview</code>.
 711       </p>
 712 <pre class="programlisting">dist/bin/boostdep --title "Module Weights" --footer "Generated on 21.05.2015 20:53:11" --html --module-weights &gt; module-weights.html
 713 </pre>
 714 </div>
 715 <div class="section">
 716 <div class="titlepage"><div><div><h3 class="title">
 717 <a name="boostdep.reference.primary"></a><a class="link" href="index.html#boostdep.reference.primary" title="--primary">--primary</a>
 718 </h3></div></div></div>
 719 <p>
 720         <code class="literal">boostdep --primary <span class="emphasis"><em>module</em></span></code> lists the
 721         primary (direct) dependencies of <span class="emphasis"><em>module</em></span>. It takes the
 722         same options as <code class="literal">--module-overview</code>.
 723       </p>
 724 <pre class="programlisting">dist/bin/boostdep --title "Primary Dependencies of filesystem" --footer "Generated on 21.05.2015 20:53:11" --html --primary filesystem &gt; filesystem-primary.html
 725 </pre>
 726 </div>
 727 <div class="section">
 728 <div class="titlepage"><div><div><h3 class="title">
 729 <a name="boostdep.reference.secondary"></a><a class="link" href="index.html#boostdep.reference.secondary" title="--secondary">--secondary</a>
 730 </h3></div></div></div>
 731 <p>
 732         <code class="literal">boostdep --secondary <span class="emphasis"><em>module</em></span></code> lists
 733         the secondary (indirect) dependencies of <span class="emphasis"><em>module</em></span>. It
 734         takes the same options as <code class="literal">--module-overview</code>.
 735       </p>
 736 <pre class="programlisting">dist/bin/boostdep --title "Secondary Dependencies of filesystem" --footer "Generated on 21.05.2015 20:53:11" --html --secondary filesystem &gt; filesystem-secondary.html
 737 </pre>
 738 <p>
 739         You can combine <code class="literal">--primary</code> and <code class="literal">--secondary</code>
 740         in one invocation.
 741       </p>
 742 <pre class="programlisting">dist/bin/boostdep --title "Dependencies of filesystem" --footer "Generated on 21.05.2015 20:53:11" --html --primary filesystem --secondary filesystem &gt; filesystem.html
 743 </pre>
 744 </div>
 745 <div class="section">
 746 <div class="titlepage"><div><div><h3 class="title">
 747 <a name="boostdep.reference.reverse"></a><a class="link" href="index.html#boostdep.reference.reverse" title="--reverse">--reverse</a>
 748 </h3></div></div></div>
 749 <p>
 750         <code class="literal">boostdep --reverse <span class="emphasis"><em>module</em></span></code> lists the
 751         reverse dependencies of <span class="emphasis"><em>module</em></span>, that is, it lists which
 752         modules depend on <span class="emphasis"><em>module</em></span>. It takes the same options
 753         as <code class="literal">--module-overview</code>.
 754       </p>
 755 <pre class="programlisting">dist/bin/boostdep --title "Reverse Dependencies of filesystem" --footer "Generated on 21.05.2015 20:53:11" --html --reverse filesystem &gt; filesystem-reverse.html
 756 </pre>
 757 <p>
 758         You can combine <code class="literal">--reverse</code> with <code class="literal">--primary</code>
 759         and <code class="literal">--secondary</code> for a complete module report.
 760       </p>
 761 <pre class="programlisting">dist/bin/boostdep --title "Dependency Report for filesystem" --footer "Generated on 21.05.2015 20:53:11" --html --primary filesystem --secondary filesystem --reverse filesystem &gt; filesystem.html
 762 </pre>
 763 </div>
 764 <div class="section">
 765 <div class="titlepage"><div><div><h3 class="title">
 766 <a name="boostdep.reference.subset"></a><a class="link" href="index.html#boostdep.reference.subset" title="--subset">--subset</a>
 767 </h3></div></div></div>
 768 <p>
 769         <code class="literal">boostdep --subset <span class="emphasis"><em>module</em></span></code> lists the
 770         subset dependencies of <span class="emphasis"><em>module</em></span>, that is, it lists which
 771         modules comprise the subset which <span class="emphasis"><em>module</em></span> requires in
 772         order to be usable. The dependencies are determined by tracing the <code class="literal">#include</code>
 773         directives starting from <span class="emphasis"><em>module</em></span>'s headers.
 774       </p>
 775 <p>
 776         The difference between using the modules reported by <code class="literal">--subset</code>
 777         and those reported by the sum of <code class="literal">--primary</code> and <code class="literal">--secondary</code>
 778         is that the former only guarantees that <span class="emphasis"><em>module</em></span> will
 779         be usable, whereas the latter guarantees it for every module in the subset.
 780       </p>
 781 <p>
 782         <code class="literal">--subset</code> takes the same options as <code class="literal">--module-overview</code>.
 783       </p>
 784 <pre class="programlisting">dist/bin/boostdep --title "Subset Dependencies of filesystem" --footer "Generated on 21.05.2015 20:53:11" --html --subset filesystem &gt; filesystem-subset.html
 785 </pre>
 786 <p>
 787         You can combine <code class="literal">--subset</code> with the other module report
 788         options.
 789       </p>
 790 </div>
 791 <div class="section">
 792 <div class="titlepage"><div><div><h3 class="title">
 793 <a name="boostdep.reference.header"></a><a class="link" href="index.html#boostdep.reference.header" title="--header">--header</a>
 794 </h3></div></div></div>
 795 <p>
 796         <code class="literal">boostdep --header <span class="emphasis"><em>header</em></span></code> creates
 797         an inclusion report for <span class="emphasis"><em>header</em></span>. It takes the same options
 798         as <code class="literal">--module-overview</code>.
 799       </p>
 800 <pre class="programlisting">dist/bin/boostdep --title "Inclusion Report for &lt;boost/shared_ptr.hpp&gt;" --footer "Generated on 21.05.2015 20:53:11" --html --header boost/shared_ptr.hpp &gt; header-boost-shared_ptr.html
 801 </pre>
 802 </div>
 803 <div class="section">
 804 <div class="titlepage"><div><div><h3 class="title">
 805 <a name="boostdep.reference.track_sources"></a><a class="link" href="index.html#boostdep.reference.track_sources" title="--track-sources">--track-sources</a>
 806 </h3></div></div></div>
 807 <p>
 808         The <code class="literal">--track-sources</code> option instructs <span class="emphasis"><em>Boostdep</em></span>
 809         to scan the <code class="literal">src</code> library subdirectory for <code class="computeroutput"><span class="preprocessor">#include</span></code> directives. By default, only
 810         the <code class="literal">include</code> subdirectory is scanned.
 811       </p>
 812 </div>
 813 <div class="section">
 814 <div class="titlepage"><div><div><h3 class="title">
 815 <a name="boostdep.reference.title"></a><a class="link" href="index.html#boostdep.reference.title" title="--title">--title</a>
 816 </h3></div></div></div>
 817 <p>
 818         <code class="literal">--title <span class="emphasis"><em>title</em></span></code> sets the contents of
 819         the HTML <code class="literal">&lt;title&gt;</code> tag. It must precede <code class="literal">--html</code>
 820         to have an effect.
 821       </p>
 822 </div>
 823 <div class="section">
 824 <div class="titlepage"><div><div><h3 class="title">
 825 <a name="boostdep.reference.footer"></a><a class="link" href="index.html#boostdep.reference.footer" title="--footer">--footer</a>
 826 </h3></div></div></div>
 827 <p>
 828         <code class="literal">--footer <span class="emphasis"><em>footer</em></span></code> sets the page footer
 829         text. It has no effect if <code class="literal">--html</code> is not given.
 830       </p>
 831 </div>
 832 <div class="section">
 833 <div class="titlepage"><div><div><h3 class="title">
 834 <a name="boostdep.reference.html"></a><a class="link" href="index.html#boostdep.reference.html" title="--html">--html</a>
 835 </h3></div></div></div>
 836 <p>
 837         <code class="literal">--html</code> switches to HTML output mode (the default is plain
 838         text). It must precede the commands that generate output.
 839       </p>
 840 </div>
 841 </div>
 842 </div>
 843 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
 844 <td align="left"><p><small>Last revised: March 04, 2016 at 11:24:14 GMT</small></p></td>
 845 <td align="right"><div class="copyright-footer"></div></td>
 846 </tr></table>
 847 <hr>
 848 <div class="spirit-nav"></div>
 849 </body>
 850 </html>