Quelle arborescence de fichiers utiliser pour nos dépôts ?

Version imprimable

20/09/2013, 19h44
Neckara

1 pièce(s) jointe(s)

Quelle arborescence de fichiers utiliser pour nos dépôts ?

Quelle arborescence de fichiers utiliser pour nos dépôts ?
Venez décrire votre organisation et en débattre !

Lorsqu'on travaille sur un projet, respecter les bons principes de la programmation et ajouter des commentaires pour pouvoir générer une documentation n'est pas suffisant.

En effet, pensez à la personne qui essayera de relire vos dizaines voire centaines de fichiers. Il faut qu'elle puisse trouver le plus rapidement les informations/fichiers qu'elle cherche.

J'ai souvent vu des projets avec à la racine :
- un dossier bin pour les exécutables ;
- un dossier lib pour les dépendances ;
- un dossier include pour les fichiers d'en-têtes de la bibliothèque ;
- un dossier src pour les sources (.cpp et .h) ;
- un dossier doc pour la documentation ;
- un fichier Makefile/CMake/de projet pour compiler ;
- un README ;
- un fichier INSTALL décrivant la procédure d’installation ;
- un dossier datafile/ressources pour tous les fichiers sons/images.

Mais quand on se penche sur le contenu de ces dossiers et des fichiers, chacun fait un peu à sa sauce.
On peut se retrouver avec 50 fichiers dans un seul dossier dans les sources ou à l'inverse avoir 7 fichiers pour 4 dossiers.

http://www.developpez.net/forums/att...1&d=1379702854

D'après vous,
:fleche: Comment devrait être constituée l'arborescence d'un projet ?
:fleche: Que mettre dans les fichiers README et INSTALL ? Quel « plan » adopter, quel « pattern » suivre pour ces fichiers ?
:fleche: Pour les fichiers sources, faut-il créer un dossier par namespace ?
:fleche: Comment regrouper/trier les fichiers sources ? Combien faut-il mettre de fichiers « maximum » dans un dossier ?
:fleche: Quelle profondeur donner à notre arborescence ?

:fleche: Bref, quel est pour vous le squelette type d'une arborescence idéale de fichiers et quelles seraient vos consignes pour le remplir ?

Salut,

