AVERTISSEMENT : cette version est une version de test.

HYPRF peut vous etre utile si vous developez des programmes sous Linux ( ou eventuellement d'autres Unix )  et utilisez le compilateur GCC.
Il produit sous forme de graphes au format html une représentation synoptique de la structure des appels des fonctions d'un programme, il permet de naviguer entre ces graphes et les sources C et C++ du programme présentés au format html.
Sa principale vocation est d'aider à la maintenance de programmes que l'on n'a  pas écrits ou que l'on a oubliés.
La version actuelle est seulement testée sous Linux. Elle devrait pouvoir etre portée sous d'autres Unix , voire sous des systèmes plus exotiques.

NB : HYPRF se prononce Hyper Ref , Hyper Ref se prononce comme vous voulez.
 
 

Copyright .

Installation..

Principes de fonctionnement.

Invocation des programmes.

Les  Documents Html géneres.

Bugs et autres desagréments.

Remerciements.

Copyright .

• Copyright (C) Patrick Davalan 1998 - All right reserved - sous la license GNU/GPL :

 
• Ce programme est ' free software ' ; vous pouvez le redistribuer et/ou le modifier suivant les termes de la ' GNU General Public License '  telle qu'elle est publiée par la ' Free Software Foundation ' ; soit la version 2 de cette license ou ( à votre convenance ) toute version ulterieure.
• Ce progamme est distribué dans l'espoir qu'il vous soit utile , mais en l'etat et , dans la mesure permise par les lois en vigueur ,

SANS AUCUNE GARANTIE D'AUCUNE SORTE .
consultez la 'GNU General Public License' pour plus de details.
 
• Vous devriez avoir reçu une copie de la 'GNU General Public License' accompagnant ce programme , si ce n'est pas le cas, écrivez à la
         Free Software Fundation , Inc. ,
          675 Mass. Ave , Cambridge ,
          MA 02139 , USA
 
• Une partie de ce logiciel est construite à l'aide des programmes FLEX et BISON , cette partie est de ce fait distribuée sous la license applicable aux logiciel construits par FLEX et BISON  soit GNU / GPL.

 

• Si j'ai mentionné d'autres logiciels dans ce document , sachez qu'ils appartiennent probablement à leurs propriétaires respectifs.

 

Installation.

• Je ne suis pas très expert en procédures d'installation , enfin la procédure semble marcher
• Comme pour le moment , Hyprf ne tourne que sous Linux , aucun script configure n'est fourni. Le logiciel est géneré en format ELF ,  aucune procedure n'est fournie pour le generer en d'autres formats.

apres l'avoir decompacté , entrez make dans le repertoire creé. Ne vous souciez pas des warnings à la compilation.

• pour l'installer , vous devrez etre superuser , pour installer les librairies et programmes et faire ldconfig.

Entrez make install . Les differents fichiers sont insallés dans /usr/local/bin .... , si vous voulez changer , il faudra changer les Makefiles. ( 1 pour presque chaque  repertoire de la distribution).
Ldconfig est effectué par la procedure d'installation. si vous ne desirez pas le faire , il faudra l'oter des makefiles.
la procedure d'installation  crée un fichier .hyprfrc dans votre home directory , en principe /root comme vous avez du installer comme super user , ce fichier est sourcé par hyprf pour connaitre le repertoire sur lequel il reside.  Ce fichier devra etre recopié dans la home directory des users desirant utiliser hyprf.

• Bref , dans le cas normal , il suffit d'entrer make et make install comme root et de recopier le fichier /root/.hyprfrc dans la directory de chaque user interessé..

 

Objet , principes de fonctionnement et architecture.

• HYPRF a pour but de montrer les références entre les fonctions d'un programme. Il s'agit des références statiques telles qu'elles peuvent apparaitre dans un programme , il ne s'agit pas de tracer les appels dynamiques à l'execution d'un programme.

• HYPRF crée au format html les graphes d'appel de fonctions d'un programme. un graphe associe aux fonctions les fonctions qu'elle appelle , un autre associe aux fonctions les fonctions par lesquelles elle est appelée.

• A partir de ces graphes on peut acceder au sources des fonctions présentés au format html. Dans ces sources , aux appels de fonctions sont associés des liens vers la définition des fonctions appelées. A tout moment on peut retourner à un des graphes.
• HYPRF ne peut présenter au format html que des sources C et C++ . Lorsque les fonctions se trouvent dans des fichiers de spécifications de Lex ou de Yacc ( ou un de leur clones ) , ces fichiers sont également htmlifiés. Cela semble marcher assez bien pour les fichiers Yacc , par contre les fichiers Lex sont en géneral mal traités ( pas de plantage , mais une colorisation inadequate ).
• HYPRF a l'originalité ( enfin , je crois ) de construire les graphes à partir des programmes objet ou exécutables , plus exactement à partir de la sortie de l'utilitaire objdump -dl ( GNU ) , le désassemblage d'un fichier objet ou exécutable.

cette approche à pour avantage principal de m'avoir fait ecrire moins de code ( donc moins de bugs potentiels ). Elle a aussi quelques inconvenients. Je prévois de partir des programmes sources dans une prochaine version.
•  HYPRF n'est que la glue pour assembler d'autres packages :
• HRF contient les programmes écrits spécialement pour HYPRF .
• Les autres packages peuvent eventuelement etre utilisés à d'autres fins. il s'agit de :
• GRF : confection de graphes.
• PIL : gestion de piles
• LIS : gestion de listes
• DBG : quelques fonctions de debugging.
• MISC : des choses diverses  qui ne meritaient pas la confection d'un package special pour chacune.

Invocation des programmes.

• L'inconvenient principal ( enfin j'espère qu'il n'y en a pas de pire ) de cette version de test réside dans son utilisation. Toutefois , dans la plupart des cas , elle ne devrait pas poser de problèmes.

