cflow2vcg

Guilhm BONNEFILLE

Copyright  2001 par Guilhm BONNEFILLE
-------------------------------------------------------------------------------

Table des matires
1. Description
    1.1. Arbres d'appel
    1.2. cflow2vcg
    1.3. Licence
   
   
2. Installation
    2.1. Disponibilit
    2.2. Tlchargement
    2.3. Gnration
    2.4. Installation
   
   
3. Utilisation
    3.1. Usage
    3.2. Description
        3.2.1. Restriction interne/externe
       
       
    3.3. Exemples
        3.3.1. Visualisation
        3.3.2. Impression
       
       
   
   
4. Technique
5. Pour finir
    5.1. Sugestions
    5.2. A faire
        5.2.1. Enrichissement
       
       
   
   
6. Autres versions du document

-------------------------------------------------------------------------------
Chapitre 1. Description

1.1. Arbres d'appel

Lorsque l'on travaille sur une application de plus de 10-15 fonctions, il
devient difficile de bien cerner les appels entre ces fonctions. Ceci est
d'autant plus vrai dans le cadre de projets libres dont les codes sont souvent
l'&oelig;uvre d'une (ou plusieurs) autre(s) personne(s). Parfois, ces codes
sont bien documents (commentaires, document de conception, etc.). Mais
souvent, ce n'est pas le cas et les codes restent obscurs pour un nouveau
dveloppeur. Pour intervenir dans ces codes, un des lments indispensable 
leur comprhension est l'arbre d'appel.

Un arbre d'appel est une reprsentation arborescente des appels de fonctions
entre elles. On distingue deux arbres d'appels:

*L'arbre d'appel statique: il reprsente l'ensemble de toutes les
    possibilits d'appel dfinies par les codes sources (y compris celles qui
    ne sont pas accessibles car les conditons pour les provoquer ne sont jamais
    remplies).
   
*L'arbre d'appel dynamique: il reprsente l'ensemble des appels provoqus
    par une excution du programme.
   

Les plateformes de type UNIX proposent des utilitaires pour obtenir ces arbres
d'appel (par exemple cflow et gprof). Or le rsultat de ceux-ci (une sortie de
type texte), bien que parfaitement exploitable, est assez dsagrable 
manipuler. Ce rsultat est d'autant plus dsagrable  manipuler que par nature
ces informations se prtent plus  une reprsentation graphique que textuelle.
-------------------------------------------------------------------------------

1.2. cflow2vcg

La reprsentation graphique d'un arbre est loin d'tre un problme simple 
rsoudre. Heureusement, il existe un outil qui fait a trs bien: xvcg
dvelopp par I. Lemke, G. Sander<sander@cs.uni-sb.de> et the Compare
Consortium et est maintenue par Shantanu Tarafdar<shantanu@ece.neu.edu>.

Restant dans la philosophie Unix, cflow2vcg vient donc faire, aussi simplement
que possible, le lien entre cflow et xvcg. Nous ne nous interresserons qu'aux
arbres d'appels statiques car les arbres d'appels dynamiques peuvent tre
produits avec Call Graph Drawing Interface dvelopp par Vadim Engelson <
vaden@ida.liu.se>.
   
   
    Note : Bien que cflow2vcg n'en soit qu'a sa toute premire version, il n'en
    reste pas moins parfaitement utilisable. Je l'utilise d'ailleurs de faon
    oprationnelle trs rgulirement.
   
-------------------------------------------------------------------------------
1.3. Licence

cflow2vcg est dvelopp et distribu sous Licence Publique Gnrale GNU (GNU
General Public License - GPL). Ceci vous permet, en particulier, d'adapter 
cflow2vcg  vos besoins si ncessaire. Si tel est le cas, je vous invite 
prendre contact avec moi <guyou@sourceforge.net> car vos modifications peuvent
interresser les autres utilisateurs.
-------------------------------------------------------------------------------

Chapitre 2. Installation

-------------------------------------------------------------------------------
2.1. Disponibilit

cflow2vcg fonctionne actuellement sur plateforme Sun Solaris&trade;. Toutefois
vu la simplicit des moyens externes utiliss, sa gnration sur d'autre
plateforme ne prsente aucun problme. La difficult majeure reste le format
rsultat de la commande cflow qui n'est pas obligatoirement le mme sur toutes
les plateformes. Ce point n'a pas t test.

Des outils de type cflow existent sur plateforme GNU/Linux mais ne semblent pas
installs par les distributions. Une petite recherche sur un moteur de
recherche quelconque devrait vous permettre d'en trouver un rapidement.
Personnellement, le cflow que j'ai install ne produit pas la mme sortie que
le cflow de Sun Solaris&trade;. Des moyens d'analyse de ces formats de sortie
sont en cours de dveloppement.

Une impmentation de cflow fournie par Andrew Moore est disponible  l'adresse 
ftp://ftp.ntua.gr/pub/linux/debian/pool/main/c/cflow/cflow_2.0.orig.tar.gz.

Les dernires versions de cflow2vcg savent utiliser ce format.
-------------------------------------------------------------------------------

2.2. Tlchargement

cflow2vcg est hberg par SourceForge. Il dispose donc de tous les moyens de
diffusion et de communication sur son site. Les sources sont accessibles y sont
accessibles ainsi que des versions binaires.
-------------------------------------------------------------------------------

