The commands are orion, for use on the command line, and cco, for use in makefiles.
A simplified syntax of the orion command is:
orion -@local [<preprocessor options>] file ...
Some examples are here. An overview of all options is provided by typing orion -help.
This performs a local (per-function) analysis on one or more source files. Orion-specific options have an @; the remaining options are passed to the preprocessor. Orion will display a summary of its findings on the standard output, while a more detailed report, including error traces, is written to ORION.report.
C and C++ files may be given to orion in a single command. File extensions are used to distinguish C from C++, following the conventions of GCC. That is, extensions .c denote C files, and .cc, .cxx, .cpp, and .C (uppercase) denote C++. Files ending in .i and .ii are taken to be C, resp. C++ code that should not be preprocessed.
The names of the source files to be analyzed may alternatively be specified in a file (called the project file), one file per line. If myproject is the project file, then Orion is invoked by "orion -@project myproject". The report file will be called myproject.report in this case. Preprocessor options may still be specified, but will be the same for all source files mentioned in the project file. For more complicated builds, it may be more convenient to use the cco command - see cco: Integrating Orion in the makefile.
If the -@append option is given, Orion will append its detailed messages to the report file.
The option -@local indicates that Orion should perform a local analysis for each file, i.e. individual function bodies are analyzed (intra-procedural analysis). This analysis includes checks for use of uninitialized variables, null-pointer dereferences, and out-of-bound array indexing.
The precision of the analysis can be chosen through the option -@precision N, where N is a number in the range 0..10. This value influences the time available to the external solver engine to attempt to determine the feasibility of each execution trace that represents a possible violation. The default value is 1, which means that Orion applies its own built-in decision procedures. With values 2 and higher, the more powerful external solvers are invoked; the higher the value, the more time these solvers will spend on each trace. Value 0 suppresses all but the simplest feasibility checks.
For every source file, say foo.c, that it analyzes, orion creates a file foo.orion. This so-called summary file contains information that orion can use in a subsequent global (inter-procedural and inter-file) analysis. The creation of summary files is suppressed by the -@nosum option.
WARNING: The global analysis sometimes leads to internal errors and tends to be less useful than the local one.
Example:
orion -@global -@gstart prog.c:foo -@project myproject
When given the option -@global, orion checks for use-before-def errors of global pointer variables. In this case it performs an interprocedural analysis, considering execution paths across function boundaries (calls and returns). The option -@gstart specifies the starting point of these paths; in the example it is function foo in file prog.c. The option's value defaults to main.c:main.
A global analysis is typically performed on a "complete" program that is split across multiple files. These may be specified in a project file or on the command line. Orion tries to re-use information that has been computed during a previous (local) analysis, if any, as stored in the summary files. Whenever no summary file exist, or the modification time of the corresponding .c file is later, the summary is recomputed (so it is wasteful to specify the -@nosum option when both -@local and -@global are present).
For every potential global use-before-def error, Orion reports the name of the pointer variable together with a list of places where it is used. If the use is a dereference, then this is explicitly indicated - a dereference of a non-initialized pointer has a higher likelihood of being an error. Orion does not report individual error traces on the global level, because there tend to be too many of those. For the same reason, it does not perform a per-path feasibility check in this case. As a result, the -@precision option has no effect on the global analysis.
As a byproduct of the global analysis, Orion may produce warnings about functions that do not return.
The cco command (for cc + Orion) is provided for use in makefiles, and is meant to replace whatever command is used to invoke the compiler. cco still does the compilation, but in addition it performs an analysis by orion.
Example:
cco -@cc /usr/bin/cc -@cflags "-fullwarn" -@precision 5 foo.c
The -@cc specifies the compiler to invoke, with options as specified (enclosed in double quotes) after the -@cflags option. Here is a more detailed description.