typical TCL "package" horror

# I know finally the "autopath" is the WRONG name
lappend autopath /some/path/to/package/dir

package require FileLib

>>
can't find package FileLib

while executing
"package require FileLib"

----
→ go into the directory

sbin> cat pkgIndex.tcl

package ifneeded FileLib 2.0 [list source [file join $dir FileLib.tcl]]
package ifneeded StdLib 2.0 [list source [file join $dir StdLib.tcl]]

----

→ try to debug, add "set tcl_traceExec 1"
→ get a lot of "nonsens" (important info cut away)

Calling proc "::unknown" "::tcl::tm::Unkn..." "::tclPkgUnknown" "FileLib" "0-"
Calling proc "auto_load" "::tcl::tm::Unkn..." "::"
Calling proc "auto_qualify" "::tcl::tm::Unkn..." "::"
Calling proc "auto_load_index"
Calling proc "::tcl::tm::Defa..."
Calling proc "roots" "/home/dev1usr/e..."
Calling proc "add" "/home/dev1usr/e..."
Calling proc "add" "/home/dev1usr/e..."
Calling proc "add" "/home/dev1usr/e..."
Calling proc "add" "/home/dev1usr/e..."
Calling proc "add" "/home/dev1usr/e..."
Calling proc "add" "/home/dev1usr/e..."
Calling proc "add" "/home/dev1usr/e..."
Calling proc "add" "/home/dev1usr/e..."
Calling proc "add" "/home/dev1usr/e..."
Calling proc "add" "/home/dev1usr/e..."
Calling proc "add" "/home/dev1usr/e..."
Calling proc "add" "/home/dev1usr/e..."
Calling proc "add" "/home/dev1usr/e..."
Calling proc "add" "/home/dev1usr/e..."
Calling proc "add" "/home/dev1usr/e..."
Calling proc "add" "/home/dev1usr/e..."
Calling proc "::tcl::tm::Unkn..." "::tclPkgUnknown" "FileLib" "0-"
Calling proc "::unknown" "::tclPkgUnknown" "FileLib" "0-"
Calling proc "auto_load" "::tclPkgUnknown" "::"
Calling proc "auto_qualify" "::tclPkgUnknown" "::"
Calling proc "::tclPkgUnknown" "FileLib" "0-"
Calling lambda "apply" "{dir} {\n se..." "/home/dev1usr/e..."
can't find package FileLib
while executing
"package require FileLib"

---

call: man n package

→ check for the term "path" → not found in manpage
→ a lot of text but NOT a single word how to setup the path to get the package found !!

----

after some research the right name is "auto_path"

mfg ao

At Fri, 21 Jun 2024 11:40:25 +0200 aotto1968 <aotto1968@t-online.de> wrote:

>
>
> typical TCL "package" horror
>
> # I know finally the "autopath" is the WRONG name
> lappend autopath /some/path/to/package/dir

The correct name is auto_path. The docs say so:

auto_path
If set, then it must contain a valid Tcl list giving directories
to search during auto-load operations (including for package in‐
dex files when using the default package unknown handler). This
variable is initialized during startup to contain, in order: the
directories listed in the TCLLIBPATH environment variable, the
directory named by the tcl_library global variable, the parent
directory of tcl_library, the directories listed in the tcl_pkg‐
Path variable. Additional locations to look for files and pack‐
age indices should normally be added to this variable using lap‐
pend.

Additional variables relating to package management exist. More
details are listed in the VARIABLES section of the library man‐
ual page.

Where did you see "autopath"?

