]> Creatis software - bbtk.git/blob - kernel/doc/bbtkDevelopersGuide/Architecture.txt
#3249BBTKBugNewNormalbox Exit package std killing application in windows / Linux
[bbtk.git] / kernel / doc / bbtkDevelopersGuide / Architecture.txt
1  # ---------------------------------------------------------------------
2  #
3  # Copyright (c) CREATIS (Centre de Recherche en Acquisition et Traitement de l'Image
4  #                        pour la SantÈ)
5  # Authors : Eduardo Davila, Frederic Cervenansky, Claire Mouton
6  # Previous Authors : Laurent Guigues, Jean-Pierre Roux
7  # CreaTools website : www.creatis.insa-lyon.fr/site/fr/creatools_accueil
8  #
9  #  This software is governed by the CeCILL-B license under French law and
10  #  abiding by the rules of distribution of free software. You can  use,
11  #  modify and/ or redistribute the software under the terms of the CeCILL-B
12  #  license as circulated by CEA, CNRS and INRIA at the following URL
13  #  http://www.cecill.info/licences/Licence_CeCILL-B_V1-en.html
14  #  or in the file LICENSE.txt.
15  #
16  #  As a counterpart to the access to the source code and  rights to copy,
17  #  modify and redistribute granted by the license, users are provided only
18  #  with a limited warranty  and the software's author,  the holder of the
19  #  economic rights,  and the successive licensors  have only  limited
20  #  liability.
21  #
22  #  The fact that you are presently reading this means that you have had
23  #  knowledge of the CeCILL-B license and that you accept its terms.
24  # ------------------------------------------------------------------------ */
25
26
27 Reflexions sur l'archi de bbtk et des packages
28 ----------------------------------------------
29
30 *STRUCTURE DU SOURCE TREE :
31 ---------------------------
32
33 La lib bbtk devrait être dans un rep à part entiere et chaque package 
34 de la distrib standard à part avec la même structure qu'un package utilisateur
35
36 donc dans le rep racine des sources :
37
38 data/ reste data/
39
40 creation rep "kernel" qui correspond au toolkit bbtk (lib+appli)
41
42 kernel/src/ accueille src/kernel/
43 kernel/doc/ accueille doc/
44 kernel/installer/ accueille install/
45 kernel/cmake/ accueille cmake/
46 kernel/appli/ accueille appli/
47
48 creation rep packages/ qui accueille chaque package de la distrib standard
49
50 donc on aura :
51 packages/std/
52 packages/wx/
53 etc.
54
55 la structure de chaque package sera identique et identique à celle créée par bbCreatePackage pour les utilisateurs :
56
57 A la racine des sources d'un package, je propose :
58 src/ : sources (ce qui est actuellement en vrac dans /src/packages/std/ par ex.)
59 doc/ : docs 
60 doc/bbdoc : rep pour creation de la doc du package par bbdoc (bbi à terme ? cf. ci-dessous) incluant les images si besoin
61 doc/doxygen : doc doxygen
62 bbs/ : scripts associés au package
63 bbs/boxes
64 bbs/appli
65 cmake/ : fichiers cmake pour build/install
66
67 * PROPOSITION : TOUT EST BLACK BOX ET PACKAGE !
68 -----------------------------------------------
69
70 A l'heure actuelle, du point de vue de l'utilisateur ou du createur 
71 de package, il y a :
72 - les packages (libraries dynamiques) :
73   - utilisés avec 'load' dans bbi
74   - documentés :
75     - en texte par 'help' dans bbi
76     - en html par l'appli bbdoc (créée automatiquement lors du build)
77       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)
78 - les scripts (.bbs) :
79   - utilisés avec 'include' dans bbi
80   - documentés dans bbi par 'graph' qui documente le package 'user'
81   Les scripts sont de deux types :
82     - scripts de définition de complex boxes (define/endefine)
83     - scripts d'appli (appli finale, de test, de demo, ...)
84
85 Quand un utilisateur crée un nouveau package, 
86 ce package comprend à la fois une librarie dynamique 
87 (mais pas forcément, lire la suite ...) et des scripts (idem).
88 Evidemment, il a envie :
89 - que tout soit utilisable (donc que les chemins pour trouver sa lib et ses scripts soient connus de bbi).
90 - 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).
91
92 Je propose que :
93 - les complex boxes définies par des scripts fassent partie à part entière du package (et de sa doc). 
94 Le mécanisme :
95  1) dans bbi, quand on définit une boite par 'define', on peut spécifier le package dans lequel elle va être placée, 
96  ex. : "define XOR std" dit que la boite XOR va dans le package std.
97  Si ce package existe (déja loadé ou précédent 'define TOTO std') : ok l'insère. Sinon crée un nouveau package. 
98  => Déja mis en place et testé : cf scripts/test/testDefine.bbs
99  Autre manière de faire : nouveaux mots-clés de bbi 'package/endpackage'.
100  ex. : 
101 > package mypack
102 >  description "mon magnifique package"
103 >  author "foo@bar.com"
104 >  define mybox
105 >  ...
106 >  endefine 
107 >  define mybox2 
108 >  ...
109 >  endefine 
110 > endpackage
111  toutes les boites définies entre 'package/endpackage' vont dans le package 
112  (de la même manière que toutes les instances créés par 'new' entre 
113   'define/endefine' vont dans la complex box courante).
114   Ici, mybox et mybox2 seront dans mypack.
115   Intérêt du bloc 'package/endpackage' : pouvoir documenter le package 
116   grace aux commandes standard 'description/author' ...
117   (REM : finalement, le package 'user' et la boite 'workspace' 
118    peuvent se voir comme si au lancement, bbi exécutait les commandes 
119    "package user" puis "define workspace". Ca donne des idées pour avoir plusieurs workspaces...)
120
121 Revenons maintenant aux scripts de complex boxes d'un package.
122  2) Un package utilisateur (ou standard bbtk) 
123     sera fournit **AVEC SON SCRIPT DE CHARGEMENT**.
124     Par ex: std.bbs sera le script de chargement du package std. 
125     Exemple de contenu :
126     # Load the 'atomic' boxes compiled in dyn lib :
127     load std   
128     # Include the complex boxes scripts (which can load other packages...)
129     include bbXOR
130     ...
131
132     Donc un utilisateur final mettra 'include std' dans ses scripts pour 
133     utiliser le package std (simple & complex boxes).
134  
135  INTERETS : 
136  A) Un utilisateur "lambda" utilisera toujours 'include' et ne verra 
137  que des boxes (simple ou complex). Un utilisateur "averti" pourra toujours 
138  ne loader que la lib ou n'inclure que certains scripts.
139  B) La doc sera générée automatiquement via bbi.
140  Il faut bêtement étendre la commande 'graph' pour que l'on puisse lui 
141  spécifier le nom du package dont on veut générer la doc
142  (A l'heure actuelle graph cherche à documenter une boite du package 'user' 
143  ou une instance de 'workspace' et génère systématiquement la doc du 
144  package 'user' pour les références.    
145  En passant, voir aussi la réflexion ci-dessous 
146  sur les rôles ambigus des commandes help et graph).
147  (La génération auto de la doc pourra se faire 
148  de manière quasiment identique à ce qui est fait à l'heure actuelle 
149  dans la macro BBTK_DOCUMENT_SCRIPTS de cmake/bbtkMacro.cmake : 
150  cela revient à lancer bbi sur un script du type :
151  "include packagename" 
152  "graph packagename good-parameters")
153  Donc plus d'appli bbdoc : tout est fait par bbi !
154
155  3) Doc des appli (.bbs) :
156  Idem que ci-dessus avec un script du type :
157  >package std-demo
158  > description "..."
159  > define DemoXOR
160  >  include DemoXOR
161  > endefine
162  > define DemoAdd
163  >  include DemoAdd
164  > endefine
165  > ...
166  >endpackage
167  >graph std-demo [good-params]
168  bbtk doit fournir aux utilisateurs une macro cmake pour générer ce type de 
169  script, les targets qui vont bien et l'installation de la doc au même endroit 
170  que toutes les autres doc, i.e. dans /packages/<package-name>/bbdoc.
171  Ainsi toutes les refs croisées sont bonnes, on n'a que des packages 
172  documentés qui contiennent des boites (éventuellement d'applications)... 
173
174  Qu'en pensez-vous ?
175
176 Finalement on aura la structure de package :
177  PACK/src
178          scripts/PACK.bbs
179          scripts/boxes
180          scripts/appli
181          doc/boxes
182          doc/appli
183
184
185 * BUILD TREE ET INSTALLATION 
186 ----------------------------
187 Regle : 
188 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) 
189 à la fois dans le build tree et dans l'install tree.
190 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.
191 En effet, FindBBTK.cmake ou Find[PackageName].cmake :
192 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...)
193 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.
194
195 OK ?
196
197
198
199 Structure des build/install trees :
200
201 *Linux :
202 PREFIX = build_tree_path, /usr, /usr/local
203 PREFIX_SHARE = PREFIX/share/bbtk
204 *Windows
205 PREFIX = PREFIX_SHARE = build_tree_path, C:/ProgramFiles/bbtk
206
207 PREFIX/bin : bbi, etc.
208 PREFIX/lib : libbbtk.so, libbstd.so, etc.
209 PREFIX/lib/bbtk : UseBBTK.cmake, etc.
210 PREFIX/lib/bbstd : UseBBSTD.cmake, etc.
211 PREFIX/include/bbtk : bbtkSystem.h, etc. 
212 PREFIX/include/bbstd : bbstdAdd.h, etc. 
213
214 PREFIX_SHARE/
215 PREFIX_SHARE/doc/bbtkWebSite
216                  bbtkDoxygen
217                  bbtkUsersGuide
218                  etc.
219 PREFIX_SHARE/doc/bbdoc/std : index.html, *.png, etc.
220                        std-demo
221                        wx
222                        wx-demo
223                        USER_PACKAGE
224                        USER_PACKAGE-demo
225                        etc.
226
227 PREFIX_SHARE/doc/doxygen/std : index.html, *.png, etc.
228                          wx
229                          USER_PACKAGE
230                          etc.
231 PREFIX_SHARE/bbs/std/
232                  std-demo
233                  wx
234                  etc.
235                      
236