I made my very first package today and I hated that part.

See what the wiki says:

https://wiki.tcl-lang.org/page/pkg_mkIndex

pyk 2012-11-02 - dgp stated on the irc channel today that pkg_mkIndex
is not generally a good idea. It can't possibly solve the problem
right for any but the most simple packages, and even for those, typing
the index script yourself is just as easy.

"Just as easy"? I don't think so. What am I supposed to type? Where is
that documented? I spent a long time looking for that information and
couldn't find it.

pkg_mkIndex is bad indeed. My package has one, a single one .tcl file,
and pkg_mkIndex kept producing an empty pkgIndex.tcl file. In one of
many many many attempts, it generated something I could use and I just
went with it.

Of course I looked at other packages, but it's hard to make heads and
tails of the information they contain.

"Think of pkg_mkIndex as at best a (poor) tool to help you write
pkgIndex.tcl files. If you can do a better job by hand (or by template
substitution during configure) then that is probably better."
-- dkf ,tcl-core mailing list, 2012-11-07

OK, I wouldn't mind typing it all manually if only I had a clue of
what is supposed to go in a pkgIndex.tcl file. I swear, I searched
high and low and couldn't find it. Do you people know where that
information is found?

--
Luc
>>

Luc <luc@sep.invalid> wrote:
> I made my very first package today and I hated that part.
>
> See what the wiki says:
>
> https://wiki.tcl-lang.org/page/pkg_mkIndex
>
> pyk 2012-11-02 - dgp stated on the irc channel today that pkg_mkIndex
> is not generally a good idea. It can't possibly solve the problem
> right for any but the most simple packages, and even for those, typing
> the index script yourself is just as easy.
>
> "Just as easy"? I don't think so. What am I supposed to type? Where is
> that documented? I spent a long time looking for that information and
> couldn't find it.
>
> pkg_mkIndex is bad indeed. My package has one, a single one .tcl file,
> and pkg_mkIndex kept producing an empty pkgIndex.tcl file. In one of
> many many many attempts, it generated something I could use and I just
> went with it.
>
> Of course I looked at other packages, but it's hard to make heads and
> tails of the information they contain.
>
>
> "Think of pkg_mkIndex as at best a (poor) tool to help you write
> pkgIndex.tcl files. If you can do a better job by hand (or by template
> substitution during configure) then that is probably better."
> -- dkf ,tcl-core mailing list, 2012-11-07
>
> OK, I wouldn't mind typing it all manually if only I had a clue of
> what is supposed to go in a pkgIndex.tcl file. I swear, I searched
> high and low and couldn't find it. Do you people know where that
> information is found?
>
If you have this book

The Tcl Programming Language
A Comprehensive Guide
Ashok P. Nadkarni

section 13.3.8

If you don't have this book, you should buy it.

https://wiki.tcl-lang.org/page/pkgIndex.tcl

On 3/12/24 12:57, Luc wrote:
> pkg_mkIndex is bad indeed. My package has one, a single one .tcl file,

For such a simple package structure, installation as a Tcl Module is
probably the best answer.

https://www.tcl-lang.org/man/tcl8.6/TclCmd/tm.htm

--
| Don Porter Applied and Computational Mathematics Division |
| donald.porter@nist.gov Information Technology Laboratory |
| http://math.nist.gov/~DPorter/ NIST |
|______________________________________________________________________|

On Wed, 13 Mar 2024 09:31:20 -0400, Don Porter wrote:

>On 3/12/24 12:57, Luc wrote:
>> pkg_mkIndex is bad indeed. My package has one, a single one .tcl file,
>
>For such a simple package structure, installation as a Tcl Module is
>probably the best answer.
>
>https://www.tcl-lang.org/man/tcl8.6/TclCmd/tm.htm
>
**************************

Interesting. However:

1. Why did someone think that was necessary? What does tm do that
'source' won't do?

2. So one person tells me I have to buy a third-party book, another
points me to a vague and disorganized wiki page with random scattered
tips, you say I should use a module and nobody else has anything to
say. Making packages is de facto undocumented, isn't it?

--
Luc
>>