• Du fait du fonctionnement de HYPRF , les programmes à analyser doivent etres compilés et les programme sources , objets ou exécutables disponibles. De plus ils doivent etre compilés avec certaines options : pas d'option d'optimisation et l'option -g de GCC. Si on opère à partir d'un programme executable , il ne doit pas etre 'linké' avec l'option -s . Ces options sont parfaites si vous voulez utiliser GDB ( GNU debugger ) , mais peuvent ne pas etre souhaitées dans le cadre d'une exploitation normale. il vous faudra dans ce cas compiler spécialement le programme à analyser.

• Le problème principal consiste à indiquer au compilateur les options souhaitées :
• s'il s'agit d'un programme GNU , ça ne pose aucun problème , la démarche est la suivante
• Lire la doc d'installation du logiciel , elle vous indiquera que - sauf cas particulier - la génération du logiciel se fait par les 2 commandes :  ./configure" et make .
• comme ce sera probablement indiqué dans la doc , il est possible d'indiquer à make certaines valeurs de variables , après avoir entré ./configure , au lieu d'entrer la commande make , entrez make CFLAGS="-O0 -g" .
• verifier que tout c'est bien passé.
• s'il ne s'agit pas d'un programme GNU , il est très possible que la démarche à suivre soit la meme. se reporter à la doc d'installation , dans le pire des cas , vous devrez éditer et modifier à la main le Makefile.
• afin de verifier que les options seront bien passées au compilateur ,  l'option -n de make qui n'execute *pas* les commandes mais les affichent en sortie peut vous etre utile. Pour cela , entrez make CFLAGS="-O0 -g" -n .

• Lorsque cela est fait , felicitez vous , le plus dur est passé.

• Bon , maintenant vous devez executer HYPRF. Désolé , pas de widgets , pas d'icones , pas de pop-up , pas de help. La façon la plus courante et la plus simple de l'utiliser est de se placer dans le répertoire racine du logiciel a analyser par hyprf et ,  au prompt du shell , entrer simplement hypx  -f <program> , <program> etant le programme executable ou objet à analyser. D'autres options sont disponibles. hyprf n'analysera que les sources situés dans la hierarchie du répertoire courant.

il est egalement possible d'indiquer a hyprf un répertoire autre que le répertoire courant comme base de la hierarchie dans lequel les sources seront analysés. par hypx -f <program> -t <répertoire>

• Dans les 2 cas , les fichiers html des graphes seront placés dans le répertoire constituant la base de la hierarchie , leur nom est  hyp<program>index1.html et hyp<program>index2.html pour le graphe inversé . les fichiers sources htmlifiés sont placés dans le meme répertoire que le fichier source correspondant , ils ont pour nom celui du source suffixé par .html.

des fichiers temporaires sont egalement placés dans /tmp/hyprf , ils ne sont pas détruits en fin de la procédure de maniere à permettre un debugging éventuel.