2.3. Gnration

Comme nombre de projets libres, cflow2vcg utilise les facilit de gnration
offertes par configure. Pour gnrer l'application, il suffit de faire comme
d'habitude:
          % gunzip -c cflow2vcg-x-x.tar.gz | tar xf -
          % cd cflow2vcg-x-x
          % ./configure
          % make
        

Comme toujours, il est possible de paramtrer la gnration grce  configure.
Pour connatre les possibilits de paramtrage, excutez ./configure --help.
-------------------------------------------------------------------------------

2.4. Installation

L'installation de cflow2vcg dans /usr/local se fait simplement avec:
          % make install
        

Grce  configure il est possible de paramtrer trs finement l'installation.
Pour en savoir plus, extez ./configure --help.
-------------------------------------------------------------------------------

Chapitre 3. Utilisation

3.1. Usage

cflow2vcg [-e | -i] [-h] [-v]

cflow2vcg lit un fichier de type cflow sur son entre standard et produit un
quivalent au format vcg sur sa sortie standard. Ce "flot" produit peut tre
manipul par les applications capables de manipuler le format VCG et en
particulier xvcg.
-------------------------------------------------------------------------------

3.2. Description

3.2.1. Restriction interne/externe

Le fichier VCG produit par cflow2vcg permet de rduire le graphe aux appels
vers des fonctions internes (dfinies dans les fichiers annalyss par cflow) ou
au appels vers des fonctions externes (par exemple les fonctions syst). Cette
fonctionnalit est extrmement utile pour comprendre le lien entre les
diffrents modules contenus dans votre application.
-------------------------------------------------------------------------------

3.2.1.1. Visualisation

Pour restreindre l'arbre  l'un de ces types d'appel, il suffit de le
slectionner dans le dialogue Expose/Hide Edges... de xvcg.
-------------------------------------------------------------------------------

3.2.1.2. Exportation graphique

La production d'un fichier graphique  partir de xvcg ne permet pas ( moins
qu'il y ait une option que je n'ai pas trouve) de raliser cette restriction.
Pour y parvenir, cflow2vcg dispose des options [-i] et [-e] pour restreindre le
graphe d sa production.
-------------------------------------------------------------------------------

3.3. Exemples

Les exemples sont bass sur le code de cflow2vcg. Les fichiers intermdiaires
ayant servi  produire les exemples sont disponibles dans le rpertoire doc de
la distribution:

*cflow2vcg.cflow pour le rsultat de cflow,
   
*cflow2vcg.vcg pour le rsultat de cflow2vcg sur le fichier prcdent.
   

-------------------------------------------------------------------------------
3.3.1. Visualisation

Pour visualiser un graphe:
            % cflow cflow2vcg.c | cflow2vcg | xvcg -
          

Le rsultat est:

[cflow2vcg]

En ne slectionnant que les n&oelig;uds internes (soit depuis xvcg, soit depuis
cflow2vcg), on obtient:

[cflow2vcg_int]

En ne slectionnant que les n&oelig;uds externes (soit depuis xvcg soit depuis 
cflow2vcg), on obtient:

[cflow2vcg_ext]
-------------------------------------------------------------------------------

3.3.2. Impression

Pour imprimer un graphe:
            % cflow cflow2vcg.c | cflow2vcg | xvcg - -psoutput file.ps
            % lp file.ps
          

xvcg offre de nombreux paramtres pour matriser le rendu de l'impression.
Consultez son aide en ligne (man vcg) pour en savoir plus.
-------------------------------------------------------------------------------

Chapitre 4. Technique

Le principe utilis (aujourd'hui) par cflow2vcg est extrmement simple. Il
consiste  convertir ligne  ligne la sortie de cflow en instructions VCG.

Cela consiste  reconnatre si la ligne lue correspond :

*une ligne de dclaration/dfinition d'un symbole, auquel cas on doit
    produire un noeud,
   
*une ligne de simple rfrence, auquel on ne produit rien.
   

Dans tous les cas, on produit un arc depuis la fonction appelante.
-------------------------------------------------------------------------------

Chapitre 5. Pour finir

5.1. Sugestions

N'hsitez pas  me faire parvenir vos questions, remarques, bugs et autre par
mail  <guyou@sourceforge.net>.
-------------------------------------------------------------------------------

5.2. A faire

Les grosses volutions prvues sont:

*enrichissement du fichier VCG produit avec le maximum des informations
    produites par cflow (Cf. Section 5.2.1),
   
*packages (RPM),
   
*internationnalisation du fichier VCG produit et de la documentation.
   

-------------------------------------------------------------------------------
5.2.1. Enrichissement

Aujourd'hui, cflow2vcg n'exploite pas l'information de nom de fichier de
dfinition. On peut prvoir de placer cette information dans un champ info d'un
n&oelig;ud. On peut aussi envisager d'utiliser cette information pour permettre
de restreindre le graphe. Ceci pourrait passer par la cration d'un graph par
fichier. Pour y parvenir, cela ncessite de complexifier le programme puisqu'il
faudra mmoriser les informations dans une structure avant de les crire dans
le fichier de sortie.
-------------------------------------------------------------------------------

Chapitre 6. Autres versions du document

Autres documents.
