Improve project documentation

This commit is contained in:
Glenn Y. Rolland 2020-03-03 23:30:21 +01:00
parent 2c932cb2db
commit 9b89b1808b
9 changed files with 434 additions and 5 deletions

5
NOTES
View file

@ -1,5 +0,0 @@
aller voir du coté des classes:
- GeneralPath
- QuadCurves2D
- ...

58
doc/rapport/Makefile Normal file
View file

@ -0,0 +1,58 @@
LATEX = latex
PDFLATEX = pdflatex
PSLATEX = pslatex
DVIPDF = dvipdf
DVIPS = dvips
PS2PDF = ps2pdf
GDATE := $(shell date +"-%Y-%m-%d_r%H")
GFILENAME := CDC$(GDATE).tar.bz2
LOCALDIR = $(shell pwd)
MAINFILE = rapport
#PNGFILES := $(shell ls *.png)
#EPSFILES := $(patsubst %.png,%.eps,$(PNGFILES))
#PNG2EPSCC = convert
TEXFILES := $(MAINFILE).tex
DVIFILES := $(MAINFILE).dvi
PDFFILES := $(MAINFILE).pdf
PSFILES := $(MAINFILE).ps
all: dvi dvi ps pdf pdf
#png2eps: $(EPSFILES)
#%.eps : %.png
# @$(PNG2EPSCC) $< $@
# @echo -e "png2eps\t$< $@"
clean:
@rm -f rapport.dvi rapport.rtf rapport.pdf rapport.ps
@rm -f *.out *.log *.toc *.aux
# @rm -f *.eps
@rm -f *~
pdf: $(TEXFILES)
$(PDFLATEX) $(TEXFILES)
ps: $(TEXFILES)
$(DVIPS) $(DVIFILES)
dvi: $(PRJFILES)
$(LATEX) $(TEXFILES)
#mail: package sendmail
#
#pdfmail :
# make && make
# echo "Et voila le dernier pdf" | mutt lsr-dev -a $(PDFFILES) -s "[CDC] Rev$(GDATE) (en PDF)"
#
#sendmail:
# echo "Et voila" | mutt lsr-dev -a ../Archives/$(GFILENAME) -s "[CDC] Rev$(GDATE) (en TeX)"
#
package: clean storefile
#storefile:
# tar -cjvf ../$(GFILENAME) -C ../ cdc
# mv ../$(GFILENAME) ../Archives

26
doc/rapport/arbo.tex Normal file
View file

@ -0,0 +1,26 @@
\section{Arborescence du projet}
\par L'archive du projet contient (au moins) les répertoires et fichiers suivants :
\begin{verbatim}
Libnazgul/
|-- README // Instructions pour la compilation du projet
|-- HEADER // Header du projet Libnazgul
|-- LICENSE // Licence qui couvre le projet
|-- Makefile // Règles de compilation
|-- doc/
| |-- ennonce // Enoncé du projet en format postscript
| |-- rapport/ // Rapport Latex
| |-- Makefile // Règles de compilation
| |-- ...
|
|--test
| |-- Makefile // Règles de compilation
| |-- create_delete // Le main de la fonction
| |-- put_get_mono // Test avec un seul processus
| |-- put_get_multi // Test avec plusieurs processus
|
|
|-- src/ // Sources de la bibliothèque
|-- Makefile // Règles de compilation
|-- ...
\end{verbatim}

12
doc/rapport/avenir.tex Normal file
View file

@ -0,0 +1,12 @@
\chapter{A venir}
\par Bien que nous ayons fini le projet, il se peut qu'il ne soit pas
sans défauts. C'est pourquoi dans l'avenir, il faudrai corriger les
bogues éventuels que tous nos tests n'auraient pas fait appara{\^i}tre.
Mais il n'y a pas que cela; le ``code'' pourrai {\^e}tre amélioré et
allégé. Nous pourrions également faire plus ``subtil'' par endroits.
Nous devrions aussi vérifier tous les codes d'erreurs renvoyés par les
fonctions après leur appel. Il serai également possible de faire en sorte
d'utiliser moins de mémoire en réduisant le nombre de {\em shm}; pour
cela il faudrai changer de structure de donnée. Nous aimerions également
finir l'outil d'analyse {\em msgSpaceState} des {\em msgSpace}.

17
doc/rapport/couv.tex Normal file
View file

