NAME

       creduce - C and C++ program reducer

DESCRIPTION

       creduce 2.11.0 (unknown) -- a C and C++ program reducer

       C-Reduce requires an "interestingness test" and one or more files to reduce, which must be
       writable. The interestingness test is an executable program (usually a shell script)  that
       returns 0 when a partially reduced file is interesting (a candidate for further reduction)
       and returns non-zero when a partially reduced file is not interesting (not a candidate for
       further reduction -- all uninteresting files are discarded).

       C-Reduce  runs the interestingness test in a fresh temporary directory containing only the
       partially reduced file(s). Thus,  when  the  interestingness  test  examines  a  partially
       reduced file, it must do so using a relative path to the current working directory. On the
       other hand, when the interestingness test refers to any file that is  not  being  reduced,
       this should be done using an absolute path.

       The  interestingness  test  should be deterministic and should not expect any command line
       arguments.

       C-Reduce can and does introduce  infinite  loops  during  reduction.  Therefore,  if  your
       interestingness  test  runs the compiled program, this should be done under a timeout. You
       can implement the timeout yourself, for example  using  the  UNIX  "timeout"  command,  or
       alternatively  you  can  give  C-Reduce a timeout (which is on by default, but is set very
       long: 5 minutes). An advantage of using C-Reduce's timeout is that when a test  is  killed
       due  to  timing out, a message will be printed. If you do implement a timeout yourself, we
       recommend that your interestingness test returns exit code 124  when  a  subcommand  times
       out.  This  will  not  affect  the reduction but it will cause C-Reduce to print a message
       stating the interestingness test reported a  timeout.  It  is  important  to  ensure  that
       timeouts are not occurring too often (especially during C-Reduce's initial passes) or else
       C-Reduce will work poorly.

       There is a particularly subtle issue regarding timeouts, which is that the interestingness
       test  may slow down due to resource contention when C-Reduce runs multiple copies of it on
       different cores. We have observed slowdowns of  up  to  50%  due  to  (we  suspect)  cache
       thrashing.  You  must  take  this  slowdown  into  account when choosing a timeout or else
       timeouts might occur very frequently.

       As a quick example of an interestingness test, if you consider a file to be interesting if
       GCC's vectorizer fires while compiling it, you might write this shell script:

              gcc -w -O3 foo.c -S && grep xmm foo.s

       To see if your interestingness test is working, try running these commands:

              DIR=`mktemp  -d`  cp file_to_reduce [optionally, more files to reduce] $DIR cd $DIR
              /path/to/interestingness_test echo $?

       This should result in "0" being echoed to the terminal.  If  this  does  not  happen,  the
       interestingness test is flawed and C-Reduce won't be able to make use of it.

       If  you  haven't written an interestingness test before, please refer to this tutorial for
       additional guidance:

              https://embed.cs.utah.edu/creduce/using/

       If at all possible, run C-Reduce on preprocessed code, generated for example using:

              gcc -E -P file.c

       If you cannot reduce preprocessed code, you can either reduce  just  the  non-preprocessed
       file  or  else  perform a multi-file reduction on the file and its transitive includes (or
       any subset of  them).  In  the  first  case  you  need  to  set  the  CREDUCE_INCLUDE_PATH
       environment  variable  to  a  colonseparated  list  of  include  directories  in order for
       clang_delta to find them.

       If your interestingness test involves a cross compiler  and  the  characteristics  of  the
       cross target differs from the host you will need to set CREDUCE_TARGET_TRIPLE to match the
       cross target. This is particularly important if you are working with non-preprocessed code
       and use CREDUCE_INCLUDE_PATH.

       Press  "s"  at any time to skip to the next pass (this feature is disabled unless the Perl
       module Term::ReadKey is available on your system).

   Summary of options:
       --abs-timing
              Print timestamps about reduction progress using absolute time

       --add-pass <pass> <sub-pass> <priority>
              Add the specified pass to the schedule

       --also-interesting <exitcode>
              A process exit code (somewhere in the range  64-113  would  be  usual)  that,  when
              returned  by  the  interestingness  test, will cause C-Reduce to save a copy of the
              variant [default: -1]

       --debug
              Print debug information

       --die-on-pass-bug
              Terminate C-Reduce if a pass encounters an otherwise non-fatal problem

       --max-improvement <bytes>
              Largest improvement in file size from a single transformation that C-Reduce  should
              accept (useful only to slow C-Reduce down)

       --n <N>
              Number of cores to use; C-Reduce tries to automatically pick a good setting but its
              choice may be too low or high for your situation

       --no-cache
              Don't cache behavior of passes

       --no-default-passes
              Start with an empty pass schedule

       --no-give-up
              Don't give up on a pass that hasn't made progress for 50000 iterations

       --no-kill
              Wait for parallel instances to terminate on their own instead of killing them (only
              useful for debugging)

       --not-c
              Don't  run  passes that are specific to C and C++, use this mode for reducing other
              languages

       --print-diff
              Show changes made by transformations, for debugging

       --remove-pass <pass> [sub-pass]
              Remove all instances of the specified pass from the schedule.

       --save-temps
              Don't delete /tmp/creduce-xxxxxx directories on termination

       --shaddap
              Suppress output about non-fatal internal errors

       --skip-initial-passes
              Skip initial passes (useful if input is already partially reduced)

       --skip-key-off
              Disable skipping the rest of the current pass when "s" is pressed

       --sllooww
              Try harder to reduce, but perhaps take a long time to do so

       --tidy Do not make a backup copy of each file to reduce as file.orig

       --timeout
              Interestingness test timeout in seconds [default: 300]

       --timing
              Print timestamps about reduction progress

       --version
              Print the version information

       usage: creduce [options] interestingness_test file_to_reduce [optionally,  more  files  to
       reduce]

              creduce --help for more information