Tclish User Guide

1. the install.tcl script
2. the img/ subdirectory, with img/custom.cfg
3. the packages/ subdirectory, with your custom package files.

• wrap install.tcl with a static wish executable so users won't need tcl.
• wrap install.tcl, img/ and packages/ subdirectories so the entire install is one self-extracting file.
• set up install.tcl to fetch img/ and packages/ information from a web site

Example custom.cfg
title "TclBlast! - The Tcl/Tk CD-ROM" creator "The Tcl/Tk Consortium" copyright "Copyright \251 1998" patchString "/tmp/tclbuild" credits "Thanks to all of the volunteers" buttonBackground black buttons "-foreground black \ -tile [create_photo goldbg.gif] \ -activeforeground white \ -activetile [create_photo redbg.gif]" icon [create_photo blast-lg.gif] startup screen main screen about screen

create_photo imgfile

imgfile is a gif or jpg image in the img/ subdirectory. Returns an image name for use in other commands.

title title

title is the string used in the title bar of the main window

creator creator

creator is given credit on the "about" page

copyright message

message is shown as a copyright message on the "about" page

patchstring string

string is used as the search string to the patch_files command, described later. It should be as long as the longest expected substitution string. Default value is /tmp/build/123456789-123456789-123456789-123456789-123456789-/123456789-123456789-123456789-123456789-123456789-

credits string

string appears on the "about" page

buttonBackground color

color is used as the background for buttons

buttons optionlist

buttons are additionally configured with optionlist. This should be an option list compatible with BLT extended buttons

icon image

image is used in the background of the intro screen. It should be an image name, which can be obtained using the create_photo command.

package *intro {
    category Overview
    title Introduction
    description {
Tcl/Tk and its extensions are powerful tools 
for software development, and this CD-ROM 
makes it easy to get up and running.
In the list on left, click on the name of a 
package to obtain a description of that package.  
Click on the check box next to the package to 
select it for installation.  Then, click on 
the Next button below, and this program will 
guide you through the installation process.

If you're looking for more information about Tcl/Tk, 
check out the Tcl/Tk Consortium site:
    http://www.tclconsortium.org
    }
    icon [create_photo blast-tiny.gif]
}
      

name gives a logical name to the package, which is used to refer to it in the .pkg files.

subcommand_list is made of a list of the following subcommands:

category category

Put the package under category category in the browser menu. This will create the category if it doesn't already exist. This will also appear as the main title in the description.

title title

Use the name title in the browser menu. This will appear as the subtitle in the description. Note: It's a good idea to make the package name the same as category plus title, so that users can easily match any errors that occur while installing the package to the package description.

version version_number

This defines a version number for the package.

description text

This text will be displayed as the description when the user clicks the title in the browser.

icon [imagename | imagedata]

This defines an image to use as an icon in the browser display when the user clicks on the title. It can take one of two forms, either an image name returned from the create_photo command, or a base64 encoded string version of the image file. If using the create_photo command, the image will need to be in the img/ subdirectory.

requires packagelist

This defines a list of packages (by package name) that should be installed if this package is installed. If the user attempts an install without the required packages, they will be warned and asked to confirm they know what they're doing.

installcmd tcl_proc

This gives the name of a tcl procedure, which should be defined in the package file, that will be executed when it's time to install the package. The tcl procedure will be described in its own section in this document.

If installcmd is not defined for a package, the package is treated as informational. It will appear as an entry on the browser, but no action will be taken to install it.

platformnamecmd tcl_proc

This gives the name of a tcl procedure, which should be defined in the package file, that will be executed when it's time to figure out which platform is needed. The tcl procedure should return an appropriate string for the platform.

If installcmd is not defined for a package, a default platform is used. This matches the platforms that tclish is distributed under.

files file ...

This command accepts a list of files that are required to install the package. The files listed here should be in the packages/ subdirectory. This list is used to retrieve those files during a web install. The character * in the filename will be replaced with the platform name of the install - sunos, sol, sol26, hp10, aix4, or linux.

parameters parameterlist

This sets up parameters that will be obtained from the user before installing the package, such as install location. The parameter subcommand will be described in detail in its own section in this document.

parameters {
sourcedir {Log Master Server 2.5.1} \ 
  {Please select a directory for 
  the LogMaster server} \ 
  lm_rootdir lm_rootdir_default
directory {License Manager} \ 
  { Please select a directory for 
  the license server } \ 
  lm_licdir lm_licdir_default
form {License File} \ 
  {Please select the file containing 
  the license sent by BMC.}
  {{-file License File}} ""
}
      

type

This gives the type for the parameter. There are three types - sourcedir, directory, and form. sourcedir prompts for a read-only directory, which must already exists. directory prompts for a directory which must be writable, and will be created if it doesn't exist. form allows a configurable number of fill-in-the-blank parameters which appear together on a form.

title

This title will be used on the screen asking the user for the value of the parameter.

description

This description will be given on the screen asking the user for the value of the parameter.

name

This gives a name to the parameter. If two packages each define a parameter with the same name, tclish will assume that the parameter's value need only be obtained one time during the install, so the two packages will share that parameter - so be careful with naming to prevent unintended collisions.

For form parameters, name is actually a list of names, one per entry on the form. For each name in that list which has a first element of "-file", the entry in the form will have a "browse..." button. (-file will be dropped from the name of the parameter.) Also, the parameter name will appear on the form as a description for that blank in the form.

default

This specifies a default value for the parameter. It may optionally take the form "-force default" in which case the user is never prompted, the default is always taken.

default may also be the name of a tcl procedure defined in the package files. In that case, before prompting the user, the tcl procedure is run, and its return value is taken as the default. (The return value may specify "-force" also.)