On 3/13/24 11:28, Luc wrote:
> On Wed, 13 Mar 2024 09:31:20 -0400, Don Porter wrote:
>
>> On 3/12/24 12:57, Luc wrote:
>>> pkg_mkIndex is bad indeed. My package has one, a single one .tcl file,
>>
>> For such a simple package structure, installation as a Tcl Module is
>> probably the best answer.
>>
>> https://www.tcl-lang.org/man/tcl8.6/TclCmd/tm.htm
>>
> **************************
>
>
> Interesting. However:
>
> 1. Why did someone think that was necessary? What does tm do that
> 'source' won't do?
>
> 2. So one person tells me I have to buy a third-party book, another
> points me to a vague and disorganized wiki page with random scattered
> tips, you say I should use a module and nobody else has anything to
> say. Making packages is de facto undocumented, isn't it?

They are pointing you do different resources since seem to be having
problems and did not give any details of what your package looks like.

I've never had any issues with just creating packages. Is your package
provide line correct?

If pkg_mkIndex fails, then generating the package index by hand is
trival, see
https://core.tcl-lang.org/tclws/file?name=pkgIndex.tcl&ci=tip for an
example.

On Wed, 13 Mar 2024 11:39:53 -0500, Gerald Lester wrote:

>They are pointing you do different resources since seem to be having
>problems and did not give any details of what your package looks like.

Sorry if I may come across as rude, I really don't want that, but pray
tell, if making packages were to be fully documented, what would such
documentation look like? Would it be something like,

"Drop by clt, tell us the details of your package and someone will
tell you what exactly what you need to do to make a package."

I don't think so.

>I've never had any issues with just creating packages.

Good for you. And how did you learn how to do it?

>If pkg_mkIndex fails, then generating the package index by hand is
>trival, see
>https://core.tcl-lang.org/tclws/file?name=pkgIndex.tcl&ci=tip for an
>example.

Interesting document. But it can't answer some questions. To wit,
let's see what the pkgIndex.tcl for BWidget looks like:

package ifneeded BWidget 1.9.16 "\
package require Tk 8.1.1;\
[list tclPkgSetup $dir BWidget 1.9.16 {
{arrow.tcl source {ArrowButton ::ArrowButton::create ::ArrowButton::use}}
{labelframe.tcl source {LabelFrame ::LabelFrame::create ::LabelFrame::use}}
{labelentry.tcl source {LabelEntry ::LabelEntry::create ::LabelEntry::use}}

1. Oh, I can require a certain version of Tk here? Should I? Where?
What is the exact correct position for that? Where is that detail
specified?

2. The manual says,

"source - Evaluate a file or resource as a Tcl script
SYNOPSIS
source fileName
source -encoding encodingName fileName"

I'm not really sure of what a "resource" means here, but the synopsis
leads me to believe that source can only 'source' files.

But the BWidget pkgIndex.tcl is 'sourcing' something else there. What
is it doing? Is it sourcing procs? Is it sourcing classes? Is it
sourcing namespaces? Is that possible? Who told the author of BWidget
that sourcing whatever his pkgIndex.tcl is sourcing was within the
realm of possibility? Where do you people learn these things?

OK, I can inspect arrow.tcl for example and find out that ArrowButton
is a namespace. But I never knew we could 'source' a namespace. And
how could I? The word 'source' is not even mentioned once in the
'namespace' manual page.

Now, what is the meaning of this line?

ArrowButton ::ArrowButton::create ::ArrowButton::use

A bare word (it looks like it to me) followed by two procs with fully
qualified names. It is particularly confusing because the arrow.tcl
file (clearly specified at the beginning of the line) does contain the
::ArrowButton::create proc, but makes no mention of ::ArrowButton::use.
In fact, grep tells me that no file in BWidget mentions this
mysterious ::ArrowButton::use proc. So what is ::ArrowButton::use?

I don't want to discuss the internals of BWidget. It's just a random
example. The question is, why is that included in the pkgIndex.tcl
file? Why does Tcl/Tk have no problem with a proc that doesn't exist?
How do I know what is possible or permitted and what is not?

Do you see now where I am coming from?

--
Luc
>>

On 3/13/24 13:01, Luc wrote:
> On Wed, 13 Mar 2024 11:39:53 -0500, Gerald Lester wrote:
>
>> They are pointing you do different resources since seem to be having
>> problems and did not give any details of what your package looks like.
>
> Sorry if I may come across as rude, I really don't want that, but pray
> tell, if making packages were to be fully documented, what would such
> documentation look like? Would it be something like,
>
> "Drop by clt, tell us the details of your package and someone will
> tell you what exactly what you need to do to make a package."
>
> I don't think so.
>
>
>> I've never had any issues with just creating packages.
>
> Good for you. And how did you learn how to do it?

Honestly don't remember, it was right after the package command was
introduced, something like about 30 years ago or more (I think that was
Tcl 8.0 -- or may have even been in 7.6 -- maybe earlier, but I don't
think so).

>
>> If pkg_mkIndex fails, then generating the package index by hand is
>> trival, see
>> https://core.tcl-lang.org/tclws/file?name=pkgIndex.tcl&ci=tip for an
>> example.
>
> Interesting document.

It is NOT A DOCUMENT! As I wrote it is an EXAMPLE. It is a simple
example that can be used for a good number of use cases.

> But it can't answer some questions. To wit,...
<deleted a bunch of verbiage about BWidgets>

> Why does Tcl/Tk have no problem with a proc that doesn't exist?

You need to step back and understand about Tcl's auto loading via the
standard unknown proc for an answer to that.

> How do I know what is possible or permitted and what is not?

Almost anything is possible and just about anything is permitted. That
does not mean you should do it.

I have seen package if needed that read from database and others that
pulled over a socket. Does not mean you should do that until you really
understand what is going on by looking at the code that implements the
package system and the auto load systems.

In Tcl there are many times multiple ways to do things that were added
over the years with the newwer ones being improvements and the older
ones kept so as not to break existing code.

> Do you see now where I am coming from?

Actually no. Your post goes all over the place.

On Wed, 13 Mar 2024 13:34:28 -0500, Gerald Lester wrote:

>Almost anything is possible and just about anything is permitted. That
>does not mean you should do it.

Almost? What is not possible?

>I have seen package if needed that read from database and others that
>pulled over a socket.

But have you seen any of that documented?

>Does not mean you should do that until you really
>understand what is going on by looking at the code that implements the
>package system and the auto load systems.

"Read the code and figure it all out by yourself."

Confirmed. It's undocumented.

>Actually no. Your post goes all over the place.

No. I make a very clear point that the procedure is undocumented and
everybody seems to learn it only through some kind of grapevine.

- What does Tcl expect from a pkgIndex.tcl file?
- What is the absolute minimum information it must contain?
- What is the correct format of the information?
- What else is allowed?
- In what format?
- What are the effects of such options?

But ok, I consider it answered. Thank you.

--
Luc
>>

Luc <luc@sep.invalid> wrote:
> On Wed, 13 Mar 2024 13:34:28 -0500, Gerald Lester wrote:
>>Almost anything is possible and just about anything is permitted. That
>>does not mean you should do it.
> Almost? What is not possible?

(As an ice breaker for starting - below it I'm more serious)
In the past, "making coffee" was a standard answer to that, but in
some EuroTcl conferences of last few years, we have learnt better,
so, I'll say "making hot chocolate", until John's devices fill that
gap ;-)

>>I have seen package if needed that read from database and others that
>>pulled over a socket.
> But have you seen any of that documented?

The relevant documentation is the doc for "package" and within
that the paragraph about "ifneeded".
from there, we will analyze the building blocks one by one...

package ifneeded fubar 1.42.54 {puts hello}

Essentially, with that command you tell the tcl interp that:
If ever you need version 1.42.54 of package fubar, then
execute this script: {puts hello}

If your script lateron calls this command:
package require fubar
then you'll see the "hello" printed out, and it will detect, that
calling this script didn't really do its job of "providing" the
package:

% package require fubar
hello
attempt to provide package fubar 1.42.54 failed: no version of package fubar provided
%

Now lets have another look at what BWidget does:
package ifneeded BWidget 1.9.16 "\
package require Tk 8.1.1;\
[list tclPkgSetup $dir BWidget 1.9.16 {
{arrow.tcl source {ArrowButton ::ArrowButton::create ::ArrowButton::use}}
{labelframe.tcl source {LabelFrame ::LabelFrame::create ::LabelFrame::use}}
{labelentry.tcl source {LabelEntry ::LabelEntry::create ::LabelEntry::use}}

Upon eventually requiring BWidget later, the following script would
be executed:

package require Tk 8.1.1
tclPkgSetup $dir BWidget 1.9.16 { ... }

where $dir is actually replaced already within BWidget's pkgIndex.tcl,
so commands are really something like:

package require Tk 8.1.1
tclPkgSetup /x/y/z BWidget 1.9.16 { ... }

What is inside the curlies is only relevant to that command "tclPkgSetup"
which expects a nested list structure describing files, types, and a
list of commands that will be made available by treating the file
according to its type.

tclPkgSetup is really a helper procedure, whose definition can be
examined using: info body tclPkgSetup
I didn't find any man-page for that helper command. Googling
for it might find something.