@ -0,0 +1,17 @@
\title{Rapport du projet de système: Libnazgul \\ \today}
\date{}
\author{\vspace{1cm} \\ {\sc Cours de système} \\
de Jean-Marie Rifflet et Marin Bertier. \\~\\
{\sc Université Paris 7 - Denis Diderot.}
\\ \vspace{3cm} \\
\begin{tabular}{ r l l }
& Glenn ROLLAND & {\em $<$glenux@fr.st$>$}, \\
& Sebastian SCHAWOHL & {\em $<$stormrider@nerim.fr$>$},\\
& Rivka ZANA & {\em $<$rivka\_zan@hotmail.com$>$}
\end{tabular}
}
%& Rivka ZANA & {\em $<$crivka@caramail.com$>$}
%\date{\today}
%\title{Janat}
%\author{Par Moi}
\maketitle

152
doc/rapport/devel.tex Normal file
View file

@ -0,0 +1,152 @@
\chapter{Le développement}
\section{Outils utilisés pour le développement}
\subsection{Travail collaboratif}
\par Nous avons travaillé ensemble gr{\^a}ce à CVS (Concurrent Versions System). Notre projet est hébergé chez Sourceforge\footnote{\url{http://www.sourceforge.net}}.
Le CVS permet la modification du code du projet en m{\^e}me temps par plusieurs personnes. Les modifications et les mises à jour de chacun des membres du projet sont diffusées instantanément, avec un risque minimisé de conflits lors des modifications du m{\^e}me code.
\subsection{Moyens techniques}
\par Chacun selon nos préférences, nous avons utilisés des machines sous GNU/Linux ou Microsoft Windows et codé avec Vim.
La personne sous Microsoft Windows avait une session graphique sur un serveur GNU/Linux, appartenant a un autre membre du projet,
gr{\^a}ce à l'utilisation de VNC\footnote{\url{http://www.realvnc.com}} (Virtual Network Computing).
Cela afin de permettre à l'utilisateur de Microsoft Windows de pouvoir
tester la bibliothèque dans les meilleures conditions, car sous
Microsoft Windows l'utilisateur n'est pas prévenu des
{\em segmentation fault} et autres erreurs système.
\section{Programmation}
\subsection{Description des fonctions et de leurs effets}
\par Nous allons dresser un descriptif de l'utilité des fonctions
utilisées dans notre bibliothèque. Vous trouverez tous les prototypes
des fonctions dans le fichier \\``\verb+/src/proto.h+'', avec en
commentaire le fichier d'où il est issu. Par contre pour les fonctions
qui génèrent les {\em ids}, leur prototype est dans le fichier ``\verb+/src/ids.h+'', généré par ``\verb+/src/ids.c+''.
Le fichier ``\verb+/src/proto.h+'' est connu des logiciels qui utilisent
notre bibliothèque, tandis que ``\verb+/src/ids.h+'' non.
Nous allons donc vous décrire nos différentes fonctions en les classant
par famille.
\newline
\par Nous avons quatre grandes {\em familles} de fonctions.
\begin{description}
\item{\sc msgBuffer*} Ce sont toutes les fonctions qui concernent les
buffers : comment on les créés, les ``attachent'' aux processus.
\item{\sc msgPool*} Ce sont les fonctions qui permettent de créer ou de
détruire une {\em pool}, de l'ouvrir ou encore de poser un ``verrou''.
\begin{description}
\item{\sc msgPool*} Fonctions servant à gérer une {\em pool}, qui
correspond à un ensemble de {\em buffers}.
\item{\sc msgPoolDataTab*} Fonctions utiles pour la gestion des
informations d'une {\em pool} telles que la taille des {\em buffers},
leur nombre\dots
\end{description}
\item{\sc msgQueue*} Toutes les fonctions gérant les ``queues'', {\em
files de maessages}. On y
trouve celle qui en créé une, celles qui vérifient si elle est
disponible ou pas, celles qui ajoutent un élément ou au contraire en
enlève un.
\begin{description}
\item{\sc msgQueue*} Rassemble toutes les fonctions servant à la gestion
des files de messages.
\item{\sc msgQueueElem*} Les fonctions utiles pour gérer un élément
d'une file de messages.
\item{\sc msgQueue(Prot/Read)*} Fonctions servant à protéger une file.
\end{description}
\item{\sc msgSpace*} Ensemble de fonctions qui gèrent les espaces de
messages : création, ouverture, listes\ldots
\begin{description}
\item{\sc msgSpace*} Fonctions pour la création, ``ouverture'', ``fermeture''\dots d'un espace de messages.
\item{\sc msgSpaceList*} Ce sont toutes les fonctions utiles pour la
gestion de la liste cha{\^i}née des {\em msgSpace} existants.
\item{\sc msgSpaceListElem*} Fonctions correspondant à la gestion d'un
élément de la {\em msgSpaceList}.
\end{description}
\end{description}
\subsection{Détails sur certaines fonctions}
\par Nous détaillerons ici quelques fonctions qui peuvent ne pas
par{\^i}tre claires, malgré les explications au-dessus, ou qui n'ont
pas encore été abordées.
\par Voici la liste des fonctions non abordées dans la partie
précédente, mais néanmoins utiles pour la compréhension de notre
bibliotèque. Les fonctions pour la génération d'{\em ids} ne seront
pas traitées ici, car leur utilité est décrite dans la partie {\sc Difficultés recontrées}.
\begin{itemize}
\item{\sc msgAllocate(\dots)} Prend en argument : un espace de mesage\\
{\em msgSpace *}, un numéro de {\em pool} qui est un {\em int}, une
taille {\em int} et une option {\em int}. Cette fonction, comme
spécifié dans l'énoncé, alloue un buffer
dans le {\em pool} spécifié, ou sinon dans le {\em pool} le plus proche
en taille (supérieure ou égale) et qui sera ``potentiellement'' libre
le plus rapidement, sauf s'il l'est déjà. Pour cela, on regarde le
nombre de {\em locks}, qu'il y a dessus gr{\^a}ce aux sémaphores. On
choisit le buffer dont le {\em pool} a le moins de ``locks'' en fonction
du nombre de ses buffers.
\item{\sc msgFree(\dots)} Cette fonction prend en argument un espace de
message {\em msgSpace *} et l'adresse d'un buffer {\em void *}. Celle-ci
restitue le buffer au {\em pool} d'où il a été extrait.
\item{\sc msgGet(\dots)} Notre fonction {\em void * msgGet(\dots)}, est
telle qu'elle corresponde bien à l'énoncé. Elle prend en argument un
espace de messages {\em msgSpace *}, un numéro de file, ou {\em queue},
{\em int} et l'adresse d'un buffer {\em void *}. Elle renvoie l'adresse
du buffer en t{\^e}te de la file du numéro donné dans l'espace de
messages spécifiés. Lors d'un appel à cette fonction, celle-ci
``locke'' d'abord le sémaphore qu'il y a sur la {\em queue}. Si la file
est vide, cela bloque le {\em get}.\\
{\sc Remarque :} Nous n'avons pas implémenté le cas du \verb+ANYFILE+.
\item{\sc msgPut(\dots)} Cette fonction fait exactement ce qu'elle est
sensée faire tel que énoncé dans le rapport. Elle prend en argument un
espace de messages {\em msgSpace *}, un numéro de file, ou {\em queue}, {\em int} et
l'adresse d'un buffer {\em void *}. Elle insère le buffer dans le numéro
de file de messages de l'espace de messages. Lorsque l'on appelle cette
fonction, à la fin, on ``délocke'' le sémaphore sur la {\em queue}.
\item{\sc msgSpaceState(\dots)} Cette fonction prend en argument, un
``id'' d'espace de message, {\em msgSpaceId}, et permet de conna{\^i}tre
l'état de l'espace de message dont l'``id'' est donnée en argument.
\end{itemize}
\newpage
\section{Difficultés rencontrées}
\par Nous n'avons pas eu de grosses difficultés à proprement parlé.
Nous avions juste quelques restrictions, comme le fait de ne pas
pouvoir utiliser de pointeurs absolus, car l'espace d'adressage entre
les différents processus n'est pas forcément le m{\^e}me. Ils ont
seulement un segment de mémoire partagée en commun. Il a donc
fallu utiliser les différentes {\em id} des espaces de messages {\em msgSpace}, ou
encore des {\em pools} pour pouvoir faire en sorte que les processus peuvent
bien accéder aux {\em buffers} situés dans la mémoire partagée.
\par Le choix des identifiants ne fut pas simple non plus, car il
fallait en changer en fonction des différentes implémentations. Par
exemple nous pouvions avoir des identifiants du type ``\verb+/tmp/identifiant+'',
qui ne marchaient que sur un type de machines. Sur les autres il
fallait en avoir un du type ``\verb+/identifiant+''. Cela nous a amener
à faire une distinction de cas et générer un identifiant différent
selon que l'on soit sur une machine de type {\em HP-UX}, {\em SunOS}
ou {\em Linux}.
\par Malheureusement le fait de travailler sur plusieurs types de
machines n'était pas seulement g{\^e}nant pour les identifiants,
mais également pour créer la bibliothèque. En effet, il faut ajouter
plus ou moins d'options à la compilation: soit il faut ajouter \verb+-lrt+, dans un cas ou \verb+-lrt -lpthread+ dans l'autre. Ceci afin
d'inclure les bonnes librairies pour que notre bibliothèque puisse
fonctionner convenablement.
\par Ces distinctions se font dans les {\em Makefile}, \verb+/src/Makefile+ et \verb+/test/Makefile+.
\par Encore une autre difficulté d{\^u}e à Posix, est la
projection de fichier ou {\em mapping} avec {\em mmap}. L'offset
peut {\^e}tre aligné sur les pages mémoires sur
certains systèmes. Or ceci est emb{\^e}tant lorsque l'on veut
accéder à un fichier qui commence n'importe où dans le bloc mémoire.
Pour remédier à cela, nous {\em mappons} jusqu'à ``juste derrière le
buffer''. Nous autorisons le buffer en lecture/écriture et nous déplaçons
l'adresse obtenue au début du buffer.

43
doc/rapport/intro.tex Normal file
View file

@ -0,0 +1,43 @@
\chapter{À propos du projet}
\section{Condition d'utilisiation}
\par Ce programme est un logiciel libre; vous pouvez le redistribuer et/ou
le modifier conformément aux dispositions de la Licence Publique Générale GNU,
telle que publiée par la Free Software Foundation; version 2 de la licence, ou encore toute version ultérieure.
\par Ce programme est distribué dans l'espoir qu'il sera utile, mais {\em sans aucune garantie}; sans même la garantie implicite de {\em commercialisation} ou {\em d'adaptation à un objet particulier}. Pour plus de détails, voir la Licence Publique Générale GNU.
\par Un exemplaire de la Licence Publique Générale GNU doit être fourni avec ce programme; si ce n'est pas le cas, écrivez à la Free Software Foundation Inc., 675 Mass Ave, Cambridge, MA 02139, Etats-Unis.
\section{Les auteurs}
\par Le projet est réalisé par Glenn ROLLAND, Sebastian SCHAWOHL et Rivka ZANA, élèves en 2ème année d'IUP GMI à l'Université Paris 7 - Denis Diderot.
\section{Les objectifs}
\par L'objectif de ce projet est de réaliser une bibliothèque permettant
à plusieurs processus d'un m{\^e}me sytème de communiquer entre eux via des messages, sans
faire la recopie de ces messages dans l'espace d'adressage du noyau.
\par Nous devions donc mettre en oeuvre les techniques de la programmation
système ainsi que la création d'une bibliothèque de fonctions. Nous avons utilisés les mécanismes de mémoire partagée et de synchronisation version Posix.
\section{Obtenir l'archive du projet}
\par L'archive du projet est sensée accompagner ce rapport. Elle se présente
sous la forme d'un fichier tarball. Pour la décompresser il suffit de taper
``\verb+tar -xzvf Libnazgul-XXXX-XX-XX-rYYYY.tar.gz+''.
\par Si toutefois cette archive n'est pas présente aux c{\^o}tés de ce document,
vous pouvez récupérer les sources du projet via CVS anonyme en tapant dans un terminal:\\
``\verb+cvs -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/libnazgul login+''\\
(appuyez sur la touche entrée à l'invite du mot de passe),
puis :\\
``\verb+cvs -z3 -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/libnazgul co libnazgul+''
\section{Site internet du projet}
\par Le projet Libnazgul est hebergé par
Sourceforge\footnote{\url{http://www.sourceforge.net}},
et son adresse est :
\newline
{\url{http://www.sourceforge.net/projects/libnazgul/}}.
\par Ce site vous permettra de télécharger le projet, d'en avoir
une description et également d'y contribuer.
\newpage

17
doc/rapport/manuel.tex Normal file
View file

@ -0,0 +1,17 @@
\chapter{Manuel d'utilisation}
\section{Que faire de nos sources? \ldots les compiler}
%\subsection{Les compiler}
\par Pour pouvoir utiliser notre bibliotèque, il faut commencer par la
créer. Pour cela placez-vous dans le répertoire de l'archive (noté ici
\verb+/+) ou dans le sous-répertoire \verb+src/+ et tapez ``\verb+make+''.
\section{Que faire ensuite? \ldots inclure notre bibliothèque}
%\subsection{Inclure notre bibliothèque dans un programme}
\par Dans votre programme, si vous voulez utiliser notre bibliothèque
il vous suffit de l'inclure. Au début de votre programme tapez ``\verb+#include ''libnazgul.h``+''.
\par Une fois notre bibliothèque incluse, vous pourrez sans problèmes
appeler les fonctions contenues à l'intérieur : {\it msgSpaceCreate(\ldots), msgPut(\ldots), msgFree(\ldots) etc\dots}

109
doc/rapport/rapport.tex Normal file
View file

@ -0,0 +1,109 @@
\documentclass[12pt,a4paper]{report}
\usepackage{a4wide}
\usepackage{geometry}
\usepackage{typehtml}
\usepackage[latin1]{inputenc}
\usepackage{listings}
\usepackage[french]{babel}
\usepackage{fancyheadings}
\usepackage{color}
\usepackage{float}
\usepackage[cyr]{aeguill} % Police vectorielle TrueType, guillemets français
%\DeclareGraphicsExtensions{.jpg,.mps,.pdf,.png} % Formats d'images
%--------------------------------------------------------------
\pagestyle{fancy}
\rhead[\sc{LIBNAZGUL is Not Another Zero G User Library}]{\sc{LIBNAZGUL is Not Another Zero G User Library}}
\lhead[\it{}]{\it{}}
%\rhead[\it{Projet de Système.}]{\it{Projet de Système.}}
%---------------------------------------------------------------
\newif\ifpdf
\ifx\pdfoutput\undefined
\pdffalse
\else
\pdfoutput=1
\pdftrue
\fi
\ifpdf
% ! The next three lines should be one !
\usepackage[pdftex,colorlinks=true,urlcolor=blue,pdfstartview=FitH]{hyperref}
\pdfcompresslevel=9
\hypersetup{
pdftitle={RAPPORT DU PROJET DE SYSTEME},
pdfauthor={ROLLAND Glenn, SCHAWOHL Sebastian, ZANA Rivka},
pdfsubject={LIBNAZGUL},
pdfkeywords={PROJET}
pdfcreator={GleNuX}
}
\usepackage[pdftex]{thumbpdf} % Vignettes
%\usepackage[pdftex, %
% bookmarks = true,% % Signets
% bookmarksnumbered = true,% % Signets numérotés
% pdfpagemode = None,% % Signets/vignettes fermé à l'ouverture
% pdfstartview = FitH,% % La page prend toute la largeur
% pdfpagelayout = SinglePage,% Vue par page
% colorlinks = true,% % Liens en couleur
% urlcolor = magenta,% % Couleur des liens externes
% pdfborder = {0 0 0}% % Style de bordure : ici, pas de bordure
% ]{hyperref} % Utilisation de HyperTeX
\usepackage[pdftex]{graphicx}
% \usepackage[pdftex]{thumbpdf}
\else
\usepackage[dvips]{epsfig}
\usepackage{hyperref}
\usepackage[T1]{fontenc}
\fi
%---------------------------------------------------------------
\begin{document}
%---------------------------------------------------------------
\newcommand{\texima}[3]{
\begin{figure}[H]
\begin{center}
\ifpdf
% Dans le cas du PDF
% utiliser une image .png, .jpeg ou .jpg
\includegraphics[width=#2,height=#3]{#1.png}
\else
% et dans le cas du DVI / PS
% utiliser du .ps ou du .eps
\epsfig{figure=#1.eps,width=#2,height=#3}
\fi
\end{center}
\end{figure}
}
\newcommand{\texillustr}[3]{
\ifpdf
% Dans le cas du PDF
% utiliser une image .png, .jpeg ou .jpg
\includegraphics[width=#2,height=#3]{#1.png}
\else
% et dans le cas du DVI / PS
% utiliser du .ps ou du .eps
\epsfig{figure=#1.eps,width=#2,height=#3}
\fi
}
\input{couv.tex} % Page de garde
\tableofcontents % Sommaire
\clearpage
\input{intro.tex} % Intro, compilation, exécution
\input{arbo.tex} % arborescence du projet
\input{manuel.tex} % Manuel de l'utilisateur
\input{devel.tex} % outils, ce qu'on a pu trouver dur
\input{avenir.tex}
%\input{conclusion.tex} % est-ce vraiment utile ?
\end{document}