]> Creatis software - bbtk.git/blob - kernel/doc/bbtkDevelopersGuide/Architecture.txt
*** empty log message ***
[bbtk.git] / kernel / doc / bbtkDevelopersGuide / Architecture.txt
1 Reflexions sur l'archi de bbtk et des packages
2 ----------------------------------------------
3
4 *STRUCTURE DU SOURCE TREE :
5 ---------------------------
6
7 La lib bbtk devrait être dans un rep à part entiere et chaque package 
8 de la distrib standard à part avec la même structure qu'un package utilisateur
9
10 donc dans le rep racine des sources :
11
12 data/ reste data/
13
14 creation rep "kernel" qui correspond au toolkit bbtk (lib+appli)
15
16 kernel/src/ accueille src/kernel/
17 kernel/doc/ accueille doc/
18 kernel/installer/ accueille install/
19 kernel/cmake/ accueille cmake/
20 kernel/appli/ accueille appli/
21
22 creation rep packages/ qui accueille chaque package de la distrib standard
23
24 donc on aura :
25 packages/std/
26 packages/wx/
27 etc.
28
29 la structure de chaque package sera identique et identique à celle créée par bbCreatePackage pour les utilisateurs :
30
31 A la racine des sources d'un package, je propose :
32 src/ : sources (ce qui est actuellement en vrac dans /src/packages/std/ par ex.)
33 doc/ : docs 
34 doc/bbdoc : rep pour creation de la doc du package par bbdoc (bbi à terme ? cf. ci-dessous) incluant les images si besoin
35 doc/doxygen : doc doxygen
36 bbs/ : scripts associés au package
37 bbs/boxes
38 bbs/appli
39 cmake/ : fichiers cmake pour build/install
40
41 * PROPOSITION : TOUT EST BLACK BOX ET PACKAGE !
42 -----------------------------------------------
43
44 A l'heure actuelle, du point de vue de l'utilisateur ou du createur 
45 de package, il y a :
46 - les packages (libraries dynamiques) :
47   - utilisés avec 'load' dans bbi
48   - documentés :
49     - en texte par 'help' dans bbi
50     - en html par l'appli bbdoc (créée automatiquement lors du build)
51       ces doc html sont référencées dans la doc html du package 'user' générée par 'graph' dans bbi (cf. ci-dessous)
52 - les scripts (.bbs) :
53   - utilisés avec 'include' dans bbi
54   - documentés dans bbi par 'graph' qui documente le package 'user'
55   Les scripts sont de deux types :
56     - scripts de définition de complex boxes (define/endefine)
57     - scripts d'appli (appli finale, de test, de demo, ...)
58
59 Quand un utilisateur crée un nouveau package, 
60 ce package comprend à la fois une librarie dynamique 
61 (mais pas forcément, lire la suite ...) et des scripts (idem).
62 Evidemment, il a envie :
63 - que tout soit utilisable (donc que les chemins pour trouver sa lib et ses scripts soient connus de bbi).
64 - que tout soit documenté et référençable (i.e. que les chemins pour référencer les doc de ses boites soient connus des autres packages).
65
66 Je propose que :
67 - les complex boxes définies par des scripts fassent partie à part entière du package (et de sa doc). 
68 Le mécanisme :
69  1) dans bbi, quand on définit une boite par 'define', on peut spécifier le package dans lequel elle va être placée, 
70  ex. : "define XOR std" dit que la boite XOR va dans le package std.
71  Si ce package existe (déja loadé ou précédent 'define TOTO std') : ok l'insère. Sinon crée un nouveau package. 
72  => Déja mis en place et testé : cf scripts/test/testDefine.bbs
73  Autre manière de faire : nouveaux mots-clés de bbi 'package/endpackage'.
74  ex. : 
75 > package mypack
76 >  description "mon magnifique package"
77 >  author "foo@bar.com"
78 >  define mybox
79 >  ...
80 >  endefine 
81 >  define mybox2 
82 >  ...
83 >  endefine 
84 > endpackage
85  toutes les boites définies entre 'package/endpackage' vont dans le package 
86  (de la même manière que toutes les instances créés par 'new' entre 
87   'define/endefine' vont dans la complex box courante).
88   Ici, mybox et mybox2 seront dans mypack.
89   Intérêt du bloc 'package/endpackage' : pouvoir documenter le package 
90   grace aux commandes standard 'description/author' ...
91   (REM : finalement, le package 'user' et la boite 'workspace' 
92    peuvent se voir comme si au lancement, bbi exécutait les commandes 
93    "package user" puis "define workspace". Ca donne des idées pour avoir plusieurs workspaces...)
94
95 Revenons maintenant aux scripts de complex boxes d'un package.
96  2) Un package utilisateur (ou standard bbtk) 
97     sera fournit **AVEC SON SCRIPT DE CHARGEMENT**.
98     Par ex: std.bbs sera le script de chargement du package std. 
99     Exemple de contenu :
100     # Load the 'atomic' boxes compiled in dyn lib :
101     load std   
102     # Include the complex boxes scripts (which can load other packages...)
103     include bbXOR
104     ...
105
106     Donc un utilisateur final mettra 'include std' dans ses scripts pour 
107     utiliser le package std (simple & complex boxes).
108  
109  INTERETS : 
110  A) Un utilisateur "lambda" utilisera toujours 'include' et ne verra 
111  que des boxes (simple ou complex). Un utilisateur "averti" pourra toujours 
112  ne loader que la lib ou n'inclure que certains scripts.
113  B) La doc sera générée automatiquement via bbi.
114  Il faut bêtement étendre la commande 'graph' pour que l'on puisse lui 
115  spécifier le nom du package dont on veut générer la doc
116  (A l'heure actuelle graph cherche à documenter une boite du package 'user' 
117  ou une instance de 'workspace' et génère systématiquement la doc du 
118  package 'user' pour les références.    
119  En passant, voir aussi la réflexion ci-dessous 
120  sur les rôles ambigus des commandes help et graph).
121  (La génération auto de la doc pourra se faire 
122  de manière quasiment identique à ce qui est fait à l'heure actuelle 
123  dans la macro BBTK_DOCUMENT_SCRIPTS de cmake/bbtkMacro.cmake : 
124  cela revient à lancer bbi sur un script du type :
125  "include packagename" 
126  "graph packagename good-parameters")
127  Donc plus d'appli bbdoc : tout est fait par bbi !
128
129  3) Doc des appli (.bbs) :
130  Idem que ci-dessus avec un script du type :
131  >package std-demo
132  > description "..."
133  > define DemoXOR
134  >  include DemoXOR
135  > endefine
136  > define DemoAdd
137  >  include DemoAdd
138  > endefine
139  > ...
140  >endpackage
141  >graph std-demo [good-params]
142  bbtk doit fournir aux utilisateurs une macro cmake pour générer ce type de 
143  script, les targets qui vont bien et l'installation de la doc au même endroit 
144  que toutes les autres doc, i.e. dans /packages/<package-name>/bbdoc.
145  Ainsi toutes les refs croisées sont bonnes, on n'a que des packages 
146  documentés qui contiennent des boites (éventuellement d'applications)... 
147
148  Qu'en pensez-vous ?
149
150 Finalement on aura la structure de package :
151  PACK/src
152          scripts/PACK.bbs
153          scripts/boxes
154          scripts/appli
155          doc/boxes
156          doc/appli
157
158
159 * BUILD TREE ET INSTALLATION 
160 ----------------------------
161 Regle : 
162 On doit pouvoir utiliser bbtk ou n'importe quel package aussi bien en tant que package bbi (load/include) ou que librairie c++ (via cmake) 
163 à la fois dans le build tree et dans l'install tree.
164 De plus, un install tree doit pouvoir être déplacé et rester utilisable modulo la spécification explicite du répertoire quand on lance cmake.
165 En effet, FindBBTK.cmake ou Find[PackageName].cmake :
166 1) Ne sont pas installés dans l'install tree mais dans le rep de cmake donc ne sont pas copiés si on copie l'install tree (le Find*.cmake est le seul fichier installé hors install tree à ma connaissance. D'autres ? Ca poserait problème...)
167 2) Même si on installe "à la main" FindBBTK.cmake, le code qu'il contient ne recherche les install de bbtk qu'à des endroits "canoniques" donc si on pose l'install tree dans un endroit "exotique", il ne le trouvera pas et le chemin devra être entré manuellement.
168
169 OK ?
170
171
172
173 Structure des build/install trees :
174
175 *Linux :
176 PREFIX = build_tree_path, /usr, /usr/local
177 PREFIX_SHARE = PREFIX/share/bbtk
178 *Windows
179 PREFIX = PREFIX_SHARE = build_tree_path, C:/ProgramFiles/bbtk
180
181 PREFIX/bin : bbi, etc.
182 PREFIX/lib : libbbtk.so, libbstd.so, etc.
183 PREFIX/lib/bbtk : UseBBTK.cmake, etc.
184 PREFIX/lib/bbstd : UseBBSTD.cmake, etc.
185 PREFIX/include/bbtk : bbtkSystem.h, etc. 
186 PREFIX/include/bbstd : bbstdAdd.h, etc. 
187
188 PREFIX_SHARE/
189 PREFIX_SHARE/doc/bbtkWebSite
190                  bbtkDoxygen
191                  bbtkUsersGuide
192                  etc.
193 PREFIX_SHARE/doc/bbdoc/std : index.html, *.png, etc.
194                        std-demo
195                        wx
196                        wx-demo
197                        USER_PACKAGE
198                        USER_PACKAGE-demo
199                        etc.
200
201 PREFIX_SHARE/doc/doxygen/std : index.html, *.png, etc.
202                          wx
203                          USER_PACKAGE
204                          etc.
205 PREFIX_SHARE/bbs/std/
206                  std-demo
207                  wx
208                  etc.
209                      
210