Recent Changes - Search:

Analysis

(:toc:)

Wize Analysis

Wize analysis features are generally accessed via wted Commands/Run-Tcl menu option. This section pertains to the direct or command-line usage.

Wize introduces a new -W flag to Tcl/Tk, for accessing it's analysis features. Two forms are available. The first form, -Wall should be familiar to anyone experienced with C development using GNU's C Compiler gcc. As in gcc, all is an argument to -W that specifies the warning level used.

In addition to all (the default) any of the following symbolic names may be used:

   "off", "syntax", "compile", "switch", "args", "shadow",
    "ensemble", "types", "vars", "extern", "implicit", "all", "runtime", "proccalls"

This value may also be set progamatically using "::tcl_warn(level)". Note that running wize, or ted as wted will default the value to "-Wall".

A second more verbose form of "-W" may be used: -Wlevel=all. The purpose of this second variant is to provide access to additional functions, eg. code-coverage and profiling. Multiple functions may be specified using comma separators. So for example, to enable code-coverage and profiling one might use:

    "wize -Wprofile=1,coverage=2"

Besides "level", Wize supports these functions:

     "level", "mask", "nowarn", "filtered", "version", "subproc",
     "strict", "profile", "coverage", "debug", "calls", "msgcat",
     "unused", "ctags"

All settings other than "level" (or "mask") take an integer argument, where "0" generally indicates "off" or disabled.

In the following sections, individual functions are described. Note that for functions producing stderr output (except ctags) the string "-Wfunction:" is prefixed. That is -Wprofile is the prefix for "-Wprofile:".

LEVEL

As mentioned above, this sets the level for warnings. Usually it is recommended to use the default "all" or perhaps on occasion "runtime". Explanation of the values are:

    off      - Disable all warnings
    syntax   - Warn on syntax errors.
    compile  - Warn if switch/if statements aren't compiled.
    args     - Check arguments to functions
    proto    - Use proc prototypes and complain if call seen before defined.
    ensemble - Check that ensembles/module procs are defined (N/A)
    types    - Check types for calls with prototypes.
    vars     - Check variable accesses.
    extra    - Extra checking.
    all      - Do all basic checking. (the default)
    runtime  - Check arguments of runtime calls.
    proccalls- Trace proc calls.

In addition, each of the above levels may be specified with an integer. eg.

   1=syntax, 2=compile, 3=args, ... 

PROCCALLS

Setting proccalls to nonzero will cause all proc calls to be printed out to stderr. Setting proccalls to > 1 will also print the return.

DEBUG

The debug function enables command-line or gui debugging of Tcl using Wize. This loads the program and stops at the first line of code executed within a proc. Only code within procs is debugged. Code outside of procs is considered support or infra-structure. Usually an argument of 1 is used to debug. Type "help" at the prompt for a command summary.

Here is an example:

user#   wize -Wdebug=1 /tmp/bb.tcl 
#0   [foo 0] at /tmp/bb.tcl:24 
    set i 1
(tgdb)

PROFILING

Profiling support in Wize measures the amount of time in seconds spent within individual procs within an application. The following levels are provided:

  1. Each proc records its time.
  2. Also track time spent in child proc calls.

When using 2, a proc will also collect the amount of time spent inside child proc calls. Note that this does not include child commands, because the result would always be 100%. This because Tcl is really nothing more than a command dispatcher, so all time is spent in commands. Here is sample output:

    user#   wize -Wprofile=1 /tmp/bb.tcl 
    -Wprofile:      0.000621 / 1       =      0.000621 ::foo
    -Wprofile:      0.000199 / 1       =      0.000199 ::bar
    -Wprofile:##################################################
    -Wprofile:#      ttltime / callcnt =   timepercall procname
    -Wprofile:#     0.000820 / 2       =      0.000410

    user#  wize -Wprofile=2 /tmp/bb.tcl 
    -Wprofile:      0.000628 / 1       =      0.000628 [ 32%,     1] ::foo
    -Wprofile:      0.000206 / 1       =      0.000206 [  0%,     0] ::bar
    -Wprofile:##################################################
    -Wprofile:#      ttltime / callcnt =   timepercall [subcall%, subcallcnt] procname
    -Wprofile:#     0.000834 / 2       =      0.000417 [ 24%,     1]