Eventually, the script have called something like
package provide BWidget 1.9.16
(which, btw., the "tclPkgSetup" does inside it, among other stuff)

So we could create our dummy package correctly like this:

package ifneeded fubar 1.42.54 { package provide fubar 1.42.54 }

and a later

package require fubar

will return "1.42.54" as the version successfully loaded.

Anything else that your package will later need to get loaded
ought to be prepared within that script.

> - What does Tcl expect from a pkgIndex.tcl file?

That it sets up the "ifneeded" script, that will be executed once
the package is actually required by a specific application script.

> - What is the absolute minimum information it must contain?

It could be empty, but then it would be useless.
It could contain a "puts hello", but that would be printed regardless
of whether the package is actually needed for a tcl application, so
would be very bad practise.
Ideally it would only contain "package ifneeded" invocations for each
package it is meant to make available.

package ifneeded moinmoin 0.0.1 {
puts "Good morning, Tcl!"
package provide moinmoin 0.0.1
}

> - What is the correct format of the information?

A tcl script that does the "right thing"(tm) for the package at hand.

> - What else is allowed?

As little as possible to get the package advertising done.

Anything else would make tcl startup slower for all scripts,
even those not needing that package.

> - In what format?

in tcl script format. (That means, it could contain nested
blocks of utter garbage, as long as that garbage is corrctly
understood by the command to which the garbage is really passed.)

> - What are the effects of such options?

That depends on the command, to which they are actually passed.

On Wed, 13 Mar 2024 20:33:22 -0000 (UTC), Andreas Leitgeb wrote:

>(As an ice breaker for starting - below it I'm more serious)
**************************

That is informative. Thank you.

--
Luc
>>

On 3/13/2024 9:28 AM, Luc wrote:
> On Wed, 13 Mar 2024 09:31:20 -0400, Don Porter wrote:
>
>> On 3/12/24 12:57, Luc wrote:
>>> pkg_mkIndex is bad indeed. My package has one, a single one .tcl file,
>>
>> For such a simple package structure, installation as a Tcl Module is
>> probably the best answer.
>>
>> https://www.tcl-lang.org/man/tcl8.6/TclCmd/tm.htm
>>
> **************************
>
>
> Interesting. However:
>
> 1. Why did someone think that was necessary? What does tm do that
> 'source' won't do?
>
> 2. So one person tells me I have to buy a third-party book, another
> points me to a vague and disorganized wiki page with random scattered
> tips, you say I should use a module and nobody else has anything to
> say. Making packages is de facto undocumented, isn't it?
>
>

Many years ago I heard about a new language called C. I read a few things about it but thought it was a very strange language, with a lot of funny looking operators.

Then I discovered the C white book by Brian Kernighan and Dennis Ritchie. I got my employer to pay for it, but also bought one for myself, in case I left the job for better pastures.

Tcl is an open source, community supported language. The documentation is created by people just like you who don't get paid anything for it. You can volunteer to help if you think you can do better.

But if you want the Kernighan experience, you need to buy the "Tcl programming language" book by Ashok. If you can't afford the paper-bound book, then buy the pdf. It costs about the same as a gallon of orange juice and a loaf of bread, but took the author a lot of time putting it together. Ashok also has a great resource for looking up most anything from the official documentation at his website, which he provides for free.

You would save yourself a lot of effort if you would save up the $18 and buy the pdf version of his book.

That is where I learned about tcl OO, tcl modules, and threads, just to name a few items.

The advantage of the module system over just "source" is that you can incorporate the package command's versioning system. It was written IMO to simplify the package system whose command had become rather complicated.

I create modules. The http command is a module. There are many others that are available by package require.

It's your choice, get frustrated, or get the book.

On Wed, 13 Mar 2024 19:09:00 -0700, et99 wrote:

>But if you want the Kernighan experience, you need to buy the "Tcl
>programming language" book by Ashok. If you can't afford the paper-bound
>book, then buy the pdf. It costs about the same as a gallon of orange
>juice and a loaf of bread, but took the author a lot of time putting it
>together. Ashok also has a great resource for looking up most anything
>from the official documentation at his website, which he provides for free.

As someone who actually has had to skip meals very frequently lately
in a constant struggle not to go homeless, I absolutely prefer the
gallon of orange juice and loaf of bread.

And I am sick, really sick of reading advertisements for that book.

Forget this topic. I don't care anymore.

--
Luc
>>