doc/man/sconsign.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2
   3 <!--
   4 SPDX-FileCopyrightText: Copyright The SCons Foundation (https://scons.org)
   5 SPDX-License-Identifier: MIT
   6 -->
   7
   8 <!DOCTYPE reference [
   9 <!ENTITY % version SYSTEM "../version.xml">
  10 %version;
  11 <!ENTITY % scons SYSTEM '../scons.mod'>
  12 %scons;
  13 ]>
  14
  15 <refentry id='sconsign1'
  16           xmlns="http://www.scons.org/dbxsd/v1.0"
  17           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  18           xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0 http://www.scons.org/dbxsd/v1.0/scons.xsd">
  19 <refmeta>
  20 <refentrytitle>SCONSIGN</refentrytitle>
  21 <manvolnum>1</manvolnum>
  22 <refmiscinfo class='source'>SCons __VERSION__</refmiscinfo>
  23 <refmiscinfo class='manual'>SCons __VERSION__</refmiscinfo>
  24 </refmeta>
  25 <refnamediv id='name'>
  26 <refname>sconsign</refname>
  27 <refpurpose>print SCons signature file information</refpurpose>
  28 </refnamediv>
  29 <!-- body begins here -->
  30 <refsynopsisdiv id='synopsis'>
  31 <cmdsynopsis>
  32   <command>sconsign</command>
  33     <arg choice='opt' rep='repeat'><replaceable>options</replaceable></arg>
  34     <arg choice='opt' rep='repeat'><replaceable>file</replaceable></arg>
  35 </cmdsynopsis>
  36 </refsynopsisdiv>
  37
  38
  39 <refsect1 id='description'>
  40 <title>DESCRIPTION</title>
  41 <para>
  42 Displays the contents of one or more
  43 <firstterm>sconsign</firstterm> files,
  44 the signature/dependency database
  45 used by the &SCons; build tool.
  46 The database contains all Nodes that are known to the build,
  47 either by declaration in the build configuration,
  48 produced as side effects, or detected by inspection.
  49 </para>
  50
  51 <para>By default,
  52 <command>sconsign</command>
  53 dumps the entire contents of the
  54 sconsign file(s).
  55 Without options,
  56 individual dependency entries are printed in the following format:</para>
  57
  58 <screen>
  59 depfile: content-signature timestamp length
  60         implicit-dependency-1: content-signature timestamp length
  61         implicit-dependency-2: content-signature timestamp length
  62         ...
  63         build-signature [action-string]
  64 </screen>
  65
  66 <para>
  67 <emphasis role="bold">content-signature</emphasis>
  68 is the hash of the file's contents (<firstterm>csig</firstterm>)
  69 and <emphasis role="bold">build-signature</emphasis>
  70 is the hash of the command line or other build action
  71 used to build a target (<firstterm>bactsig</firstterm>).
  72 If provided,
  73 <emphasis role="bold">action-string</emphasis>
  74 is the unexpanded string action or the function called.
  75 <emphasis role="bold">None</emphasis>
  76 is printed in place of any missing timestamp,
  77 <emphasis role="bold">csig</emphasis>,
  78 or <emphasis role="bold">bactsig</emphasis>
  79 values for any entry or any of its dependencies.
  80 If the entry has no implicit dependencies,
  81 or no build action,
  82 the corresponding lines are omitted.
  83 </para>
  84
  85 <para>
  86 An indicator line is printed for each directory,
  87 as directories do not have signatures in the database
  88 and so would not otherwise be shown.
  89 </para>
  90
  91 <para>
  92 By default,
  93 <command>sconsign</command>
  94 assumes that any
  95 <replaceable>file</replaceable>
  96 arguments that end with a
  97 <filename>.dblite</filename>
  98 suffix contains
  99 signature entries for
 100 more than one directory
 101 (that is, was specified by the
 102 <function>SConsignFile</function>
 103 &SCons; function).
 104 Any
 105 <replaceable>file</replaceable>
 106 argument that has no suffix
 107 is assumed to be an old-style (deprecated)
 108 sconsign file containing the signature entries
 109 for a single directory.
 110 If neither of those is true,
 111 <command>sconsign</command>
 112 attempts to guess the format.
 113 If that does not work,
 114 an explicit format
 115 may be specified using the
 116 <option>-f</option>
 117 or
 118 <option>--format=</option>
 119 options.
 120 </para>
 121 <para>
 122 If there are no
 123 <replaceable>file</replaceable>
 124 arguments, the name
 125 <filename>.sconsign.dblite</filename>
 126 is assumed by default.
 127 </para>
 128
 129 </refsect1>
 130
 131 <refsect1 id='options'>
 132 <title>OPTIONS</title>
 133 <para>Various options control what information is printed
 134 and the format:</para>
 135
 136 <variablelist>
 137   <varlistentry>
 138   <term>
 139     <option>-a</option>,
 140     <option>--act</option>,
 141     <option>--action</option>
 142   </term>
 143   <listitem>
 144 <para>Prints only the build action information
 145 for all entries or the specified entries.</para>
 146
 147   </listitem>
 148   </varlistentry>
 149   <varlistentry>
 150   <term>
 151     <option>-c</option>,
 152     <option>--csig</option>
 153   </term>
 154   <listitem>
 155 <para>Prints only the content signature (csig) information
 156 for all entries or the specified entries.</para>
 157
 158   </listitem>
 159   </varlistentry>
 160   <varlistentry>
 161   <term>
 162     <option>-d <replaceable>DIRECTORY</replaceable></option>,
 163     <option>--dir=<replaceable>DIRECTORY</replaceable></option>
 164   </term>
 165   <listitem>
 166 <para>When the signatures are being
 167 read from a
 168 <filename>.dblite</filename>
 169 file, or the
 170 <option>-f dblite</option>
 171 or
 172 <option>--format=dblite</option>
 173 options are used,
 174 prints information about
 175 only the signatures
 176 for entries in the specified
 177 <replaceable>DIRECTORY</replaceable>.</para>
 178
 179   </listitem>
 180   </varlistentry>
 181   <varlistentry>
 182   <term>
 183     <option>-e <replaceable>ENTRY</replaceable></option>,
 184     <option>--entry=<replaceable>ENTRY</replaceable></option>
 185   </term>
 186   <listitem>
 187 <para>Prints information about only the specified
 188 <replaceable>ENTRY</replaceable>.
 189 Multiple <option>-e</option> options may be used,
 190 in which case information about each
 191 <replaceable>ENTRY</replaceable>
 192 is printed in the order in which the
 193 options are specified on the command line.</para>
 194
 195   </listitem>
 196   </varlistentry>
 197   <varlistentry>
 198   <term>
 199     <option>-f <replaceable>FORMAT</replaceable></option>,
 200     <option>--format=<replaceable>FORMAT</replaceable></option>
 201   </term>
 202   <listitem>
 203 <para>The file(s) to be printed
 204 are in the specified
 205 <replaceable>FORMAT</replaceable>.
 206 Legal values are
 207 <emphasis role="bold">dblite</emphasis>
 208 (the SCons.dblite format used by default,
 209 as well as when the
 210 <function>SConsignFile</function>
 211 function is called, except when a filename argument
 212 of <constant>None</constant> is given)
 213 and
 214 <emphasis role="bold">sconsign</emphasis>
 215 (the format used for an individual
 216 <filename>.sconsign</filename>
 217 file in each directory).</para>
 218
 219   </listitem>
 220   </varlistentry>
 221   <varlistentry>
 222   <term>
 223     <option>-h</option>,
 224     <option>--help</option>
 225   </term>
 226   <listitem>
 227 <para>Prints a help message and exits.</para>
 228
 229   </listitem>
 230   </varlistentry>
 231   <varlistentry>
 232   <term>
 233     <option>-i</option>,
 234     <option>--implicit</option>
 235   </term>
 236   <listitem>
 237 <para>Prints the list of cached implicit dependencies
 238 for all entries or for the specified entries.</para>
 239
 240   </listitem>
 241   </varlistentry>
 242   <varlistentry>
 243   <term><option>--raw</option></term>
 244   <listitem>
 245 <para>Prints a pretty-printed representation
 246 of the raw Python dictionary that holds
 247 build information about individual entries
 248 (both the entry itself and its implicit dependencies).
 249 An entry's build action is still printed in its usual format.</para>
 250
 251   </listitem>
 252   </varlistentry>
 253   <varlistentry>
 254   <term>
 255     <option>-r</option>,
 256     <option>--readable</option>
 257   </term>
 258   <listitem>
 259 <para>Prints timestamps in a human-readable string,
 260 enclosed in single quotes.</para>
 261
 262   </listitem>
 263   </varlistentry>
 264   <varlistentry>
 265   <term>
 266     <option>-t</option>,
 267     <option>--timestamp</option>
 268   </term>
 269   <listitem>
 270 <para>Prints the timestamp information
 271 for all entries or the specified entries.</para>
 272
 273   </listitem>
 274   </varlistentry>
 275   <varlistentry>
 276   <term>
 277     <option>-v</option>,
 278     <option>--verbose</option>
 279   </term>
 280   <listitem>
 281 <para>Prints labels identifying each field being printed.</para>
 282
 283   </listitem>
 284   </varlistentry>
 285 </variablelist>
 286 </refsect1>
 287
 288 <refsect1 id='environment'>
 289 <title>ENVIRONMENT</title>
 290 <variablelist>
 291   <varlistentry>
 292   <term><envar>SCONS_LIB_DIR</envar></term>
 293   <listitem>
 294 <para>Specifies the directory that contains the SCons Python module directory
 295 (e.g.
 296 <filename class='directory'>/home/aroach/scons-src/SCons</filename>).
 297 </para>
 298
 299   </listitem>
 300   </varlistentry>
 301 </variablelist>
 302 </refsect1>
 303
 304 <refsect1 id='see_also'>
 305 <title>SEE ALSO</title>
 306 <para>
 307 The &SCons; reference (manpage) at
 308 <ulink url="https://scons.org/doc/production/HTML/scons-man.html"/>,
 309 the SCons User Guide at
 310 <ulink url="https://scons.org/doc/production/HTML/scons-user.html"/>,
 311 the SCons source code
 312 <ulink url="https://github.com/SCons/scons">
 313 on GitHub</ulink>.
 314 </para>
 315 </refsect1>
 316
 317 <refsect1 id='authors'>
 318 <title>AUTHORS</title>
 319 <para>Originally: Steven Knight <email>knight@baldmt.com</email>
 320   and Anthony Roach <email>aroach@electriceyeball.com</email>.</para>
 321   <para>
 322 Since 2010: The SCons Development Team <email>scons-dev@scons.org</email>.
 323 </para>
 324 </refsect1>
 325 </refentry>