CODE COVERAGE

The code-coverage function provides a simple but elegant method to determine which lines are never executed. This is particularly useful when used in conjunction with a test suite. Multi-levels of code coverage are provided based on the value of function argument:

  1. Summary with 1 line per proc.
  2. Adds the file name and also reports uncalled.
  3. Add summary line for missed segments.
  4. Use line.col+lines format for missed segments.
  5. Use absolute line number in file rather than offset in proc.
  6. Verbose output of all missed lines.

The following shows sample output using the various levels:

    user#  wize -Wcoverage=1 /tmp/bb.tcl 
    -Wcoverage: 100% of     20 bytes "::foo"
    -Wcoverage: 100% of     12 bytes "::bar"
    -Wcoverage:### 100% for 2 called procs (or 8% including the 1 uncalled procs). ###

    user#  wize -Wcoverage=2 /tmp/bb.tcl 
    -Wcoverage: 100% of     20 bytes "::foo" in file "/tmp/bb.tcl"
    -Wcoverage: 100% of     12 bytes "::bar" in file "/tmp/bb.tcl"
    -Wcoverage:   0% of    416 bytes "::flap" in file "/tmp/bb.tcl"
    -Wcoverage:### 100% for 2 called procs (or 8% including the 1 uncalled procs). ###

    user#  wize -Wcoverage=3 /tmp/bb.tcl 
    -Wcoverage:: "::foo" in file "/tmp/bb.tcl" missed: 27-41 
    -Wcoverage:  73% of     51 bytes "::foo" in file "/tmp/bb.tcl"
    -Wcoverage: 100% of     12 bytes "::bar" in file "/tmp/bb.tcl"
    -Wcoverage:   0% of    416 bytes "::flap" in file "/tmp/bb.tcl"
    -Wcoverage:### 78% for 2 called procs (or 11% including the 1 uncalled procs). ###

    user#  wize -Wcoverage=4 /tmp/bb.tcl 
    -Wcoverage:: "::foo" in file "/tmp/bb.tcl" missed: 3.15+14 
    -Wcoverage:  73% of     51 bytes "::foo" in file "/tmp/bb.tcl"
    -Wcoverage: 100% of     12 bytes "::bar" in file "/tmp/bb.tcl"
    -Wcoverage:   0% of    416 bytes "::flap" in file "/tmp/bb.tcl"
    -Wcoverage:### 78% for 2 called procs (or 11% including the 1 uncalled procs). ###

    user#  wize -Wcoverage=5 /tmp/bb.tcl 
    -Wcoverage:: "::foo" in file "/tmp/bb.tcl" missed: #25.15+14 
    -Wcoverage:  73% of     51 bytes "::foo" in file "/tmp/bb.tcl"
    -Wcoverage: 100% of     12 bytes "::bar" in file "/tmp/bb.tcl"
    -Wcoverage:   0% of    416 bytes "::flap" in file "/tmp/bb.tcl"
    -Wcoverage:### 78% for 2 called procs (or 11% including the 1 uncalled procs). ###

    user#  wize -Wcoverage=10 /tmp/bb.tcl 
    -Wcoverage:: "::foo" in file "/tmp/bb.tcl" missed: #25.15+14 
    "if" miss at line #25.15 : "
        incr n
      "
    -Wcoverage:  73% of     51 bytes "::foo" in file "/tmp/bb.tcl"
    -Wcoverage: 100% of     12 bytes "::bar" in file "/tmp/bb.tcl"
    -Wcoverage:   0% of    416 bytes "::flap" in file "/tmp/bb.tcl"
    -Wcoverage:### 78% for 2 called procs (or 11% including the 1 uncalled procs). ###

CALLS

The calls function outputs (for each proc) static calls to other procs and/or commands seen by the compiler. The argument to -calls is an integer mask controlling various aspects of output. Multiple values may be combined. For example, using 17 indicates to filter non-procs and empty calls.

     1  = filter non-procs
     2  = filter procs 
     4  = no-filter dups 
     8  = mark cmds with a start
     16 = filter empty 
     32 = sort called proc/cmds.

