Skip to content
This repository
Newer
Older
100644 158 lines (106 sloc) 5.758 kb
e2d48d31 »
2011-11-03 mv docs/{tracing,environment}.pod and update
1 =head1 Synopsis
2
3 Environment variables available in the Niecza (.NET) runtime
4
5 =head1 General
6
7 Niecza has a large number of debug modes which can be activated by
8 adding an environment variable. Most of these are boolean options
9 which enable a specific form of debug output. Boolean options only
10 care about the presence or absence of the named environment variable.
11
12 =head1 Non-debug options
13
14 =head2 C<NIECZA_CODEGEN_UNVERIFIABLE>
15
16 Removes redundant C<unbox.any> instructions from the generated IL stream,
17 improving performance slightly at the expense of making the generated
18 code unverifiable (and likely to segfault in critical failure scenarios).
19
20 =head2 C<NIECZA_KEEP_IL>
21
22 Instructs the module saver to save a copy of the CgOp-level code in the
23 generated C<.ser> files. Used as part of the bootstrap procedure
24 (see L<compiler.pod>) and also for cross-compiling.
25
26 =head1 Special mention
27
28 =head2 C<NIECZA_FAIL_FAST>
29
30 Processed by the compiler, not the runtime. Disables the normal conversion
31 of exceptions to SORRYs, allowing you to see the full backtrace.
32
33 =head1 Debug options
34
35 =head2 C<NIECZA_ALL_EXCEPTIONS>
36
37 When set, all Perl 6 level exceptions (not internal ones like
38 ExitRunloopException or ResumeUnwindException) will be printed as if they
39 were unhandled, whether they are actually handled or not. Prints at a
40 very early stage so it's useful in cases where exception handling itself
41 is seriously broken.
42
43 =head2 C<NIECZA_C3_TRACE>
44
45 Displays a running account of the state of the C3 superclass linearization
46 algorithm.
47
48 =head2 C<NIECZA_CLR_TRACE>
49
50 Generates some debug info from the CLR object wrapper generator.
51
52 =head2 C<NIECZA_CODEGEN_TRACE>
53
54 This is an integer parameter. If set to 1, an informative message will be
55 printed before generating CLR methods for any Perl 6 block. If set to 2,
56 individual steps in the NamProcessor.Scan recursion will be logged.
57
58 =head2 C<NIECZA_DEFER_TRACE>
59
60 Setting this when running the compiler causes the equivalent of
61 setting C<NIECZA_TRACE=all> in the context of the child only. Useful
62 for debugging problems that appear only in compile-and-run mode,
63 since it avoids tracing the compiler itself (a procedure which generates
64 much unneeded output, wasting time and space).
65
66 =head2 C<NIECZA_DIE_AT_PCT>
67
68 Throw an exception and generate a stack dump at a specific point in the
69 parsing process. Only meaningful in conjunction with
70 C<NIECZA_HIGHWATER_TRACE>; for instance, setting this to C<53> will die
71 immediately after the generation of the "53%" status report.
72
73 =head2 C<NIECZA_FORCE_SAVE>
74
75 Causes C<.dll> files to be generated for all MSIL emission, even MSIL
76 emission that would not normally be saved such as for evals and BEGIN
77 blocks.
78
79 =head2 C<NIECZA_HIGHWATER_TRACE>
80
81 Generates running status reports for all regex matches against long
82 strings (greater than 100 characters). The status measured is the
83 high-water mark, the highest character position yet seen (for speed
84 reasons, this is only sampled when backtracking, at the end of rules,
85 and on entry to longest-term matching).
86
87 =head2 C<NIECZA_JSYNC_WRITER_FAILSOFT>
88
89 Encode unencodable objects as the string C<"UNSERIALIZABLE Type">, to
90 make it easier to find them in the data structure.
91
92 =head2 C<NIECZA_LTM_TRACE>
93
94 Generates extensive reports on the construction and use of longest-term
95 automata.
96
97 =head2 C<NIECZA_MMD_TRACE>
98
99 Dumps the status of the overloading resolution algorithm (currently only
100 used for CLR overloaded methods).
101
102 =head2 C<NIECZA_RX_TRACE>
103
104 Traces entry and exit to all regex methods. Each trace point includes
105 the position of the attempt; exits include success/failure information
106 and match range if applicable. Also traces C<< <ws> >>.
107
108 =head2 C<NIECZA_SER_FAIL_INFO>
109
110 Normally exceptions generated during the thaw process are treated as
111 indications of an incompatible format change too fundamental for the
112 signature and version number to be correctly parsed, so they are not
113 shown to the user. This option causes such exceptions to be displayed.
114
115 =head2 C<NIECZA_SER_TRACE>
116
117 Dumps information on the saving and loading of objects from serialized
118 store files, in particular types and file offsets. Useful for inspecting
119 store files and debugging synchronization failures between save and load.
120
121 =head2 C<NIECZA_TRACE>
122
123 This enables per-operation tracing by instrumenting the trampoline.
124 It may be set to C<all> or C<stat>. If it is set to C<all>, then the
125 call tree will be printed in real time; each trampoline bounce displays
126 a node and the current call depth. If it is set to C<stat>, then the
127 call stack will be printed every 1 million bounces (by default).
128
129 The C<all> mode is useful for debugging the context of crashes,
130 especially infinite loops in a single operation. For Perl 6-level
131 infinite loops, C<stat> is more useful; C<stat> can also be used as a
132 primitive profiler, though its utility is limited by the fact that it
133 does not count real time.
134
135 =head2 C<NIECZA_TRACE_CALLS>
136
137 This dumps all edges in the callgraph for profiling purposes. The
138 C<perf/call-log-analyze.pl> script transforms the output into a
139 more readable form.
140
141 =head2 C<NIECZA_TRACE_DOWNCALLS>
142
143 Setting this causes all interaction between the Perl 6 compiler proper
144 and the C# runtime stub to be logged; for instance creation of subs,
145 creation of packages, installation of sub code, and variable lookups.
146
147 =head2 C<NIECZA_TRACE_PERIOD>
148
149 This sets the display interval for C<NIECZA_TRACE=stat>. Defaults to
150 C<1000000>. Setting it lower is potentially useful in a profiling
151 context.
152
153 =head2 C<NIECZA_VERBOSE_EXCEPTIONS>
154
155 Displays details of call arguments like C<callframe.args.perl> in
156 backtraces in addition to the usual C<$?FILE> / C<$?LINE> / C<&?BLOCK.name>
157 information. Has an unfortunate tendency to cause infinite loops.
Something went wrong with that request. Please try again.