diff options
author | William Joye <wjoye@cfa.harvard.edu> | 2019-02-15 18:19:17 (GMT) |
---|---|---|
committer | William Joye <wjoye@cfa.harvard.edu> | 2019-02-15 18:19:17 (GMT) |
commit | b863b050cd0148499e6725724829e066890f518c (patch) | |
tree | 7828a9e8d84da3f73abe446fc50a9c0b0c11528a /tcllib/devdoc | |
parent | 7f1623e3f658b2dc4ddad0f1b9309a156de82065 (diff) | |
download | blt-b863b050cd0148499e6725724829e066890f518c.zip blt-b863b050cd0148499e6725724829e066890f518c.tar.gz blt-b863b050cd0148499e6725724829e066890f518c.tar.bz2 |
update tcllib
Diffstat (limited to 'tcllib/devdoc')
-rw-r--r-- | tcllib/devdoc/critcl-tcllib.txt | 116 | ||||
-rw-r--r-- | tcllib/devdoc/cvs.branches.fig | 32 | ||||
-rw-r--r-- | tcllib/devdoc/devguide.html | 50 | ||||
-rw-r--r-- | tcllib/devdoc/dirlayout_install.txt | 85 | ||||
-rw-r--r-- | tcllib/devdoc/indexing.txt | 418 | ||||
-rw-r--r-- | tcllib/devdoc/installation.txt | 85 | ||||
-rw-r--r-- | tcllib/devdoc/releaseguide.html | 72 |
7 files changed, 858 insertions, 0 deletions
diff --git a/tcllib/devdoc/critcl-tcllib.txt b/tcllib/devdoc/critcl-tcllib.txt new file mode 100644 index 0000000..d63b7d8 --- /dev/null +++ b/tcllib/devdoc/critcl-tcllib.txt @@ -0,0 +1,116 @@ +* Enhancing tcllib with CriTcl + + I have been looking into using critcl [http://wiki.tcl.tk.critcl] + to enhance some of the computationally intensive packages in + tcllib with compiled functions. The intention here is to provide + an alternative implementation for the 'hot-spots' in a package. In + the case of the uuencode package, for instance, we can provide + just the function that encodes or decodes a chunk of data. The + remainder of the package can be left in Tcl - which importantly + means that the public interface to the package remains identical. + + There is already some precedent for enhancing tcllib in this + way. Trf is used in the base64, md5 and sha1 packages to + optionally provide a compiled implementation of the + package. Importantly we still have a pure-tcl implementation. + + Provided that we accept that this hot-spot compilation strategy is + a good idea there is an issue to do with how the compiled code is + bundled. Critcl can build libraries or packages. Packages are the + same as libraries except that the library is placed into a + platform dependent subdirectory and a suitable pkgIndex file is + created. + + There are four main possibilities: + 1) library-per-package + 2) package-per-package + 3) package-per-module + 4) tcllib-c-package + +** library-per-package + a library is built for each critcl-enabled tcllib package. For + instance, 'critcl -lib uuencode.dll base64/uuencode.tcl'. This + doesn't generate any package loading tcl code and so doesn't + require a new package name. Instead the calling code will have to + handle loading the correct library. Once loaded the compiled + commands are available in the tcl namespace. For example, + ' load uuencode.tcl ; uuencode::CEncode abc ' + +** package-per-package + a compiled package is built for each critcl-enabled package. For + instance, 'critcl -pkg uuencode_c base64/uuencode.tcl'. This + builds the same library and for library-per-package but also + generates the package loading code. This requires a unique package + name (such as ${package}_c). + +** package-per-module + a compiled package is built for each tcllib module. For instance, + 'critcl -pkg base64c base64/base64c.tcl base64/uuencode.tcl + base64/yencode.tcl'. This collects all the critcl sections for a + module (which may contain a number of packages) into one library + and then creates the package loading code for this library. + +** tcllib-c-package + a compiled package is built for tcllib. This combines all the + critcl sections for all tcllib packages together in one + library. An advantage to this is that there is only one package + name and only one library. + + + +* Examples + +** library-per-package + + critcl -lib yencode.dll base64\yencode.tcl + critcl -lib uuencode.dll base64\uuencode.tcl + critcl -lib md4c.dll md4\md4c.tcl + critcl -lib md4c.dll md4\md4c.tcl + critcl -lib sum.dll crc\sum.tcl + + This gives us the named dll's in the current directory. For this case + I get (under Windows): + md4c.dll - 15,360 + md5c.dll - 15,360 + sum.dll - 12,800 + uuencode.dll - 13,312 + yencode.dll - 12,800 + +** package-per-package + + This creates libraries of the same size as library-per-package. + +** package-per-module + + critcl -libdir . -pkg base64c base64c\base64c.tcl base64\uuencode.tcl + base64\yencode.tcl + critcl -libdir . -pkg md4c md4\md4c.tcl + critcl -libdir . -pkg md5c md5\md5c.tcl + critcl -libdir . -pkg crc crc\crcc.tcl crc\sum.tcl + + This gives: + base64c.dll - 14,848 + crcc.dll - 12,800 + md4c.dll - 15,360 + md5c.dll - 15,360 + +** tcllib-c-package + + critcl -libdir . -pkg tcllibc <all the above> + tcllibc.dll - 19,968 + +* Conclusion + + We can see that the overhead of producing a dynamic library is + quite significant - at least for Windows. Building a library for + all 5 packages is only around 4000 bytes larger than the library + for a single package. There is also a cost involved in loading + each dynamic library as they have to be loaded from disk and + relocated in memory. Other concerns are the package namespace + pollution - by which I mean the proliferation of package names + caused by creating compiled packages for each tcllib package. Also + ease of loading - I don't really think abandoning the tcl package + mechanism is a good idea. + +Pat Thoyts + diff --git a/tcllib/devdoc/cvs.branches.fig b/tcllib/devdoc/cvs.branches.fig new file mode 100644 index 0000000..3c6f6a3 --- /dev/null +++ b/tcllib/devdoc/cvs.branches.fig @@ -0,0 +1,32 @@ +#FIG 3.2 +Landscape +Center +Inches +Letter +100.00 +Single +-2 +1200 2 +6 3000 2025 5400 2400 +4 0 12 50 0 0 14 0.0000 4 150 2385 3000 2175 Point releases are branched\001 +4 0 12 50 0 0 14 0.0000 4 150 1530 3000 2370 from RELEASES\001 +-6 +6 2400 750 5700 1200 +4 0 1 50 0 0 14 0.0000 4 195 3225 2400 900 Developer performs internal releases,\001 +4 0 1 50 0 0 14 0.0000 4 195 3285 2400 1095 merging from HEAD into RELEASES\001 +-6 +2 1 0 4 0 7 50 0 -1 0.000 0 0 7 1 0 2 + 2 1 4.00 240.00 480.00 + 300 600 5700 600 +2 1 0 2 1 7 50 0 -1 0.000 0 0 -1 1 0 2 + 2 1 2.00 120.00 240.00 + 2100 600 2400 1800 +2 1 0 5 12 7 50 0 -1 0.000 0 0 -1 1 0 3 + 2 1 5.00 300.00 600.00 + 2700 1800 3000 3000 5700 3000 +2 1 0 4 17 7 50 0 -1 0.000 0 0 7 1 0 3 + 2 1 4.00 240.00 480.00 + 1200 600 1500 1800 5700 1800 +4 0 0 50 0 0 14 0.0000 4 195 2835 3150 1575 Staging for release : RELEASES\001 +4 0 0 50 0 0 14 0.0000 4 195 1905 3900 300 Development : HEAD\001 +4 0 0 50 0 0 14 0.0000 4 150 930 4800 2700 Tcllib 1.2.0\001 diff --git a/tcllib/devdoc/devguide.html b/tcllib/devdoc/devguide.html new file mode 100644 index 0000000..c438ca4 --- /dev/null +++ b/tcllib/devdoc/devguide.html @@ -0,0 +1,50 @@ +<!- Guide for Tcllib developers --> + +<h1>Guide for Tcllib developers. +</h1> +<hr> + +<h2>CVS Repository +</h2> +<table><tr><td valign=top> + <!-- The local source of this image is + tcllib/devel/cvs.branches.* + --> + <img src="http://sourceforge.net/dbimage.php?id=2221"> +</td><td valign=top><p> + +The CVS repository for Tcllib contains two main branches, the HEAD for +development, and RELEASES as the staging area for official +releases. At RELEASES the minor branches containing the various +official releases are anchored at. +</p></td></tr></table> + +<p>All the branches are of interest to the developers for + Tcllib. Ongoing development happens in HEAD, which can be + unstable or may not work at all. Whenever a developer considers + a piece of code, or module, he is responsible for as + sufficiently stable she has to perform an internal release which + merges this part from HEAD into RELEASES. Tools to help with + this will be provided. +</p> + +<p>The branches for the official releases of tcllib are of interest to + a developer because it is expected that fixes for important bugs + not only go into the HEAD branch but also into the release + branches for the release they were found in and all releases + following that one. This is to allow the release manager to + create patch releases of existing releases distributing important + bugfixes as well. +</p> + +<p>Version numbers for modules are handled as described below. This + way of handling them was chosen so that the modules in the + development branch always uses version numbers different from + the version numbers in the official releases made so far. +</p> +<ul> +<li>Whenever an internal release of a module FOO is done, the + developer performing this internal release has to increment + the version number of the module <b>after</b> the release was + executed. +</ul> diff --git a/tcllib/devdoc/dirlayout_install.txt b/tcllib/devdoc/dirlayout_install.txt new file mode 100644 index 0000000..8cacea0 --- /dev/null +++ b/tcllib/devdoc/dirlayout_install.txt @@ -0,0 +1,85 @@ +Tcllib installation directory layout +==================================== + +This document describes the possible layouts for an installed tcllib, +discusses their pro and contra and makes a choice for Tcllib 1.4. A +roadmap of changes in the future is made available as appendix. + +[L1/D] Deep layout +------------------ + + This is the layout of Tcllib 1.3 (and versions before that). + + A single directory tcllib<version> is created, and all + subdirectories of the 'modules' subdirectory in the + distribution is copied into it. This is restricted at large to + *.tcl files, with exception made for some modules with special + needs. + + Pro: + Contra: + Makes the handling of the various package indices, + well, not difficult, but uncomfortable. + + +[L2/Fa] Flat layout 1 +--------------------- + + A directory is created for each module of tcllib. + + Pro: + Handling of package indices is easier than for L1/D, a + toplevel index file with all its problems is not + required anymore. + + Contra: + Directories should be versioned to avoid conflicts + between multiple releases. modules have no + version. This can be faked for modules containing one + package, but not for the modules with more. + + +[L2/Fb] Flat layout 2 +--------------------- + + A directory is created for each package in tcllib. + + Pro + Handling of package indices is easy, one per package. + + Contra: + Modules containing more than one package are difficult + to handle. The system has to split them into the + individual packages. This rendered very difficult + because of shared package index files. + + This can be solved by moving tcllib (back) towards of + one package per module. When that goal is reached + L2/Fa and L2/Fb become the same, and the contra for + L2/Fa vanishes too as an exact version number can be + associated with each directory. + +Chosen layout for Tcllib 1.4 +---------------------------- + + L1/D + + Despite the problems with package indices the contras against + the flat structures are too strong at this point in + time. Automatic solutions are not really possible, or require + a very high effort. + +Roadmap +------- + Change the module directories of tcllib to contain exactly one + package per directory, with appropriate index (and meta data). + + This not only makes sense for easier handling of installation + and package indices, but also in the greater context of + wrapping code for deployment. + + +----------------------------------- +This document is in the public domain. + + Andreas Kupries <andreas_kupries@users.sf.net> diff --git a/tcllib/devdoc/indexing.txt b/tcllib/devdoc/indexing.txt new file mode 100644 index 0000000..ddc501a --- /dev/null +++ b/tcllib/devdoc/indexing.txt @@ -0,0 +1,418 @@ +Tcllib package indexing +======================= + +This document describes the possibilities for using one or more +pkgIndex.tcl files in an installation of tcllib to provide the +information about all of its packages to a tcl interpreter, discusses +their pro and contra and makes a choice for Tcllib 1.4. A roadmap of +changes in the future is made available as an appendix. + +Background under which to see the solutions: + + There are three level of groupings: + + - The tcllib project itself + - Modules in the project (== subdirectory of 'modules') + - Packages in a module. + + Each module currently contains one package index file. + + Some modules contain more than one package. They share the index. + + Most packages require specific versions of the Tcl + interpreter. They perform the checks in their package index + file and do not register if the pre-requisites are not + fulfilled. + + Other checks are possible, but currently not in use. + +Note I: + Whether a solution is actually applicable depends on external + factors, like the chosen directory layout of an installed + tcllib. + +Note II: + All solutions currently depend on the specific implementation + of [tclPkgUnknown] coming with the basic core, simply by the + fact that the files looked at are called 'pkgIndex.tcl'. This + is therefore no contra argument against any specific solution, + but against all. We ignore this as currently there is no + better replacement in existence. + +Note III: + We have to support Tcl before 8.3. as some packages in tcllib + allow this. + + +[i1/ng] No global package index +------------------------------- + + In this solution the module package indices are the only index + files present in an installation. + + This solution is applicable if and only if one of the flat + directory layouts (L2/Fa or L2/Fb) has been chosen. + + Pro: + Simple. No need for complex management. + + +[i2/ad] Global package index, auto_path extension, direct +--------------------------------------------------------- + + A single global package index is present in the toplevel + directory of the installation. + + This solution is applicable if and only if the deep directory + layout (L2/D) has been chosen. + + The package index contains a series of statements extending + the auto_path variable with all module directories. The list + of names of the module directories is hardcoded. In other + words, it is _not_ determined via [glob]. + + Example: + lappend auto_path [file join $dir md4] + lappend auto_path [file join $dir md5] + lappend auto_path [file join $dir sha1] + ... + + + Pro: + [[0]] Compared to [i3/ag] this should be bit faster + as glob'ing the directory tree of tcllib is + avoided. This performance-boost is not a big + pro according to the opinions below. + + [[1]] Relies on the module package index files for + the actual registration of packages, thus + automatically inherits the correct constraints + on the registration of packages. No additional + complexities. + + [[2]] Easier to generate than [i6/dr]. + + Contra: + [[3]] Hard coding the directory names implies that + adding modules to the installed tcllib is not + as easy as just creating a new directory for + the module/package. The global index has to be + updated too. + + Contra-Contra: + <<Don: New, updated packages should be + installed separately, outside of + tcllib. The ticked version number + ensures that it is prefered over the + package in tcllib.>> + + <<AK: Agree fully>> + + [[4]] Extending the 'auto_path' list causes the + package management of the tcl core to re-read + the list and glob through all of them for new + package indices. This has a high cost in terms + of filesystem access, i.e. is an issue of + performance. + + Contra-Contra: + <<Don: IMHO, it's not really tcllib's + job to fix [tclPkgUnknown]'s + performance problems. If performance + is a problem, users could try the + patch with Tcl Feature Request 680169 + and see if it helps.>> + + <<AK: Not sure yet about this>> + + + [[5]] This enables auto-loading in each module + (according to any tclIndex file installed). + This should not be done by the package + indexer, but by the package itself. See + control for an example. + + [[10]] Will not work with Tcl releases prior to + 8.3.1. Only then was [tclPkgUnknown] + "enhanced" to deal with changing ::auto_path + values. If tcllib 1.4 wishes to continue + supporting pre-8.3.1 Tcl, then this option has + to be supplemented with a fallback. + + +[i3/ag] Global package index, auto_path extension, glob +------------------------------------------------------- + + This is like [i2/ad], except that the list of sub directories + is not hardcoded into the index, but determined through glob. + + Example: + foreach subdir [glob -nocomplain -type d $dir/*] { + lappend auto_path $subdir + } + + Pro: + Anti-[[3]] + [[1]] + + Contra: + All the contras of [i2/ad] and Anti-[[0]]. + + +[i4/sd] Global package index, sourcing module indices, direct +------------------------------------------------------------- + + A single global package index is present in the toplevel + directory of the installation. + + This solution is applicable if and only if the deep directory + layout (L2/D) has been chosen. + + The package index contains a series of statements source'ing + the package index files of the modules in tcllib. The list + of names of the module directories is hardcoded. In other + words, it is _not_ determined via [glob]. + + Example: + set main $dir + set dir [file join $main md4] ; source [file join $dir pkgIndex.tcl] + set dir [file join $main md5] ; source [file join $dir pkgIndex.tcl] + set dir [file join $main sha1] ; source [file join $dir pkgIndex.tcl] + ... + + Pro: + [[0]], but compared to [i5/sg]. + [[1]] + [[2]] + [[6]] In contrast to [i2/ad] and [i3/ag] repeated + glob'ing for package index files is + avoided. This cuts down on costly FS accesses. + I.e. another perf. boost. + + Contra: + [[3]] + +[i5/sg] Global package index, sourcing module indices, glob +----------------------------------------------------------- + + This is like [i4/sd], except that the list of package indices + to source is not hardcoded into the index, but determined + through glob. + + Example: + foreach subdir [glob -nocomplain -type d $dir/*] { + set dir $subdir + source [file join $dir pkgIndex.tcl] + } + + Pro: + Anti-[[3]] + [[1]] + [[2]] + + Contra: + All the contras of [i2/sd], and Anti-[[0]] + + +[i6/dr] Global package index, direct registration +------------------------------------------------- + + A single global package index is present in the toplevel + directory of the installation. + + This solution is applicable if and only if the deep directory + layout (L2/D) has been chosen. + + The package index contains a series of statements which + directly register all the tcllib packages. + + Example: + if {[constraint]} {return} + package ifneeded md4 [list source [file join $dir md4 md4.tcl]] + package ifneeded md5 [list source [file join $dir md4 md4.tcl]] + package ifneeded sha1 [list source [file join $dir md4 md4.tcl]] + ... more constraints ... package ifneeded + + Pro: + [[7]] This is the fasted solution as the number of + accesses to the filesystem is minimal. + + Contra: + [[[3]] + Anti-[[1]] Care has to be taken to ensure that + the constraints the module indices + place on the registration of packages + are replicated in the global + index. All other solutions simply used + the module indices and thus got it + right automatically. Now supporting + code is required to detect such + constraints and then to properly + recreate them globally. + + = High complexity for the maintainer. + +[i7/ad] Global package index, auto_path extension, direct +--------------------------------------------------------- + + A single global package index is present in the toplevel + directory of the installation. + + This solution is applicable if and only if the deep directory + layout (L2/D) has been chosen. + + The package index contains a single statement extending the + auto_path variable with the tcllib main directory. The + standard package management will then find all module sub + directories and the package indices in them. + + Example: + lappend auto_path $dir + + Pro: + [[1]] + [[8]] This is the easiest solution by far in terms + of code to write, and complexities to solve + (none). + + [[9]] <<Don: I believe this is the only proposal listed + that actually fixes tcllib Bug 720318 + (successful [package require] of packages + within a SafeBase) because it is the only one + that changes the value of ::auto_path.>> + + <<AK: This is true, yet brittle. It depends on + when the SafeBase sees the auto_path. If it + happens to be before a [package require + something] forced the reading of all package + indices (and thus the extension of + 'auto_path') we are still SOL.>> + + Contra: [[4]] + [[10]] + + +[i8/pm] Global package index, pkg_mkIndex +----------------------------------------- + +Just use [pkg_mkIndex modules */*.tcl] to generate the master index. + + Pro: + Easy to do. + + Contra: + Does not handle constraints in subordinate package + indices, simply because they are actually ignored + during processing. + + Adding code to handle constraints evolves this into + [i6/dr]. + + Note: The contra is hard enough IMHO to make this solution not + applicable for 1.4, which does have constraints, and handling + them wrong (not at all) is a bug. + + +General discussion +------------------ + +Given that a deep directory layout was chosen [i1/ng] is not +applicable and therefore dropped from the discussion. + +In the pro and contra arguments listed above three independent axes of +reasoning emerged: + +a) Performance of the solution, with the number of accesses to + filesystem the main factor determining it. + +b) Complexity/difficulty of the solution with regard to + adding/updating packages. + +c) Complexity of generating the master index. + +Axis (b) has essentially been thrown out. Trying to modify the +installation of tcllib itself is bad practice. Install new/updated +packages separately. The version numbering takes care of the rest, +i.e. usage of the new over the older version found in tcllib. + +With respect to axis (c), complexity of generation, [i7/ad] is the +definite winner, with the other *d solutions close behind (all use +fixed scripts, I7/ad wins on size). This is followed by the *g +solutions as they require actual dynamic generation of code. And at +the bottom of the ladder is [i6/dr] with its need for close inspection +of the sub-ordinate indices to get everything right. + +Now axis (a), performance, [i6/dr] is most likely the winner as it +causes only one index to be read and nothing else. This is followed by +the all *d solutions, which read the subordinate indices, but do not +need much glob'ing. The actual order in this group is difficult to +determine. I guess that the auto_path extending methods are slower +than the sourcing methods, and the adding of one directory faster than +the adding of all, as the latter looks for much more subdirectories. +The next group are the *g solutions as they perform their own glob'ing too +beyond that done by the package mgmt. + +Two final rankings + + (c), then (a) (a), then (c) + ------------- ------------- + [i7/ad] [i6/dr] + [i4/sd] [i4/sd] + [i2/ad] [i7/ad] + [i5/sg] [i2/ad] + [i3/ag] [i5/sg] + [i6/dr] [i3/ag] + ------------- ------------- + +[i4/sd] seems to be a good compromise solution between performance and +complexity of generation, but [i7/ad] is not too bad either. + +[i4/sd] reminder: + set main $dir + set dir [file join $main md4] ; source [file join $dir pkgIndex.tcl] + set dir [file join $main md5] ; source [file join $dir pkgIndex.tcl] + set dir [file join $main sha1] ; source [file join $dir pkgIndex.tcl] + ... + +[i7/ad] reminder: + lappend auto_path $dir + +Other opinions: + + Don Porter prefers [i7/ad], and [i6/dr] as second choice. Also + as [i7/ad] fallback for older Tcl before 8.3.1 + + Joe English strictly opposes any solution modifying the + auto_path, violating his opinion that index scripts should + have no side-effects beyond registering a package. + + +Chosen solution for Tcllib 1.4 +------------------------------ + +After comparing the code for the combination of [i7/ad] and [i6/dr] as +submitted by Don Porter, and for [i4/sd] as submitted by myself +(Andreas), and a small discussion on the Tcl'ers chat between Don and +me, we took [i4/sd] for the main body of the index, and the header of +Don's code. Basically the chosen package index is a combination of +[i7/id] and of [i4/sd] as fallback. + +This is still as easy to generate as [4/sd], the index is also only a +bit more complex, and speed should be okay too. + +Don convinced me that while extending auto_path is definitely bad in +the long-term it is still okay for the short-term and release 1.4. + + +Roadmap +------- + +After Tcllib has been driven into the state of one package per module +directory, and switched to a flat directory layout for its +installation we switch to [i1/ng] for the indexing structure. + + +----------------------------------- +This document is in the public domain. + + Andreas Kupries <andreas_kupries@users.sf.net> diff --git a/tcllib/devdoc/installation.txt b/tcllib/devdoc/installation.txt new file mode 100644 index 0000000..e8b95b7 --- /dev/null +++ b/tcllib/devdoc/installation.txt @@ -0,0 +1,85 @@ +Tcllib installation directory layout +==================================== + +This document describes the possible layouts for an installed tcllib, +discusses their pro and contra and makes a choice for Tcllib 1.4. A +roadmap of changes in the future is made available as appendix. + +[L1/D] Deep layout +------------------ + + This is the layout of Tcllib 1.3 (and versions before that). + + A single directory tcllib<version> is created, and all + subdirectories of the 'modules' subdirectory in the + distribution is copied into it. This is restricted at large to + *.tcl files, with exception made for some modules with special + needs. + + Pro: + Contra: + Makes the handling of the various package indices, + well, not difficult, but uncomfortable. + + +[L2/Fa] Flat layout 1 +--------------------- + + A directory is created for each module of tcllib. + + Pro: + Handling of package indices is easier than for L1/D, a + toplevel index file with all its problems is not + required anymore. + + Contra: + Directories should be versioned to avoid conflicts + between multiple releases. modules have no + version. This can be faked for modules containing one + package, but not for the modules with more. + + +[L2/Fb] Flat layout 2 +--------------------- + + A directory is created for each package in tcllib. + + Pro + Handling of package indices is easy, one per package. + + Contra: + Modules containing more than one package are difficult + to handle. The system has to split them into the + individual packages. This rendered very difficult + because of shared package index files. + + This can be solved by moving tcllib (back) towards of + one package per module. When that goal is reached + L2/Fa and L2/Fb become the same, and the contra for + L2/Fa vanishes too as an exact version number can be + associated with each directory. + +Chosen layout for Tcllib 1.4 +---------------------------- + + L2/D + + Despite the problems with package indices the contras against + the flat structures are too strong at this point in + time. Automatic solutions are not really possible, or require + a very high effort. + +Roadmap +------- + Change the module directories of tcllib to contain exactly one + package per directory, with appropriate index (and meta data). + + This not only makes sense for easier handling of installation + and package indices, but also in the greater context of + wrapping code for deployment. + + +----------------------------------- +This document is in the public domain. + + Andreas Kupries <andreas_kupries@users.sf.net> diff --git a/tcllib/devdoc/releaseguide.html b/tcllib/devdoc/releaseguide.html new file mode 100644 index 0000000..1fd086c --- /dev/null +++ b/tcllib/devdoc/releaseguide.html @@ -0,0 +1,72 @@ +<!- Guide to the creation of source releases for Tcllib --> + +<h1>Guide to the creation of source releases for Tcllib +</h1> +<hr> + +<h2>Recap +</h2> +<table><tr><td valign=top> + <!-- The local source of this image is + tcllib/devel/cvs.branches.* + --> + <img src="http://sourceforge.net/dbimage.php?id=2221"> +</td><td valign=top><p> +The CVS repository for Tcllib contains two main branches, + the HEAD for development, and RELEASES as the staging area for + official releases. +</p></td></tr></table> + +<h2>Dependencies +</h2> + +<h2>Creation of a new official release +</h2> + +<p>To create a new official release of Tcllib the release manager has + to perform the steps described below: +</p> + + +<ol> +<li> Retrieve the sources at the current head + from the CVS repository, using a command like +<pre> + CVSROOT=:pserver:anonymous@cvs.tcllib.sourceforge.net:/cvsroot/tcllib + cvs -d${CVSROOT} co tcllib +</pre> + Vary this command according to taste as long as the overall + meaning is not changed. Compression options and the like. + +<li> Tag these sources with a new branch tag for the new release of + tcllib, like +<pre> + cvs -d${CVSROOT} rtag tcllib +</pre> + +<li> Commit the changes, then update the working directory. + +<li> Use a tclsh to run the <b>sak</b> tool with the argument <i>gendist</i>, like +<pre> + tclsh /path/to/tcllib/sak.tcl gendist +</pre> + +<li> This results in the creation of a <i>tcllib-VERSION</i> directory +in the current working directory, and of two archives, <i>.zip</i>, +and <i>.tar.gz</i>. A starkit will be created if <b>sdx</b> is present +in the PATH. If additionally a file named <b>tclkit</b> is present in +the current working directory a starpack will be created too, using +this tclkit as the runtime. + + +<li> Now follow the instructions in the Sourceforge site documentation + for uploading the archives generated by the last + step to + <b>ftp://upload.sourceforge.net/incoming</b>, and + follow the procedures for creating packages and + releases at Sourceforge. +</ol> + +<p>At last notify the relevant persons in other communities like +Debian (See list of contacts) about the new release. +</p> |