Artifact [17b19243e2]

Artifact 17b19243e2996beee616890d2cf051e13c24390f:

Wiki page [KitCreator] by rkeene on 2010-10-21 13:04:06.
D 2010-10-21T13:04:06
L KitCreator
P fe3e885b9ebf129f400a33680ac5730525b0ea55
U rkeene
W 21150
<i>Tclkit Building Made Trivial</i>

<p>KitCreator is a simple build system for creating a <a href="http://www.equi4.com/tclkit/">Tclkit</a>.  It was created to ease creation of Tclkits.  If you just want to use Tcl on your platform, it is recommended that you use a <a href="http://www.equi4.com/tclkit/download.html">pre-existing Tclkit</a>.  See also locally built pre-built <a href="http://rkeene.org/projects/info/wiki/Tclkits">Tclkits</a>.</p>

<p>A <a href="http://www.equi4.com/tclkit/">Tclkit</a> is, briefly, a single-file executable that contains Tcl (both the interpreter, and all the resources it requires to operate) and other Tcl-related packages (Tk, Incr Tcl, etc).  A tclkit can be used to create a <i>Starpack</i>, which is the Tclkit plus the resources required for your Tcl-based application in a single file.  This makes application delivery easy and consistent as it will be a single file that the user runs to use the application.  Additionally, since a Tclkit is generic, any Tclkit from any platform can be used as the base for a Starpack.  That is, from GNU/Linux you can take the Tclkit for AIX and add your application to produce a native executable for AIX.</p>

<p>KitCreator can create a library that provides the Tcl (and optionally Tk) API for a system.  This is called KitDLL.  The library has all of the support files embedded into it.  The library's virtual filesystem can be extended by appending a zip file to it.  It can also be extended by appending a zip file to the application itself.</p>

<p>KitCreator can be used to cross-compile a Tclkit, however you may need to have a working Tclkit for your native system first.  KitCreator can be used to create this local boot-strap Tclkit.</p>

<p>Download:
  <ul>
    <li>
      Current Release, Version <b>0.5.2.acfbaa597c</b>
      <ul>
        <li><a href="http://www.rkeene.org/devel/kitcreator-0.5.2.acfbaa597c.tar.gz">Download Source Code</a></li>
        <li><a href="http://www.rkeene.org/devel/kitcreator/kitbuild/0.5.2.acfbaa597c/">Build Log</a></li>
        <li><a href="dir?ci=0.5.2">Browse Source Repository</a></li>
      </ul>
    </li>
    <li>
      Previous Generation Release, Version <b>0.4.0.2408</b>
      <ul>
        <li><a href="http://www.rkeene.org/devel/kitcreator-0.4.0.2408.tar.gz">Download Source Code</a></li>
        <li><a href="http://www.rkeene.org/devel/kitcreator/kitbuild/0.4.0.2408/">Build Log</a></li>
        <li><a href="dir?ci=0.4.0">Browse Source Repository</a></li>
      </ul>
    </li>
  </ul>
</p>

<hr>

<p>
  <b>Some examples:</b>
  <ol type="1">
    <li>Create a Tclkit:
      <ol type="a">
        <li><tt>$ ./kitcreator</tt></li> 
      </ol>
    </li> 
    <li>Create a Tclkit for Tcl 8.5.9:
      <ol type="a">
        <li><tt>$ ./kitcreator 8.5.9</tt></li> 
      </ol>
    </li> 
    <li>Create a Tclkit for Tcl from CVS HEAD:
      <ol type="a">
        <li><tt>$ ./kitcreator cvs_HEAD</tt></li> 
      </ol>
    </li> 
    <li>Compile a 64-bit Tclkit:
      <ol type="a">
        <li><tt>$ ./kitcreator --enable-64bit</tt></li> 
      </ol>
    </li> 
    <li>Cross-compile a Tclkit:
      <ol type="a">
        <li>Bootstrap (optional, you can use an existing Tclkit):
          <ol type="i">
            <li><tt>$ ./kitcreator</tt></li> 
            <li><tt>$ mv tclkit-8.4.19 tclkit-local</tt></li> 
            <li><tt>$ TCLKIT=&quot;$(pwd)/tclkit-local&quot;</tt></li> 
            <li><tt>$ export TCLKIT</tt></li> 
          </ol>
        </li> 
        <li>Cross-compile:
          <ol type="i">
            <li><tt>$ CC=mipsel-linux-uclibc-gcc</tt></li> 
            <li><tt>$ CXX=false</tt></li> 
            <li><tt>$ AR=mipsel-linux-uclibc-ar</tt></li> 
            <li><tt>$ RANLIB=mipsel-linux-uclibc-ranlib</tt></li> 
            <li><tt>$ export CC CXX AR RANLIB</tt></li> 
            <li><tt>$ ./kitcreator --host=mipsel-linux-uclibc</tt></li> 
          </ol>
        </li>
      </ol>
    </li>
    <li>Compile a 64-bit Tclkit 8.5.8 using SunStudio 12.1 on Solaris/x86:
      <ol type="a">
        <li><tt>$ CC='/opt/sunstudio12.1/bin/cc -m64'</tt></li> 
        <li><tt>$ CXX='/opt/sunstudio12.1/bin/CC -m64'</tt></li> 
        <li><tt>$ PATCH='gpatch'</tt></li> 
        <li><tt>$ export CC CXX PATCH</tt></li> 
        <li><tt>$ ./kitcreator 8.5.8 --enable-64bit</tt></li> 
      </ol>
    </li> 
    <li>To clean up post-build:
      <ol type="a">
        <li><tt>$ ./kitcreator clean</tt></li> 
      </ol>
    </li> 
    <li>Create a Tclkit without Metakit4 support (falls back to Zip for storage):
      <ol type="a">
        <li><tt>$ KITCREATOR_PKGS='tk itcl'</tt></li> 
        <li><tt>$ export KITCREATOR_PKGS</tt></li> 
        <li><tt>$ ./kitcreator</tt></li> 
      </ol>
    </li> 
    <li>Create a Tclkit with Metakit4 support, but using Zip for storage:
      <ol type="a">
        <li><tt>$ ./kitcreator --enable-kit-storage=zip</tt></li>
      </ol>
    </li>
    <li>Create a KitDLL without Metakit support (will not create a Tclkit binary, just the library):
      <ol type="a">
        <li><tt>$ KITCREATOR_PKGS='tk itcl kitdll'</tt></li> 
        <li><tt>$ export KITCREATOR_PKGS</tt></li> 
        <li><tt>$ ./kitcreator</tt></li> 
      </ol>
    </li>

  </ol>
</p>

<hr>

<p class="kitcreator_longtext">
<b>Method of Operation</b>

<i>Details:</i> The general mechanism that enables a Tclkit to operate is a small Tcl initialization routine linked statically to the core libraries needed to operate a Tcl interpreter, the Tcl VFS Layer, and a database-backed (Metakit) Virtual File System that is appended to the end of the executable.</p><p>This project brings together all of the required pieces, plus some additional pieces that were found in the original Tclkit:
  <ol type="1">
    <li>Tk (dynamically linked)</li> 
    <li>Itcl (dynamically linked)</li>
  </ol>
The source code for these pieces are downloaded, compiled, and linked, and the database containing the appropriate filesystem data is created.  What sets this project apart from other similar projects is that:
  <ol type="1">
    <li>It attempts to be modular;</li> 
    <li>It supports cross-compiling;</li> 
    <li>It downloads the source from their original repositories;</li> 
    <li>It allows you to specify an arbitrary version of Tcl (including CVS); and</li> 
    <li>It uses GNU Autoconf scripts for compiling the part of the Tclkit that brings the whole thing together (the Kitsh)</li>
  </ol>
To accomplish these goals the following mechanisms are in place:
  <ol type="1">
    <li>The top-level "kitcreator" script; and</li> 
    <li>Per-project subdirectories, each containing a "build.sh" script</li>
  </ol>

