=pod

=head1 NAME

B<ooprolog> - Object Oriented Analysis Steps of OOAnalyzer in Prolog

=head1 SYNOPSIS

ooprolog [--facts <file> | --results <file>] [options]

ooprolog --help

=head1 DESCRIPTION

B<ooprolog> runs the Prolog analysis phase of the OOAnalyzer tool as a
stand-alone command.  Running the Prolog analysis step separately from
the B<ooanalyzer> command has multiple benefits for monitoring the
progress of the object oriented recovery, and allowing easier restarts
following failures.  More documentation can be found by following the
"notes" link at the end of the B<OOAnalyzer> section on the Pharos Github
page.

In the most commonly used mode, where the B<--facts> option has been
specified, it reads a Prolog facts file generated by the B<ooanalyzer>
command, runs the Prolog analysis to recover the object oriented
constructs.  Typically the user specifies either the B<--results> option
to generate a Prolog results file, and/or the B<--json> option to
generate JSON output suitable for use with the OOAnalyzer plugins for
HexRays and Ghidra.

If the B<--facts> option its not specified, the B<--results> option is
instead treated as an input file, reading the Prolog results from an
earlier execution of either B<ooanalyzer> or B<ooprolog>.  Typically the
B<--json> option is specified to generate a JSON output file from the
results.

Except for specifying either B<--facts> or B<--results>, no other options
are required,

=head1 OPTIONS

The following options are specific to the B<ooprolog> program.

=over 4

=item B<--facts>=I<FACTS_FILE>, B<-f>=I<FACTS_FILE>

Read the Prolog-format facts file generated by OOAnalyzer.  This is the
typical input format for the B<ooprolog> command.

=item B<--json>=I<JSON_FILE>, B<-j>=I<JSON_FILE>

Convert the results, which were either generated from the facts file, or
read from the results file to the JSON format. This file will describe
class member layout, the assignment of methods to classes, inheritance
relationships between classes, special methods like constructors, and
other object-oriented (OO) properties.  While the JSON file is human
readable to some extent, the results are intended to be used in
conjunction with the OOAnalyzer HexRays and Ghidra plugins which will
present an interactive representation of the recovered classes. 

=item B<--results>=I<RESULTS_FILE>, B<-r>=I<RESULTS_FILE>

Either generate the specified results file from the facts file specified
by the B<--facts> option or read the previously generated results from
the specified file.

=item B<--ground>=I<GROUND_FILE>, B<-g>=I<GROUND_FILE>

Read the "ground truth" from the specified file, and compare the results
with the generated results.  Report any differences to the appropriate
logging levels (info and error primarily).  This feature is experimental,
there is currently no documentation for the ground truth file format, and
there are no publicly released tools for generating the ground truth.
You may be able to reverse engineer some of the details from the code,
and we may release additional tools to support this feature in the future.

=item B<--rtti>=I<true|false>, B<-R>=I<true|false>

Enable or disable Run Time Type Information (RTTI).  RTTI is enabled by
default (B<--rtti=true>).  There's typically no reason to specify this
option since using RTTI is almost always beneficial, but in some rare
cases where the RTTI information is corrupt or misleading, it may be
useful to disable it.  This option can also used to compare the accuracy
of OOProlog with and without the assistance of RTTI.  

=item B<--guess>=I<true|false>, B<-G>=I<true|false>

Enable or disable speculative reasoning.  Guessing is enabled by default
(B<--guess=true>).  There's typically no reason to specify this option
since guessing almost always significantly improves the quality of the
results.

Ideally, OOProlog (and OOAnalyzer) would be able to reason conclusively
about the object-oriented facts extracted from the executable.  In
practice, many object-oriented constructs are often sufficiently
ambiguous in the executable that it is not possible to reach a conclusion
with rigor.  OOProlog uses a speculative reasoning mechanism
(colloquially called "guessing") that allows the tool to make educated
guesses which are often based on the absence of evidence contrary to the
guess.  If the guess is found to be in contradiction to known facts, the
opposite conclusion will be guessed instead.  This option disables
guessing, which often results in dramatically faster (and less complete)
analysis.  This option can also used to compare the accuracy of OOProlog
with and without the assistance of speculative reasoning.

=item B<--log-level>=I<#>, B<-l>=I<#>

Sets the logging level, determining how much output is generated.  Log
level 1 is fatal errors, level 2 is non-fatal errors, level 3 is
warnings, level 4 is informational messages, and levels 5-7 are
increasing level of debugging. This option can be very educational for
understanding how OOAnalyzer reasons about the program, explores
different possibilities, and handles contradictory data.

=item B<--config>=I<CONFIG_FILE>, B<-C>=I<CONFIG_FILE>

Look for OOProlog's Prolog implementation files in a location derived
from the contents of the given I<CONFIG_FILE>, which should be a pharos
YAML config file.

=item B<--stack-limit>=I<#>, B<-S>=I<#>

This option sets the SWI Prolog stack limit.  Because the analysis of
large object-oriented programs often requires a lot of stack space, this
value defaults to a value that is quite high (200GB) consuming available
RAM as needed.  If the stack limit is exceeded, the OOProlog command will
ask you to increase this value.  If you want to prevent excessive RAM
consumption, you may need to set this option.

=item B<--table-space>=I<#>, B<-T>=I<#>

This option sets the SWI Prolog table space limit.  Because the analysis
of large object-oriented programs often requires a lot of table space,
this value defaults to a value that is quite high (200GB) consuming
available RAM as needed.  If the stack limit is exceeded, the OOProlog
command will ask you to increase this value.  If you want to prevent
excessive RAM consumption, you may need to set this option.

=item B<--library-path>=I<PROLOG_DIR>, B<-T>=I<PROLOG_DIR>

Set the I<PROLOG_DIR> to be the path that B<ooprolog> uses to find its
Prolog implementation files.  Generally this option does not need to be
set.

=item B<--halt>=I<true|false>, B<-H>=I<true|false>

It is sometimes helpful when debugging OOProlog to interact with the
Prolog command prompt and pose Prolog queries to inspect the results.  By
specifying B<--halt=false>, the OOProlog will open an interactive SWI
Prolog shell after the analysis phase.   The default value is true. 

=item B<--help>, B<-h>

Output program option help information and exit.

=back

=head1 EXAMPLES

A typical invocation of OOProlog to convert facts from OOAnalyzer into
results and a JSON file suitable for use with the plugins:

  $ ooprolog --facts facts.pl --results results.pl --json output.json

To regenerate the JSON file from a previously generated results file
without re-running the expensive analysis step:

  $ ooprolog --results results.pl --json output.json

To examine the initial conclusions reached by OOProlog without the
assistance of speculative reasoning or RTTI type information:

  $ ooprolog --facts facts.pl --rtti=false --guess=false --log-level=7

=head1 NOTES

OOProlog results are intended to be identical to those generated by the
OOAnalyzer.  In some cases (e.g. JSON generation) different
implementations are used which may result in minor differences, but these
are unintentional.

=head1 AUTHOR

Written by the Software Engineering Institute at Carnegie Mellon
University.  The primary authors were Michael Duggan, Cory Cohen, and
Edward Schwartz.

=head1 COPYRIGHT

Copyright 2020 Carnegie Mellon University.  All rights reserved.  This
software is licensed under a "BSD" license.  Please see F<LICENSE.txt>
for details.

=head1 SEE ALSO

L<ooanalyzer(1)>

=cut

Local Variables:
mode:text
fill-column: 73
indent-tabs-mode:nil
End:
