[Tkabber-dev] r1077 - in trunk/tkabber: . contrib/starkit

tkabber-svn at jabber.ru tkabber-svn at jabber.ru
Sat Mar 31 22:15:44 MSD 2007


Author: sergei
Date: 2007-03-31 22:15:42 +0400 (Sat, 31 Mar 2007)
New Revision: 1077

Added:
   trunk/tkabber/contrib/starkit/README
Modified:
   trunk/tkabber/ChangeLog
   trunk/tkabber/contrib/starkit/main.tcl
Log:
	* contrib/starkit/main.tcl: Fixed usage of starkit::topdir variable,
	  requre Tk package because Linux tclkit doesn't require it by
	  default and forget zlib package to make it possible to use
	  compressed XMPP streams (thanks to Konstantin Khomoutov, Sergey
	  Yudin and Ruslan Rakhmanin).

	* contrib/starkit/README: Added README for those, who want to create
	  Tkabber starkits (thanks to Konstantin Khomoutov, Sergey Yudin and
	  Ruslan Rakhmanin).


Modified: trunk/tkabber/ChangeLog
===================================================================
--- trunk/tkabber/ChangeLog	2007-03-30 20:28:32 UTC (rev 1076)
+++ trunk/tkabber/ChangeLog	2007-03-31 18:15:42 UTC (rev 1077)
@@ -1,3 +1,15 @@
+2007-03-31  Sergei Golovan  <sgolovan at nes.ru>
+
+	* contrib/starkit/main.tcl: Fixed usage of starkit::topdir variable,
+	  requre Tk package because Linux tclkit doesn't require it by
+	  default and forget zlib package to make it possible to use
+	  compressed XMPP streams (thanks to Konstantin Khomoutov, Sergey
+	  Yudin and Ruslan Rakhmanin).
+
+	* contrib/starkit/README: Added README for those, who want to create
+	  Tkabber starkits (thanks to Konstantin Khomoutov, Sergey Yudin and
+	  Ruslan Rakhmanin).
+
 2007-03-30  Sergei Golovan  <sgolovan at nes.ru>
 
 	* splash.tcl, tkabber.tcl: Override bgerror even if splash screen is

