Check-in [4304dd5b57]

Login
Bounty program for improvements to Tcl and certain Tcl packages.
Tcl 2019 Conference, Houston/TX, US, Nov 4-8
Send your abstracts to [email protected]
or submit via the online form by Sep 9.

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Overview
Comment:Tip495 revision.

Fixed typos. Fixed the manual location for practcl. Updated the spec on the API

Downloads: Tarball | ZIP archive | SQL archive
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA3-256: 4304dd5b57c2d49ad012dd4bc2a0d81b331baf359e20076dd8da6de106d9585b
User & Date: hypnotoad 2018-10-27 11:03:27
Context
2018-10-27
11:04
Updated the tip479 spec to place the new commands for dictargs wrapping in a dedicated namespace and leave room in the spec for handling alternate argument handing schemes check-in: 16ec396728 user: hypnotoad tags: trunk
11:03
Tip495 revision. check-in: 4304dd5b57 user: hypnotoad tags: trunk
01:18
Needed to run a script. check-in: dd27c995d4 user: dgp tags: trunk
Changes
Hide Diffs Unified Diffs Ignore Whitespace Patch

Changes to tip/495.md.

14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31


32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53

54
55
56
57
58
59
60
61
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
..
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189

# Rationale

A present day application developer has to use several more languages than simply Tcl
and C to develop extensions for the language. Binary packages require a developer to
master autoconf, Makefile and nmake. The reference Sample extension is really only useful
for very, very trivial extensions. And even there requires some knowledge of the process to
do the appropriate cuttoing and pasting. Most TEA packages have no concept of how they
can populate a VFS for a kit, or bundle themselves as a zip file for proper packaging
in a TEAPOT.

As one of the developers in charge of fixing day to day problems in TEA, I find myself
writing a lot more sh than Tcl. And most of that writing is working around limitations
in the sh language itself.

SH and autoconf are not going away. We are just changing their role from "building our
make system" to "finding all the platform specific quirks so that Tcl can be our
make system".



The reforms to TEA are several fold, but designed in such a way that present packages
can continue to use their current build systems, unmodified. New projects (or old projects
that upgrade to the TEA 4 standard) will be able to utilize the new features of TEA.

The principle change is that the process of building binaries is being moved out of
the Makefile and Nmake, and into a Tcl script. Vestigal batch files for each can be
left which call the new mechanisms in the old way.

Instead of the prime mover for packages being:

    ./configure
    make all
    
New TEA packages will use the convention of:

    tclsh make.tcl all

The make.tcl file does not have to implement bread and butter compile, integration and
installation functions.  They will be provided by a new package "practcl" which is
distributed via tcllib, after Tcl 8.7 as a core distributed package, and a version
of the library will also ship in the /tclconfig directory that TEA packages include

in source distributions. It is a self contained library with no external dependencies,
and runs in Tcl 8.6, or 8.5 with the TclOO extension.

# Specification

## make.tcl

All Tcl extensions will have a make.tcl file. That file will contain all of the
instructions needed to build, install, package, and integrate that extension.

make.tcl will accept the following commands:

1. **all** - Replicate the behavior of the previous TEA system, generate a dynamic library
2. **install** *?destination?* - Install the package to local environment or to the optional directory
3. **teapot** - Generate a .zip or .tm file containing an installation image of the package
4. **info** - Return a dict containing the following information:
	name    - The name of the project
	version - The version of the project
	teapot_file - The name of the file generated by teapot
	library_file - The name of the dynamic library
	static_file - The name of the static library


5. **packages** - Returns a list of packages and versions of those packages this project generates
5. **dynamic** - Generate a dynamic library
6. **static** - Generate a static library

7. **shell** - Optional - Generate an executable with the package statically linked

8. **test** - Run the test suite for the package













## config.tcl