Following is some sample output:

    user#   wize -Wcalls=1 /tmp/bb.tcl 
    -Wcalls: flap ==>  
    -Wcalls: bar ==>  
    -Wcalls: foo ==>  foo bar 


    user#   wize -Wcalls=2 /tmp/bb.tcl 
    -Wcalls: flap ==>  switch error for if regexp set lindex info string return expr incr 
    -Wcalls: bar ==>  puts 
    -Wcalls: foo ==>  puts if incr 


    user#   wize -Wcalls=4 /tmp/bb.tcl 
    -Wcalls: flap ==>  switch error error for if regexp set lindex set if info string return expr incr 
    -Wcalls: bar ==>  puts 
    -Wcalls: foo ==>  puts if incr foo bar 


    user#   wize -Wcalls=8 /tmp/bb.tcl 
    -Wcalls: flap ==>  *switch *error *for *if *regexp *set *lindex *info *string *return *expr *incr 
    -Wcalls: bar ==>  *puts 
    -Wcalls: foo ==>  *puts *if *incr foo bar 

UNUSED

The unused function is used to report procs that are totally unused in an application. That is, have never been called and for which the compiler has compiled no code containing static calls the proc. Note results here should be taken with a grain of salt as dynamic calls are still possible by calling the value of a variable. Here is an example:

 user#   wize -Wunused=1 /tmp/bb.tcl
 -Wunused: ::flap

Unused calls will include many procs such as those that are called indirectly via command callbacks, such as in menus.

CTAGS

The ctags function is used to generate "tags" output which can be used to navigate through your application with VI or TED. With 'C' a tags file is generated using the "ctags" program under unix, and newer versions of "ctags" will generate Tcl tags. However, ctags will not add namespace qualifiers to procs, something that Wize does. Moreover, with Wize there is no need to specify files: you just run your program. eg.

    user#   wize -Wctags=1 myprog.tcl 2> tags

If you think program stderr output may be intermixed, post-processing may be used thus:

    mv tags; tags.old; fgrep '/^' tags.old > tags

MSGCAT

The msgcat function is used to dump all calls to the "mc" function, for supporting language translations in an application. The resulting output can be post processed to automatically generate the .msg file. If called with a value of 1, only the text is output. With a value of 2 or higher and the namespace of the program is also output. This is to facilitate namespace specific language catalogs.

    user#   wize -Wmsgcat=1 ted.tcl
    -Wmsgcat:  {All Files}
    -Wmsgcat:  File


    user#   wize -Wmsgcat=2 ted.tcl
    -Wmsgcat: ::ted {All Files}
    -Wmsgcat: ::ted File

MASK

The mask function may be used to mask out specific levels. For example, to just do args and mask out syntax/compile use -Wlevel=args,mask=3. Not normally used.

Most element values are integers, but level and mask support named. For writes to level, the symbolic names in bits may be used. For mask, a list of ints and symbolic names from bits may be used, wherein integer values are OR'ed into the result, and values prefixed with ~ are inverted. eg:

    set ::tcl_warn(mask) {syntax 0x4 ~compile ~0xffff0000}

FILTERED

Not really a function but rather an internal counter that is incremented each time a message is filtered.

NOWARN

Not really a function but rather an skip counter that is set by using the "#NOWARN: N" option. This indicates how many of the next warning messages to skip.

VERSION

The version function supports specifying a Tcl version/patch-level as a number for the application. This is a 6 digit number that includes the patch-level. For example using -Wversion=80503 indicates Tcl version 8.5 patch-level 3. This provides a shorthand way for code to check support for incremental features. Fore example:

   if {$::tcl_warn(version) >= 80503} {
      ...
   }

SUBPROC

Format messages like gcc so vim and emacs can parse errors.

STRICT

The struct function sets the default strictness checking for typedef types as used by prototypes. The values are:

  2  - topts and vopts are strict.
  10 - all types are strict.
Edit - History - Print - Recent Changes - Search
Page last modified on January 05, 2010, at 11:21 AM