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