Instead of having autoconf write all over Makefiles and pkgIndex, the new TEA
performs all of its substitutions in one file: **config.tcl**. That file contains
a key/value list readable by a Tcl script. *nmake* environments will
perform identical subsitutions to the same file.
................................................................................
A standard library of tools (provisinally named "practcl") will be provided in
tcllib and as a single file distribution in the same repository as the TEA
reference files. (http://core.tcl.tk/tclconfig)

This library includes implementations for all build, installation, and integration tasks. The
file can be directly sourced, or invoked with `package require practcl`.

<pre>
## Example make.tcl file
	
set CWD [pwd]
set ::SRCDIR   [file dirname [file normalize [info script]]]
set ::SANDBOX  [file dirname $::SRCDIR]
package require practcl
	
# Build and configure and object named "LIBRARY"
array set ::project [::practcl::config.tcl $CWD]
::practcl::library create LIBRARY [array get ::project]
LIBRARY define set builddir $CWD
LIBRARY define set srcdir $SRCDIR
LIBRARY meta set author {{Tcl Core}}
LIBRARY meta set license BSD
LIBRARY add [file join $::SRCDIR generic sample.c]
LIBRARY add [file join $::SRCDIR generic sample.tcl]
LIBRARY define add public-verbatim [file join $::SRCDIR generic sample.h]
	
# Run ./configure or nmakehlp to generate the config.tcl file
if {![LIBRARY define exists TCL_SRC_DIR]} {
  # Common interactions will have pre-canned implementations
  LIBRARY make detect
}
	
# Define a target which generates the dynamic C code
LIBRARY make add implement {
  filename sample.c
} {
  # This script evaluates with in the LIBRARY
  # object's namespace
  my go
  my implement $::project(builddir)
  set fout [open pkgIndex.tcl w]
  puts $fout [LIBRARY package-ifneeded]
  close $fout
}
	
# Define the "all" target, and create aliases for "libraries"
# and "binaries"
LIBRARY make add all {
  aliases {binaries libraries}
  depends library
}
	
# Define the "library" target
LIBRARY make add library {
  triggers implement
  filename [LIBRARY define get libfile]
} {
  puts "BUILDING [my define get libfile]"
  my build-library [my define get libfile] [self]
}
	
# Process command line
switch [lindex $argv 0] {
  install {
    # Ensure the library is compiled
    LIBRARY make depends library doc
	# Make do acts on all of the steps computed by
	# make depends
	LIBRARY make do
	# Project specific installation procedure
  }
  info {
    # Output information that integrators need
    set dat [LIBRARY target pkginfo]
    foreach {field value} $dat {
  	  puts [list $field: $value]
	}
	exit 0
  }
  teapot {
    # Ensure the library is compiled
    LIBRARY make depends library
	LIBRARY make do
	# Code to generate teapot distribution
  }
  default {
	# Work like a makefile and trigger build targets
	# Unlike a standard makefile "trigger" will re-kick
	# off any indicated steps
	LIBRARY make trigger {*}$argv
	LIBRARY make do
  }
}
</pre>

# More Info

*This is a work in progress.*

Details are trickling in from the [Practcl project](http://www.etoyoc.com/tcl/Practcl.pdf).







|







|
|
|
>
>













|




|
|
<
|
>
|












<
<
|



|
|
>
>
|


>
|
>
|
>
>
>
>
>
>
>
>
>
>
>
>







 







<
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<





<
>
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53

54
55
56
57
58
59
60
61
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
95
96
97
98
99
100
101
102
...
106
107
108
109
110
111
112

113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197

198
199
200
201
202

203
# Rationale

A present day application developer has to use several more languages than simply Tcl
and C to develop extensions for the language. Binary packages require a developer to
master autoconf, Makefile and nmake. The reference Sample extension is really only useful
for very, very trivial extensions. And even there requires some knowledge of the process to
do the appropriate cutting and pasting. Most TEA packages have no concept of how they
can populate a VFS for a kit, or bundle themselves as a zip file for proper packaging
in a TEAPOT.

As one of the developers in charge of fixing day to day problems in TEA, I find myself
writing a lot more sh than Tcl. And most of that writing is working around limitations
in the sh language itself.

In this project SH and autoconf are not completely going away. We are just changing their
role from "building our make system" to "finding all the platform specific quirks so that
Tcl can be our make system". Though for simple projects we do open the door to restricting
their role to building the Tcl core, and then allow Tcl scripts to leverage what autoconf
discovered.

The reforms to TEA are several fold, but designed in such a way that present packages
can continue to use their current build systems, unmodified. New projects (or old projects
that upgrade to the TEA 4 standard) will be able to utilize the new features of TEA.

The principle change is that the process of building binaries is being moved out of
the Makefile and Nmake, and into a Tcl script. Vestigal batch files for each can be
left which call the new mechanisms in the old way.

Instead of the prime mover for packages being:

    ./configure
    make all

New TEA packages will use the convention of:

    tclsh make.tcl all

The make.tcl file does not have to implement bread and butter compiler, integration and
installation functions.  They will be provided by a new package "practcl" which will be

distributed as a single file in the /tclconfig directory that TEA packages include
in source distributions. A version will also be provided as a tcllib module.
The practcl module is a self contained library with no external dependencies,
and runs in Tcl 8.6, or 8.5 with the TclOO extension.

# Specification

## make.tcl

All Tcl extensions will have a make.tcl file. That file will contain all of the
instructions needed to build, install, package, and integrate that extension.

make.tcl will accept the following commands:

1. **all** - Replicate the behavior of the previous TEA system, generate a dynamic library


2. **info** - Return a dict containing the following information:
	name    - The name of the project
	version - The version of the project
	teapot_file - The name of the file generated by teapot
	library_file - The name of the dynamic library file
	static_file - The name of the static library file
	stubs_file - The name of the stubs library file
3. **install** *?destination?* - Install the package to local environment or to the optional directory
4. **packages** - Returns a list of packages and versions of those packages this project generates
5. **dynamic** - Generate a dynamic library
6. **static** - Generate a static library
7. **stubs** - Generate a stubs library
8. **shell** - Optional - Generate an executable with the package statically linked
9. **teapot** - Generate a .zip or .tm file containing an installation image of the package
10. **test** - Run the test suite for the package

## tcllib (and other large libraries)

Projects such as tcllib which contain many modules, and are unlikely to be installed
whole inside of a tclkit, will be given additional make directives:

1. **module-list** - Return a list of modules
2. **module-install** *destination* *module|all* *?module?...*- Install named modules
to the destination. Unlike the standard installation, this method does not place the
module inside of a versioned package/module file structure. The module is simply dropped
as either a .tm file for directory with the module's name and a pkgIndex.tcl file, within
the directory specified.

## config.tcl

Instead of having autoconf write all over Makefiles and pkgIndex, the new TEA
performs all of its substitutions in one file: **config.tcl**. That file contains
a key/value list readable by a Tcl script. *nmake* environments will
perform identical subsitutions to the same file.
................................................................................
A standard library of tools (provisinally named "practcl") will be provided in
tcllib and as a single file distribution in the same repository as the TEA
reference files. (http://core.tcl.tk/tclconfig)

This library includes implementations for all build, installation, and integration tasks. The
file can be directly sourced, or invoked with `package require practcl`.


        ## Example make.tcl file

        set CWD [pwd]
        set ::SRCDIR   [file dirname [file normalize [info script]]]
        set ::SANDBOX  [file dirname $::SRCDIR]
        package require practcl

        # Build and configure and object named "LIBRARY"
        array set ::project [::practcl::config.tcl $CWD]
        ::practcl::library create LIBRARY [array get ::project]
        LIBRARY define set builddir $CWD
        LIBRARY define set srcdir $SRCDIR
        LIBRARY meta set author {{Tcl Core}}
        LIBRARY meta set license BSD
        LIBRARY add [file join $::SRCDIR generic sample.c]
        LIBRARY add [file join $::SRCDIR generic sample.tcl]
        LIBRARY define add public-verbatim [file join $::SRCDIR generic sample.h]

        # Run ./configure or nmakehlp to generate the config.tcl file
        if {![LIBRARY define exists TCL_SRC_DIR]} {
          # Common interactions will have pre-canned implementations
          LIBRARY make detect
        }

        # Define a target which generates the dynamic C code
        LIBRARY make add implement {
          filename sample.c
        } {
          # This script evaluates with in the LIBRARY
          # object's namespace
          my go
          my implement $::project(builddir)
          set fout [open pkgIndex.tcl w]
          puts $fout [LIBRARY package-ifneeded]
          close $fout
        }

        # Define the "all" target, and create aliases for "libraries"
        # and "binaries"
        LIBRARY make add all {
          aliases {binaries libraries}
          depends library
        }

        # Define the "library" target
        LIBRARY make add library {
          triggers implement
          filename [LIBRARY define get libfile]
        } {
          puts "BUILDING [my define get libfile]"
          my build-library [my define get libfile] [self]
        }

        # Process command line
        switch [lindex $argv 0] {
          install {
            # Ensure the library is compiled
            LIBRARY make depends library doc
          # Make do acts on all of the steps computed by
          # make depends
          LIBRARY make do
          # Project specific installation procedure
          }
          info {
            # Output information that integrators need
            set dat [LIBRARY target pkginfo]
            foreach {field value} $dat {
              puts [list $field: $value]
          }
          exit 0
          }
          teapot {
            # Ensure the library is compiled
            LIBRARY make depends library
          LIBRARY make do
          # Code to generate teapot distribution
          }
          default {
          # Work like a makefile and trigger build targets
          # Unlike a standard makefile "trigger" will re-kick
          # off any indicated steps
          LIBRARY make trigger {*}$argv
          LIBRARY make do
          }
        }


# More Info

*This is a work in progress.*


The Practcl module is now in Tcllib [Practcl project](https://core.tcl-lang.org/tcllib/doc/trunk/embedded/www/tcllib/files/modules/practcl/practcl.html).