>
> package require FileLib
>
> >>
> can't find package FileLib
>
> while executing
> "package require FileLib"
>
> ----
> → go into the directory
>
> sbin> cat pkgIndex.tcl
>
> package ifneeded FileLib 2.0 [list source [file join $dir FileLib.tcl]]
> package ifneeded StdLib 2.0 [list source [file join $dir StdLib.tcl]]
>
> ----
>
> → try to debug, add "set tcl_traceExec 1"
> → get a lot of "nonsens" (important info cut away)
>
> Calling proc "::unknown" "::tcl::tm::Unkn..." "::tclPkgUnknown" "FileLib" "0-"
> Calling proc "auto_load" "::tcl::tm::Unkn..." "::"
> Calling proc "auto_qualify" "::tcl::tm::Unkn..." "::"
> Calling proc "auto_load_index"
> Calling proc "::tcl::tm::Defa..."
> Calling proc "roots" "/home/dev1usr/e..."
> Calling proc "add" "/home/dev1usr/e..."
> Calling proc "add" "/home/dev1usr/e..."
> Calling proc "add" "/home/dev1usr/e..."
> Calling proc "add" "/home/dev1usr/e..."
> Calling proc "add" "/home/dev1usr/e..."
> Calling proc "add" "/home/dev1usr/e..."
> Calling proc "add" "/home/dev1usr/e..."
> Calling proc "add" "/home/dev1usr/e..."
> Calling proc "add" "/home/dev1usr/e..."
> Calling proc "add" "/home/dev1usr/e..."
> Calling proc "add" "/home/dev1usr/e..."
> Calling proc "add" "/home/dev1usr/e..."
> Calling proc "add" "/home/dev1usr/e..."
> Calling proc "add" "/home/dev1usr/e..."
> Calling proc "add" "/home/dev1usr/e..."
> Calling proc "add" "/home/dev1usr/e..."
> Calling proc "::tcl::tm::Unkn..." "::tclPkgUnknown" "FileLib" "0-"
> Calling proc "::unknown" "::tclPkgUnknown" "FileLib" "0-"
> Calling proc "auto_load" "::tclPkgUnknown" "::"
> Calling proc "auto_qualify" "::tclPkgUnknown" "::"
> Calling proc "::tclPkgUnknown" "FileLib" "0-"
> Calling lambda "apply" "{dir} {\n se..." "/home/dev1usr/e..."
> can't find package FileLib
> while executing
> "package require FileLib"
>
> ---
>
> call: man n package
>
> → check for the term "path" → not found in manpage
> → a lot of text but NOT a single word how to setup the path to get the package found !!
>
> ----
>
> after some research the right name is "auto_path"
>
> mfg ao
>
>

--
Robert Heller -- Cell: 413-658-7953 GV: 978-633-5364
Deepwoods Software -- Custom Software Services
http://www.deepsoft.com/ -- Linux Administration Services
heller@deepsoft.com -- Webhosting Services

On 21.06.24 14:25, Robert Heller wrote:
> At Fri, 21 Jun 2024 11:40:25 +0200 aotto1968 <aotto1968@t-online.de> wrote:
>
>>
>>
>> typical TCL "package" horror
>>
>> # I know finally the "autopath" is the WRONG name
>> lappend autopath /some/path/to/package/dir
>
> The correct name is auto_path. The docs say so:
>
> auto_path
> If set, then it must contain a valid Tcl list giving directories
> to search during auto-load operations (including for package in‐
> dex files when using the default package unknown handler). This
> variable is initialized during startup to contain, in order: the
> directories listed in the TCLLIBPATH environment variable, the
> directory named by the tcl_library global variable, the parent
> directory of tcl_library, the directories listed in the tcl_pkg‐
> Path variable. Additional locations to look for files and pack‐
> age indices should normally be added to this variable using lap‐
> pend.
>
> Additional variables relating to package management exist. More
> details are listed in the VARIABLES section of the library man‐
> ual page.
>
> Where did you see "autopath"?
>
>>

the core problem is *not* the "autopath" is wrong because at the time I use it I
does not know it was wrong. The core problem is that is was *very* difficult to figure
out what was the "right" name. special the tcl_traceExec… does not help and more
important the package.n docu (package require…) does *not* spend a single word on
*how* to find a package.

On 6/21/2024 1:17 PM, aotto1968 wrote:
snip

>
> the core problem is *not* the "autopath" is wrong because at the time I use it I
> does not know it was wrong. The core problem is that is was *very* difficult to figure
> out what was the "right" name. special the tcl_traceExec… does not help and more
> important the package.n docu (package require…) does *not* spend a single word on
> *how* to find a package.
>

I'm not sure if this would have helped in your case, but I've used this with some success. It outputs every package command issued and by using a search pattern to limit the output to the ifneeded commands, sometimes gets me what I need to know.

Being on windows, I use the console and the update calls get quicker output. If on linux, I suppose you could also pipe it through grep.

rename package package_orig

proc package {args} {
if { [info exist ::packpat] } {
if { [string match -nocase *${::packpat}* $args]} {
puts "----package: $args" ; update idletasks
}
}
tailcall package_orig {*}$args
} console show ; update

set ::packpat "ifneeded*bwidget"

catch {package require foobar} ;# this won't be found, so it causes a big search

et99 <et99@rocketship1.me> wrote:
> On 6/21/2024 1:17 PM, aotto1968 wrote:
> snip
>>
>> the core problem is *not* the "autopath" is wrong because at the
>> time I use it I does not know it was wrong. The core problem is
>> that is was *very* difficult to figure out what was the "right"
>> name. special the tcl_traceExec… does not help and more important
>> the package.n docu (package require…) does *not* spend a single word
>> on *how* to find a package.
>
> I'm not sure if this would have helped in your case, but I've used
> this with some success. It outputs every package command issued and
> by using a search pattern to limit the output to the ifneeded
> commands, sometimes gets me what I need to know.

aotto1968's complaint is that the "package" man page does not mention
that the auto_path variable stores the search path list for finding
packages. And, I looked, it does not make any mention of the
"specialness" of that variable.

