=head1	NAME

tracecc - Debugging (tracing) preprocessor for C, C++, Objective-C and Java.

=head1	SYNOPSIS

  tracecc [<options>] <inputfile> <outputfile>
  tracecc [<options>] <directory>

=head1	DESCRIPTION

Tracecc converts sources containing special tracing instructions
(*.ctr, *.cpt, *.mtr, *.jtr) to C, C++, Objective-C and Java
source files (*.c, *.cpp, *.m, *.java).

Depending on the options the output file will or will not contain
instructions to write a trace (which source code positions does a program
reach, values of variables).

=head1	OPTIONS

=over	6

=item	B<-h>

Show a help text.

Long option: B<--help>

=item	B<-v>

Show the version number.

Long option: B<--version>

=item	B<-c>

Configure the program (set the options in the command line as permanent
options).

Long option: B<--configure>

=item	B<-C>

Show the permanent options.

Long option: B<--show-configuration>

=item	B<-u>

Unconfigure, remove the permanent options set by the user.

Long option: B<--unconfigure>

=item	B<-r>

Reset the program, skip permanent options set by the user and defaults
set by the administrator, use built-in defaults instead.

This option must appear before any of the following options.

Long option: B<--reset>

=item	B<-d>

Turn writing of debug instructions on.

Long option: B<--debug-enable=>I<bool>

=item	B<-d->

Turn writing of debug instructions off.

=item	B<-s>

Use standard output for debug instructions (only in combination with -d).

Long option: B<--debug-stdout=>I<bool>

=item	B<-s->

Write debug information to a file instead of standard output.

=item	B<-t>

Add timestamp to debug information.

Long option: B<--debug-timestamp=>I<bool>

=item	B<-t->

Do not add a timestamp to debug information.

=item	B<-i> I<IDE>

Debug information is printed in the style of the specified IDE or
compiler (``none'', ``gcc'' for Gnu C compiler, ``msvc'' for MS
Visual Studio C compiler, ``workshop'' for Sun Workshop C compiler
or ``tasm'' for Turbo Assembler).

Long option: B<--debug-ide=>I<IDE>

=item	B<-l>

Write ``#line ...'' information to C/C++/Objective-C output files.

Long option: B<--linenumbers=>I<bool>

=item	B<-l->

Do not write ``#line ...'' information.

=item	B<-m>

Enable make mode. When running on a directory in make mode the program
checks for each input file whether the output file exists and is up to date.
A conversion is only started if the output file does not exist or is not
up to date.

Long option: B<--make=>I<bool>

=item	B<-m->

Disables makde mode.

=item	B<-p>

Allows C++ style comments. By default the program converts all C++ style
comments ``//'' to C style comments ``/* ... */''.

Long option: B<--cpp-comments=>I<bool>

=item	B<-p->

Do not allow C++ style comments.

=item	B<-b> I<width>

Sets the box width for comment boxes.

Long option: B<--boxwidth=>I<width>

=back

=head1	RETURN VALUE

The program returns an exit status 0 on success, all other values indicate
errors.

=head1	SPECIAL INSTRUCTIONS FOR TRACECC

The special instructions for tracecc in the source code are identified
by ``$'', this character is not used by C or Java.

=over	6

=item	B<$(trace-init >I<outpufile>B<)>

Starts debugging and specifies the output file name.
The suggested place for this instruction is the beginning of the
main() function.

=item	B<$(trace-end)>

Ends debugging. The suggested place for this instruction is the end
of the main() function.

=item	B<$? "format", ...>

Specifies a text to print as debug information when the program reaches
this position.

When entering a function you should use something like

  $? "+ myfunction ..."

Before leaving a function (immediately before the return statement) use

  $? "- myfunction %d", result

Note: you must change ``%d'' to something matching the function result type.

=item	B<Comment box>

  $*
  This is a comment box content
  $*

will be converted to

  /* ******************************************************* */
  /* * This is a comment                                   * */
  /* ******************************************************* */

=back

=head1	AUTHOR

Dirk Krause

=head1	COPYRIGHT AND LICENSE

Copyright (c) 2010, Dirk Krause
All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:

 * Redistributions of source code must retain the above
   copyright notice, this list of conditions and the
   following disclaimer.

 * Redistributions in binary form must reproduce the above
   copyright notice, this list of conditions and the following
   disclaimer in the documentation and/or other materials
   provided with the distribution.

 * Neither the name of the Dirk Krause nor the names of
   contributors may be used to endorse or promote products
   derived from this software without specific prior written
   permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

=head1	SEE ALSO

trana(1), http://dktools.sourceforge.net/tracecc.html