Lorsque je crées un projet qui est destiné à être compilé par plusieurs systèmes ( autotools, code::blocks et cmake, pour ne citer qu'eux), j'ai tendance à créer un dossier par catégorie.

Pour ce qui est de la documentation, je rajoute (parce que je l'utilise :D) souvent un dossier "doxygen" qui contiendra la configuration (doxyfile, par défaut ;) ) et les éventuelles pages connexes ("group.dox", "namespace.dox" et autres joyeusetés qui permettent de créer des pages en relation avec un concept en général mais non relative à une classe particulière), le tout en faisant en sorte que la documentation générée se trouve dans le dossier doc.

Je place d'office tous mes fichiers d'en-tête dans le dossier include, mais je le subdivise régulièrement en fonction de "modules" particuliers.

De la même manière, je mets tous mes fichier d'implémentation, à l'exception des fichiers relatifs au tests unitaire, dans le dossier src, subdivisé par espace de noms ou par "module".

Ceci dit, j'essaye généralement que la compilation ne se fasse pas dans le même dossier, afin d'éviter que le gestionnaire de version concurrente n'en vienne à essayer de commiter des choses qui n'ont pas lieu d'être (comme les fichiers objets par exemple).

au final, l'arborescence ressemble à quelque chose comme
Code:

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 <root_directory> |-> autotool (toutes les joyeusetés prorpres au outils autocof, autoheader, et automake) | |-> src (les joyeusetés propres à la compilation des sources, en respectant l'aborescence du dossier contenant les fichier d'implémentation) | |-> tests (et celles pour les tests unitaires) |-> codeblocks (les fichiers propes aux projet code::blocks) |-> cmake (et ceux propres au système CMake) |-> doc (gentillement rempli par doxygen) |-> doxygen (j'en ai parlé plus haut) |-> include | |-> module1 | |-> module2 |-> src | |-> module1 | |-> module2 |-> test | |-> module1 | |-> module2
Quant aux bibliothèques externes, elles sont installées dans des dossiers clairement séparés (boost dans un dossier qui lui est propre, et Qt dans un autre), à part quelques unes (libiconv, icu ou libxml2) qui sont directement dans le dossier de mon compilateur.

J'utilise des variables d'environnement pour maintenir tout cela en place, comme

QTDIR qui est le dossier racine dans lequel se trouve Qt
QTBIN qui est le dossier dans lequel se trouvent les exécutables et les dll de Qt (définie sous windows comme étant égale à %QTDIR%\qtbase\bin et sous linux comme étant égale à ${QTDIR}/qtbase/bin)
BOOSTDIR qui est le dossier racine de boost
BOOST_VERSION qui correspond à une chaine de caractères représentant la version de boost (actuellement 1_54)
BOOST_HEADERS qui indique le dossier dans lequel se trouvent les en-tête de boost (définie, sous windows comme étant égale à %BOOSTDIR%\include\boost-%BOOST_VERSION% , sous linux comme étant égale à ${BOOSTDIR}/include/boost-${BOOST_VERSION} et
BOOST_LIB (définie sous windows comme étant égale à %BOOSTDIR%\lib et sous linux comme étant égale à ${BOOSTDIR}/lib )
De cette manière, je peux passer d'une version à l'autre rien qu'en changeant la valeur de QTDIR ou de BOOST_VERSION, et je peux les utiliser dans les différents scripts / EDI pour la configuration ;)

Note que je dispose de scripts pour définir ces variables sans devoir toucher au variables d'environnement au niveau du panneau de configuration ;)

Enfin, je n'ai aucun a priori quant au nombre (minimal ou maximal) de fichiers qu'un dossier peut / doit contenir.

Je structure mon arborescence en fonction des modules que je crées et chaque dossier contient donc les fichiers nécessaires et utiles au module en question ;)

S'il y en a un qui contient 7 fichiers et l'autre qui en contient 150, c'est qu'un module est beaucoup plus complexe que l'autre, tout simplement ;)

22/09/2013, 11h31
CedricMocquillon
Chez moi ça ressemblait pas mal à ce que viens d'exposer koala01. J'ai cependant récemment changé mon organisation pour privilégier un dossier par module (un module étant une entité compilée à part généralement sous forme de lib statique ou dynamique) :
Code:

1 2 3 4 5 6 7 8 9 <root_directory> |-> module1 | |-> module1 (include) | |-> src | |-> test |-> module2 | |-> module2 (include) | |-> src | |-> test
J'utilise également des sous-répertoires "detail" (dans les includes ou les sources) à la manière de boost.
Je trouve le découpage par module plus "propre" si tes modules sont très indépendants (ça permet notamment de partager plus facilement un module, de le versionner à part, ...)
Après (honte à moi) je n'ai pas de répertoire doc, doxygen et autres, mais pour respecter l'idée, je devrais sans doute en avoir un dans chaque module.
22/09/2013, 12h48
Neckara

Bonjour,

Que mets-tu dans tes dossiers "détails" ?
Je présume que tu mets dedans toutes les classes/fonctions qui ne se retrouvent pas "exposées" dans l'interface de ta bibliothèque ?
22/09/2013, 13h38
Bousk
Bonjour,

en général je suis plus ou moins toujours le même schéma:
Code:

1 2 3 4 5 6 - root -- Docs -- Exe -- Dev --- Src --- Externals
22/09/2013, 13h42
CedricMocquillon

@Neckara : oui c'est bien ça: tout ce qui est nécessaire pour que le module puisse fonctionner mais qui n'est pas utile pour l'utilisateur du module (hors interface donc du dit module)
22/09/2013, 14h47
koala01
Citation:
Envoyé par CedricMocquillon

Chez moi ça ressemblait pas mal à ce que viens d'exposer koala01. J'ai cependant récemment changé mon organisation pour privilégier un dossier par module (un module étant une entité compilée à part généralement sous forme de lib statique ou dynamique) :

Code:

1 2 3 4 5 6 7 8 9 <root_directory> |-> module1 | |-> module1 (include) | |-> src | |-> test |-> module2 | |-> module2 (include) | |-> src | |-> test

J'utilise également des sous-répertoires "detail" (dans les includes ou les sources) à la manière de boost.
Je trouve le découpage par module plus "propre" si tes modules sont très indépendants (ça permet notamment de partager plus facilement un module, de le versionner à part, ...)
En effet, cela permet de garder très certainement une hiérarchie plus "propre" et, à bien y réfléchir, je vais très certainement "migrer" vers ce type d'organisation ;):D

Citation:

Après (honte à moi) je n'ai pas de répertoire doc, doxygen et autres, mais pour respecter l'idée, je devrais sans doute en avoir un dans chaque module.

Et encore, cela dépend fortement : rien ne t'interdit effectivement d'avoir un dossier doxygen (pour ne citer que lui) dans chaque module, pour tout ce qui a trait au module en question, mais qu'est ce qui t'interdit d'avoir un dossier doxygen également dans le dossier racine de ton application / projet, pour tout ce qui est relatif au projet en général et pas forcément à un module particulier :question:

L'avantage en générant la documentation sur le dossier racine, c'est que tu obtiens directement la doc de tous les modules, sans devoir commencer à ouvrir un onglet par module (à cause des interdépendances) et que cela te permet, justement, d'avoir une vision plus globale de ces dépendances ;)

Et, même si tu décides de placer le contenu de tous tes modules dans l'espace de noms global (c'est un choix que je ne cautionne pas, mais bon, certains le font :D), tu peux avantageusement utiliser la notion de groupe ( @group pour en définir un, @ingroup pour indiquer qu'une classe ou une fonction fait partie du groupe en question) pour que la documentation se répartisse dans les différents modules ;) (d'ailleurs, il semble cohérent d'utiliser la notion de groupe même si tu utilises des espaces de noms différents en fonction de tes modules :D)

Pour ma part, ça a tendance à ressembler à ça pour les projets sérieux :
(en + les éléments versionnés, en - les éléments ignorés dans le dépôt)

Code:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
 
+depot
|+.bzrignore
|+executive (répertoire d'exécution, réplique de l'environnement client)
|+projects
||+Projet.cbp
||-bin (contient les binaires)
|||-BuildTarget1
|||-BuildTarget2
||-obj (contient les temporaires nécessaires durant le build)
|||-BuildTarget1
|||-BuildTarget2
|+Projet1 (ici une application)
||+dossier
||+fichier.cpp
||+fichier.h
|+Projet2 (ici une lib)
||-bin (contient les .dll)
||-lib (contient les .a)
||+dossier
||+fichier.cpp
||+fichier.h
|+Projet3
|+codecommun1
|+codecommun2

23/09/2013, 10h29
deusyss

Personnellement, jusqu'à il y a peu, je m'adaptais à mes développements, me focalisant surtout sur une structure bien ordrée et rangée.

Récemment, ayant cherché à créer un exécutable windows à partir de code source PYTHON, les outils m'ont imposés d'eux mêmes une certaine structure. Maintenant, donc, mes projets sont plutôt organisé avec cette structure:
<DOSS PJ>
----<fichiers sources *.py>
----<fichier icone>
----<packages>
----<Dossiers doc>
----<Dossier bdd>
----<Dossier img>
----<Autre dossier data>
----<Dossier pour la creation de l'exe>
--------Fichier de licence
--------Fichier texte pre install
--------Fichier texte post install

J'integre le contenu de readme dans la documentation. Pour le reste, je met à dispo code source, paquet .deb, zip windows standalone et un exe d'install windows. Je me passe donc de fichier INSTALL.txt

EDIT: A titre personnel, je pense que la structure retenue et utilisée importe peu, du moment que celle-ci utilise une certaine logique et reste cohérente

pour moi, ça dépend du type de projet. Par exemple, si je fais une lib (donc destinée à être utilisée par d'autres), je sépare bien les en-têtes des sources, sinon je préfère autant regrouper les fichiers par classe (en-tête et source d'une même classe dans le même dossier). Pour les programmes qui requièrent des ressources (images, vidéos, sons, ...), je crée un fichier ressource à la racine. En gros, ça ressemblera à ça:

Code:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
 
+trunk
-- bin // les binaires qui sont générés
    |-- win64
          |-debug
          |-release
    |-- win32
          |-debug
          |-release
    |-- linux64
          |-debug
          |-release
    |-- linux32
          |-debug
          |-release
-- ext // code externe
    |-- bin // les binaires compilés
          |-- win64
              |-debug
              |-release
          |-- win32
              |-debug
              |-release
          |-- linux64
              |-debug
              |-release
          |-- linux32
              |-debug
              |-release
    |-- libs // ici je met les libs telles que je les ai récupéré, avec la doc, le code source, etc. j'aime bien les mettre dans le dépôt, mais ce n'est pas systématique
          |-- boost
          |-- sfml
-- ressources // images, videos, sons, fichier de config, etc.
-- projects
    | -- visual
    | -- codeblocks
    | -- cmake
-- src
    | -- model
    | -- view
    | -- controller
    | -- common
-- temp // ici tous les fichiers temporaires (objets, etc.), ce répertoire n'est présent qu'en local (pas sur le dépôt)
-- doc

23/09/2013, 12h35
imikado

On peut répondre pour les projets web, ou c'est réservé aux langages compilés ?
23/09/2013, 12h48
cob59

Vous commitez vos binaires, vous ?
23/09/2013, 13h50
Neckara

Citation:

Envoyé par imikado

On peut répondre pour les projets web, ou c'est réservé aux langages compilés ?

Un projet web n'est pas forcément un projet basé sur des langages uniquement interprétés ;)
Mais oui, tu peux présenter ton arborescence.

Citation:

Envoyé par cob59

Vous commitez vos binaires, vous ?

Personnellement, je dirais non.
Le dossier "bin" est souvent vide et n'est remplit que par l'utilisateur lorsqu'il souhaite compiler les sources.
Mais j'ai déjà vu des projets qui commitaient bien les binaires.
23/09/2013, 14h03
jouana

A ça j'ajouterais une branche pour chaque version de livraison
23/09/2013, 14h03
imikado
Oui je sais, mais merci pour la réponse, personnellement, utilsant un framework, il me génère l'arborescence suivante:
Code:

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 + MonProjet |-conf |-data |--img |--log |--upload |-layout |-model |-module |--monModule |---view |-plugin |-plubic |--css |---images |--js
23/09/2013, 14h43
Bousk

Citation:

Envoyé par cob59

Vous commitez vos binaires, vous ?

Oui, il y a toujours un binaire/executable release fonctionnel qui est dans le repo.
Il n'y a pas que des développeurs dans une équipe.
23/09/2013, 15h03
germinolegrand

Pour ce qui est des binaires, de mon côté il y a un dépôt exprès "releases" qui contient des versions des logiciels compilées à l'usage de ceux qui n'ont pas de compilateur dans l'équipe, mais il y a aussi les outils destinés à entretenir l'environnement de développement (dépôt "tools"), ainsi que les .a et .dll dont on n'assure pas la maintenance ou dont le processus de génération est trop complexe pour être faite par tous les devs (exemple la SFML qu'il faut générer depuis un dépôt github, nécessite les outils supplémentaires git et cmake).
23/09/2013, 15h06
cob59

Citation:

Envoyé par Bousk

Oui, il y a toujours un binaire/executable release fonctionnel qui est dans le repo.
Il n'y a pas que des développeurs dans une équipe.

En général je préfère créer un dossier package/ en haut de l'arborescence, et y livrer régulièrement (pas forcément à chaque commit) des archives ou installateurs prêts à l'emploi, qui contiennent les bin/lib/data requis. Dans mon cas, via l'utilisation de CPack.

C'est aussi simple pour les non-dev qui ont juste à télécharger 1 setup/.zip et ça évite de commiter systématiquement des binaires volumineux, longs à uploader et pas forcément stables/livrables.
23/09/2013, 21h00
skypers

Ça dépend des projets, bien évidemment. Pour la plupart de mes projets en C/C++, je suis ce schéma :

build

bin (si généré(s))
lib (si générée(s))
*.o
Makefile
include
samples
src
tests
COPYING
README.md
CHANGELOG
.git

Et je fais de la compilation out-of-src-tree. Sur de gros projets, je remplace simplement le Makefile par un CMakeFile.

Pour mes projets en Haskell, je suis la recommandation de cabal et m’y tiens.
25/09/2013, 15h42
esperanto

Citation:

Envoyé par cob59

Vous commitez vos binaires, vous ?

En aucun cas!
Une règle qui me semble fondamentale dans un gestionnaire de versions est de ne jamais valider (traduction du mot commit) ce qui est créé par des outils (compilateur, langage de formatage, ou autre) : on doit pouvoir relancer les outils et reconstituer les fichiers.

Si vous le faites :
- vous n'êtes pas certain que le fichier généré est synchro avec les sources (il peut avoir été compilé avant vos dernières modifs), parfois on voudrait que ce soit le cas, parfois non (genre mettre dans le dépôt la dernière version de prod...)
- à chaque fois que vous relancez toute la chaîne de compilation, vous allez recréer ces fichiers et vous prenez le risque qu'ils soient absorbés quand vous lancez le commit
(exemple vécu avec un projet libre dont je ne suis pas l'auteur mais auquel je collabore : un fichier html est généré à chaque fois avec des numéros de version dedans; à chaque commit le VCS le voit comme un fichier modifié, et une fois sur 2 j'ai un conflit avec le même fichier "modifié" par un collègue...)
D'autant plus qu'un diff entre binaires est toujours moins bon que pour des fichiers textes (il n'existe pas d'algorithme "merge" capable de fonctionner sur n'importe quel format binaire, alors que pour le texte divisé en ligne ça existe).

Donc, d'accord pour un répertoire "bin" à la racine, mais dans le gestionnaire de versions, il doit être vide (ou se limiter à des .ignore ou ce genre de choses).
D'ailleurs je trouve que c'est également valable pour un répertoire lib/ contenant les dépendances : avec Ant ou Maven (Java) on a prévu des dépôts spécifiques pour les dépendances, je ne vois pas pourquoi on ne ferait pas de même dans d'autres langages.

Citation:

Envoyé par Bousk

Oui, il y a toujours un binaire/executable release fonctionnel qui est dans le repo.
Il n'y a pas que des développeurs dans une équipe.

En général les non-développeurs ne vont pas chercher dans Git ou Subversion. Ceux qui veulent les binaires n'ont rien à faire des sources, et inversement, c'est pour ça qu'on n'utilise pas les mêmes outils pour les deux dépôts (pour les dépôts de binaires, le plus souvent un simple FTP suffit)
04/10/2013, 12h32
jblecanard

Salut à tous

Je ne commite pas mes binaires non plus, ni tout ce qui peut être régénéré. Si un non développeur à un niveau suffisamment élevé pour utiliser un repo git ou svn, alors il doit aussi être capable de lancer la compile et générer le projet. Dans le cas contraire, on met un dépôt de binaires prêt à sa disposition via un autre canal.

Je me permet de compléter un peu le débat avec un point qui n'a pas été vraiment soulevé : le code multi-plateforme. Je n'utilise pas la technique des macros pour sélectionner le code qui va sur une plateforme ou sur l'autre. Je préfère les mettre dans des .cc (ou .cpp selon votre convention) séparés totalement et laisser l'outil de compilation construire la liste des fichiers à utiliser.

Un .cc mutliplateforme ira dans:
src/[chemin]/fichier.cc

Un .cc qui doit être implémenté différemment ira dans:
src/[platform1]/[chemin]/fichier.cc
src/[platform2]/[chemin]/fichier.cc
15/10/2013, 14h26
r0d

J'ai une question à propos de ces arborescences de projets: lorsque vous utilisez des libs externes, comment gérez-vous les versions de ces libs externes (dépendances)?

Prenons pour exemple boost, que tout le monde connait et qui fonctionne bien en tant qu'exemple car elle évolue beaucoup.
La première approche consiste à se fixer une version: je fais mon appli avec la version 1.5.2 de boost, et je reste, jusqu'à la fin, sur cette version. L'avantage est que c'est beaucoup plus simple à gérer. Les désavantages sont multiples, et on les connait.

La meilleure solution, surtout lorsqu'on travaille sur des projets voués à être maintenus et à évoluer pendant des années, est de mettre régulièrement à jour les dépendances. Mais alors, est-ce que vous faites apparaitre la version de la lib ou non? Par exemple, le dossier qui contient les en-têtes de boost s'appelera-t-il "boost-1.5.2" ou "boost"?
15/10/2013, 14h32
white_tentacle

En général, les libs externes ne sont pas intégrées au repository. Il y aura exception si la lib est petite, que ça a du sens de la recompiler (par exemple : elle est modifiée par rapport à la version upstream).

Du coup, la question ne se pose pas trop en terme d’organisation projet.
15/10/2013, 14h37
germinolegrand

Pour ma part j'ai choisi d'intégrer les lib externes dans un dépôt exprès. J'ai des dépendances entre mes différents dépôts. Je pense que je vais rencontrer des problèmes quand il s'agira de revenir sur un vieux commit (encore que, non, suffit de regarder la date et de revert les différents dépôts à la même date), mais en tout cas c'est plus pratique pour travailler.
15/10/2013, 14h42
koala01

Citation:

Envoyé par white_tentacle

En général, les libs externes ne sont pas intégrées au repository. Il y aura exception si la lib est petite, que ça a du sens de la recompiler (par exemple : elle est modifiée par rapport à la version upstream).

Du coup, la question ne se pose pas trop en terme d’organisation projet.

Tout à fait d'accord :D

Citation:

Envoyé par r0d

J'ai une question à propos de ces arborescences de projets: lorsque vous utilisez des libs externes, comment gérez-vous les versions de ces libs externes (dépendances)?

Prenons pour exemple boost, que tout le monde connait et qui fonctionne bien en tant qu'exemple car elle évolue beaucoup.
La première approche consiste à se fixer une version: je fais mon appli avec la version 1.5.2 de boost, et je reste, jusqu'à la fin, sur cette version. L'avantage est que c'est beaucoup plus simple à gérer. Les désavantages sont multiples, et on les connait.

La meilleure solution, surtout lorsqu'on travaille sur des projets voués à être maintenus et à évoluer pendant des années, est de mettre régulièrement à jour les dépendances. Mais alors, est-ce que vous faites apparaitre la version de la lib ou non? Par exemple, le dossier qui contient les en-têtes de boost s'appelera-t-il "boost-1.5.2" ou "boost"?

Personnellement, je passerais plutôt une (des) variable(s) d'environnement / globales à l'EDI utilisé, #define dans un config.h (par exemple) ou tests dans l'outil de configuration que tu utilises (en fonction des cas :D) avec les valeurs adéquates:

Par exemple, des variables comme BOOST_VER_STRING qui prendraient une valeur 1_xy pour tout ce qui a trait au fait de déterminer les noms des bibliothèques et dossiers ou BOOST_VERSION pour tout ce qui permet de déterminer une version minimale à utiliser (outils de configuration automatique, essentiellement)
15/10/2013, 18h22
r0d

Citation:

Envoyé par white_tentacle

En général, les libs externes ne sont pas intégrées au repository. Il y aura exception si la lib est petite, que ça a du sens de la recompiler (par exemple : elle est modifiée par rapport à la version upstream).

Ha oui j'avais oublié que beaucoup de gens n'intègrent pas les dépendances externes au dépôt. C'est peut-être même une bonne pratique?

Moi maintenant j'ajoute presque toutes mes dépendances externes à presque tous mes dépôts. Pour deux raisons:
- J'aime bien lorsque, quelque soit l'environnement de dev (un pc vierge par exemple), tu checkout le dépôt, tu compiles, ça marche. Pas besoin d'aller chercher les dépendances à droite et à gauche.
- Si tu récupères un projet vieux de 5 ans (et ça m'arrive assez régulièrement), c'est pas toujours évident (parfois impossible même) de trouver les bonnes versions de certaines libs.

Les inconvénients sont nombreux, mais après 10 ans de pratique, je trouve que ces deux avantages, à eux seuls, pèsent plus que les inconvénients.
15/10/2013, 20h19
Neckara

Bonjour,

Personnellement, dès que la lib est petite, je l'intègre au dépôt, c'est plus simple, un seul cmake . && make à faire.

Dès que la lib est assez "importante", je met ses sources et quelques binaires en téléchargement et je donne les URL dans mon fichier INSTALL.