Debian Codegraph @

tcl/cache.tcl.in

raw
1 ##########################################################################
2
3 # CACHE.TCL, cache management procedures
4 # Copyright (C) 2022-2026 Xavier Delaruelle
5 #
6 # This program is free software: you can redistribute it and/or modify
7 # it under the terms of the GNU General Public License as published by
8 # the Free Software Foundation, either version 2 of the License, or
9 # (at your option) any later version.
10 #
11 # This program is distributed in the hope that it will be useful,
12 # but WITHOUT ANY WARRANTY; without even the implied warranty of
13 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14 # GNU General Public License for more details.
15 #
16 # You should have received a copy of the GNU General Public License
17 # along with this program. If not, see <http://www.gnu.org/licenses/>.
18
19 ##########################################################################
20
21 # Get full path name of module cache file for given modulepath
22 proc getModuleCacheFilename {modpath} {
23 return $modpath/.modulecache
24 }
25
26 # test if a given file path has a limited access by check permission mode set
27 # for others
28 proc isFileAccessLimited {fpath isdir} {
29 # check if file stat info can be fetched
30 if {[file readable $fpath]} {
31 # extract permissions for "other"
32 set other_perms [string index [file attributes $fpath -permissions] end]
33 # test file can be read by other: o+r right, which means file should at
34 # least have 0b100 mode, which can be binary-compared against 0b011 (3)
35 # if file is a directory, test it can also be searched: o+x right, which
36 # means dir should at least have 0b101 mode, which can be compared
37 # against 0b010 (2)
38 set perms_mask [expr {$isdir ? {2} : {3}}]
39 return [expr {($other_perms | $perms_mask) != 7}]
40 } else {
41 return 1
42 }
43 }
44
45 # walk through directory content and return every files and dirs with limited
46 # access rights
47 proc getLimitedAccessesInDirectory {modpath} {
48 # cannot test limited accesses on Windows platform
49 if {[getState is_win]} {
50 return {}
51 }
52
53 # walk through directory to find elements with limited access
54 array set limited_arr {}
55 lappend full_list $modpath
56 for {set i 0} {$i < [llength $full_list]} {incr i 1} {
57 set elt [lindex $full_list $i]
58 set eltname [getModuleNameFromModulepath $elt $modpath]
59 if {[file isdirectory $elt]} {
60 # skip ignored dirs
61 if {![isPathIgnored $modpath $elt 1]} {
62 if {[isFileAccessLimited $elt 1]} {
63 set limited_arr($eltname) d
64 # only walk through directory content if its access is not limited
65 } else {
66 # get all elements found in directory (regular and dot files)
67 set direlt_list [glob -nocomplain -directory $elt *]
68 foreach eltindir [glob -nocomplain -types hidden -directory\
69 $elt -tails *] {
70 if {$eltindir ni {. ..}} {
71 lappend direlt_list $elt/$eltindir
72 }
73 }
74 if {[llength $direlt_list]} {
75 lappend full_list {*}$direlt_list
76 }
77 }
78 }
79 } else {
80 # skip ignored files (rc files are exempt from ignore pattern
81 # check: without their limited access record, the content of a
82 # pattern-matching rc file with restricted access would get
83 # plainly recorded in cache file)
84 if {![isPathIgnored $modpath $elt 0] && [isFileAccessLimited $elt\
85 0]} {
86 set limited_arr($eltname) f
87 }
88 }
89 }
90
91 # filter .version/.modulecache files found at the root of modulepath dir
92 foreach elt [list .version .modulecache] {
93 if {[info exists limited_arr($elt)]} {
94 unset limited_arr($elt)
95 }
96 }
97
98 reportDebug "found [array names limited_arr] ([array size limited_arr])\
99 with limited access"
100 return [array get limited_arr]
101 }
102
103 # Build cache file content for given modulepath
104 proc formatModuleCacheContent {modpath} {
105 set content {}
106 # rc files are evaluated during modulepath walk to apply the path ignore
107 # patterns they may define: silence their evaluation errors like during
108 # an avail-like walk (their bare content is recorded whether their code
109 # is correct or not)
110 inhibitErrorReport
111
112 # collect files from modulepath directory
113 array set found_list [findModules $modpath * 0 1]
114
115 # collect files and dirs from modulepath directory with limited access
116 array set limited_list [getLimitedAccessesInDirectory $modpath]
117
118 uninhibitErrorReport
119
120 # concatenate element found and those with limited access as the second
121 # kind may not be part of found list
122 set elt_list [lsort -unique [concat [array names found_list] [array names\
123 limited_list]]]
124
125 # build cache entry for every file found
126 foreach elt $elt_list {
127 # ignore element if it has been flagged in skip list (one of its parent
128 # directory has limited access) or if modulepath has itself a limited
129 # access
130 if {[info exists skip_list($elt)] || $elt eq {}} {
131 continue
132 }
133
134 set entry_list [list]
135 set fetch_content 0
136
137 # mention in cache that file or directory has limited access to test if
138 # they can be accessed by user when cache is evaluated
139 if {[info exists limited_list($elt)]} {
140 if {$limited_list($elt) eq {d}} {
141 # mark all elements contained in dir to skip them as their parent
142 # directory has limited access (due to lsort on foreach loop we
143 # are assured to treat parent dir before the entries it contains)
144 foreach elttoskip [array names found_list -glob $elt/*] {
145 set skip_list($elttoskip) 1
146 }
147 lappend entry_list limited-access-directory $elt
148 } else {
149 lappend entry_list limited-access-file $elt
150 }
151 } else {
152 switch -- [lindex $found_list($elt) 0] {
153 modulerc {
154 lappend entry_list modulerc-content $elt
155 set fetch_content 1
156 }
157 modulefile {
158 lappend entry_list modulefile-content $elt [lindex\
159 $found_list($elt) 1]
160 set fetch_content 1
161 }
162 default {
163 # also record obtained error to get all the information to
164 # cover everything fetched by findModules. only modulefile
165 # validity is checked in findModules
166 lappend entry_list modulefile-invalid $elt {*}[lrange\
167 $found_list($elt) 0 1]
168 }
169 }
170 }
171 # fetch file content
172 if {$fetch_content} {
173 if {[catch {
174 set fcontent [readFile $modpath/$elt]
175 # extract module header from the start of the file
176 if {![regexp {^#%Module[0-9\.]*} [string range $fcontent 0 32]\
177 fheader]} {
178 set fheader {}
179 }
180 lappend entry_list $fheader $fcontent
181 } errMsg]} {
182 # rethrow read error after parsing message
183 knerror [parseAccessIssue $modpath/$elt]
184 }
185 }
186 # format cache entry
187 append content "\n$entry_list"
188 }
189
190 # prepend header if some content has been generated
191 if {[string length $content]} {
192 set cache_header "#%Module[getState cache_mcookie_version]"
193 set content $cache_header$content
194 }
195
196 return $content
197 }
198
199 # read a cache file
200 proc readCacheContent {cachefile} {
201 set res {}
202 if {[catch {
203 # read full file
204 set fid [open $cachefile r]
205 # use defined buffer size to limit number of read system call
206 fconfigure $fid -buffersize [getConf cache_buffer_bytes]
207 set fdata [read $fid]
208 close $fid
209 # extract magic cookie (first word of cache file)
210 set fh [string trimright [lindex [split [string range $fdata 0 32]]\
211 0] #]
212 set fhvers [string range $fh 8 end]
213 } errMsg ]} {
214 reportError [parseAccessIssue $cachefile]
215 } else {
216 # check cache validity
217 if {![string equal -length 8 $fh {#%Module}]} {
218 reportInternalBug {Magic cookie '#%Module' missing} $cachefile\
219 {Cache ERROR}
220 # check if version requirement is present
221 } elseif {[string length $fh] <= 8} {
222 reportInternalBug {Modules version requirement missing} $cachefile\
223 {Cache ERROR}
224 # check if min version requirement is met
225 } elseif {[versioncmp [getState modules_release] $fhvers] <0} {
226 reportDebug "Cache file $cachefile requires at least Modules version\
227 $fhvers"
228 } else {
229 # set file content as result
230 set res $fdata
231 }
232 }
233 return $res
234 }
235
236 # evaluate cache file
237 proc execute-cachefile {cachefile modpath} {
238 # register current modulepath for cachefile commands to know where they are
239 lappendState modulepath $modpath
240 lappendState debug_msg_prefix "\[cache:$cachefile\] "
241
242 # initialize cache gathering structures for modulepath
243 set ::g_cacheModpath($modpath) {}
244 set ::g_cacheFLimitedModpath($modpath) {}
245 set ::g_cacheDLimitedModpath($modpath) {}
246
247 # initialize cache file evaluation interp configuration
248 if {![info exists ::g_cachefileUntrackVars]} {
249 # list variable that should not be tracked for saving
250 array set ::g_cachefileUntrackVars [list ModulesCurrentCachefile 1\
251 cachecontent 1 env 1]
252
253 # commands that should be renamed before aliases setup
254 array set ::g_cachefileRenameCmds [list]
255
256 # list interpreter alias commands to define
257 array set ::g_cachefileAliases [list modulefile-content\
258 modulefile-content modulerc-content modulerc-content\
259 modulefile-invalid modulefile-invalid limited-access-file\
260 limited-access-file limited-access-directory\
261 limited-access-directory reportInternalBug reportInternalBug\
262 readCacheContent readCacheContent formatErrStackTrace\
263 formatErrStackTrace]
264
265 # alias commands where an argument should be passed
266 array set ::g_cachefileAliasesPassArg [list]
267
268 # trace commands that should be associated to aliases
269 array set ::g_cachefileAliasesTraces [list]
270
271 }
272 set itrp __cachefile
273
274 reportTrace '$cachefile' {Evaluate cache file}
275 # create cachefile interpreter at first interpretation
276 if {![interp exists $itrp]} {
277 createInterp $itrp
278
279 # dump initial interpreter state to restore it before each cachefile
280 # interpretation.
281 dumpInterpState $itrp g_cachefileVars g_cachefileArrayVars\
282 g_cachefileUntrackVars g_cachefileProcs
283
284 # interp has just been created
285 set fresh 1
286 } else {
287 set fresh 0
288 }
289
290 # reset interp state command before each interpretation
291 resetInterpState $itrp $fresh g_cachefileVars g_cachefileArrayVars\
292 g_cachefileUntrackVars g_cachefileProcs g_cachefileAliases\
293 g_cachefileAliasesPassArg g_cachefileAliasesTraces\
294 g_cachefileRenameCmds g_cachefileCommands
295
296 # reset modulefile-specific variable before each interpretation
297 interp eval $itrp set ::ModulesCurrentCachefile "{$cachefile}"
298
299 # evaluate cache file
300 ##nagelfar ignore +4 Suspicious # char
301 set exec_res [interp eval $itrp {
302 set cachecontent [readCacheContent $::ModulesCurrentCachefile]
303 if {$cachecontent eq {}} {
304 # simply skip cache file, no exit on error here
305 return 0
306 }
307
308 info script $::ModulesCurrentCachefile
309 if {[catch {eval $cachecontent} errorMsg]} {
310 # format stack trace to report cachefile information only
311 reportInternalBug [formatErrStackTrace $::errorInfo\
312 $::ModulesCurrentCachefile [list {*}[info procs] {*}[info\
313 commands]]] {} {Cache ERROR}
314 return 0
315 } else {
316 return 1
317 }
318 }]
319
320 reportDebug "exiting $cachefile (result=$exec_res)"
321
322 lpopState debug_msg_prefix
323 lpopState modulepath
324
325 return $exec_res
326 }
327
328 # cache file command to record modulefile content
329 proc modulefile-content {mod mtime header content} {
330 set modfile [currentState modulepath]/$mod
331
332 # record modulefile information in memory structures
333 set ::g_modfileContent($modfile) [list $header $content]
334 set ::g_fileMtime($modfile) $mtime
335 set ::g_modfileValid($modfile) [list true {}]
336
337 # gather all modulefiles/modulercs of a modulepath in a global variable
338 # with same information structure than findModules result
339 lappend ::g_cacheModpath([currentState modulepath]) $mod [list modulefile\
340 $mtime $modfile]
341 }
342
343 # cache file command to record modulerc content
344 proc modulerc-content {modrc header content} {
345 set modrcfile [currentState modulepath]/$modrc
346
347 # record modulerc information in memory structures
348 set ::g_modfileContent($modrcfile) [list $header $content]
349
350 # gather all modulefiles/modulercs of a modulepath in a global variable
351 # with same information structure than findModules result
352 lappend ::g_cacheModpath([currentState modulepath]) $modrc [list modulerc]
353 }
354
355 # cache file command to record an invalid modulefile
356 proc modulefile-invalid {mod type msg} {
357 set modfile [currentState modulepath]/$mod
358
359 # record modulefile information in memory structures
360 set ::g_modfileValid($modfile) [list $type $msg]
361
362 # also gather all invalid modulefiles of a modulepath in a global variable
363 # with same information structure than findModules result
364 lappend ::g_cacheModpath([currentState modulepath]) $mod [list $type $msg\
365 $modfile]
366 }
367
368 # gather modulepath limited access files in specific structure
369 proc limited-access-file {mod} {
370 lappend ::g_cacheFLimitedModpath([currentState modulepath]) $mod 1
371 }
372
373 # gather modulepath limited access files in specific structure
374 proc limited-access-directory {dir} {
375 lappend ::g_cacheDLimitedModpath([currentState modulepath]) $dir 1
376 }
377
378 # finds all module-related files matching mod in the modulepath dir by looking
379 # into the cache file
380 proc findModulesInCacheFile {modpath mod depthlvl fetch_mtime} {
381 set cachefile [getModuleCacheFilename $modpath]
382
383 # check if cache should be ignored, either globally or for currently
384 # running top-level sub-command
385 if {[getConf ignore_cache] || [topCommandName] in [getConfList\
386 ignore_cache_subcmds]} {
387 return [list 0 {}]
388 }
389
390 # check if a cache file is available (exist, readable and not expired)
391 if {![info exists ::g_cachefilesAvail($cachefile)]} {
392 if {[file readable $cachefile]} {
393 reportDebug "cache file '$cachefile' exists and is readable"
394 # check expiry if enabled
395 if {[set expiry_secs [getConf cache_expiry_secs]] != 0} {
396 set cachemtime [getFileMtime $cachefile]
397 # cache is also considered expired if its mtime cannot be fetched
398 set ::g_cachefilesAvail($cachefile) [expr {$cachemtime ne {} &&\
399 $expiry_secs > ([getState clock_seconds] - $cachemtime)}]
400 if {!$::g_cachefilesAvail($cachefile)} {
401 reportDebug "cache file '$cachefile' has expired"
402 }
403 } else {
404 set ::g_cachefilesAvail($cachefile) 1
405 }
406 } else {
407 reportDebug "cache file '$cachefile' cannot be found or read"
408 set ::g_cachefilesAvail($cachefile) 0
409 }
410 }
411
412 # return if no cache file available
413 if {!$::g_cachefilesAvail($cachefile)} {
414 return [list 0 {}]
415 }
416
417 # evaluate cache file if not yet done
418 if {![info exists ::g_cachefilesSourced($cachefile)]} {
419 set exec_res [execute-cachefile $cachefile $modpath]
420 # keep track of already sourced cache files not to run them again
421 set ::g_cachefilesSourced($cachefile) $exec_res
422 } else {
423 reportDebug "cache file '$cachefile' has already been evaluated"
424 }
425
426 # return if cache file has not been correctly sourced
427 if {!$::g_cachefilesSourced($cachefile)} {
428 return [list 0 {}]
429 }
430
431 # tailor cache file content to what is requested
432 array set cache_arr $::g_cacheModpath($modpath)
433 reportDebug "[array size cache_arr] elements are cached for '$modpath'"
434 array set flimited_arr $::g_cacheFLimitedModpath($modpath)
435 reportDebug "[array size flimited_arr] limited access files for '$modpath'"
436 array set dlimited_arr $::g_cacheDLimitedModpath($modpath)
437 reportDebug "[array size dlimited_arr] limited access dirs for '$modpath'"
438
439 # filter entries unless all are requested
440 set findall [expr {$mod in {{} *}}]
441 defineModEqStaticProc [isIcase] [getConf extended_default] $mod
442 if {!$findall || $depthlvl > 0} {
443 foreach elt [array names cache_arr] {
444 set eltroot [lindex [file split $elt] 0]
445 set eltdepthlvl [llength [file split $elt]]
446 set elttail [file tail $elt]
447 set eltparent [file dirname $elt]
448
449 # exclude if not matching mod pattern (which is always a root name)
450 if {$eltroot ne {.modulerc} && !$findall && ![modEqStatic $eltroot\
451 match]} {
452 unset cache_arr($elt)
453 # also exclude if not corresponding to search depth level (or if one
454 # modulefile has already been added for directories lying at other
455 # depth level)
456 } elseif {$depthlvl > 0 && $elttail ne {.modulerc} && $eltdepthlvl\
457 != $depthlvl && [info exists modfile_indir($eltparent)]} {
458 unset cache_arr($elt)
459 } else {
460 # track a valid non-hidden modulefile has been added in parent
461 # directory
462 if {[string index $elttail 0] ne {.} && ![info exists\
463 modfile_indir($eltparent)] && [lindex $cache_arr($elt) 0] eq\
464 {modulefile}} {
465 set modfile_indir($eltparent) 1
466 }
467 }
468 }
469 }
470
471 array set hidden_list {}
472 set limited_list [list]
473 # add limited access files and directories to result if they match query
474 foreach elt [concat [array names flimited_arr] [array names\
475 dlimited_arr]] {
476 set eltroot [lindex [file split $elt] 0]
477 if {$eltroot eq {.modulerc} || $findall || [modEqStatic $eltroot\
478 match]} {
479 set fpelt [file join $modpath $elt]
480 lappend limited_list $fpelt
481 # indicate file is hidden in structure that will be transmitted to
482 # findModulesFromDirsAndFiles for no-indepth module search
483 if {[string index [file tail $elt] 0] eq {.} && [info exists\
484 flimited_arr($elt)]} {
485 set hidden_list($fpelt) 1
486 }
487 }
488 }
489
490 # walk through list of matching limited access dirs and files to find
491 # modules available to current user (transmit list of known files and dirs
492 # to avoid file stat tests). rc files recorded in cache are evaluated
493 # first there, as their patterns may apply to this walk
494 findModulesFromDirsAndFiles $modpath $limited_list $depthlvl $fetch_mtime\
495 cache_arr modfile_indir hidden_list flimited_arr dlimited_arr
496
497 reportDebug "found [array names cache_arr] ([array size cache_arr])"
498 set cache_list [array get cache_arr]
499
500 return [list 1 $cache_list]
501 }
502
503 # ;;; Local Variables:
504 # ;;; Mode: tcl-mode
505 # ;;; tcl-indent-level: 3
506 # ;;; tcl-continued-indent-level: 3
507 # ;;; indent-tabs-mode: nil
508 # ;;; End:
509 # vim:set tabstop=3 shiftwidth=3 expandtab autoindent: