doc/design-doc/codegen-3.2.dirgen.txt

   1 doc of shlib
   2
   3   Copyright (C) 2022- Free Software Foundation, Inc.
   4
   5   Copying and distribution of this file, with or without modification,
   6   are permitted in any medium without royalty provided the copyright
   7   notice and this notice are preserved.
   8
   9 The following contributions warranted legal paper exchanges with the
  10 Free Software Foundation.
  11
  12
  13
  14 # guide-catalog
  15 ================
  16
  17
  18 # introduction
  19 ==============
  20     catadir is a directory relatived with a catalog.
  21
  22
  23 # example
  24 =========
  25
  26 # concept
  27 =========
  28
  29 # global variables
  30 ==================
  31
  32 variables for a node.
  33 @ for a catanode string
  34 # NCATAID, number in current catalog or directory. with a random hex sfx, it's
  35   used to alias with a node in other catalog.
  36 # NTYPE, dir, relative item, or content type. it means the node created in
  37   dest-output.
  38 # NNAME, name for file and variable.
  39 # NDESC, the content or description info for a node.
  40
  41 strfmt ()
  42 {
  43         :
  44 }
  45
  46 var2str ()
  47 {
  48         strfmt
  49 }
  50
  51 str2var ()
  52 {
  53         :
  54 }
  55
  56 str2node ()
  57 {
  58         :
  59 }
  60
  61 node2str ()
  62 {
  63         :
  64 }
  65
  66
  67
  68
  69
  70
  71
  72
  73
  74
  75
  76
  77
  78
  79
  80
  81
  82
  83
  84
  85
  86
  87
  88
  89
  90
  91
  92
  93
  94 @ catalogÎÄ¼þµÄ²îÒìÊä³ö¡£
  95 # ¸ù¾ÝnodeµÄÃû³Æ£¬id-position£¬desc£¬ntype½øÐÐË³ÐòµÄcomp(²»°üº¬contµÄnode)£¬²¢ÉèÖÃ{new}/{del}{modify}µÄtag¡£Í¬Ê±½«¶ÔÓ¦µÄÐÞ¸ÄµÄnode±£´æµ½new/del/modify.tmpÎÄ¼þ¡£
  96 # ÔÚnew catalogÎÄ¼þÖ®ÖÐ£¬Æ¥ÅäorgÎÄ¼þÖ®ÖÐµÄnew/del/modifyµÄnode£¬ÊÇ·ñÓÐÏàÍ¬/Ïà½üµÄnode£¬ÒÔfullcataidµÄ{=>}±íÊ¾£¬²¢Ìí¼Ó{mov}µÄtag¡£
  97 # ¶ÔÓÚmodifyµÄnode£¬±È¶ÔNCATAID£¬NTYPE£¬NNAME£¬NDESC£¬Êä³ö{=>}ÐÞ¸ÄÐÅÏ¢
  98 # ±È¶Ôimi¶¨Òå£¬Êä³ö{=>}ÐÞ¸ÄÐÅÏ¢
  99
 100 @ catalog to output files.
 101 # ¶ÔÓÚnodeµÄnew/del/modify/mov½øÐÐÎÄ¼þ²Ù×÷
 102 # node-info
 103 + strfmt catalog::catanode::STR_FMT =>
 104 + NCATAID
 105 + NTYPE
 106 + NNAME
 107 + NDESC
 108 + NCATAID=>NFULLCATAID
 109 + NTYPE=>NODE_TYPE(dir/item/cont)
 110 + NTYPE=>SRC_TYPE if NODE_TYPE=(.+)dir
 111 # on dir enter/exit
 112 + ITEM_TYPE=dirnode, others
 113 # on node proc
 114 + NTYPE=>ITEM_TYPE if NODE_TYPE=item
 115 # ITEM_TYPE=>NFEXT
 116 + NFEXT=>DIR_TYPE=>DIR_TYPE_LIST£¬
 117 + NFEXT=>FILE_EXT_LIST
 118 # for one output dir£¬
 119 + DIR_TYPE+SRC_TYPE=>SRC_DIR_TYPE
 120 + OUTPUT_SUBDIR_FMT[$DIR_TYPE]=>
 121     OUTPUT_SUBDIR(dir under SRCPKG_DIR)
 122 + OUTPUT_${SRC_TYPE^^}_SUBDIR_FMT[$DIR_TYPE]=>
 123     OUTPUT_${SRC_TYPE^^}_SUBDIR(dir under OUTPUT_SUBDIR)
 124 + NODE_DIR_FMT[$DIR_TYPE]=>
 125     NODE_DIR(dir name if NODE_TYPE=dir£¬append to CATALOG_DIRS)
 126 + NODE_ITEMDIR_FMT[$DIR_TYPE]=>
 127     NODE_ITEMDIR(ITEM dir if needed/defined)
 128 + NODE_${SRC_TYPE^^}_ITEMDIR_FMT[$DIR_TYPE]=>
 129     NODE_ITEMDIR(if NODE_ITEMDIR is not exist)
 130 + NODE_DIR=>CATALOG_DIRS(if NODE_TYPE=dir)
 131 + OUTPUT_SUBDIR+
 132     OUTPUT_${SRC_TYPE^^}_SUBDIR+
 133     CATALOG_DIRS+
 134     OUTPUT_DIR_FMT[$DIR_TYPE]=>
 135     OUTPUT_DIR()
 136 # for one file in one output dir of a node¡£
 137 + FILE_EXT_LIST=>FEXT
 138 + FNAME_FMT[$FEXT]+
 139     NODE_ITEMDIR=>FNAME£¬
 140 + FNAME_REGEX[$FEXT]£¬
 141 + NXXX_REGEX[$FEXT]£¬
 142 + FNAME=>FNAME_LIST(used for existing chk & gen)
 143 # ²ÎÊýbackup£¬Ê¹ÓÃ{=>}ÐÞ¸ÄÖ®ºóµÄÔÙÊä³ö²ÎÊý£¬½øÐÐorg=>newµÄÊä³öchk£¬²¢mv
 144 # Èç¹ûÎ´°üº¬ÐÞ¸Äflag£¬Ê¹ÓÃorgµÄ²ÎÊýchk£¬²¢Êä³öÎÄ¼þ¡£
 145
 146 @ existing chk
 147 #
 148
 149 @ contÊä³ö
 150 # ±éÀúnode£¬¶ÔÓÚ°üº¬contµÄitem node£¬½âÎöºóµÄÐÅÏ¢(°üº¬uniq-idÒ»¼ÒÎÄ¼þÂ·¾¶)±£´æµ½Éè¼ÆÎÄ¼þ¡£
 151 #
 152 # °üº¬contµÄitem node£¬ÕâÐ©nodeÐèÒªÊä³öcode¶ÔÓÚ¡£ÏÈ½øÐÐchk£¬Êä³öÐèÒª½øÐÐnew/del/modify/mov²Ù×÷µÄ²Ù×÷ÐÅÏ¢ºÍÎÄ¼þÁÐ±í¡£
 153
 154
 155
 156
 157
 158
 159
 160
 161
 162
 163
 164
 165 @ for a catanode info extension variable:
 166 # NFULLCATAID, it's the full cataid in catalog.
 167 # NNODETYPE, dir, or srcdir, or item.
 168 # NSRCTYPE, if NNODETYPE == srcdir, it is bin/shlib/lib/src/sample.
 169 # NITEMTYPE, if NNODETYPE == item, it is equal to NTYPE.
 170
 171
 172 @ for an itemnode:
 173 # NDIRTYPE_ARRAY[], defined in one kind of item in NFEXT. if no '@' pfx, add a
 174   blank before name string.
 175 # NFTYPE_ARRAY[], file types in one kind of NDIRTYPE_ARRAY.
 176 # NDIRTYPE, one of NDIRTYPE_ARRAY. it is "@{NSRCTYPE}-@{NDIRTYPE_ARRAY[$i]:1}".
 177 # NFTYPE, one of NFTYPE_ARRAY.
 178 # NITEMDIR, if NDIRTYPE_ARRAY[$i] defined with '@' pfx, it's the name of node,
 179   it means all generated file put in this dir. it only generated from item
 180   node.
 181 # NDIR_STR, if it is a dir node, it's the name of dir, generated from STR_FMT
 182   defined in $NDIRTYPE.
 183 # NCATA_STR[], every NDIR_STR put into this array. used as "str=${NCATA_STR[@]}; str=${str//\ /\/}", it translated to a dir string.
 184 # NCATA_STR_IDX, current idx id for NCATA_STR.
 185 # NFTYPE, one of the file type defined under NSRCTYPE dir.
 186 # STR_FMT, get from NFTYPE, and use it to generate file name for corresponding
 187   NFTYPE.
 188 # NFNAME, file name string generated from STR_FMT.
 189 #
 190 #
 191
 192 @ file name string recognize in an item:
 193 # NNAME, get from sub-node-list.
 194 # NFNAME, list files named with '$NNAME' content.
 195 # SEPCHAR, '.'.
 196 # NVALUE[]
 197 # NFEXT, file ext-name.
 198 # NFTYPE, get file type from file ext-name in NFEXT.
 199 # NVNAME[], get variables defined in NFTYPE.
 200 # NVNAME[$i], corresponding variable with value in NVALUE[$i].
 201 #
 202
 203 # NSRCTYPE
 204 # NNODETYPE
 205 # NITEMTYPE
 206 # NDIRTYPE[_LIST]
 207 # NFTYPE[_LIST]
 208 # STR_FMT
 209 # STR_REGEX
 210 #
 211 # NSRCTYPE
 212 # NDIRTYPE
 213 # NFEXT
 214 #
 215 #
 216
 217
 218 # SRC_DIR_TYPE
 219 # DIR_NODE_TYPE
 220 # ITEM_NODE_TYPE
 221 # FILE_TYPE
 222
 223
 224
 225 @ NTYPE_SFX, if a node is dir or item, it need a sfx for dir/item node name
 226   string.
 227 @ ITEM_KINDS, all item kins used in current catalog.
 228 @ NDIR_ARRAY, relative dir name array in src-pkg. it's the output dest dir.
 229   it's generated from ITEM_KINDS.
 230 @ NITEM_LIST,
 231 @ NFEXT_DISABLE_LIST, ignore files with specified ext-name in global.
 232 @ NTYPE_LIST[<dir-type>], in the corresponding dir, it stores sfx name for
 233   dirnode. NTYPE_LIST for
 234   global. normally, it's a global setting, because there are few dirnode types,
 235   and at most time, a dirnode do not use sfx.
 236 @ NFEXT_FIRST[<dir-type>], file ext-name list for current dir in current
 237   itemnode/dirnode. ITEM_KINDS
 238   defines various kinds of itemnode that maybe used in current catalog doc.
 239   if a node is include in a dir, ext-name is the sfx of dir.
 240
 241
 242 ITEM_KINDS='citem/cunititem/cunit/cmodule/cmdlitem'
 243 DIR_KINDS='dir/module/unit'
 244
 245
 246
 247
 248
 249
 250
 251
 252
 253
 254
 255
 256
 257 # directory ergodic
 258 ===================
 259     a directory maybe a dirnode, or an itemnode with directory.
 260         when scan directory to generate catalog info, there are two method to scan
 261 in current dir:
 262
 263 @ pure directory scan. it's used to generating catalog.
 264 @ analyze catalog file, then scan directory by node info defined in catalog.
 265
 266     for a directory, this is the scan procedure.
 267
 268 # scan current directory
 269 ========================
 270
 271 CG_OUTPUT_DIR
 272
 273 ```
 274 $ cd ~
 275 $ mkdir TestDir
 276 $ cd TestDir/
 277 $ touch '1.TestDir.This dir is for testing.desc'
 278 $ touch SubItem.c SubItem.h SubItem_test.c '1.SubItem.Test SubItem.desc'
 279 $ mkdir SubDir1
 280 $ cd SubDir1
 281 $ touch '2.TestDir1.This sub dir is for testing.desc'
 282 $ touch Dir1SubItem.c Dir1SubItem.h Dir1SubItem_test.c '1.Dir1SubItem.Test Dir1SubItem.desc'
 283 $ cd
 284 $ find TestDir
 285 TestDir
 286 TestDir/SubItem.c
 287 TestDir/SubDir1
 288 TestDir/SubDir1/Dir1SubItem.c
 289 TestDir/SubDir1/1.Dir1SubItem.Test Dir1SubItem.desc
 290 TestDir/SubDir1/2.TestDir1.This sub dir is for testing.desc
 291 TestDir/SubDir1/Dir1SubItem_test.c
 292 TestDir/SubDir1/Dir1SubItem.h
 293 TestDir/1.TestDir.This dir is for testing.desc
 294 TestDir/SubItem.h
 295 TestDir/SubItem_test.c
 296 TestDir/1.SubItem.Test SubItem.desc
 297 $
 298 ```
 299 nodels ()
 300 {
 301     local list=( $NFEXT_FIRST $NTYPE_LIST )
 302     local ext=
 303     local grep_opt=
 304
 305     for ext in $NFEXT_FIRST $NTYPE_LIST; do
 306         grep_opt+="-e '$ext' "
 307     done
 308
 309     for ext in ${NFEXT_DISABLE_LIST}; do
 310         grep_opt+="-v '$ext' "
 311     done
 312
 313     while read file; do
 314         [[ -d $file ]] && echo $file
 315         eval grep $grep_opt <<< "$file"
 316     done < <(ls -f -1 -d -v * | uniq)
 317 }
 318
 319 ## 1. get current dirnode info var
 320 ==================================
 321
 322 * 1. 'ls -f -1 -d -v *${NNAME}* | grep -e "[.]${NNAME}$" -e "^${NNAME}[.]" -e "[.]${NNAME}[.]"'
 323           this command list $NNAME relative files, and it is a full word matching.
 324 ```
 325 $ cd ~
 326 $ touch 1.design 1.design.txt abcdesign.txt abcdesigntxt.txt designtxt.txt
 327 $ NNAME=design
 328 $ ls -f -1 -d -v *${NNAME}*
 329 1.design
 330 1.design.txt
 331 abcdesign.txt
 332 abcdesigntxt.txt
 333 designtxt.txt
 334 $ ls -f -1 -d -v *${NNAME}* | grep -e "[.]${NNAME}$" -e "^${NNAME}[.]" -e "[.]${NNAME}[.]"
 335 1.design
 336 1.design.txt
 337 1.design.test for design.desc
 338 ```
 339           this example shows the NNAME="design", it GET file names which is using
 340         $NNAME as a field between seperator char of '.'.
 341 ```
 342 $ cd ~/TestDir
 343 $ NNAME=TestDir
 344 $ ls -f -1 -d -v *${NNAME}* | grep -e "[.]${NNAME}$" -e "^${NNAME}[.]" -e "[.]${NNAME}[.]"
 345 1.TestDir.This dir is for testing.desc
 346 ```
 347
 348 ## 2. get sub node list
 349 =======================
 350
 351         * 2. 'ls -f -1 -d -v ${NFEXT_FIRST} ${NTYPE_LIST} | grep -v "${NFEXT_DISABLE_LIST}"'
 352         'ls -f -1 -d -v ${NFEXT_FIRST}'
 353           list sub dirnode/itemnode
 354         NFEXT_FIRST is the main/first file ext-name defined in a item in current
 355         scanning-dir. if an item node included in a dir,
 356         NTYPE_LIST is the sfx name for a dir. it's generated from DIR_KINDS.
 357 ```
 358 $ cd ~/TestDir
 359 $ NFEXT_FIRST="*.c"
 360 $ NTYPE_LIST=""
 361 $ ls -f -1 -d -v ${NFEXT_FIRST} | uniq
 362 1.SubItem.Test SubItem.desc
 363 1.TestDir.This dir is for testing.desc
 364 SubItem.c
 365 SubItem.h
 366 SubItem_test.c
 367 $
 368 ```
 369
 370 ## 3. get sub itemnode info var
 371 ===============================
 372
 373         * 3. ls for one items. NFEXT_FIRST is the file ext-name defined in itemnode,
 374 #    NTYPE_LIST is a list of dirnode ext-name.
 375 #   NFEXT_FIRST and NTYPE_LIST can be generated by node defination.
 376 #   NFEXT_DISABLE_LIST is used for disable list.
 377
 378
 379 # sync mode directory scan
 380 ==========================
 381
 382 CG_OUTPUT_DIR
 383
 384
 385 # fundamental info var directly defined in catanode string.
 386 CATANODE_NNAME
 387 CATANODE_NCATAID
 388 CATANODE_NTYPE
 389 CATANODE_NDESC
 390
 391 #
 392 # dirnode
 393 #       itemnode
 394 #               output-dirs
 395 #                       generated-files
 396 #
 397
 398 # other info var generated from fundamental info var & other relatives.
 399 CATANODE_NOUTDIR_LIST, 'one catanode' output dirs/files in 'those dirs' under a
 400   src-pkg.
 401 CATANODE_NOUTPUT_DIR, 'current' processing 'output dir' name.
 402 CATANODE_NDEXT_LIST, dir ext types defined in current catalog file.
 403 CATANODE_NDEXT, 'dir ext-name' for 'current catanode' if it is a 'dirnode'.
 404 CATANODE_NIDEXT_LIST, item dir ext types defined in current catalog file.
 405 CATANODE_NIDEXT, 'item dir ext-name' for 'current catanode' if it is a
 406   'dirnode'.
 407 CATANODE_NFEXT_LIST, all file type name in OUTPUT dir define.
 408 CATANODE_NFTYPE_FIRST, first file type name in OUTPUT dir define.
 409 CATANODE_NFEXT_FIRST, ext name for first file type in OUTPUT dir define. it's
 410   used for sub item list greb.
 411
 412
 413
 414 @ sync
 415         * 1. 'ls -f -1 -d -v *${NNAME}* | grep -e "[.]${NNAME}$" -e "^${NNAME}[.]" -e "[.]${NNAME}[.]"'
 416         * 2. 'ls -f -1 -d -v @{NFEXT_FIRST} @{NTYPE_LIST} | grep -v
 417         * 3. ''
 418 @
 419
 420
 421
 422
 423 # linenode
 424 ==========
 425
 426 #
 427 ================
 428
 429 #
 430 ================
 431
 432 #
 433 ================
 434
 435 #
 436 ================