← Back to branch summary

~ubuntu-branches/ubuntu/saucy/gnash/saucy-proposed

« back to all changes in this revision

Viewing changes to doc/C/refmanual/logging.xml

  • Committer: Bazaar Package Importer
  • Author(s): Alexander Sack
  • Date: 2008-10-13 14:29:49 UTC
  • mfrom: (1.1.9 upstream)
  • Revision ID: james.westby@ubuntu.com-20081013142949-f6qdvnu4mn05ltdc
Tags: 0.8.4~~bzr9980-0ubuntu1
https://launchpad.net/bugs/240325
* new upstream release 0.8.4 (LP: #240325)
* ship new lib usr/lib/gnash/libmozsdk.so.* in mozilla-plugin-gnash
  - update debian/mozilla-plugin-gnash.install
* ship new lib usr/lib/gnash/libgnashnet.so.* in gnash-common
  - update debian/gnash-common.install
* add basic debian/build_head script to build latest CVS head packages.
  - add debian/build_head
* new sound architecture requires build depend on libsdl1.2-dev
  - update debian/control
* head build script now has been completely migrated to bzr (upstream +
  ubuntu)
  - update debian/build_head
* disable kde gui until klash/qt4 has been fixed; keep kde packages as empty
  packages for now.
  - update debian/rules
  - debian/klash.install
  - debian/klash.links
  - debian/klash.manpages
  - debian/konqueror-plugin-gnash.install
* drop libkonq5-dev build dependency accordingly
  - update debian/control
* don't install headers manually anymore. gnash doesnt provide a -dev
  package after all
  - update debian/rules
* update libs installed in gnash-common; libgnashserver-*.so is not available
  anymore (removed); in turn we add the new libgnashcore-*.so
  - update debian/gnash-common.install
* use -Os for optimization and properly pass CXXFLAGS=$(CFLAGS) to configure
  - update debian/rules
* touch firefox .autoreg in postinst of mozilla plugin
  - update debian/mozilla-plugin-gnash.postinst
* link gnash in ubufox plugins directory for the plugin alternative switcher
  - add debian/mozilla-plugin-gnash.links
* suggest ubufox accordingly
  - update debian/control
* add new required build-depends on libgif-dev
  - update debian/control
* add Xb-Npp-Description and Xb-Npp-File as new plugin database meta data
  - update debian/control

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/C/refmanual/logging.xml
 
1
<sect2 id="logging">
 
2
  <title>The Message Logging System</title>
 
3
  
 
4
  <para>
 
5
    &app;'s common message logging system uses a <emphasis>printf()</emphasis>
 
6
    style format. Despite the C-like appearance, however, &app;'s LogFile class
 
7
    by default does not use <emphasis>printf()</emphasis> for formatting the
 
8
    messages at all.
 
9
  </para>
 
10
  
 
11
  <para>
 
12
    All logging calls are converted using templated functions to use boost::format.
 
13
    This uses a similar syntax to printf(), but additionally guarantees type-safety
 
14
    and allows more advanced substition using positional identifiers besides the
 
15
    traditional printf() type identifiers. The conversion templates mean that
 
16
    the logging API remains exactly the same, regardless of which method is
 
17
    used to format the log output.
 
18
  </para>  
 
19
 
 
20
  <para>
 
21
    The templates for conversion are generated using Boost.Preprocessor. Currently,
 
22
    they allow for a maximum of 16 arguments (more than enough for all current 
 
23
    usage), but that can be expanded or reduced by changing 
 
24
    <emphasis>#define ARG_NUMBER</emphasis> in <emphasis>libbase/log.h</emphasis>.
 
25
  </para>  
 
26
 
 
27
  <para>
 
28
    If a filename is not specified before the log file is needed, a
 
29
    default name of <emphasis>gnash-dbg.log</emphasis> is used. If Gnash is
 
30
    started from the command line, the debug log will be created in
 
31
    the current directory. When executing Gnash from a launcher under
 
32
    <emphasis>GNOME</emphasis> or <emphasis>KDE</emphasis> the debug file goes in your
 
33
    home directory, since that's considered the current directory. A file name
 
34
    can be specified using either <emphasis>gnashrc</emphasis> or a 
 
35
    call to the LogFile instance itself.
 
36
  </para>
 
37
 
 
38
  <sect3 id="api">
 
39
    <title>Logging System API</title>
 
40
 
 
41
    <para>
 
42
        &app; provides 9 specialized logging calls, each using the <emphasis>printf()</emphasis>-style
 
43
        call similar to this:
 
44
        <programlisting>log_error(const char* fmt, ...)</programlisting>
 
45
        The different
 
46
        calls and their purposes are described below. The output to stdout and to disk
 
47
        are always identical, although writing the log to disk can be separately disabled.
 
48
    </para>
 
49
 
 
50
    <variablelist>
 
51
      <varlistentry>
 
52
        <term>log_error</term>
 
53
        <listitem>
 
54
          <para>
 
55
            Display an error message if verbose output is enabled. This is
 
56
            always printed at a verbosity level of 1 or more.
 
57
          </para>
 
58
        </listitem>
 
59
      </varlistentry>
 
60
 
 
61
      <varlistentry>
 
62
        <term>log_unimpl</term>
 
63
        <listitem>
 
64
          <para>
 
65
            Displays a warning to the user about missing Gnash features.
 
66
            We expect all calls to this function to disappear over time, as we
 
67
            implement those features of Flash. This is
 
68
            always printed at a verbosity level of 1 or more.
 
69
          </para>
 
70
        </listitem>
 
71
      </varlistentry>
 
72
      
 
73
      <varlistentry>
 
74
        <term>log_trace</term>
 
75
        <listitem>
 
76
          <para>
 
77
            Used only for the output of the ActionScript <emphasis>trace()</emphasis>
 
78
             function. This is
 
79
            always printed at a verbosity level of 1 or more.
 
80
          </para>
 
81
        </listitem>
 
82
      </varlistentry>
 
83
      <varlistentry>
 
84
        <term>log_debug</term>
 
85
        <listitem>
 
86
          <para>
 
87
            Logs debug information. This is printed at a verbosity level of 2 or more.
 
88
          </para>
 
89
        </listitem>
 
90
      </varlistentry>
 
91
      <varlistentry>
 
92
        <term>log_action</term>
 
93
        <listitem>
 
94
          <para>
 
95
            Log action execution information. Wrap all calls to this
 
96
            function (and other related statements) into an
 
97
            IF_VERBOSE_ACTION macro, so to allow completely removing
 
98
            all the overhead at compile time and reduce it at
 
99
            runtime. This is printed at a verbosity level of 1 or more
 
100
            only if action logging is enabled.
 
101
          </para>
 
102
        </listitem>
 
103
      </varlistentry>
 
104
      <varlistentry>
 
105
        <term>log_parse</term>
 
106
        <listitem>
 
107
          <para>
 
108
            Log SWF parsing  Wrap all calls to this function (and
 
109
            other related statements) into an IF_VERBOSE_PARSE macro,
 
110
            so to allow completely removing all the overhead at
 
111
            compile time and reduce it at runtime. This is printed at a
 
112
            verbosity level of 1 or more
 
113
            only if parser logging is enabled.
 
114
          </para>
 
115
        </listitem>
 
116
      </varlistentry>
 
117
      <varlistentry>
 
118
        <term>log_security</term>
 
119
        <listitem>
 
120
          <para>
 
121
            Display a message with security related information. This is always
 
122
            printed at a verbosity level of 1 or more.
 
123
          </para>
 
124
        </listitem>
 
125
      </varlistentry>
 
126
      <varlistentry>
 
127
        <term>log_swferror</term>
 
128
        <listitem>
 
129
          <para>
 
130
            This indicates an error in how the binary SWF file was
 
131
            constructed, i.e.probably a bug in the tools used to build
 
132
            the SWF file. Wrap all calls to this function (and other
 
133
            related statements) into an IF_VERBOSE_MALFORMED_SWF
 
134
            macro, so to allow completely removing all the overhead at
 
135
            compile time and reduce it at runtime. This is printed at a
 
136
            verbosity level of 1 or more
 
137
            only if malformed SWF logging is enabled.
 
138
          </para>
 
139
        </listitem>
 
140
      </varlistentry>
 
141
 
 
142
      <varlistentry>
 
143
        <term>void log_aserror</term>
 
144
        <listitem>
 
145
          <para>
 
146
            This indicates an erroneous actionscript request such as
 
147
            an incorrect number of arguments or an invalid argument.
 
148
            Wrap all calls to this function (and other
 
149
            related statements) into an IF_VERBOSE_ASCODING_ERRORS
 
150
            macro, so to allow completely removing all the overhead at
 
151
            compile time and reduce it at runtime. 
 
152
            This is printed at a
 
153
            verbosity level of 1 or more
 
154
            only if AS coding error logging is enabled.
 
155
          </para>
 
156
        </listitem>
 
157
      </varlistentry>
 
158
    </variablelist>
 
159
      
 
160
  </sect3>
 
161
 
 
162
    <sect3 id="logfileinstance">
 
163
    <title>The LogFile Instance</title>
 
164
 
 
165
    <para>
 
166
      This is the main API for initializing and manipulating the logging output.
 
167
      By default, the log will be written to <emphasis>gnash-dbg.log</emphasis>
 
168
      file whenever a verbose option is
 
169
      supplied.
 
170
    </para>
 
171
 
 
172
    <variablelist>
 
173
      <varlistentry>
 
174
        <term>getDefaultInstance()</term>
 
175
        <listitem>
 
176
          <para>
 
177
            This allows the construction of a LogFile on the first call, so
 
178
            ensuring that it the logfile is always initialised before use.
 
179
            It is the only way to access a LogFile instance. The logfile
 
180
            itself is never opened until it is needed.
 
181
          </para>
 
182
        </listitem>
 
183
      </varlistentry>
 
184
      <varlistentry>
 
185
        <term>setLogFilename(const std::string&amp; filename)</term>
 
186
        <listitem>
 
187
          <para>
 
188
            Use this to set a different name for the disk-based log file.
 
189
            This setting can be overridden by a directive in gnashrc. If the
 
190
            log file is already open, a call to setLogFilename() will close it;
 
191
            a file with the new name will be opened when it is next needed.
 
192
          </para>
 
193
        </listitem>
 
194
      </varlistentry>
 
195
 
 
196
      <varlistentry>
 
197
        <term>closeLog()</term>
 
198
        <listitem>
 
199
          <para>
 
200
            Close a debug log. The disk file remains.
 
201
          </para>
 
202
        </listitem>
 
203
      </varlistentry>
 
204
      <varlistentry>
 
205
        <term>removeLog()</term>
 
206
        <listitem>
 
207
          <para>
 
208
            Delete the debug log file from disk.
 
209
          </para>
 
210
        </listitem>
 
211
      </varlistentry>
 
212
      <varlistentry>
 
213
        <term>setVerbosity()</term>
 
214
        <listitem>
 
215
          <para>
 
216
            Increment the verbosity level.
 
217
          </para>
 
218
        </listitem>
 
219
      </varlistentry>
 
220
      <varlistentry>
 
221
        <term>setVerbosity(int level)</term>
 
222
        <listitem>
 
223
          <para>
 
224
            Set the verbosity level to a specified level.
 
225
          </para>
 
226
        </listitem>
 
227
      </varlistentry>
 
228
      <varlistentry>
 
229
        <term>setStamp(bool flag)</term>
 
230
        <listitem>
 
231
          <para>
 
232
            If <emphasis>flag</emphasis> is <emphasis>true</emphasis>, then print a
 
233
            timestamp prefixed to every output line. If
 
234
            <emphasis>flag</emphasis> is <emphasis>false</emphasis>, then don't print
 
235
            a timestamp.
 
236
          </para>
 
237
        </listitem>
 
238
      </varlistentry>
 
239
      <varlistentry>
 
240
        <term>setWriteDisk(bool flag)</term>
 
241
        <listitem>
 
242
          <para>
 
243
            If <emphasis>flag</emphasis> is <emphasis>true</emphasis>, then create the
 
244
            disk file. If <emphasis>flag</emphasis> is <emphasis>false</emphasis>,
 
245
            then don't create the disk file.
 
246
          </para>
 
247
        </listitem>
 
248
      </varlistentry>
 
249
    </variablelist>
 
250
 
 
251
  </sect3>
 
252
 
 
253
</sect2>