On my Slack15 install, all of the Tcl special variables are documented
in a man page named "tcl_library" (although the page contents believes
it is named "tclvars"). So auto_path's specialness /is/ documented,
but unless one has discovered that it is documented in a different
manpage from 'package', one could very well spend a lot of time and not
find the proper docs.

So the least disruptive change to cover aotto1968's complaint would be
for aotto1968 to file a patch against the package man page adding a
"see tcl_library manpage for Tcl special variables related to package
handling".

That, or aotto1968 should file a patch against the package namespace to
add a brief paragraph to the package manpage detailing that the special
global auto_path contains a list of directories within which to search
for packages when doing a package require.

Either of the above would be a proactive step to eliminate the problem.

Grumbling on Usenet about the issue is not taking any direct steps to
proactively eliminate the issue.

On 6/21/24 16:55, Rich wrote:
> et99 <et99@rocketship1.me> wrote:
>> On 6/21/2024 1:17 PM, aotto1968 wrote:
>> snip
>>>
>>> the core problem is *not* the "autopath" is wrong because at the
>>> time I use it I does not know it was wrong. The core problem is
>>> that is was *very* difficult to figure out what was the "right"
>>> name. special the tcl_traceExec… does not help and more important
>>> the package.n docu (package require…) does *not* spend a single word
>>> on *how* to find a package.
>>
>> I'm not sure if this would have helped in your case, but I've used
>> this with some success. It outputs every package command issued and
>> by using a search pattern to limit the output to the ifneeded
>> commands, sometimes gets me what I need to know.
>
> aotto1968's complaint is that the "package" man page does not mention
> that the auto_path variable stores the search path list for finding
> packages. And, I looked, it does not make any mention of the
> "specialness" of that variable.
>
> On my Slack15 install, all of the Tcl special variables are documented
> in a man page named "tcl_library" (although the page contents believes
> it is named "tclvars"). So auto_path's specialness /is/ documented,
> but unless one has discovered that it is documented in a different
> manpage from 'package', one could very well spend a lot of time and not
> find the proper docs.
>
> So the least disruptive change to cover aotto1968's complaint would be
> for aotto1968 to file a patch against the package man page adding a
> "see tcl_library manpage for Tcl special variables related to package
> handling".
>
> That, or aotto1968 should file a patch against the package namespace to
> add a brief paragraph to the package manpage detailing that the special
> global auto_path contains a list of directories within which to search
> for packages when doing a package require.
>
> Either of the above would be a proactive step to eliminate the problem.
>
> Grumbling on Usenet about the issue is not taking any direct steps to
> proactively eliminate the issue.
>

Or read through all of the man/reference/doc pages when picking up a new
language.

On 6/21/2024 2:55 PM, Rich wrote:
> et99 <et99@rocketship1.me> wrote:
>> On 6/21/2024 1:17 PM, aotto1968 wrote:
>> snip
>>>
>>> the core problem is *not* the "autopath" is wrong because at the
>>> time I use it I does not know it was wrong. The core problem is
>>> that is was *very* difficult to figure out what was the "right"
>>> name. special the tcl_traceExec… does not help and more important
>>> the package.n docu (package require…) does *not* spend a single word
>>> on *how* to find a package.

snip

> So the least disruptive change to cover aotto1968's complaint would be
> for aotto1968 to file a patch against the package man page adding a
> "see tcl_library manpage for Tcl special variables related to package
> handling".
>
> That, or aotto1968 should file a patch against the package namespace to
> add a brief paragraph to the package manpage detailing that the special
> global auto_path contains a list of directories within which to search
> for packages when doing a package require.
>
> Either of the above would be a proactive step to eliminate the problem.
>

Being that I'm mostly on windows, I use Ashok's documentation website. His index is great, and you can pre-load a search term, like so:

https://www.magicsplat.com/tcl-docs/docindex.html?search=tclvars

which takes you directly to the tclvars page where auto_path is the first variable described.

Now that Ashok is part of the core team (yay!) I think something like his webtools would be a great addition to the official tcl documentation, if Ashok would approve of such.

I use his tool from within my text editor, where the word under the cursor can be sent off as the search term using the above url and sending it through to chrome, all with a single keystroke.

Truly great resource!

At Fri, 21 Jun 2024 21:55:54 -0000 (UTC) Rich <rich@example.invalid> wrote:

>
> et99 <et99@rocketship1.me> wrote:
> > On 6/21/2024 1:17 PM, aotto1968 wrote:
> > snip
> >>
> >> the core problem is *not* the "autopath" is wrong because at the
> >> time I use it I does not know it was wrong. The core problem is
> >> that is was *very* difficult to figure out what was the "right"
> >> name. special the tcl_traceExec… does not help and more important
> >> the package.n docu (package require…) does *not* spend a single word
> >> on *how* to find a package.
> >
> > I'm not sure if this would have helped in your case, but I've used
> > this with some success. It outputs every package command issued and
> > by using a search pattern to limit the output to the ifneeded
> > commands, sometimes gets me what I need to know.
>
> aotto1968's complaint is that the "package" man page does not mention
> that the auto_path variable stores the search path list for finding
> packages. And, I looked, it does not make any mention of the
> "specialness" of that variable.
>
> On my Slack15 install, all of the Tcl special variables are documented
> in a man page named "tcl_library" (although the page contents believes
> it is named "tclvars"). So auto_path's specialness /is/ documented,
> but unless one has discovered that it is documented in a different
> manpage from 'package', one could very well spend a lot of time and not
> find the proper docs.
>
> So the least disruptive change to cover aotto1968's complaint would be
> for aotto1968 to file a patch against the package man page adding a
> "see tcl_library manpage for Tcl special variables related to package
> handling".

I suspect that the tcl_library manpage is replicated from the tclvars man
page. A number of Tcl's (and Tk's) man pages are dups. Which happen at build
or install time (links?) or possibly using an old UNIX trick where man pages
can implement a re-direct -- this is done because some man pages cover
multiple closely related topics (or groups commands that have common
documentation.

>
> That, or aotto1968 should file a patch against the package namespace to
> add a brief paragraph to the package manpage detailing that the special
> global auto_path contains a list of directories within which to search
> for packages when doing a package require.
>
> Either of the above would be a proactive step to eliminate the problem.
>
> Grumbling on Usenet about the issue is not taking any direct steps to
> proactively eliminate the issue.
>
>
>

--
Robert Heller -- Cell: 413-658-7953 GV: 978-633-5364
Deepwoods Software -- Custom Software Services
http://www.deepsoft.com/ -- Linux Administration Services
heller@deepsoft.com -- Webhosting Services

Robert Heller <heller@deepsoft.com> wrote:
> At Fri, 21 Jun 2024 21:55:54 -0000 (UTC) Rich <rich@example.invalid> wrote:
>
>>
>> et99 <et99@rocketship1.me> wrote:
>> > On 6/21/2024 1:17 PM, aotto1968 wrote:
>> > snip
>> >>
>> >> the core problem is *not* the "autopath" is wrong because at the
>> >> time I use it I does not know it was wrong. The core problem is
>> >> that is was *very* difficult to figure out what was the "right"
>> >> name. special the tcl_traceExec?????? does not help and more important
>> >> the package.n docu (package require??????) does *not* spend a single word
>> >> on *how* to find a package.
>> >
>> > I'm not sure if this would have helped in your case, but I've used
>> > this with some success. It outputs every package command issued and
>> > by using a search pattern to limit the output to the ifneeded
>> > commands, sometimes gets me what I need to know.
>>
>> aotto1968's complaint is that the "package" man page does not mention
>> that the auto_path variable stores the search path list for finding
>> packages. And, I looked, it does not make any mention of the
>> "specialness" of that variable.
>>
>> On my Slack15 install, all of the Tcl special variables are documented
>> in a man page named "tcl_library" (although the page contents believes
>> it is named "tclvars"). So auto_path's specialness /is/ documented,
>> but unless one has discovered that it is documented in a different
>> manpage from 'package', one could very well spend a lot of time and not
>> find the proper docs.
>>
>> So the least disruptive change to cover aotto1968's complaint would be
>> for aotto1968 to file a patch against the package man page adding a
>> "see tcl_library manpage for Tcl special variables related to package
>> handling".
>
> I suspect that the tcl_library manpage is replicated from the tclvars man
> page.

At least on a Slack 15 install, with the Slack distributed 8.6.12 it is
not ("tclvars" was what I tried first, as that is what it always has
been named). Note that this could very well be a glitch in the way
Slackware built their 8.6.12.

There are a couple of layers to solve the TCL documentation bug:

1. -> get better error message

> can't find package FileLib
> while executing
> "package require FileLib"

Not just write the problem itself (can't find package FileLib) but also write about what was checked.
A good error message would be:

> can't find package FileLib
> while executing
> "package require FileLib"
>
> checked the tcl variable "tcl_pkgPath" filled with:
> ...
> checked the tcl variable "auto_path" filled with:
> ...
> checked the environment variable "TCLLIBPATH" filled with:
> ...
> read more about package path lookup at:
> ...

2. -> add the "pkg_mkIndex" docu INTO the "package.n" docu

*pkg_mkIndex* has a lot of information about the package lookup …

also add *pkg_mkIndex* as sub-command "mkindex" into the "package" command…

3. all commands which depend on a special variable set should also mention the variable in the docu :-)

mfg