In the case of a form parameter, default (or the return from the tcl procedure) is taken as a list of values, one per blank in the form.

proc lm_datadir_install {pkg} {
  global parameter

  untar $parameter(lm_datadir) dd-v2.5.1-Oracle-*.tar.Z
  catch {
    eval exec chmod -R u+w $parameter(lm_datadir)
    eval exec chmod -R g+w $parameter(lm_datadir)
    eval exec chmod -R o-w $parameter(lm_datadir)
    eval exec chown -R $parameter(Userid) $parameter(lm_datadir)
    eval exec chgrp -R $parameter(Group) $parameter(lm_datadir)
  }

  return
}
      

There are a set of commands defined in the interpreter that are useful in for a typical package install.

packagefile filename

packagefile returns a fully-qualified path to filename based on the location of the packages directory, whether on the CD, or in the case of a web-based install, in a temporary location. In addition, occurrences of the character * in the filename will be replaced with the architecture string sunos, sol, sol26, aix4, hp10, or linux depending on the operating system and its version.

untar directory tarfile extra_steps

This will pipe the file tarfile through uncompress and then an untar command, in the directory directory. During the uncompress, a progress widget will be updated for the user. tarfile should be a full path, normally a path returned from the packagefile command.

It returns the current step number, which can then be incremented and passed to progress in further steps. Extra_steps specifies the number of steps that will follow the untar.

progress num ?max? ?task? ?message?

This updates the progress bar for the package. The bar will show num out of max completed, expressed as a percentage. If max isn't specified (or is ""), it will remain the same as the last time it was specified. task and message are displayed as detailed information on the window. They remain unchanged if not specified.

patch_files filelist patchstring

This will substitute the string patchstring into each of the files specified in filelist, replacing the string patchString which was defined in custom.cfg.

Where this comes in handy is updating the search path for shared libraries, etc. When building the package, specify patchString as a location to be searched for files used your program, or in the compile as a directory where the run-time linker should look for shared libraries. Then after the install, that string can be replaced with the correct value. The replacement will overlay the existing string without changing the length of the file, so the program will run normally - except it will magically know the right place to look for the files based on the user's install. Just be sure to reserve enough room (by using a long patchString.)

Example install options

installoption normal {Normal installation. Install the packages most users need.} installoption_add normal {Log Master} \ {Log Master Server 2.5.1 for Oracle} installoption_add normal {Log Master} \ {Log Master Data Directory} installoption_add normal {Log Master} \ {Log Master Client Integration} installoption_add normal {Log Master} \ {Log Master Bourne Shell Environment Config} installoption_add normal {Log Master} \ {Log Master C Shell Environment Config} installoption_add normal {Log Master} \ {Log Master Media Key} installoption license {License Only. Install or update a Log Master license key.} installoption_add license {Log Master} \ {Log Master Permanent License} installoption datadir {Data Directory. Create an additional Log Master Data Directory.} installoption_add datadir {Log Master} \ {Log Master Data Directory}

The first step is to define an installoption using the command

installoption name description

Next you must add packages to the option, using the command

installoption_add name category packagename

In addition, it's necessary for performance reasons to include a "manifest" file. It should have the same name as the tarfile (including extensions) with .manifest added on the end. This can be created using a command like:

cat tarfile | uncompress | tar tf - > tarfile.manifest

If a manifest file is not available, one will be created when the install is run - which will fail on a CDROM since it's not writable. But this can be used to create the files before burning a CD.

These are the steps in wrapping the install program:

1. Create the file http.fwp in the directory where install.tcl is located. This should contain a list of the files in the tcl standard http package, one per line (with full path.)

   Here's an example of how you might create the file:
   

   httpdir=`find /usr -type d -name http2.3 2> /dev/null | head -1`
   find $httpdir -type f > http.fwp

   Note that the filename is important - the install program looks for this file to know when to load the http package from freewrap instead of the normal way.

2. Run freewrapBLT, telling it to include install.tcl, the contents of http.fwp, and the http.fwp file itself. Example:

   freewrapBLT install.tcl http.fwp -f http.fwp

   Note that freewrap will name the executable install. If you need to make installs for multiple architectures, you might consider renaming that to something architecture specific, like install-solaris for example.

To do this, do step one, above, to wrap the install application. Then:

1. Put a listing of the binary files in your install package into a file called binpackages.fwp, also in the same directory as install.tcl. Here's an example of how to do that:

   find img packages -name '*.gif' > binpackages.fwp
   find img packages -name '*.Z' >> binpackages.fwp

   freewrap will automatically detect some binary files, based on extension, but misses some (for example, .Z files) so it's best to be explicit by separating them into this file.

2. Put a listing of the rest of the files into the file packages.fwp in the same directory as install.tcl. Example:

   find img packages -name '*.cfg' > packages.fwp
   find img packages -name '*.manifest' >> packages.fwp
   find img packages -name '*.pkg' >> packages.fwp

3. Wrap all of that into the executable (including the .fwp files.) Be sure to force freewrap to interpret the contents of binpackages.fwp as binary. Example:

   freewrapBLT install.tcl http.fwp packages.fwp binpackages.fwp \
       -f http.fwp -f packages.fwp -b binpackages.fwp

   Note that freewrap will name the executable install. If you need to make installs for multiple architectures, you might consider renaming that to something architecture specific, like install-solaris for example.

There's only one trick to the web install, and that's configuring tclish to know where the web site is. To do that, simply create the file install.url in the same directory as install.tcl, and include it when you wrap the executable. The file should contain only the URL where you will put the install. Example:

echo http://tclish.sourceforge.net/latest > install.url
freewrapBLT install.tcl install.url http.fwp -f http.fwp