This is tkbiff's INSTALL file. This file may seem rather long but it's only because tkbiff runs on so many different platforms and has a large variety of options. Once you figure out which ones you want, the actual installation time should be two minutes max for most people. If you're using SSL/TLS, installation may take a good bit longer. -------------------- Installation -------------------- 0) If you already have Tcl/Tk 8.0 (or later versions), skip to step 1. Surf over to http://tcl.sourceforge.net or http://www.activestate.com/Products/ActiveTcl and download a release of Tcl and Tk. If you don't want to compile anything, get a binary release. Once Tcl/Tk is installed, go on to the next step and start installing tkbiff. 1a) If you are using UNIX: Run "./configure". You may want to add the following flags to the configure line: --prefix=path path indicates where files should be installed in the install step (later). Default path is /usr/local allowing tkbiff to land in: /usr/local/bin/tkbiff If you're sharing an installation with other types of computers, see "Multiple-Architecture Installation" below.) -enable-shortpath=path where path is the directory containing wish and to be used in the #! line. By default, configure looks around and guesses which is the best. Note: all remaining -enable-xxx flags are defaults. That means you can configure imap (for instance) as the default and users can still get pop if desired without having to reconfigure. It's just a default. However, you should't enable features if you don't have the support for them. For example, don't enable tkbiff's TLS support if you don't have TLS (i.e., certificates, libraries). -enable-imap=hostname where hostname is the name of the imap server -enable-imap=hostname:## as above, but ## is the imap port number -enable-pop=hostname where hostname is the name of the pop server -enable-pop=hostname:## as above, but ## is the pop port number -enable-mbox=path where mbox-style mailbox is in one of the directories in path (colon-separated list) -enable-mbox where mbox-style mailbox is in one of these directories: /usr/var/mail /var/spool/mail /usr/spool/mail /var/mail /usr/mail -enable-file is the default. -enable-maildir=path where maildir-style directory (named either ...dir.../$USER or ...dir.../$USER/Maildir) is in one of the directories in path (colon-separated list) -enable-maildir where maildir-style directory is in ~user or ~user/Maildir). -enable-connectXXX=... to enable Secure Sockets and do other misc things with sockets, see SSL/TLS below. -enable-starttls to enable IMAP STARTTLS command. -enable-XXX where XXX is a 3rd-party audio player such as snack or rplay. See Audio section below for more details on this and other related audio configuration. configure generates a Makefile. Take a quick look at the beginning of the new Makefile to verify it is what you want. You can hand-edit the Makefile, but it's easier and safer to run configure with the appropriate arguments. 1b) If you are using MacOS or Windows: In this step, you'll make a few tiny edits to tkbiff.tcl. A fixed-width editor makes things easier to read but is not necessary. On Windows, wordpad or notepad works fine. On MacOS, simpletext won't work ("file too large") so you may be stuck with downloading yet a better editor if you haven't already (or using something like MSWord). Edit tkbiff.tcl and change the lines near the beginning that start "set protocol(...". - Set protocol(type,default) to "imap" or "pop". - Set protocol(host,default) to "yourmailhost" or "yourmailhost:portnumber". - Skip remaining lines unless you want to enable SSL/TLS (see below). As a special case, you can also set protocol(host,default) to "?" in which case tkbiff will interactively prompt for the hostname - very handy on systems where people don't log in and thus get a shared configuration file. As an example, here's what it looks like on my own installation. The first line declares that I am using imap. The second defines the name of the imap server as "titanic.cme.nist.gov". The rest is left as is since we don't use SSL/TLS. set protocol(type,default) imap set protocol(host,default) titanic.cme.nist.gov set protocol(connectinit) {} set protocol(connectpre) {} set protocol(connect) {socket -async $protocol(host) $protocol(port)} set protocol(connectpost) {} set protocol(starttls) {} Save the file (but don't exit the editor yet). Remember that if you are using an editor which normally handles formatted documents (such as MS Word) to save using "Save As" and select type "Text Only". 2a) If you are using UNIX, go to step 3. 2b) If you are using Windows: Continue editing tkbiff.tcl and search for the line: set env(AUDIOPATH) "C:/AUDIOS;.... Edit the line so that it lists the directories in which to find audio files. Each directory is separated by ";". Note that slashes appear the "wrong" way. That's ok. (Don't try and use \ unless you've read the Tcl documentation.) Save the file. 2c) If you are using MacOS: Edit tkbiff.tcl and search for the line: set env(AUDIOPATH) [list .... Edit the line so that it lists the directories in which to find audio files. Save the file. Drag-n-drop the file onto the "Drag & Drop Tclets" that came with Tcl. When prompted for a new name, enter "tkbiff". 3a) If you are using UNIX: Run: make install This will install everything. Even if you are just installing a personal copy for yourself, you must do the install step. (On some systems, tkbiff will not work until it is installed.) It's fine to install it in your own personal directories if you just want to try it out - or that's all you've got permission to do. Once installed, try running "tkbiff_audio Yeah" from the command line to make sure that audios work. (Yeah.au is an audio that comes with tkbiff; or try tkbiff_audio with one of your own audios.) You may have to enter "rehash" at your shell prompt for it to see tkbiff_audio at first. 3b) If you are using MacOS: If you want to use the audio clips that came with tkbiff, make sure they're in one of the directories in your audio path that you defined in step 2. Try clicking on them from the Finder. If they don't play, make them playable with a tool such as SoundApp. (SoundApp is a free tool available at numerous sites around the web.) Optional: Make tkbiff aliases for the desktop and Apple menu. 3c) If you are using Windows: If you want to use the audio clips that came with tkbiff, make sure they're in one of the directories in your audio path that you defined in step 2. Optional: Make a shortcut for the desktop or the Start menu. 4) (This step is optional) From, subject, and other fields are sometimes mime-encoded. If you want to see such headers properly displayed, install tcllib (the Tcl Standard Library) from: http://tcllib.sf.net If tcllib is installed, tkbiff will automatically use it. 5) Now, users can run tkbiff. Advice on running tkbiff for the first time is available at: http://expect.nist.gov/tkbiff/doc-firsttime.html 6) You'll eventually want to customize tkbiff for yourself. Advice on customizing tkbiff is available at: http://expect.nist.gov/tkbiff/doc-configfile.html 7) For more information ... Press "?" to get that tkbiff's online help. From there, click one of the hyperlinks. If the hyperlinks don't work for you, enter this URL into your browser by hand: http://expect.nist.gov/tkbiff/doc.html Congratulations. You have completed the installation. Below here are some installation-related topics. Most people can skip them. -------------------- Audio (on UNIX) -------------------- Audio support can be controlled by each user, however it is convenient for common system-wide choices to be made at configuration time. If users do not give full paths to their audio files, tkbiff will search for them. By default, tkbiff will search in the current directory and ~/audio. If there are directories of audio files on your system, you can configure tkbiff to search them. For example, the following command configures tkbiff to search through the current directory, ~/audio, and /usr/local/audio. configure --enable-audiopath=:~/audio:/usr/local/audio Note: the user can override this search path by setting the environment variable AUDIOPATH. See the man page for more info. configure can pick the right audio player for different platforms automatically. Presently, tkbiff understands how to play audios on the following systems: hpux irix linux solaris sunos Additional systems can be supported if you tell me how the interfaces work. See the configure.in script if you want to have a go at writing the code yourself. It's actually pretty trivial - just follow one of the other ones as an example. configure also understands requests for 3rd-party players. Unfortunately, there is no practical way to test for this. Such requests will override the defaults. The following 3rd-party players are supported. -enable-snack Use snack. -enable-arts Use arts. -enable-esound Use esound. -enable-rplay Use rplay. -enable-rplay=path Use rplay. Providing the path may be helpful if rplay is not on the path of some of your users. You can only configure for one 3rd-party player at a time. Additional 3rd-party players can be supported if you tell me how the interfaces work. See the configure.in script if you want to have a go at writing the code yourself. It's actually pretty trivial - just follow one of the other ones as an example. For each type of system with different audio, tkbiff should be installed separately. For example, if you have both hpux and irix machines, you should configure/install tkbiff twice. If you want to use audio remotely (i.e., run tkbiff on a remote machine but play sounds on your local machine), and they are different architectures, you must run tkbiff's configure on both machines. See Multiple-Architecture Installation for more info. ------------------- SSL/TLS ------------------- Read http://expect.nist.gov/tkbiff/doc-secure.html ------------------- Modifying the default GUI system-wide ------------------- tkbiff allows users to make modification to their own default GUI. (See the man page.) To make modifications to the default GUI sitewide, edit tkbiff as follows: 1) Delete everything after "DO NOT CHANGE THIS LINE". 2) Insert your new configuration file. 3) Save tkbiff. New users (without configuration files) will get the new configuration. -------------------- Multiple-Architecture Installation (UNIX only) -------------------- You might want to compile a software package in a different directory from the one that contains the source code. Doing this allows you to compile the package for several architectures simultaneously from the same copy of the source code and keep multiple sets of object files on disk. (tkbiff itself is not architecture-specific but audio "helper" scripts can be.) To compile the package in a different directory from the one containing the source code, you must use a version of make that supports the VPATH variable. GNU make and most other recent make programs can do this. cd to the directory where you want the object files and executables to go and run configure. configure automatically checks for the source code in the directory that configure is in and in .. If configure reports that it cannot find the source code, run configure with the option --srcdir=dir, where dir is the directory that contains the source code. You can save some disk space by installing architecture-independent files (e.g., scripts, include files) in a different place than architecture-dependent files (e.g., binaries, libraries). To do this, edit the Makefile after configure builds it, or have configure create the Makefile with the right definitions in the first place. To have configure do it, use the following options to configure: --prefix=indep --exec-prefix=dep where dep is the root of the tree in which to store architecture-dependent files and indep is the root in which to store -dependent files. For example, you might invoke configure this way: configure --prefix=/usr/local/bin --exec-prefix=/usr/local/bin/arch -------------------- No GUI -------------------- If you want to run tkbiff without a Tk GUI, simply run it with tclsh. (If you have already run tkbiff via wish, you'll want to use a different configuration file. (~/.tkbiff on UNIX, tkbiff.cfg in your home directory on Windows, and "tkbiff Preferences" on MacOS.) -------------------- Test Suite -------------------- There is no test suite. -------------------- Uninstalling -------------------- If you are using UNIX: "make uninstall" removes all the files that "make install" creates (excluding those in the current directory). If you are using Windows or MacOS: Drag the the configuration file to the trash. If you made an icon drag it to the trash. If you made a shortcut or added tkbiff to a menu, drag it to the trash. -------------------- Cleaning Up -------------------- If you are using Windows or MacOS: There is nothing to clean. If you are using UNIX: Several "clean" targets are available to reduce space consumption of the tkbiff source. The two most useful are as follows: "make clean" deletes all files from the current directory that were created by "make" "make distclean" is like "make clean", but it also deletes files created by "configure" Other targets can be found in the Makefile. They follow the GNU Makefile conventions.