The top-level "kitcreator" script is very simple.  Its only job is to interpret command line arguments, and call the per-project "build.sh" scripts. For the "tcl" project it also finds the appropriate "tclConfig.sh" (and stores this path in TCLCONFIGDIR) to enable subsequent build scripts to find the appropriate Tcl to link against.

The per-project "build.sh" scripts are entirely autonomous.  They are responsible for downloading the source code for the appropriate version that will compile and link against the current version of Tcl (user requested version can be found in "TCLVERS", while the actual version must be requested from the "tclConfig.sh" script), compiling it, installing a functional copy into the per-project "inst" directory, and installing anything that needs to be in the Tclkit's VFS root into the per-project "out" directory.

The exception to this is the "kitsh" project.  It is the glue that binds all the individual projects together into a single executable.  Its build script does not create an "inst" or an "out" directory because it is not a library. Instead, it collects all the other project's "out" directories into a single directory (starpack.vfs), as well a static file (boot.tcl).  It then compiles the source code, and then installs the Metakit database containing the VFS onto the resulting executable.

If the "mk4tcl" project fails to build (or is not requested to be built), the rest of the project will be built using zip files instead of Metakit databases.

To create the storage database, one of two Tclkits is used (tried in this order):
  <ol type="1">
    <li>The Tclkit specified by the TCLKIT environment variable (or "tclkit" if that variable is not set) if it is functional; or</li> 
    <li>The built Tclkit itself</li>
  </ol>
The second method will not work if the built Tclkit is not executable on the current platform (i.e., in the case of cross-compilation) and so it may be necessary to bootstrap a runnable Tclkit first.
</p>

<hr>