Added: trunk/tkabber/contrib/starkit/README
===================================================================
--- trunk/tkabber/contrib/starkit/README	                        (rev 0)
+++ trunk/tkabber/contrib/starkit/README	2007-03-31 18:15:42 UTC (rev 1077)
@@ -0,0 +1,290 @@
+$Id$
+
+This file describes a sample startup script
+for Tkabber starkits/starpacks.
+
+
+I. Purpose.
+
+The "main.tcl" file is the "main startup script" for starkits; it is
+a Tcl script which task is to "bootstrap" the application wrapped in starkit.
+
+Although this script is a sample, it's ready, without any modifications,
+to be used for creation of a working starkit.
+
+Note that throughout this text the "starkit" term is used to refer to
+both Tkabber's starkits and starpacks since there is no difference between them
+in this context.
+
+
+II. Prerequisites.
+
+This scripts expects the starkit's VFS directory to be organised
+in this way:
+VFS_root_dir/ -- starkit's VFS root directory;
+  lib/        -- Tcl/Tk extensions (like BWidget);
+  tkabber/    -- Tkabber's code (tkabber.tcl must be placed here);
+  ...
+  main.tcl    -- the starkit startup script.
+
+
+III. How it works.
+
+Besides the usual starkit initialization which is described in [1], this
+script performs two major tasks:
+* Defines the "starkit_init" Tcl procedure;
+* Sources the main Tkabber script -- "tkabber.tcl".
+
+Tkabber checks if the Tcl command named "starkit_init" is present in the
+global namespace and executes it (without passing any arguments to it) if it
+exists. At the time of calling "starkit_init" several global Tkabber
+variables are guaranteed to exist:
+* "rootdir", which is set to the full pathname of the directory
+  containing the "tkabber.tcl" script;
+* "configdir", which holds the full pathname of the Tkabber's
+  user configuration directory;
+* "toolkit_version", which holds the Tcl interpreter version.
+Also the hooks subsystem is guaranteed to be initialized so that the
+"starkit_init" procedure could make use of Tkabber hooks.
+
+The purpose of the "starkit_init" procedure is to make some preparations
+before the bulk of the Tkabber code is loaded but after Tkabber managed
+to initialize some subsystems/variables which might be crucial for the
+proper initialization of the starkit. The "starkit_init" procedure in
+the "main.tcl" script discussed here performs the following steps:
+
+* Appends the " (starkit)" string to the "toolkit_version" variable.
+  This is done since the toolkit version is reported in response to the
+  XMPP iq:version request, so it helps Tkabber supporters to better
+  know a configuration a particular user runs.
+
+* "Forgets" about a Tcl package named "zlib" which is internal to
+  any tclkit and confuses Tkabber forcing it to think that the XMPP
+  stream compression can be used (which, in fact, requires another package --
+  "ztcl" -- which, in turn, provides another Tcl package named "zlib").
+
+* Looks into two special directories and sources all the files whose
+  names match the "*.kit" pattern. These directories are:
+  * The directory where the running starkit is located;
+  * The Tkabber's user configuration directory (held in the global
+    variable named "configdir").
+  This allows to bring some Tcl/Tk packages wrapped in starkits in.
+  Two popular starkits known to work with Tkabber's starkit are
+  img.kit (containing the Img package) [2] and the snack.kit (containing
+  the Snack sound kit package) [2].
+
+  If one or more of the kit files fail to load, a warning message with
+  collected error messages is shown to the user and the loading
+  process continues after the user dismisses this dialog.
+
+* Restores the "::starkit::topdir" variable which could be mangled by
+  external starkits.
+
+* Sources the main Tkabber's script "tkabber.tcl".
+
+So, the outline of Tkabber bootstrapping process looks like this:
+
+* "main.tcl" is sourced by the tclkit reading the Tkabber's starkit.
+* "main.tcl" creates the global "starkit_init" procedure and sources the
+  main Tkabber script, transferring control to Tkabber's code.
+* Tkabber performs some initialization steps, then finds the "starkit_init"
+  command and executes it, effectively "calling the starkit code out".
+* "starkit_init" does its initialization steps, possibly bringing some
+  external Tcl/Tk packages in, then gives control back to Tkabber.
+* Tkabber then continues with its loading as usually.
+
+
+IV. Differences between 0.10.0 and pre-0.10.0 starkits:
+
+Versions of Tkabber earlier that 0.10.0 had more limited support for
+starkits. Since 0.10.0 Tkabber has received some changes that allow to
+create fully-functional and customizable starkits without patching the
+Tkabber's code (as must have been done earlier).
+
+In short, the differences include:
+
+* The "rootdir" global variable is now initialized based on the actual
+  full pathname of the "tkabber.tcl" script, so that Tkabber's code
+  can now be located in an arbitrary directory in the starkit VFS.
+  Note though that the sample "main.tcl" does make its assumption about
+  where Tkabber's code is located.
+
+* Tkabber now "calls out" the starkit code in the course of its
+  initialization process which differs from the old way the things
+  worked when transferring the control to Tkabber's code was the
+  last thing the starkit's initialization code did.
+
+* The official Tkabber starkits/starpacks made a Tcl package from the
+  Tkabber's source tree. There were not much point to do so, that's why
+  the discussed "main.tcl" just sources the main Tkabber script now.
+
+
+V. Additional stuff.
+
+Ruslan Rakhmanin [3] has created a sample "Windows Tkabber starpack
+tool" which contains all necessary files to build a Tkabber starpack for
+Windows in the Windows environment (Windows 2000 and later is required).
+To build starpack using this tool you only need (recent) Tkabber sources.
+
+Also this starpack tool uses a modified tclkit which contains a full set
+of cp* Windows charsets (which original tclkits lack) thus providing
+the full support for non-Latin-1 alphabets.
+
+There's an article (written in Russian) on the official Tkabber wiki 
+describing this tool [4].
+
+A direct link to the RAR-archive containing this tool is [5].
+
+
+VI. Reference materials:
+
+1. http://wiki.tcl.tk/8186
+2. http://mini.net/sdarchive/
+3. xmpp:archimed at jabber.ru
+4. http://ru.tkabber.jabe.ru/index.php/Tkabber_starpack
+5. http://ru.tkabber.jabe.ru/images/ru.tkabber.jabe.ru/a/ad/Tkabber_win32_starpack_template.rar
+$Id$
+
+This file describes a sample startup script
+for Tkabber starkits/starpacks.
+
+
+I. Purpose.
+
+The "main.tcl" file is the "main startup script" for starkits; it is
+a Tcl script which task is to "bootstrap" the application wrapped in starkit.
+
+Although this script is a sample, it's ready, without any modifications,
+to be used for creation of a working starkit.
+
+Note that throughout this text the "starkit" term is used to refer to
+both Tkabber's starkits and starpacks since there is no difference between them
+in this context.
+
+
+II. Prerequisites.
+
+This scripts expects the starkit's VFS directory to be organised
+in this way:
+VFS_root_dir/ -- starkit's VFS root directory;
+  lib/        -- Tcl/Tk extensions (like BWidget);
+  tkabber/    -- Tkabber's code (tkabber.tcl must be placed here);
+  ...
+  main.tcl    -- the starkit startup script.
+
+
+III. How it works.
+
+Besides the usual starkit initialization which is described in [1], this
+script performs two major tasks:
+* Defines the "starkit_init" Tcl procedure;
+* Sources the main Tkabber script -- "tkabber.tcl".
+
+Tkabber checks if the Tcl command named "starkit_init" is present in the
+global namespace and executes it (without passing any arguments to it) if it
+exists. At the time of calling "starkit_init" several global Tkabber
+variables are guaranteed to exist:
+* "rootdir", which is set to the full pathname of the directory
+  containing the "tkabber.tcl" script;
+* "configdir", which holds the full pathname of the Tkabber's
+  user configuration directory;
+* "toolkit_version", which holds the Tcl interpreter version.
+Also the hooks subsystem is guaranteed to be initialized so that the
+"starkit_init" procedure could make use of Tkabber hooks.
+
+The purpose of the "starkit_init" procedure is to make some preparations
+before the bulk of the Tkabber code is loaded but after Tkabber managed
+to initialize some subsystems/variables which might be crucial for the
+proper initialization of the starkit. The "starkit_init" procedure in
+the "main.tcl" script discussed here performs the following steps:
+
+* Appends the " (starkit)" string to the "toolkit_version" variable.
+  This is done since the toolkit version is reported in response to the
+  XMPP iq:version request, so it helps Tkabber supporters to better
+  know a configuration a particular user runs.
+
+* "Forgets" about a Tcl package named "zlib" which is internal to
+  any tclkit and confuses Tkabber forcing it to think that the XMPP
+  stream compression can be used (which, in fact, requires another package --
+  "ztcl" -- which, in turn, provides another Tcl package named "zlib").
+
+* Looks into two special directories and sources all the files whose
+  names match the "*.kit" pattern. These directories are:
+  * The directory where the running starkit is located;
+  * The Tkabber's user configuration directory (held in the global
+    variable named "configdir").
+  This allows to bring some Tcl/Tk packages wrapped in starkits in.
+  Two popular starkits known to work with Tkabber's starkit are
+  img.kit (containing the Img package) [2] and the snack.kit (containing
+  the Snack sound kit package) [2].
+
+  If one or more of the kit files fail to load, a warning message with
+  collected error messages is shown to the user and the loading
+  process continues after the user dismisses this dialog.
+
+* Restores the "::starkit::topdir" variable which could be mangled by
+  external starkits.
+
+* Sources the main Tkabber's script "tkabber.tcl".
+
+So, the outline of Tkabber bootstrapping process looks like this:
+
+* "main.tcl" is sourced by the tclkit reading the Tkabber's starkit.
+* "main.tcl" creates the global "starkit_init" procedure and sources the
+  main Tkabber script, transferring control to Tkabber's code.
+* Tkabber performs some initialization steps, then finds the "starkit_init"
+  command and executes it, effectively "calling the starkit code out".
+* "starkit_init" does its initialization steps, possibly bringing some
+  external Tcl/Tk packages in, then gives control back to Tkabber.
+* Tkabber then continues with its loading as usually.
+
+
+IV. Differences between 0.10.0 and pre-0.10.0 starkits:
+
+Versions of Tkabber earlier that 0.10.0 had more limited support for
+starkits. Since 0.10.0 Tkabber has received some changes that allow to
+create fully-functional and customizable starkits without patching the
+Tkabber's code (as must have been done earlier).
+
+In short, the differences include:
+
+* The "rootdir" global variable is now initialized based on the actual
+  full pathname of the "tkabber.tcl" script, so that Tkabber's code
+  can now be located in an arbitrary directory in the starkit VFS.
+  Note though that the sample "main.tcl" does make its assumption about
+  where Tkabber's code is located.
+
+* Tkabber now "calls out" the starkit code in the course of its
+  initialization process which differs from the old way the things
+  worked when transferring the control to Tkabber's code was the
+  last thing the starkit's initialization code did.
+
+* The official Tkabber starkits/starpacks made a Tcl package from the
+  Tkabber's source tree. There were not much point to do so, that's why
+  the discussed "main.tcl" just sources the main Tkabber script now.
+
+
+V. Additional stuff.
+
+Ruslan Rakhmanin [3] has created a sample "Windows Tkabber starpack
+tool" which contains all necessary files to build a Tkabber starpack for
+Windows in the Windows environment (Windows 2000 and later is required).
+To build starpack using this tool you only need (recent) Tkabber sources.
+
+Also this starpack tool uses a modified tclkit which contains a full set
+of cp* Windows charsets (which original tclkits lack) thus providing
+the full support for non-Latin-1 alphabets.
+
+There's an article (written in Russian) on the official Tkabber wiki 
+describing this tool [4].
+
+A direct link to the RAR-archive containing this tool is [5].
+
+
+VI. Reference materials:
+
+1. http://wiki.tcl.tk/8186
+2. http://mini.net/sdarchive/
+3. xmpp:archimed at jabber.ru
+4. http://ru.tkabber.jabe.ru/index.php/Tkabber_starpack
+5. http://ru.tkabber.jabe.ru/images/ru.tkabber.jabe.ru/a/ad/Tkabber_win32_starpack_template.rar