• si ca ne marche pas , reportez vous au chapitre BUGS.
• pour consulter les  resultats , pointez votre browser préféré sur hyp<program>index1.html qui constitue un bon depart pour la ballade.

Je pense que la présentation est suffisamment intuitive pour que la doc en ligne ne soit pas tres utile.

Les documents html générés.

•  Graphes des dépendances entre les fonctions d'un programme.
•  Les fonctions appelées par une autre sont situées à droite de la fonction appelante , dans sa hierarchie.

dans le cas du graphe inversé , c'est l'inverse.
•  Le sous graphe correspondant aux dépendances d'une fonction n'est montré qu'une fois à un endroit ou cette fonction est au plus haut niveau ( i.e. hierarchiquement le  plus près de la racine ) du graphe.

Dans le cas ou le sous-graphe des dépendances d'une fonction est montré ailleurs , un lien clickable situé apres le nom de la fonction permet d'acceder  au sous-graphe ayant pour racine cette fonction.
exemple :
 maFonction (+54)       indique que la fonction maFonction() en appelle d'autres (ou est appelée par d'autres dans le cas du graphe inversé) et que le sous-graphe correspondant  est montré 54 lignes plus haut , en clickant sur (+54) , on accède  à ce sous-graphe.
54 lignes plus haut , vous trouverez cette fonction suivie du sous-graphe indiquant ses dépendances. la ligne sera affichée :
             maFonction ¤                le caractère ¤ indiquant que cette ligne est la cible d'un lien defini dans la meme page.
• Les noms de fonctions peuvent etre des liens vers la .tion de la fonction dans le fichier source 'htmlifié' lorsque ces sources se trouvent dans la hierarchie analysée ( voir invocation ) . Dans l'exemple , cliiquer su  maFonction permet de visualiser sa definition

•  les fichiers source en format html.
•  Les fichiers sont colorisés de maniere a faire apparaitre la structure globale du source , cette colorisation fait apparaitre  de maniere particuliere :
• les commentaires.
• les directives du preprocesseur.
• les declarations et definitions  au niveau global ( situées à l'exterieur de toute accollade ).
• lorsque une fonction est appelée dans le corps du programme,, un lien - materialisé par ® - vers sa definition (lorsqu'elle est definie dans la hierarchie analysée - voir invocation - )  est placé à la droite de la ligne de l'instruction. Dans le cas ou l'instruction tiens sur plusieurs lignes , ce lien est placé sur la premiere ligne de l'instruction.

 

Bugs et autres desagréments.

• Les problèmes connus concernent principalement les lacunes dans la presentation des  documents HTML génerés Aucun 'plantage serieux'  n'est pour le moment répertorié.
• Les tags cibles dans les fichiers sources sont placés avant la définition des fonctions de manière à ce que cette définition apparaisse dans la page. Lorsque cela est possible le tag est placé après la fin de la fonction précedente de manière à faire apparaitre les commentaires judicieux que souvent les programmeurs placent avant la définition de la fonction. Il y a evidement un problème lorsqu'il s'agit de la première fonction. il y a aussi - pour d'autres raisons - un problème lorsqu'il s'agit de fonctions inline. De toute manière le tag cible ne devrait jamais etre placé plus de 16 lignes avant la définition de la fonction ce qui devrait faire apparaiter celle-ci dans la page à moins que vous n'utilisiez une taille de police démesurée.

Ces problèmes devraient etre corrigés dans une prochaine release.
• le fait que le lien vers une fonction appelée soit placé sur la première ligne de l'instruction ou se situe l'appel peut etre génant lorsqu'il s'agit d'une instruction complexe. Ce problème ne sera vraisemblablement pas corrigé prochainement.
• La DEMO , construite à partir du logiciel INDENT contient à peu près toutes les lacunes de présentation connues.
• Si vous trouvez un Bug , des informations interessantes se trouvent dans le fichier /tmp/hyprf/hyp<program>dbg , faites le moi parvenir attaché à un email.
• si vous avez des suggestions , n'hesitez pas , faite les moi parvenir.

Remerciements.

• J'ai ecrit les programmes seuls , mais rien ne surgit jamais du néant.
• Merci donc à tout ceux qui participé au projet GNU/Linux , qui m'ont ainsi permis de developper sur un bon systeme dans un bon environement.
• Merci à tout ceux qui ont produits les logiciels libres que j'utilise.
• Merci aussi à ceux qui m'ont encouragé et prodigué des conseils avisés.