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