tclmain - Run Tcl application via the package name.


DDG 2023-01-26: tclmain is a standalone application which allows you to run applications directly from the package instead of creating separate executables placed in directories belonging to the PATH variable. This approach is based on Python's syntax "python3 -m modulename" which will execute the file "__main.py__" in the package directory. Since version 0.2.0 as well an automatic application call is possible if the package provides a pkgname::main argv procedure.



Install the tclmain.tcl as tclmain in one of your folder belonging to your PATH. Package developers have either to place files like pkgname_main.tcl in the folder where the Tcl package files are or by providing a procedure pkgname::main argv like in the following example:

package provide ::testx 0.0.1

proc ::testx::hello {name} {
    puts "Hello ${name}!"

### This is the entry point for tclmain
proc ::testx::main {{argv {}}} {
    if {[llength $argv] != 1} {
        puts "Usage: tclmain -m testx NAME"
    } else {
        testx::hello [lindex $argv 0]

Here a tclmain session which can use this main procedure:

$ tclmain -i testx 
package:  testx
version:  0.0.1
location: ./examples
$ tclmain -m testx 
Usage: tclmain -m testx NAME
$ tclmain.tcl -m testx  Tclmain
Hello Tclmain!


These examples require you to place the files in the examples directory from the Github repository into a folder ~/.config/tclmain.

$ tclmain -i dummy
usage: tclmain [-h] [-m pkgname command ?arg1 arg2 ...?]
               [-i pkgname]

Error: package dummy does not exists!

$ tclmain -m Markdown 
Missing command for package Markdown.
Available commands are: main
$  tclmain -m Markdown main
Usage: tclmain -m Markdown main mdfile|- ?htmlfile|-?
       instead of filenames as well - can be used to indicate stdin and stdout

   echo '**Hello World!**' |  tclmain -m Markdown main - out.html
$  echo '**Hello world!**'  | tclmain -m Markdown main -
<p><strong>Hello world!</strong></p>

$ tclmain -i ctext
package:  ctext
version:  3.2
location: /usr/share/tcl8.6/tklib0.5/ctext

$ tclmain -m ctext                                                     
Package ctext provides no commands.

$ tclmain -i Tk
package:  Tk
version:  8.6.12
location: /usr/lib64

$ tclmain -m Tk                                                       
Missing command for package Tk.
Available commands are: demo

$ tclmain -m Tk demo
# should run the Tk demo

Below is the file Tk_demo.tcl which is the code required for the last example. This code must be placed in a file: ~/config/tclmain/Tk_demo.tcl and then the example below should work.

#!/usr/bin/env tclsh

foreach folder $auto_path {
    set demo [file join $folder demos widget]
    if {[file exists $demo]} {
        source $demo


DDG 2023-01-26: The principal idea is to simplify development of packages and applications and providing a standard interface for the user to run the application, to get help or to execute some demos. The package developer just place files like pkgname_main.tcl, pkgname_demo.tcl, pkgname_help.tcl in the package folder. Which would allow to run commands main, demo or help for the package or the command line application. There is as well a facility to add such files to a config folder in its own home directory to add these unified syntax to packages which does not (yet) provide this functionality.

DDG 2023-09-30: Version 0.2.0 adds support for the pkgname::main argv procedure approach. By giving your package such a procedure you can call the package application like this tclmain -m pkgname.