Property changes on: trunk/tkabber/contrib/starkit/README
___________________________________________________________________
Name: svn:keywords
   + Author Date Id Revision
Name: svn:eol-style
   + native

Modified: trunk/tkabber/contrib/starkit/main.tcl
===================================================================
--- trunk/tkabber/contrib/starkit/main.tcl	2007-03-30 20:28:32 UTC (rev 1076)
+++ trunk/tkabber/contrib/starkit/main.tcl	2007-03-31 18:15:42 UTC (rev 1077)
@@ -1,21 +1,31 @@
 # $Id$
+# Sample startup file for the Tkabber starkit.
+# See README for details.
 
+# See: http://wiki.tcl.tk/8186
 package require starkit
 if {[string equal [starkit::startup] sourced]} return
 
 proc starkit_init {args} {
-    global configdir
-    global toolkit_version
-    upvar 1 starkit::topdir topdir
+    global configdir toolkit_version
+    variable starkit::topdir
 
+    # Linux tclkits don't load Tk themselves:
+    package require Tk
+
+    # Prevent bogus zlib package from confusing Tkabber
+    # (stream compression doesn't work in starkits using vanilla Tkabber):
+    package forget zlib
+
     append toolkit_version " (starkit)"
 
     set spath $configdir
-    if {[info exists ::starkit::topdir]} {
-	lappend spath [file dirname $::starkit::topdir]
+    if {[info exists topdir]} {
+	lappend spath [file dirname $topdir]
     }
 
-    # See: http://wiki.tcl.tk/8186
+    # Preserve the value of ::starkit::topdir before loading
+    # another starkits, see: http://wiki.tcl.tk/8186
     set top $topdir
 
     set log ""



More information about the Tkabber-dev mailing list