%%
%% $Id$
%%
%% Copyright 1989-2016 MINES ParisTech
%%
%% This file is part of PIPS.
%%
%% PIPS is free software: you can redistribute it and/or modify it
%% under the terms of the GNU General Public License as published by
%% the Free Software Foundation, either version 3 of the License, or
%% any later version.
%%
%% PIPS is distributed in the hope that it will be useful, but WITHOUT ANY
%% WARRANTY; without even the implied warranty of MERCHANTABILITY or
%% FITNESS FOR A PARTICULAR PURPOSE.
%%
%% See the GNU General Public License for more details.
%%
%% You should have received a copy of the GNU General Public License
%% along with PIPS.  If not, see <http://www.gnu.org/licenses/>.
%%

\documentclass[a4paper]{article}

\usepackage[latin9]{inputenc}
\usepackage[backref,pagebackref]{hyperref}
\usepackage{xspace}
\usepackage{url}
\usepackage[nofancy]{svninfo}

\newcommand{\PipsTpipsPDF}{\url{http://www.cri.ensmp.fr/pips/tpips-user-manual.htdoc/tpips-user-manual.pdf}\xspace}
\newcommand{\PipsTpipsHTDOC}{\url{http://www.cri.ensmp.fr/pips/tpips-user-manual.htdoc}\xspace}
\newcommand{\PipsPIPSmakePDF}{\url{http://www.cri.ensmp.fr/pips/pipsmake-rc.htdoc/pipsmake-rc.pdf}\xspace}
\newcommand{\PipsPIPSmakeHTDOC}{\url{http://www.cri.ensmp.fr/pips/pipsmake-rc.htdoc}\xspace}
\newcommand{\PipsPIPSpropertiesPDF}{\url{http://www.cri.ensmp.fr/pips/properties-rc.htdoc/properties-rc.pdf}\xspace}
\newcommand{\PipsPIPSpropertiesHTDOC}{\url{http://www.cri.ensmp.fr/pips/properties-rc.htdoc}\xspace}


% Number all sections in the text and the TOC:
\setcounter{secnumdepth}{10}
\setcounter{tocdepth}{10}


\title{Tpips: command line interpreter}

\author{Corinne Ancourt \and Fabien Coelho \and Guillaume Oget}

\date{\svnInfoLongDate{} \emph{(revision \svnInfoRevision)}}


\begin{document}
\svnInfo $Id$

\setlength{\parindent}{0in}

\maketitle

You can get a printable version of this document on\\
\PipsTpipsPDF and a HTML version on \PipsTpipsHTDOC.

\tableofcontents

\section{Introduction}


{\tt tpips} is the {\bf line interface} and scripting language of the
PIPS project. All PIPS functionalities are available, with
on-line help and automatic completion.

{\tt tpips} is more efficient than the \texttt{pips} based scripts
(\texttt{Init}, \texttt{Display},...) because the database is not open,
read, written and closed for each command. {\tt tpips} is less
user-friendly than \texttt{wpips} and \texttt{epips}\footnote{Note that
  \texttt{wpips} and \texttt{epips} don't work anymore right now because a
  deprecated GUI library, so \texttt{tpips} is definitively the way to
  go...}, although it provides the unique opportunity to apply a
transformation or display some information on several modules with one
command, using pipsmake metavariables, \verb+%CALLERS+ and
\verb+%CALLEES+,
or environment user defined variables such as \verb+$MODULES+ %% $
(see Example~\ref{exm2}). The \texttt{jpips} future user interface will
provide these \texttt{pips}/\texttt{tpips} functionalities too.

{\tt tpips} is recommended for large benchmarks and experiments, when
analysis and optimization results do not require interactive working. {\tt
  tpips} is used for the validation of each new PIPS version.

{\tt tpips} can be used to automatically replay a manual \texttt{wpips} or
{\tt tpips} session by using \verb+logfile_to_tpips+. The
\verb+logfile_to_tpips+ command derives a {\tt tpips} script from a
logfile in a workspace (see Example~\ref{exm2}). A PIPS beginner should
start with a window interface, \texttt{wpips} or
\texttt{epips}\footnote{If they work...}, and not with \texttt{tpips}. But
the simple tools of section~\ref{sec:small-tools} can be useful for simple
tasks.

Access to Unix Shell and to PIPS properties is provided by {\tt tpips}.
PIPS properties can be modified from {\tt tpips} , and only from {\tt
  tpips} during a PIPS session (see Example~\ref{exm3}). On the other hand,
{\tt wpips} reads at the
beginning of the session the default properties and the new ones
(re)defined in the {\tt properties.rc} file, but no change can be done
afterwards.  Resetting properties during a session can be used to rebuild
an application when some modules have been updated by PIPS, e.g. after
partial evaluation.

The {\tt tpips} commands are listed on-line by the help command.
Possible arguments are completed or suggested by automatic
completion (TAB and TAB/TAB). A command may be spread on
several lines by guarding the line feed characters by
backslashes.


\section{Syntax}

Different functions can be activated with the \texttt{tpips} commands. We
decompose these functions in those related to the \emph{workspace}, the
\emph{analysis} and \emph{transformation} requests, the PIPS
\emph{properties} and \emph{options} and the the environment.  Functions
and their arguments are presented in the next subsections.


\subsection{Workspace}

The commands for workspaces are: {\tt create} a new workspace (see
\texttt{pips} command \texttt{Init}), {\tt open} an existing workspace,
{\tt close} the current workspace, and {\tt delete} the current workspace
or a specific one (see \texttt{pips} command \texttt{Delete}).

These commands can be used several times during a session or
within a {\tt tpips} script file.

\begin{description}

\item[{\bf create} $<$workspace-name$>$ $<$file-name$>$] creates and
  opens a new workspace from a source file --- or set of source files

\item[{\bf open} $<$workspace-name$>$] opens an existing workspace

\item[{\bf close} $<$workspace-name$>$] closes an opened workspace

\item[{\bf delete} $<$workspace-name$>$] deletes a closed workspace

\item[{\bf quit}] quits {\tt tpips}

\end{description}


\subsection{Requests}

To apply a transformation or request a particular resource, use the
following \texttt{tpips} commands.

For a list of the available resources and their descriptions, have a look
to \PipsPIPSmakeHTDOC or \PipsPIPSmakePDF.

\begin{description}

\item[{\bf apply} $<$rule-descriptor$>$] applies a specified rule and
  produces the associated resources.

\item[{\bf capply} $<$rule-descriptor$>$] applies concurrently a specified
  rule on the different \emph{OWNER}s of the $<$rule-descriptor$>$ and
  produces the associated resources (see Example~\ref{exm4}).

\item[{\bf display} $<$resource-descriptor$>$] makes a printable resource
  (if it does not exist) and prints it out. A printed resource is a ACSII
  file with the \verb+_FILE+ extension.

\item[{\bf make} $<$resource-descriptor$>$] makes a resource according to
  default rules

\end{description}


\subsubsection*{Generic example:}

A resource, i.e. any piece of information computed by PIPS,
can be required by command:

{\bf
\begin{verbatim*}
make <resource>
\end{verbatim*}
}

or

{\bf
\begin{verbatim*}
make <resource[owner]>
\end{verbatim*}
}

which use interproceduraly and recursively default rules (see
\texttt{pips} command \texttt{Build}). Or it is produced by a specific
rule: {\bf
\begin{verbatim}
apply <rule>
\end{verbatim}
}

which will require all its resource arguments by recursively
calling make (see \texttt{pips} command \texttt{Perform}).

The owner of a resource is the module it is attached to. By
default, the owner is assumed to be the current module.

File resources can be displayed on screen:

{\bf
\begin{verbatim}
display <printable_resource> 
\end{verbatim}
}
as with the \texttt{pips} \texttt{Display} script.


\subsection{PIPS properties and options}

For a list of the available properties and their descriptions, have a look
to \PipsPIPSpropertiesHTDOC or \PipsPIPSpropertiesPDF.

\begin{description}
\item[{\bf activate} $<$rule-name$>$] activates a rule. Several rules
  can be used to produce a resource. At any time one of these rules is the
  default rule.

\item[{\bf module} $<$module-name$>$] specifies the current module to
  work on.

\item[{\bf getproperty} $<$property-name$>$] prints the value of a PIPS
  property.

\item[{\bf setproperty} $<$property-name$>$ $<$value$>$] sets the value
  of a property --- after type check. Possible types are: boolean, int and
  string.

\item[{\bf checkpoint} $<$number$>$] checkpoints the current workspace
  every $<$number$>$ pipsmake operations.

\end{description}
 
\subsubsection*{Generic example:}

A specific current module is selected as current module with:
{\bf
\begin{verbatim}
module MODULE_NAME
\end{verbatim}
}

When several rules, i.e. functions, can be used to compute
the same resource, for instance a parallel version of a
module, the rule selection command is:

{\bf
\begin{verbatim}
activate <rule>
\end{verbatim}
}

It is equivalent to the \texttt{pips} \texttt{Select} command.

\subsection{Environment}

The {\tt tpips} Unix-related commands are: \texttt{cd}, \texttt{setenv},
\texttt{getenv}, \texttt{echo}, and \texttt{shell}.

\begin{description}

\item[{\bf shell} $<$sh-command$>$ $<$parameters$>$] Executes the line
  as a shell command. With no arguments, run an inferior shell;

\item[{\bf source} $<$filenames...$>$] reads {\tt tpips} commands from
  files;

\item[{\bf cd} $<$directory-name$>$] changes the default directory;

\item[{\bf echo} $<$string$>$] prints $<$string$>$;

\item[{\bf getenv} $<$variable-name$>$] prints the value of
  $<$variable-name$>$ (equivalent to \verb+echo ${<variable-name>}+);
%% $
\item[{\bf setenv} $<$variable-name$>$ = $<$value$>$] sets $<$value$>$ to $<$variable-name$>$;

\item[{\bf help} $<$command$>$] prints out general help or detailed help
  about an item;

\item[{\bf info} $<$name$>$] print information about $<$name$>$. Here
  $<$name$>$ can be the \texttt{module}, \texttt{modules},
  \texttt{workspace} or \texttt{directory} words.

\end{description}


\subsection{Parameters}

The parameters of the different commands are :
\begin{description}
%%\quote
\item [$<$file-name$>$] Unix path and file name.
  \par Shell syntax, such as \verb+*.f+, can be used when \verb+s+ option
  is specified or \verb+TPIPS_IS_A_SHELL+ variable is set;

\item [$<$workspace-name$>$] Unix file name --- no path;

\item [$<$module-name$>$] Fortran function name in capital letters or a C
  function name;

\item [$<$rule-name$>$] rule name (see Section \ref{rules});

\item [$<$resource-descriptor$>$] It is a \verb+resource[OWNER]+
  expression: a pipsmake resource name to be computed for each module
  associated to OWNER (see Sections \ref{res} and \ref{resf});

\item [$<$rule-descriptor$>$] It is a \verb+rulename[OWNER]+ expression: a
  pipsmake instantiated rule to be applied on each module associated to
  OWNER (see Section \ref{rules});

\item [the OWNER] --- used in the previous $<$rule-descriptor$>$ and
$<$resource-descriptor$>$ --- can take these formats:
\begin{description}
%%\quote
\item [module-name] the target module name;
\item [\%PROGRAM] the whole program (for global resource);
\item [\%MAIN] the main module of the program;
\item [\%MODULE] the current module;
\item [\$\{MODULES\}] the modules associated to the Shell variable
  {\tt MODULES}. The different names are SPACE or/and TAB separated;
\item [\%ALL] All workspace modules, including C compilation
units\footnote{A PIPS compilation unit is associated to each C user
source file. it contains all the initial declarations, but the
function definitions.};
\item [\%ALLFUNC] All workspace functions, excluding C compilation units;
\item [\%CALLEES] All the callees of the current selected module;
\item [\%CALLERS] All the callers of the current selected module.
\end{description}
If no OWNER is specified, then the current  module is assumed. For
generic owners, a  sign (\%) has been added to differentiate them
from existing module names and environment variables.

\end{description}


\section{Simple session}

A simple {\tt tpips} session is made of a few steps. First, a
workspace must be created:
{\bf
\begin{verbatim}
create work source1.f source2.f
\end{verbatim}
}

and a subdirectory of the current directory, here
\texttt{work.database}, is created to store and retrieve
code and information computed by PIPS about subroutines and
functions found in \texttt{source1.f} or \texttt{source2.f}.

Then, you have to select a module, let say \texttt{FOO}, by typing:
{\bf
\begin{verbatim}

module FOO
\end{verbatim}
}

unless there is only one function or subroutine in the Fortran
file(s) which were passed to the create command, in
which case it is automatically selected.

To keep it simple the first time, you should then try to
display the sequential code of routine \texttt{FOO} by typing:

{\bf
\begin{verbatim}
display PRINTED_FILE
\end{verbatim}
}

Other resource names let you visualize the parallelized code
(\texttt{PARALLELPRINTED\_FILE}), or the call graph
(\texttt{CALLGRAPH\_FILE})...  Names for printable resources usually
contain the string \texttt{FILE}.

The standard command to leave {\tt tpips} is {\tt quit} but a control-D
or end-of-file condition are valid too.

Interactive analysis of module \texttt{MATMUL} from source code
\texttt{pgmsrc.f}, in workspace \texttt{pgm}:

{\bf
\begin{verbatim}
$ tpips
tpips > create pgm pgm-src.f

tpips > module MATMUL

tpips > display PARALLELPRINTED_FILE

tpips > quit

\end{verbatim}
}
%% $

\section{Examples}

\subsection{Call Graph}
\label{exm1}

To visualize the  call graph of the application, the following tpips
session can be executed. The call graph of each application routine is
displayed.

This example presents a use of:

\begin{itemize}
\item environment variable: \verb+setenv PIPS_SRCPATH SRC+
\item shell path file name expression that will be expanded: \verb+*.f+,
\item a $<$resource-descriptor$>$ : \verb+CALLGRAPH_FILE[%ALL]+
\end{itemize}
This \texttt{tpips} example is useful to test PIPS parsing on each new
benchmark.

\begin{verbatim}
setenv PIPS_SRCPATH SRC      # initiates the source file directory to SRC

create wc *.f                 # creates the wc workspace for the
                              # Fortran files of the  PIPS_SRCPATH 
                              # directory

display CALLGRAPH_FILE[%ALL]  # CONTROL GRAPH COMPUTATION for each routine

close 
quit

\end{verbatim}


\subsection{Dependences}
\label{exm2}

A programmer that would like to see the routines dependence graph to
parallelize interprocedurally the application can executed the following
\texttt{tpips} commands.

This example presents some PIPS analyses and use of
\begin{itemize}
\item module selection: \verb+module TEST+
\item $<$rule-name$>$: \verb+MUST_REGIONS+, \verb+REGION_CHAINS+
\item \verb+logfile_to_tpips+ command
\end{itemize}

\begin{verbatim}

sh>tpips                            # run tpips
tpips> create wfoo essai.f          # create a workspace for the program essai.f
tpips> module TEST                  # select the default module TEST
tpips> display CALLGRAPH_FILE       # display the sub-callgraph for the
                                       module TEST
tpips> make PROPER_EFFECTS[%ALL]    # compute proper effects for every
                                       modules
tpips> activate MUST_REGIONS        # select the rule must_regions instead
                                       of the default rule may_regions
tpips> activate REGION_CHAINS       # select the rule regions_chains for
                                       computing Use-Def chains in essai.f
tpips> display DG_FILE[%ALL]        # display all the dependance graphs
tpips> close wfoo                   # close the workspace
tpips> quit                         # quit tpips
\end{verbatim}

To store this simple session in a {\tt tpips} file, use the command:
\begin{verbatim}
logfile_to_tpips wfoo > foo.tpips
\end{verbatim}
that generates the following {\tt tpips} commands in the file
\verb+foo.tpips+.

\begin{verbatim}
#
# file generated by logfile_to_tpips for workspace wfoo
#
create wfoo essai.f
module TEST
display CALLGRAPH_FILE[TEST]
display PROPER_EFFECTS[TEST]
activate MUST_REGIONS
activate REGION_CHAINS
display DG_FILE[TEST]
close
quit
# EOF
\end{verbatim}

ote that  expression  \verb+%ALL+ has been expanded by all
program routines, in that example there is only one \verb+TEST+
routine in \verb+essai.f+.


\subsection{Transformations}
\label{exm3}

The following transformations are designed for application optimization.
Specialization and code reduction eliminating useless instructions and
declarations are performed.

This example presents some PIPS transformations and use of
\begin{itemize}
\item program restructuration, cloning, dead code elimination, useless
  declaration elimination, and code regeneration;
\item pips property: \verb+PREPROCESSOR_MISSING_FILE_HANDLING "generate"+;
\item transformation application : \verb+apply CLONE_ON_ARGUMENT[FUNCT]+.
\item $<$rule-name$>$ : \verb+PRINT_CODE+...
\item $<$rule-descriptor$>$:
  \verb+SUPPRESS_DEAD_CODE[${modules}]+,  \verb+UNSPLIT[%PROGRAM]+...
%% $
\item $<$resource-descriptor$>$ :  \verb+PRINTED_FILE[FUNCT]+,  \verb+CALLGRAPH_FILE[%ALL]+...
\end{itemize}
\begin{verbatim}
# Delete Workspace clone in case  it already exists

delete clone                      

setenv PIPS_SRCPATH SRC

# Stop as soon as the first user error occurs

setproperty ABORT_ON_USER_ERROR TRUE   

# Generates missing files  and routines 

setproperty PREPROCESSOR_MISSING_FILE_HANDLING "generate" 

# Substitute Fortran statement functions

setproperty PARSER_EXPAND_STATEMENT_FUNCTIONS TRUE

# Restructures the program to eliminate as many GOTO as possible

setproperty UNSPAGHETTIFY_TEST_RESTRUCTURING=TRUE
setproperty UNSPAGHETTIFY_RECURSIVE_DECOMPOSITION=TRUE

#
# prettyprinter settings

setproperty PRETTYPRINT_ALL_DECLARATIONS TRUE

# creates the workspace

create clone *.f


echo # initial version of FUNCT

display PRINTED_FILE[FUNCT]

#
# just to insure that all routines are generated.

make CALLGRAPH_FILE[%ALL]

#
# let us clone FUNCT on the second argument. 
# no interprocedural analysis is needed. 

setproperty TRANSFORMATION_CLONE_ON_ARGUMENT 2
capply CLONE_ON_ARGUMENT[FUNCT]

# The clone transformation generates 4 clones
# because there are 4 different values for the second
# argument of FUNCT

setenv modules "FUNCT_0 FUNCT_1 FUNCT_2 FUNCT_3"

#
# suppress dead code must be applied twice...
# eliminate dead code after cloning

apply SUPPRESS_DEAD_CODE[${modules}]
apply SUPPRESS_DEAD_CODE[${modules}]

# Eliminates useless declaration after cloning and dead code
# suppression

apply CLEAN_DECLARATIONS[FUNCT ${modules}]

echo # after cloning, dead code elimination and declarations cleaning

make  PRINTED_FILE[${modules}]

#
# regenerates the source files with calls to cloned functions only
# 

activate PRINT_CODE
apply UNSPLIT[%PROGRAM]

close 
\end{verbatim}


\subsection{Analyses}
\label{exm4}

This example presents some classical PIPS analyzes:

\begin{itemize}
\item computation of preconditions;
\item transformers;
\item effects;
\item regions
\end{itemize}
and a {\it concurrent} transformation application.

\verb+capply PARTIAL_EVAL[%ALL]+
applies a partial evaluation on all routines concurrently without any
verification process between two transformations. The partial evaluation
of a routine does not modify other routine predicates, even if the code
(one routine) has been modified by the transformation. It is not
necessary to ask for a sequential application that will impose the
analysis and re-computation of all routine predicates between two partial
evaluations.

\begin{verbatim}
create foo *.f

echo
echo CALL_GRAPH[%ALL] Computation
echo

display CALLGRAPH_FILE[%ALL]

# ask interprocedural information

activate PRECONDITIONS_INTER_FULL
activate TRANSFORMERS_INTER_FULL

module FUNCT

capply PARTIAL_EVAL[%ALL]

#echo
#echo PRINT_CODE_PROPER_EFFECTS Activation
#echo
#
#activate PRINT_CODE_PROPER_EFFECTS
#display PRINTED_FILE[%ALL]
#
#echo
#echo PRINT_CODE_CUMULATED_EFFECTS Activation
#echo
#
#activate PRINT_CODE_CUMULATED_EFFECTS
#display PRINTED_FILE[%ALL]

echo
echo PRINT_CODE_TRANSFORMERS Activation
echo


activate PRINT_CODE_TRANSFORMERS
display PRINTED_FILE[%ALL]

echo
echo PRINT_CODE_PRECONDITIONS Activation
echo

activate PRINT_CODE_PRECONDITIONS
display PRINTED_FILE[%ALL]

echo
echo ICFG_WITH_LOOPS_REGIONS
echo 

activate PRINT_ICFG_WITH_LOOPS_REGIONS
display ICFG_FILE[%ALL]

echo 
echo REGIONS Computation
echo

activate MUST_REGIONS
activate PRINT_CODE_REGIONS
display PRINTED_FILE[%ALL]


close 
quit
\end{verbatim}


\subsection{Graphical  Graph View}
\label{exm5}

This example presents a call to a graphical call graph view.

\begin{verbatim}
# resize the entities table. Useful for  large benchmarks. 

setenv NEWGEN_MAX_TABULATED_ELEMENTS 150000
setenv MAINROUTINE  TOTO 

delete DVCG
create DVCG *.f


echo
echo CALLGRAPH_FILE[${MAINROUTINE}] Computation
echo


make CALLGRAPH_FILE[${MAINROUTINE}]


echo
echo DVCG_FILE[${MAINROUTINE}] Computation
echo

make DVCG_FILE[${MAINROUTINE}]

# type DaVinci DVCG.database/${MAINROUTINE}/${MAINROUTINE}.daVinci
# to  visualize 

close 
quit
\end{verbatim}


\subsection{Parallelization}
\label{exm6}

This example presents some classical analyses and transformations designed
to parallelize benchmarks, for instance the \texttt{adm} program of the
Perfect club.

\begin{verbatim}
#
# Perfect club ADM benchmark.

echo Perfect/adm.f
#
delete adm
create adm adm.f  cputim.f elapse.f 

setproperty UNSPAGHETTIFY_TEST_RESTRUCTURING=TRUE
setproperty UNSPAGHETTIFY_RECURSIVE_DECOMPOSITION=TRUE
setproperty PARALLELIZATION_STATISTICS=TRUE

echo ADM scalar privatization...
 
capply PRIVATIZE_MODULE[%ALL]


activate PRECONDITIONS_INTER_FULL
activate TRANSFORMERS_INTER_FULL

activate RICE_SEMANTICS_DEPENDENCE_GRAPH

apply PARTIAL_EVAL[%ALL]

echo ADM parallelization...
make PARALLELPRINTED_FILE[%ALL]

close
quit
\end{verbatim}


\section{Rules --- Pips options}
\label{rules}

Rules are used to compute resources. Several rules can be activated to
compute a single resource. For instance a parallel version of a module may
be computed from the interprocedural precondition
(\verb+PRECONDITIONS_INTER_FULL+), interprocedural transformer
(\verb+TRANSFORMERS_INTER_FULL+) and accurate dependencies
(\verb+RICE_SEMANTICS_DEPENDENCE_GRAPH+). Rules are selected by
\verb+activate+ or selected and applied by \verb+apply+ and \verb+capply+.
More rules and more information on each particular rule are presented in
the pipsmake documentation, \PipsPIPSmakeHTDOC or \PipsPIPSmakePDF.

\begin{verbatim*}
#### ANALYSES ####

ATOMIC_CHAINS                    
CONTINUATION_CONDITIONS  
FLINTER  
PROPER_REFERENCES

### COMPLEXITITY 

ANY_COMPLEXITIES  
FP_COMPLEXITIES  
UNIFORM_COMPLEXITIES
SUMMARY_COMPLEXITY

### PRIVATIZATION

ARRAY_PRIVATIZER  
ARRAY_SECTION_PRIVATIZER  
DECLARATIONS_PRIVATIZER 
PRIVATIZE_MODULE

### EFFECTS

CUMULATED_EFFECTS  
CUMULATED_REDUCTIONS  
CUMULATED_REFERENCES  
IN_EFFECTS 
IN_SUMMARY_EFFECTS 
OUT_EFFECTS  
OUT_SUMMARY_EFFECTS  
PROPER_EFFECTS
SUMMARY_EFFECTS


### PRECONDITIONS

PRECONDITIONS_INTER_FAST  
PRECONDITIONS_INTER_FULL  
PRECONDITIONS_INTRA  
SUMMARY_PRECONDITION


### TRANSFORMERS

SUMMARY_TRANSFORMER
TRANSFORMERS_INTER_FAST
TRANSFORMERS_INTER_FULL
TRANSFORMERS_INTRA_FAST
TRANSFORMERS_INTRA_FULL


### REGIONS 

IN_OUT_REGIONS_CHAINS  
IN_REGIONS 
IN_SUMMARY_REGIONS 
MAY_REGIONS 
MUST_REGIONS
OUT_REGIONS  
OUT_SUMMARY_REGIONS  
REGION_CHAINS
SUMMARY_REGIONS

### CALLGRAPH 

FULL_GRAPH_OF_CALLS  
CALLGRAPH  
GRAPH_OF_CALLS 

### DEPENDENCES

RICE_ALL_DEPENDENCE
RICE_CRAY
RICE_DATA_DEPENDENCE
RICE_FAST_DEPENDENCE_GRAPH
RICE_FULL_DEPENDENCE_GRAPH
RICE_REGIONS_DEPENDENCE_GRAPH
RICE_SEMANTICS_DEPENDENCE_GRAPH

### REDUCTIONS

PROPER_REDUCTIONS
SUMMARY_REDUCTIONS


#### TRANSFORMATIONS #### 

FORWARD_SUBSTITUTE            
PARTIAL_EVAL 

### RESTRUCTURATION 

ATOMIZER  
CLEAN_DECLARATIONS  
CLONE  
CLONE_ON_ARGUMENT  
CLONE_SUBSTITUTE  
RESTRUCTURE_CONTROL
SUPPRESS_DEAD_CODE
UNSPAGHETTIFY
UNSPLIT
USE_DEF_ELIMINATION

### LOOP TRANSFORMATION

DISTRIBUTER  
FULL_UNROLL 
LOOP_INTERCHANGE  
LOOP_NORMALIZE  
LOOP_REDUCTIONS  
STRIP_MINE
UNROLL

### PARALLELIZATION

COARSE_GRAIN_PARALLELIZATION  
NEST_PARALLELIZATION 
\end{verbatim*}

\begin{verbatim*}
#### PRETTYPRINT #### 

### PRINT_CALL_GRAPH                          

PRINT_CALL_GRAPH                          
PRINT_CALL_GRAPH_WITH_COMPLEXITIES        
PRINT_CALL_GRAPH_WITH_CUMULATED_EFFECTS   
PRINT_CALL_GRAPH_WITH_IN_REGIONS          
PRINT_CALL_GRAPH_WITH_OUT_REGIONS         
PRINT_CALL_GRAPH_WITH_PRECONDITIONS       
PRINT_CALL_GRAPH_WITH_PROPER_EFFECTS      
PRINT_CALL_GRAPH_WITH_REGIONS             
PRINT_CALL_GRAPH_WITH_TRANSFORMERS        

### PRINT_CHAINS_GRAPH                        

PRINT_CHAINS_GRAPH                        

### PRINT_CODE  WITH ...                             

PRINT_CODE                                
PRINT_CODE_AS_A_GRAPH                     
PRINT_CODE_AS_A_GRAPH_COMPLEXITIES        
PRINT_CODE_AS_A_GRAPH_CUMULATED_EFFECTS   
PRINT_CODE_AS_A_GRAPH_IN_REGIONS          
PRINT_CODE_AS_A_GRAPH_OUT_REGIONS         
PRINT_CODE_AS_A_GRAPH_PRECONDITIONS       
PRINT_CODE_AS_A_GRAPH_PROPER_EFFECTS      
PRINT_CODE_AS_A_GRAPH_REGIONS             
PRINT_CODE_AS_A_GRAPH_TRANSFORMERS        
PRINT_CODE_COMPLEMENTARY_SECTIONS         
PRINT_CODE_COMPLEXITIES                   
PRINT_CODE_CONTINUATION_CONDITIONS        
PRINT_CODE_CUMULATED_EFFECTS              
PRINT_CODE_CUMULATED_REDUCTIONS           
PRINT_CODE_CUMULATED_REFERENCES           
PRINT_CODE_IN_EFFECTS                     
PRINT_CODE_IN_REGIONS                     
PRINT_CODE_OUT_EFFECTS                    
PRINT_CODE_OUT_REGIONS
PRINT_CODE_PRECONDITIONS
PRINT_CODE_PRIVATIZED_REGIONS
PRINT_CODE_PROPER_EFFECTS
PRINT_CODE_PROPER_REDUCTIONS
PRINT_CODE_PROPER_REFERENCES
PRINT_CODE_PROPER_REGIONS
PRINT_CODE_REGIONS
PRINT_CODE_STATIC_CONTROL
PRINT_CODE_TRANSFORMERS

### PRINT_DEPENDENCE_GRAPH

PRINT_EFFECTIVE_DEPENDENCE_GRAPH
PRINT_LOOP_CARRIED_DEPENDENCE_GRAPH
PRINT_WHOLE_DEPENDENCE_GRAPH

### PRINT_ICFG

PRINT_ICFG
PRINT_ICFG_WITH_COMPLEXITIES
PRINT_ICFG_WITH_CONTROL
PRINT_ICFG_WITH_CONTROL_COMPLEXITIES
PRINT_ICFG_WITH_CONTROL_CUMULATED_EFFECTS
PRINT_ICFG_WITH_CONTROL_IN_REGIONS
PRINT_ICFG_WITH_CONTROL_OUT_REGIONS
PRINT_ICFG_WITH_CONTROL_PRECONDITIONS
PRINT_ICFG_WITH_CONTROL_PROPER_EFFECTS
PRINT_ICFG_WITH_CONTROL_REGIONS
PRINT_ICFG_WITH_CONTROL_TRANSFORMERS
PRINT_ICFG_WITH_CUMULATED_EFFECTS
PRINT_ICFG_WITH_IN_REGIONS
PRINT_ICFG_WITH_LOOPS
PRINT_ICFG_WITH_LOOPS_COMPLEXITIES
PRINT_ICFG_WITH_LOOPS_CUMULATED_EFFECTS
PRINT_ICFG_WITH_LOOPS_IN_REGIONS
PRINT_ICFG_WITH_LOOPS_OUT_REGIONS
PRINT_ICFG_WITH_LOOPS_PRECONDITIONS
PRINT_ICFG_WITH_LOOPS_PROPER_EFFECTS
PRINT_ICFG_WITH_LOOPS_REGIONS
PRINT_ICFG_WITH_LOOPS_TRANSFORMERS
PRINT_ICFG_WITH_OUT_REGIONS
PRINT_ICFG_WITH_PRECONDITIONS
PRINT_ICFG_WITH_PROPER_EFFECTS
PRINT_ICFG_WITH_REGIONS
PRINT_ICFG_WITH_TRANSFORMERS

PRINT_INITIAL_PRECONDITION

### PRINT_PARALLELIZED_CODE

PRINT_PARALLELIZED77_CODE
PRINT_PARALLELIZED90_CODE
PRINT_PARALLELIZEDCMF_CODE
PRINT_PARALLELIZEDCRAFT_CODE
PRINT_PARALLELIZEDCRAY_CODE
PRINT_PARALLELIZEDHPF_CODE
PRINT_PARALLELIZEDOMP_CODE

### PRINT_SOURCE

PRINT_SOURCE
PRINT_SOURCE_COMPLEXITIES
PRINT_SOURCE_CONTINUATION_CONDITIONS
PRINT_SOURCE_CUMULATED_EFFECTS
PRINT_SOURCE_IN_EFFECTS
PRINT_SOURCE_IN_REGIONS
PRINT_SOURCE_OUT_EFFECTS
PRINT_SOURCE_OUT_REGIONS
PRINT_SOURCE_PRECONDITIONS
PRINT_SOURCE_PROPER_EFFECTS
PRINT_SOURCE_REGIONS
PRINT_SOURCE_TRANSFORMERS
\end{verbatim*}


\section{Resources}
\label{res}

The names of the current useful resources are given. These resources are
computed by the \verb+make+ and \verb+display+ commands. These
non-printable resources are encoded in internal data structures. The
corresponding printable resources are listed in the following section.
These resources and others are detailed the pipsmake documentation,
\PipsPIPSmakeHTDOC or \PipsPIPSmakePDF.

\begin{verbatim}
CALLEES
CALLERS
CHAINS  
COMPLEXITIES  
DG      
ENTITIES 
SUMMARY_COMPLEXITY

## CODE 

CODE  
PARALLELIZED_CODE
PARSED_CODE


## EFFECTS

CUMULATED_EFFECTS
CUMULATED_IN_EFFECTS
IN_EFFECTS
IN_SUMMARY_EFFECTS
OUT_EFFECTS
OUT_SUMMARY_EFFECTS
PROPER_EFFECTS
SUMMARY_EFFECTS
\end{verbatim}

\begin{verbatim}
## REGIONS
 
COPY_OUT_REGIONS                        
CUMULATED_IN_REGIONS                    
INV_IN_REGIONS                          
INV_REGIONS                             
IN_REGIONS
IN_SUMMARY_REGIONS
OUT_REGIONS
OUT_SUMMARY_REGIONS
PRIVATIZED_REGIONS
PROPER_REGIONS
REGIONS 
SUMMARY_REGIONS

## REDUCTIONS 

CUMULATED_REDUCTIONS                    
PROPER_REDUCTIONS
SUMMARY_REDUCTIONS

## REFERENCES

CUMULATED_REFERENCES                    
PROPER_REFERENCES
\end{verbatim}

\begin{verbatim}
## PRECONDITION                   

INITIAL_PRECONDITION                    
PRECONDITIONS    
PROGRAM_PRECONDITION
SUMMARY_PRECONDITION

## TRANSFORMERS 

SUMMARY_TRANSFORMER
TRANSFORMERS 

## CONTINUATION 

MAY_CONTINUATION
MAY_SUMMARY_CONTINUATION
MUST_CONTINUATION
MUST_SUMMARY_CONTINUATION
\end{verbatim}


\section{Printable resources}
\label{resf}

The printable resources usually contain the string FILE. They can be
computed by invoking the \verb+display+ {\tt tpips} command. They are
stored as human readable ASCII file in the workspace. The current
resources which are printable follow, for more information see the
pipsmake documentation, \PipsPIPSmakeHTDOC or \PipsPIPSmakePDF.  .

\begin{verbatim}
CALLGRAPH_FILE                   # call graph file
DG_FILE                          # Dependence graph file         
DVCG_FILE                        # Davinci Dependence graph file 
FLINTED_FILE                     # source file with errors
GRAPH_PRINTED_FILE               # control graph
ICFG_FILE                        # interprocedural control flow graph       
INITIAL_FILE                     # after splitting      
PARALLELPRINTED_FILE             # parallel version
PRINTED_FILE                     # annoted sequential version 
SOURCE_FILE                      # after the preprocessing phase
USER_FILE                        # after regeneration of user files
\end{verbatim}


\section{Options}

Usage:\\
\texttt{tpips} [\texttt{-nscvh?jw}] [\texttt{-l \emph{logfile}}]
[\texttt{-r \emph{rcfile}}] [\texttt{-e \emph{tpips-cmds}}]
\texttt{\emph{tpips-scripts}}

\begin{description}

\item [-n]  no execution mode. Just check the script syntax;
\item [-s] behaves like a shell. {\tt tpips} commands simply extend a shell;
\item [-c] behaves like a command, not a shell (it is the default option);
\item [-v] displays version and architecture information;
\item [-h or -?] provides some help;
\item [-j] jpips special mode;
\item [-w] starts with a wrapper (jpips special again)...
\item [-l] $<$logfile$>$: log to $<$logfile$>$;
\item [-r] $<$rcfile$>$: source the $<$rcfile$>$ file (default
  \verb|$HOME/.tpipsrc|); %% $
\item [-e] tpips-cmds: executes the $<$tpips-cmds$>$ commands.
\end{description}


\section{Environment}

Before using {\tt tpips}, you need to add a PIPS root directory to your
path and to set some PIPS environment variables. In order to do that, you
can source from the PIPS distribution the shell script \texttt{pipsrc.sh}
for any sh compatible shell, e.g. ksh or bash, or \texttt{pipsrc.csh} for
any csh compatible shell, e.g.  tcsh.


\section{Small tools}
\label{sec:small-tools}

\texttt{tpips} is the way to go with PIPS but it may be too complex to do
some simple tasks used for some demonstrations or some well defined tasks.


\subsection{\texttt{pips\_c2openmp}}
\label{sec:pips_f2openmp}

This tools parallelizes the C source files given in parameters and leaves
the OpenMP generated files in the locally created database.

It is close to an automation of the example at section~\ref{exm6}, but for
C.

\subsection{\texttt{pips\_f2openmp}}
\label{sec:pips_f2openmp}

This tools parallelizes the Fortran source files given in parameters and
leaves the OpenMP generated files in the locally created database.

It is close to an automation of the example at section~\ref{exm6}.


\end{document}

%%% Local Variables:
%%% mode: latex
%%% TeX-master: t
%%% ispell-local-dictionary: "american"
%%% End: