cflow2vcg

Guilhèm BONNEFILLE

Copyright © 2001 par Guilhèm BONNEFILLE
-------------------------------------------------------------------------------

Table des matières
1. Description
    1.1. Arbres d'appel
    1.2. cflow2vcg
    1.3. Licence
   
   
2. Installation
    2.1. Disponibilité
    2.2. Téléchargement
    2.3. Génération
    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 documentés (commentaires, document de conception, etc.). Mais
souvent, ce n'est pas le cas et les codes restent obscurs pour un nouveau
développeur. Pour intervenir dans ces codes, un des éléments indispensable à
leur compréhension est l'arbre d'appel.

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

  * L'arbre d'appel statique : il représente l'ensemble de toutes les
    possibilités d'appel définies 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 représente l'ensemble des appels provoqués
    par une exécution du programme.
   

Les plateformes de type UNIX© proposent des utilitaires pour obtenir ces arbres
d'appel (par exemple cflow et gprof). Or le résultat de ceux-ci (une sortie de
type texte), bien que parfaitement exploitable, est assez désagréable à
manipuler. Ce résultat est d'autant plus désagréable à manipuler que par nature
ces informations se prètent plus à une représentation graphique que textuelle.
-------------------------------------------------------------------------------

1.2. cflow2vcg

La représentation graphique d'un arbre est loin d'être un problème simple à
résoudre. Heureusement, il existe un outil qui fait ça très bien : xvcg
développé 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 développé par Vadim Engelson <
vaden@ida.liu.se>.
   
   
    Note : Bien que cflow2vcg n'en soit qu'a sa toute première version, il n'en
    reste pas moins parfaitement utilisable. Je l'utilise d'ailleurs de façon
    opérationnelle très régulièrement.
   
-------------------------------------------------------------------------------
1.3. Licence

cflow2vcg est développé et distribué sous Licence Publique Générale GNU (GNU
General Public License - GPL). Ceci vous permet, en particulier, d'adapter 
cflow2vcg à vos besoins si nécessaire. 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 utilisés, sa génération sur d'autre
plateforme ne présente aucun problème. La difficulté majeure reste le format
résultat de la commande cflow qui n'est pas obligatoirement le même 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
installés 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 même sortie que
le cflow de Sun Solaris&trade;. Des moyens d'analyse de ces formats de sortie
sont en cours de développement.

Une impémentation 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 dernières versions de cflow2vcg savent utiliser ce format.
-------------------------------------------------------------------------------

2.2. Téléchargement

cflow2vcg est hébergé 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. Génération

Comme nombre de projets libres, cflow2vcg utilise les facilité de génération
offertes par configure. Pour générer 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 paramétrer la génération grâce à configure.
Pour connaître les possibilités de paramétrage, exécutez ./configure --help.
-------------------------------------------------------------------------------

2.4. Installation

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

Gràce à configure il est possible de paramétrer très finement l'installation.
Pour en savoir plus, exétez ./configure --help.
-------------------------------------------------------------------------------

Chapitre 3. Utilisation

3.1. Usage

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

cflow2vcg lit un fichier de type cflow sur son entrée 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 réduire le graphe aux appels
vers des fonctions internes (définies dans les fichiers annalysés par cflow) ou
au appels vers des fonctions externes (par exemple les fonctions systè). Cette
fonctionnalité est extrèmement utile pour comprendre le lien entre les
différents 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
sélectionner 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 trouvée) de réaliser 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 basés sur le code de cflow2vcg. Les fichiers intermédiaires
ayant servi à produire les exemples sont disponibles dans le répertoire doc de
la distribution :

  * cflow2vcg.cflow pour le résultat de cflow,
   
  * cflow2vcg.vcg pour le résultat de cflow2vcg sur le fichier précédent.
   

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

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

Le résultat est :

[cflow2vcg]

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

[cflow2vcg_int]

En ne sélectionnant 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 paramètres pour maîtriser 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 extrèmement simple. Il
consiste à convertir ligne à ligne la sortie de cflow en instructions VCG.

Cela consiste à reconnaître si la ligne lue correspond à :

  * une ligne de déclaration/définition d'un symbole, auquel cas on doit
    produire un noeud,
   
  * une ligne de simple référence, 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'hésitez pas à me faire parvenir vos questions, remarques, bugs et autre par
mail à <guyou@sourceforge.net>.
-------------------------------------------------------------------------------

5.2. A faire

Les grosses évolutions prévues 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
définition. On peut prévoir 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 création d'un graph par
fichier. Pour y parvenir, cela nécessite de complexifier le programme puisqu'il
faudra mémoriser les informations dans une structure avant de les écrire dans
le fichier de sortie.
-------------------------------------------------------------------------------

Chapitre 6. Autres versions du document

Autres documents.