<p><b>Included Packages</b></p><table cellspacing=0 cellpadding=0 summary='' class=wikit_table><tr class='wikit_table_header'><th class="wikit_table_header_cell"> Package Name </th><th class="wikit_table_header_cell"> Package Version </th><th class="wikit_table_header_cell"> Included When...   </th><th class="wikit_table_header_cell"> Linking Method </th></tr><tr class='wikit_table_row_even'><td class="wikit_table_row_cell"> Tk           </td><td class="wikit_table_row_cell"> <i>same as Tcl</i> </td><td class="wikit_table_row_cell"> Always             </td><td class="wikit_table_row_cell"> Dynamic        </td></tr><tr class='wikit_table_row_odd'><td class="wikit_table_row_cell"> Incr Tcl     </td><td class="wikit_table_row_cell"> 3.4b1           </td><td class="wikit_table_row_cell"> Always             </td><td class="wikit_table_row_cell"> Dynamic        </td></tr><tr class='wikit_table_row_even'><td class="wikit_table_row_cell"> starkit      </td><td class="wikit_table_row_cell"> 1.3.2           </td><td class="wikit_table_row_cell"> Always             </td><td class="wikit_table_row_cell"> Static         </td></tr><tr class='wikit_table_row_odd'><td class="wikit_table_row_cell"> Metakit      </td><td class="wikit_table_row_cell"> 2.4.9.7         </td><td class="wikit_table_row_cell"> Always             </td><td class="wikit_table_row_cell"> Static         </td></tr><tr class='wikit_table_row_even'><td class="wikit_table_row_cell"> TclVFS       </td><td class="wikit_table_row_cell"> 20080503        </td><td class="wikit_table_row_cell"> Always             </td><td class="wikit_table_row_cell"> Static         </td></tr><tr class='wikit_table_row_odd'><td class="wikit_table_row_cell"> PWB          </td><td class="wikit_table_row_cell"> 1.1             </td><td class="wikit_table_row_cell"> Always             </td><td class="wikit_table_row_cell"> Static         </td></tr><tr class='wikit_table_row_even'><td class="wikit_table_row_cell"> Rechan       </td><td class="wikit_table_row_cell"> 1.0             </td><td class="wikit_table_row_cell"> Always             </td><td class="wikit_table_row_cell"> Static         </td></tr><tr class='wikit_table_row_odd'><td class="wikit_table_row_cell"> Zlib         </td><td class="wikit_table_row_cell"> 1.1             </td><td class="wikit_table_row_cell"> Always             </td><td class="wikit_table_row_cell"> Static         </td></tr><tr class='wikit_table_row_even'><td class="wikit_table_row_cell"> Thread       </td><td class="wikit_table_row_cell"> 2.6.5           </td><td class="wikit_table_row_cell"> --enable-threads   </td><td class="wikit_table_row_cell"> Dynamic        </td></tr><tr class='wikit_table_row_odd'><td class="wikit_table_row_cell"> Registry     </td><td class="wikit_table_row_cell"> <i>varies</i>      </td><td class="wikit_table_row_cell"> Building for Win32 </td><td class="wikit_table_row_cell"> Static         </td></tr><tr class='wikit_table_row_even'><td class="wikit_table_row_cell"> DDE          </td><td class="wikit_table_row_cell"> <i>varies</i>      </td><td class="wikit_table_row_cell"> Building for Win32 </td><td class="wikit_table_row_cell"> Static         </td></tr><tr class='wikit_table_row_odd'><td class="wikit_table_row_cell"> http         </td><td class="wikit_table_row_cell"> <i>varies</i>      </td><td class="wikit_table_row_cell"> Always             </td><td class="wikit_table_row_cell"> Static         </td></tr><tr class='wikit_table_row_even'><td class="wikit_table_row_cell"> opt          </td><td class="wikit_table_row_cell"> <i>varies</i>      </td><td class="wikit_table_row_cell"> Always             </td><td class="wikit_table_row_cell"> Static         </td></tr><tr class='wikit_table_row_odd'><td class="wikit_table_row_cell"> msgcat       </td><td class="wikit_table_row_cell"> <i>varies</i>      </td><td class="wikit_table_row_cell"> Always             </td><td class="wikit_table_row_cell"> Static         </td></tr><tr class='wikit_table_row_even'><td class="wikit_table_row_cell"> tcltest      </td><td class="wikit_table_row_cell"> <i>varies</i>      </td><td class="wikit_table_row_cell"> Unless MINBUILD    </td><td class="wikit_table_row_cell"> Static         </td></tr></table><hr><p><b>Tested Platforms</b></p><table cellspacing=0 cellpadding=0 summary='' class=wikit_table><tr class='wikit_table_header'><th class="wikit_table_header_cell"> Operating System </th><th class="wikit_table_header_cell"> CPU Architecture </th><th class="wikit_table_header_cell"> Tcl Version </th><th class="wikit_table_header_cell"> Compiler </th><th class="wikit_table_header_cell"> Cross-compile </th></tr><tr class='wikit_table_row_odd'><td class="wikit_table_row_cell"> Linux 2.6   </td><td class="wikit_table_row_cell"> x86     </td><td class="wikit_table_row_cell"> 8.4.19   </td><td class="wikit_table_row_cell"> gcc 4.1.2         </td><td class="wikit_table_row_cell"> no </td></tr><tr class='wikit_table_row_even'><td class="wikit_table_row_cell"> Linux 2.6   </td><td class="wikit_table_row_cell"> x86     </td><td class="wikit_table_row_cell"> 8.5.8    </td><td class="wikit_table_row_cell"> gcc 4.1.2         </td><td class="wikit_table_row_cell"> no </td></tr><tr class='wikit_table_row_odd'><td class="wikit_table_row_cell"> Linux 2.6   </td><td class="wikit_table_row_cell"> x86     </td><td class="wikit_table_row_cell"> CVS HEAD </td><td class="wikit_table_row_cell"> gcc 4.1.2         </td><td class="wikit_table_row_cell"> no </td></tr><tr class='wikit_table_row_even'><td class="wikit_table_row_cell"> Solaris 8   </td><td class="wikit_table_row_cell"> SPARC   </td><td class="wikit_table_row_cell"> 8.4.19   </td><td class="wikit_table_row_cell"> gcc 3.4.6         </td><td class="wikit_table_row_cell"> no </td></tr><tr class='wikit_table_row_odd'><td class="wikit_table_row_cell"> Solaris 8   </td><td class="wikit_table_row_cell"> SPARC   </td><td class="wikit_table_row_cell"> 8.5.8    </td><td class="wikit_table_row_cell"> gcc 3.4.6         </td><td class="wikit_table_row_cell"> no </td></tr><tr class='wikit_table_row_even'><td class="wikit_table_row_cell"> Solaris 10  </td><td class="wikit_table_row_cell"> SPARC   </td><td class="wikit_table_row_cell"> 8.4.19   </td><td class="wikit_table_row_cell"> gcc 3.4.3         </td><td class="wikit_table_row_cell"> no </td></tr><tr class='wikit_table_row_odd'><td class="wikit_table_row_cell"> Solaris 10  </td><td class="wikit_table_row_cell"> SPARC   </td><td class="wikit_table_row_cell"> 8.5.8    </td><td class="wikit_table_row_cell"> gcc 3.4.3         </td><td class="wikit_table_row_cell"> no </td></tr><tr class='wikit_table_row_even'><td class="wikit_table_row_cell"> Solaris 10  </td><td class="wikit_table_row_cell"> SPARC   </td><td class="wikit_table_row_cell"> 8.4.19   </td><td class="wikit_table_row_cell"> SunStudio 12      </td><td class="wikit_table_row_cell"> no </td></tr><tr class='wikit_table_row_odd'><td class="wikit_table_row_cell"> Solaris 10  </td><td class="wikit_table_row_cell"> SPARC   </td><td class="wikit_table_row_cell"> 8.5.8    </td><td class="wikit_table_row_cell"> SunStudio 12      </td><td class="wikit_table_row_cell"> no </td></tr><tr class='wikit_table_row_even'><td class="wikit_table_row_cell"> HP/UX 11iv1 </td><td class="wikit_table_row_cell"> PA-RISC </td><td class="wikit_table_row_cell"> 8.4.19   </td><td class="wikit_table_row_cell"> gcc               </td><td class="wikit_table_row_cell"> no </td></tr><tr class='wikit_table_row_odd'><td class="wikit_table_row_cell"> HP/UX 11iv1 </td><td class="wikit_table_row_cell"> PA-RISC </td><td class="wikit_table_row_cell"> 8.5.8    </td><td class="wikit_table_row_cell"> gcc               </td><td class="wikit_table_row_cell"> no </td></tr><tr class='wikit_table_row_even'><td class="wikit_table_row_cell"> Linux       </td><td class="wikit_table_row_cell"> ARM     </td><td class="wikit_table_row_cell"> 8.4.19   </td><td class="wikit_table_row_cell"> gcc 4.3.3         </td><td class="wikit_table_row_cell"> yes </td></tr><tr class='wikit_table_row_odd'><td class="wikit_table_row_cell"> Windows     </td><td class="wikit_table_row_cell"> x86     </td><td class="wikit_table_row_cell"> 8.4.19   </td><td class="wikit_table_row_cell"> mingw32 gcc 3.4.2 </td><td class="wikit_table_row_cell"> yes </td></tr><tr class='wikit_table_row_even'><td class="wikit_table_row_cell"> Windows     </td><td class="wikit_table_row_cell"> x86     </td><td class="wikit_table_row_cell"> 8.5.8    </td><td class="wikit_table_row_cell"> mingw32 gcc 3.4.2 </td><td class="wikit_table_row_cell"> yes </td></tr></table><hr><p><b>Versioning Information</b></p><p><i>Version Numbers</i></p><p><ol type="1" class="wikit_ol_depth_0"><li>The version number for a KitCreator release is in the following format:<ol type="a" class="wikit_ol_depth_1"><li><i>Major</i>.<i>Minor</i>.<i>Revision</i>.<i>Version Control Tag</i></li> 
</ol></li> 
<li>The components are incremented based on various criteria:<ol type="a" class="wikit_ol_depth_1"><li><i>Major</i>: When the interface changes in an incompatible way possibly with no way to revert to the previous behavior</li> 
<li><i>Minor</i>: When the basic functionality is altered or any interfaces changes are mode (all interface changes that are incompatible will support the previous behavior); Substantial new features</li> 
<li><i>Revision</i>: Bug fixes to existing features, new minor features that do not alter the usage of the built Tclkit</li> 
</ol></ol></p><p><i>Basic Version Annotation</i></p><p><ol type="1" class="wikit_ol_depth_0"><li>KitCreator 0.0.1 - Initial separation from other projects (no release)</li> 
<li>KitCreator 0.0.2 - Minor fixes (no release)</li> 
<li>KitCreator 0.0.3 - Cleanup (no release)</li> 
<li>KitCreator 0.0.4 - CVS compiling support (first release)</li> 
<li>KitCreator 0.0.5 - Cleaned up Metakit4 support</li> 
<li>KitCreator 0.0.6 - Added support for &quot;buildsrc&quot; directories to all sub-projects</li> 
<li>KitCreator 0.0.7 - 64-bit (especially SPARC) fixes, and started adding cross-compiling support</li> 
<li>KitCreator 0.0.8 - Cross-compiling support and improved for Win32 and Linux/MIPSEL</li> 
<li>KitCreator 0.1.0 - Zlib package added to allow static linking and HP-UX fixes</li> 
<li>KitCreator 0.2.0 - Pure-tcl read-only Mk4 implementation; Added Thread package support added; Fixed Windows build issues</li> 
<li>KitCreator 0.2.1 - Fixed failure to clean kitsh directory when producing releases</li> 
<li>KitCreator 0.2.2 - Updated to latest zlib (<i>note: this caused build failures on non-UNIX systems</i>)</li> 
<li>KitCreator 0.2.3 - Further work on Pure-Tcl Mk4 implementation</li> 
<li>KitCreator 0.2.4 - Statically link to Zlibc</li> 
<li>KitCreator 0.3.0 - Zip storage added if Mk4 fails to build; Fixed bug in Windows builds where Tk was unusable; Reverted to working version of zlib; Fixed bug in &quot;<tt>tcl::pkgconfig</tt>&quot;</li> 
<li>KitCreator 0.3.1 - Added support for &quot;<tt>--enable-kit-storage</tt>&quot; option to allow user to specify what storage mechanism to use</li> 
<li>KitCreator 0.3.2 - Fixed bug in sync logic if new &quot;<tt>--enable-kit-storage</tt>&quot; option is used</li> 
<li>KitCreator 0.3.3 - Fixed bug preventing &quot;Mk4tcl&quot; package from being &quot;<tt>package required</tt>&quot; even if present when using Zip Tclkit storage</li> 
<li>KitCreator 0.3.4 - Fixed issue causing kit initialization failure when not boot strapping</li> 
<li>KitCreator 0.4.0 - Added support for detecting encoding from the environment.  Some Tcl 8.6+ features integrated (zlib).  Updated to use platform-specific calls to find ourselves.  Fixed major issue with Zip kit storage and new interpreters</li> 
<li>KitCreator 0.5.0 - KitDLL released</li> 
<li>KitCreator 0.5.1 - Added "zlib" to KitDLL, fixing support for compressed files within a Zip archive</li> 
<li>KitCreator 0.5.2 - Updated to support building Metakit4 dynamically, but falling back to static building if that fails</li> 
<li>KitCreator 0.6.0 - Tcl 8.5 made the default (future)</li> 
<li>KitCreator 0.7.0 - Tcl 8.6 features will be integrated more heavily (future)</li> 
<li>KitCreator 1.0.0 - Stable long term release, Tcl 8.6 made the default (future)
</li></ol></p>

Z de8a22598a37f7a6255b9c0a39440cfb