cli.txt

?
                    COMMAND LINE INTERFACE (CLI)
             incrs: Lists all available increments (sets of related commands)
            <incr>: Enters an increment
            <comm>: Executes a command in an increment already entered
     <incr> <comm>: Executes a command in the specified increment
       help <incr>: Lists the commands available in the specified increment
       help <comm>: Provides help for a command in an increment already entered
help <incr> <comm>: Provides help for a command in the specified increment

Adding "full" at the end of a >help command displays any detailed help
file for the specified increment or command.  >help full is equivalent to
>help <incr> full for the current increment.  The system starts up in the
>nb increment, so >help nb lists the commands that are always available.

The following are used when displaying and entering a command's parameters:
   (...)  denote alternatives for a mandatory parameter
   [...]  denote an optional parameter
       ~  skips an optional parameter
       =  tags an optional parameter
       &  obtains a symbol's value
   "..."  delimits a string with embedded blanks (treated as one parameter)
       /  precedes a comment (rest of input line is ignored)
       \  overrides any special meaning for the next character
Optional parameters must be entered in the same order that they are displayed
by >help <comm>.
/
? ct
Commands in this increment often take an expression as the last parameter.
An expression contains variables and operators.  Variables can be defined
using the >assign command.  The code library also provides the following
variables, which cannot be modified using the >assign command:
   $dirs: directories that have been added to the library by >import
  $files: all code files (headers and implementations) found in $dirs
   $hdrs: headers in $files
   $cpps: implementations (.c*) in $files
   $subs: headers that declare items which are external to the code base
   $exts: headers whose directories were not included by an >import
          (which will cause >parse to fail>
   $vars: all variables (those above, or user-defined)

An expression is evaluated left to right, but parentheses can be used to
override this.  A variable is a set of directories, files, or C++ code
items.  The following notation is used below:
  D: the name of a directory (from >import) or a set of directories
  F: the name of a specific file or a set of files
  C: the name of a C++ code item or a set of such items
  S: any of the above (D, F, or C)

The current operators are listed below.  What the operator returns is shown
on the left; this becomes the input to commands such as >assign and >type.
The type of parameter(s) that the operator expects are shown on the right:
  S: S1 | S2     set union of S1 and S2 (the '|' is optional)
  S: S1 & S2     set intersection of S1 and S2
  S: S1 - S2     set difference between S1 and S2
  F: f S         the files in S
  D: d S         the directories in S
  F: F fn <str>  files in F with the file name <str>*
  F: F ft <str>  files in F with the file type *.<str>
  F: F ms <str>  files in F with a file name that contains <str>
  F: F in D      files in F whose directory is in D
  F: im F     *  implements: for each item declared in F, add the file
                 that defines it, and vice versa
  F: us F        users: files that #include any in F
  F: ub F        used by: files that any in F #include
  F: as F        affecters: ub F, transitively
  F: ab F        affected by: us F, transitively
  F: ca F        common affecters: (as f1) & (as f2) & ... (as fN)
  F: ns F     *  needers: files that also need F in a build
                 (im ab F, transitively)
  F: nb F     *  needed by: files that F also needs in a build
                 (im as F, transitively)
  C: db S     *  declared by: code items declared within S
  C: ds C     *  declarers: code items that declare the items in C
  C: df C     *  definitions: distinct definitions of the items in C
  C: rb S     *  referenced by: code items referenced within S
  C: rs C     *  referencers: code items that reference the items in C

Here is how related unary operators act on the F parameter:
  lower layers      F parameter      higher layers
       |<----ub/as/nb----|----us/ab/ns---->|

The code must have been parsed before operators marked with an asterisk
can be used.  Parsing occurs automatically when required.

For further details, see the article "A Static Analysis Tool for C++"
at www.codeproject.com.
/
? ct.coverage
These subcommands manage databases that map functions to the testcases that
invoke them.  To support this mapping, a function must invoke Debug::ft and
be captured in a <test>.funcs.txt function trace (usually by having a script
execute >testcase begin <test>, followed by >save funcs &testcase.name).  A
code coverage database is then created as follows:

1. copy all testcase function trace summaries (*.funcs.txt) to OutputPath/
2. >read buildlib         // set up compile environment
3. >parse - win32 $files  // compile the code base (here, for Win32)
4. >check rsc $files      // finds functions that invoke Debug::ft
5. >coverage update       // scans test traces (OutputPath/*.funcs.txt) and
                          // saves the database in InputPath/coverage.db.txt

The database can be loaded later on with >coverage load.  It can then be
updated with steps 2 to 5, which finds modified functions and traces from
tests that have been added or re-executed.  The >coverage update subcommand
displays the following:

1. Functions that have been added, changed, or deleted.
2. Testcases that should be rerun to test the functions that were modified.
   The state of these testcases is also set to "reexecute" in the testcase
   database.
3. Functions that were modified but which are not invoked by any testcase.

Finally, >coverage under N lists all functions that are invoked by fewer than
N testcases, and >coverage erase deletes, from the database, a function that
is no longer valid (this should only be necessary after a template function
or a function in a class template has been removed from the code base).
/
? ct.export
The options are specified in a string that contains any of the following:
  n: namespace view: items sorted by namespace; declarations/definitions merged
  c: canonical file view: items sorted (enums-typedefs-data-functions)
  o: original file view: items in original order
  h: include class hierarchy
  s: include statistics, such as the number of reads and writes on each item
     (omitting this is useful when doing a diff between .lib files)
  u: display each file's symbol usage and recommended changes to #includes,
     usings, and forward declarations (in a separate .trim file)
  x: display the brief global cross-reference (file names as references)
  z: display the verbose global cross-reference (line numbers as references)
  k: display code comments (excludes non-text comments and those at the top
     of each file)
If no options are entered, they default to "nchsux".  At least one option
of "ncoh" must be specified to generate a .lib file.  If a cross-reference
is requested, it appears in a separate .xref file.
/
? ct.parse
The options are specified in a string that contains any of the following:
  t: display logs when compiling templates (normally suppressed because
     an item accessed through a template parameter cannot be resolved)
  p: trace function calls during parsing (mostly Parser.cpp and Lexer.cpp)
  c: generate "object code" when compiling (use >save trace <fn> afterwards)
  f: trace function calls when compiling (mostly Cxx*.cpp files)
  i: trace template instantiations (otherwise omitted)
For no options, use a hyphen ('-'). Either 'p' and/or 'c' must be specified
for any tracing to occur. If tracing is started before issuing the >parse
command, all files are traced, with ParserTracer (if selected) acting as the
option 'c' and FunctionTracer acting as options 'pf'.
/
? ct.rename
The current name can be qualified with scopes.  The following can be renamed:
namespaces, classes, data, functions, enumerations, enumerators, macros, and
typedefs.
/
? nb.sched
The following columns appear in >sched show output:
         id  Thread::Id (identifier)
       name  Thread.AbbrName (abbreviated name)
       host  SysThreadId (host identifier)
          f  Faction (w=watchdog s=system P=payload M=maintenance O=operations
                      B=background A=audit; lower case if not running locked)
          b  BlockingReason (S=sleeping N=network C=console D=database)
The following statistics are reset at the end of each 15-minute interval:
         ex  number of exceptions
     yields  number of yields
    rtc t/o  number of run-to-completion timeouts (running locked too long)
   max msgs  maximum length of message queue
  max stack  maximum stack usage
  max usecs  longest time running locked
total usecs  total time running locked
       %cpu  percentage of available CPU time used, during both the current
             15-minute interval and the most recent 5-second interval
/
? nt.testcase
These subcommands support test scripts and a testcase database.  The prolog,
epilog, recover, begin, end, and failed subcommands are used in test scripts.
The retest, query, erase, and reset subcommands are used to inspect and manage
the testcase database.  See also the >coverage command in the >ct increment,
which supports code coverage by making use of the testcase database.