This page is a living document. It will eventually contain the joint
knowledge of all users about the Tcl Plugin, derived from everyone's
questions, problems and solutions. If you do not see your question
addressed here, send email to tclplugin-core at lists.sourceforge.net and we will add your question (or answer!) to the list.
1. What is the Tcl Plugin? How can I get it?
- 1.1. What is the Tcl Plugin?
The Tcl Plugin is a plug-in component for popular web browsers such
as Netscape Communicator and Microsoft Internet Explorer. When the browser
encounters an embedded Tcl script, it invokes the Tcl Plugin to interpret
it. There's a variety of plugins available (over 170 of them!) for all
kinds of things, from viewing image types that the browser itself does not
support to navigational aids, to remembering passwords and much more! The
Tcl Plugin is the only programmmable plugin, that is, it does
whatever it is told by the script it executes.
- 1.2. How can I get the Tcl Plugin?
You can download it from our web site. Visit the download web page
to get the plugin
- 1.3. How do I check if I already have the Tcl Plugin?
You can check by pulling down the "Help" menu and selecting "About
Plug-ins". If the page you get lists the Tcl Plugin then you have it
- 1.4. What platforms is it available for?
We distribute precompiled binaries for the following platforms:
- Sun Solaris 2.4 or later for both SPARC and Intel X86.
- Sun SunOS 4.1.* for SPARC.
- Windows NT 3.51 and 4.0, and Windows 95 for Intel X86.
- Linux 2.0.27 for Intel X86.
- IRIX 6.3
- Macintosh (PowerPC)
- 1.5. What about my favorite platform?
If that happens to be Windows 3.1 or Windows for Workgroups, sorry.
We will not support the plugin for Windows 3.1 or Windows for Workgroups.
If your favorite platform happens to be something else, you can attempt to
build the plugin from the sources, they are available for free (see below).
- 1.6. My users do not have the Tcl Plugin -- what to do?
You can ensure that your users will have the option to download the
plugin easily, by including the following HTML in your pages:
<!-- Copy the following in your pages: -->
Are you ready to view these pages ?
align=absbottom bg="#ffffff" height=22 width=22>
<tt><-</tt> Should be <font color="#009900">green</font> if you have the
latest <a href="/software/tcktk/plugin/" target="_top">Tcl Plugin</a> version!
Otherwise <a href="/software/tcltk/plugin.html" target="_top">download</a>
<!-- End update checking section -->
- 1.7. How much does it cost?
The Tcl Plugin is available free of charge for any use, including
- 1.8. Is source code available?
Yes, you can download the source code from our
- 1.9. Can I really use it in commercial applications?
2. Installation problems:
- 2.1. How do I install the Tcl Plugin?
When you download the plugin, you save the distribution to a disk
file. Depending on your platform, you then need to do one of the following:
- On Unix, uncompress and untar the distribution. You will obtain a
directory containing the distribution files and an "install.sh"
shell script. Run the shell script and follow its instructions.
- On Windows, execute the file you downloaded; it is a self
extracting and self installing archive. Follow its instructions.
The installation produces a log file and offers to save previous
installations of the Tcl Plugin.
- 2.2. How do I report problems?
If you are installing on Unix, the installer offers allows you to
submit a trouble report. When you do, the install log file is included in
the report and you can type some descriptive comments about what went
wrong. When you hit submit, the installer send the report you composed as
email to [email protected]
If you are installing on Windows, the installer also produces a log
file (in c:\tclplug\install.log). Compose a message using your favorite
email program and include the log file. Please also include a description
of what went wrong. Send your email to [email protected].
- 2.3. It does not work!
That's the kind of report we hate! :) Please include more details and
if at all possible, the log file. The proper place to send such problem
reports is to [email protected]
The kind of information that you might include is:
- It crashed my browser when I visited the page at <include the
URL here, so we can look at it>.
- It hung my browser when I did <describe the action that caused
your browser to hang>
- Here's a stack trace of the crash: <include a stack trace obtained
from the debugger; thanks!>
- 2.4. Where is this Help->About plug-ins information?
In Netscape, pull down the Help menu, and choose the About Plug-ins
item. You're out of luck if you use Microsoft Internet Explorer, it
has no way of checking which plugins are installed.
- 2.5. I get a blank page when I follow these instructions!
page. In Netscape Communicator pull down the Edit menu, choose Preferences
is in fact selected.
- 2.6. The plugin is shown in Help->About plug-ins but it doesn't work!
Again, not enough details. We absolutely need the installation log
file to help you with this one. If you installed in a non-standard
place, you may have to set some environment variables (see
for details) for things to work. Is the plugin marked as enabled in
the Help->About plug-ins page?
- 2.7. The plugin does not show up in Help->About plug-ins.
Some things to check for:
- Did the installer put a shared object ('.so' for Unix, '.dll' for
Windows) in the program/plugins directory in your browser's installation?
- Did your Tcl runtime files get installed (in the tclplug directory
under your browser's installation on Unix, or in c:\tclplug on Windows)?
- If you did a custom install on Unix, did you remember to
the NPX_PLUGIN_PATH variable if you put the shared
libraries somewhere non-standard?
- 2.8. I can see other plugins such as Adobe Acrobat but not the Tcl Plugin
Aha! Check if the program you activate through the "netscape" command
is a shell script, and if so, find the actual executable that that
shell script starts. When you invoke the executable directly, and visit
Help->About plug-ins, the Tcl plugin shows up. Why?
The reason is that the Adobe Acrobat plugin hijacks Netscape Navigator
and tells it where to find its plugins. This effectively prevents you
from using any other plugin besides Adobe Acrobat. The solution is
to not use the shell script and instead invoke the Netscape executable
- 2.9. I did a custom installation of the plugin and it doesn't work!
You're probably using a Unix system, right? If so, Netscape looks for
plugins in a few places that you should know about:
- It also searches the directories specified in the NPX_PLUGIN_PATH
This means that if you didn't install the plugin in one of the standard
places, you must update the value of the NPX_PLUGIN_PATH
environment variable so that Netscape can find the plugin shared libraries.
- 2.10. The plugin shows up in Help->About plug-ins but when I visit a
page it complains about init.tcl not being found, or something.
If you installed the runtime libraries in a non-standard place (e.g.
not in the <yourhome>/.netscape/tclplug on Unix, or c:\\tclplug
on Windows) then you need to set the TCL_PLUGIN_DIR
environment variable to point at where you did install these runtime
- 2.11. Sun's demos work but when I create my own Tclet it doesn't work!
Check that the web server you are loading the pages from sends the right
mime type, application/x-tcl, and that you've stored the script in a file
whose name ends with '.tcl'.
Both of these conditions have to be met for the plugin to work.
3. Using the Plugin:
- 3.1. How do I write my own Tclet?
That's all there is to it!
- 3.2. In Microsoft Internet Explorer the plugin redisplay is flaky.
Yes, we know about that. It's one of the known bugs. We are not sure
whether it's a problem in our code or theirs.
- 3.3. I wrote a Tclet and it doesn't work in the plugin, but yours do work!
Check that the server from which you're loading the Tclet is sending the
right mime type (application/x-tcl) when it sees a file with the '.tcl'
extension. That's what causes the plugin to kick in and activate.
- 3.4. When I visit a page containing my Tclet it freezes the browser!
If your Tclet implements some kind of infinite loop or very lengthy
computation, that'll freeze the browser. What happens is that the Tclet
grabs the CPU and does not let go.
The Tclet is executing in the same process (and thread, for those systems
that have threads) as the browser, so if it does not yield control then the
browser will be frozen.
- 3.5. When I edit my Tclet and revisit the page, I still get the old
Yes, this is another problem that we know of, and sadly we can't fix it.
The problem is that the browser (especially Netscape Communicator)
agressively caches everything and does not check often whether a file it
fetches has in fact changed.
There are several approaches to getting around this problem:
- Set the cache size to zero. This is reported to work although it does
not work for us.
- Instead of visiting the page in which the Tclet is embedded, view the
Tclet directly (visit the '.tcl' file instead of the '.html' file). The
Tclet will start in full-page mode.
Then, when you want to refresh, hit the 'Reload' button while holding down
the 'Shift' key.
This forces the browser to reload the file from the source.
Note that this does not work if you're viewing the HTML file that embeds
the Tclet -- only the HTML file is refreshed!
- 3.6. Focus behaves strangely!
For some older releases of the Tcl plugin,
you needed to set focus explicitly into the Tclet with 'focus .' or else
none of the widgets was able to get focus.
This is fixed in the 2.0 release.
- 3.7. Why my 1.0 plugin tclet does not find it's embed_args anymore ?
Because you should not have expected tag names to be case sensitive
(ie MyValue=1.2 is in html equivalent to MYVALUE=1.2, myvaLUE=1.2,..etc..).
The Plugin code now simplifies your code by converting the tag to
canonical lowercase for you (so in all those examples the
1.2 value will be found in $embed_args(myvalue)).
4. What can it do? What can't it do?
- 4.1. Is the plugin able to execute all Tcl and Tk code?
The Tcl Plugin contains a complete implementation of Tcl and Tk, so all Tcl
and Tk programs that rely only on the core facilities should be runnable in
the Tcl plugin.
However, some commands are disabled for Tclets.
- 4.2. Why are some commands disabled?
This is for security reasons.
Tcl is a complete programming language and it lets a Tcl script manipulate
the file system and other resources on the computer on which it is
Since the origin and trustworthiness of a script loaded from a web site are
generally unknown, it is better to be safe than sorry and disable all
- 4.3. What commands are disabled?
The following Tcl commands are disabled by default: cd, exec, fconfigure,
file, glob, pwd, socket.
The following Tk commands are disabled by default: bell, clipboard, grab,
menu, send, tk, toplevel, wm.
Most of these commands are disabled because of security concerns. For
example, exec is disabled to prevent a Tclet from executing arbitrary
commands on the hosting computer, and clipboard is disabled to prevent a
Tclet from grabbing other programs' text insertions from the clipboard.
- 4.4. How can I get these commands back? I know what I'm doing!
Use a security policy that reenables them. Check out the policy
command. You cannot reenable commands without using a security policy.
A security policy (explained below in more detail) is a controlled way to
- 4.5. I don't need a security policy, my site is behind a firewall!
Ah, well, we think you do :). Are you going to view pages that reside
outside your firewall? If so, you might encounter a page that contains a
Tclet and that Tclet could try to do bad things.
You just can't be sure that all Tclets you will ever encounter are
trustworthy because your site is behind a firewall. Sorry.
- 4.6. I'm the security expert here, and my boss won't let me install the
plugin unless I tell him it's safe.
Convince yourself that it's safe enough for your site, by reading the
sources. They're available, as explained above.
5. Configuration and Security.
- 5.1. What is a security policy?
A security policy is a way to control what a Tclet can do.
Security policies add capabilities to the environment in which a Tclet
executes; for example, a security policy might add access to a restricted
set of files on the local file system, or allow a Tclet to open network
sockets to a restricted set of hosts and ports.
At the extreme, a security policy might restore the state of a completely
unrestricted Tcl interpreter, enabling a Tclet to do anything that a
regular trusted Tcl program can do.
- 5.2. How does this work?
A Tclet executes in a separate interpreter, controlled by the main
interpreter of the plugin.
When this slave interpreter starts, it has a restricted environment that
isolates the Tclet from all the potentially dangerous facilities of the Tcl
The slave interpreter may contain aliases, commands that when invoked
execute code in the master interpreter.
These aliases can be used to give a Tclet controlled access to unsafe
features, allowing it only to use these features in safe ways.
A security policy, concretely, consists of a set of aliases added to the
slave and code that runs in the master when each alias is invoked.
The policy can also control the specific resources that can be accessed;
for example, a policy might restrict the socket command to only be able to
open connections to a restricted set of hosts and ports.
All of this is described in much more detail in the online manual pages at
- 5.3. How do I find out what security policies are available?
At present there is no configuration management tool that will give you
this information. We are planning to add such a tool, and when it's
available it will allow you to control what policies are available and the
set of resources and capabilities provided by each.
For now, check the config directory of the plugin installation on
On Unix, this directory is most likely to be found in
On Windows, the directory is likely to be at
- 5.4. How do I change the resources allowed by a security policy?
Until the configuration tool is ready, edit the configuration files by
hand. Their syntax is really simple and designed to be understandable at a
glance. On the other hand, you're able to do really sophisticated things
with it, because everything is just a Tcl script.
A caution: edit the configuration files at your own peril! You can
easily introduce a security hole that can be taken advantage of by a
malicious Tclet. Carefully consider whether the changed resource and
capability set makes sense. Always follow the principle of least required
privileges, and try to restrict access to exactly the smallest set of
absolutely required capabilities and resources.
- 5.5. How do I write my own security policy?
First, be aware that writing a security policy is complicated and requires
good understanding of security issues. If you don't have this background,
ask someone who has it to write your policy for you.
Discuss the reasons why you need a new security policy with someone
knowledgeable and see if you can't reuse one of the policies we supply.
If you still want to write your own, start by copying one of the policies
Learn the syntax (it's fully described in the online manual pages).
Slowly modify the policy you started from, and test each modification with
an eye towards what security holes it might open.
We freely admit that even we have made several errors in writing even
simple security policies; always question yourself, especially when you
start to feel good about the new security policy!
The new security policy must be stored in a file ending with the extension
'.cfg' in the config directory of your plugin installation.
That's how the plugin finds security policies when a Tclet requests one
with the policy command.
You must also edit the main configuration file for the plugin,
plugin.cfg and enable your policy for use by Tclets in the
- 5.6. How can I control which Tclets can use each security policy?
The main configuration file for the plugin, plugin.cfg, has a
section policies where each policy is enabled or disabled.
Policies can also be enabled or disabled conditionally, depending on
properties of the requesting Tclet.
- 5.7. How do I turn off a specific security policy for all Tclets?
Disable it in the policies section; see how we do this for the
inside and trusted policies.
- 5.8. How do I enable a security policy for all Tclets?
Enable it in the policies section. You can see how this is done by
examining the entry for the home policy.
- 5.9. Where can I read about security policies?
Read the online manual pages..
- 6.1. How do I extend the plugin?
You can write Tcl code; it's likely that you'll have to change the way you
do things slightly to make things work in the plugin.
For example, you can't use menus or toplevels unless you ask for a security
policy that lets you use them.
Also, because you are running inside a browser, your code does not have
access to stardard output and other amenities available to a regular Tcl
You can use a dynamically loaded extension written in a compiled language
such a C or C++.
extension into the plugin is explained in the next FAQ topic,
Finally, because sources are available, you can link your extension right
into the plugin and produce a modified version of the plugin.
For example, you might want to do this with the Tix extension (see the [Link "Tix
home page" http://sourceforge.net/projects/tix/],
for more details).
- 6.2. How do I use my favorite extension in the plugin?
Right now dynamic loading into the plugin is not completely
implemented. It only works well on Windows, and when you're using the
external process option on Unix.
Eventually we will support dynamic loading completely
and you will be able to dynamically load extensions on demand into
the plugin with very little change to your extension. Here's what
extension writers must do to make their extension loadable:
You need to implement a safe entry point. If your extension is
named foo.so, and your regular entry point is Foo_Init, you now
need to implement a second entry point, Foo_SafeInit. This
entry point is called with exactly the same arguments as the
original Foo_Init entry point.
Your safe entry point is responsible for only providing safe
functionality to the interpreter being initialized. If your
extension has functionality that could be used to damage the
integrity of the hosting system in any way, or if it could be
used to compromise the user's privacy of information, your
safe entry point should *NOT* provide that functionality to
the interpreter being initialized.
Extensions that do not have a safe entry point will not be
loaded by Tcl into a safe interpreter. Since all tclets run inside
safe interpreters, such extensions will not be usable by tclets.
7. General Questions.
- 7.1. What's the current version?
The current version for Unix and Windows is 2.0. The 2.0 version is now in
Alpha for the Macintosh, we hope to produce a final version 2.0 for the
- 7.2. What bugs remain in this version?
Lots. Here's a partial list:
- 7.3. What's the release schedule for the Tcl Plugin?
We are about to do 2.0 final for Unix and Windows. Then, we will probably
do a 2.0 patch release to fix the most serious bugs, and during 1998 we
will do a 3.0 release cycle.
At this time there's really no more detailed information about the schedule.
We don't even know, ourselves!
- 7.4. What are your future plans?
We plan to release version 3.0 of the plugin during 1998.
We will include strong authentication and security in this version,
and really good connectivity between Java and Tcl.
We may split the project into two parts, a plugin intended for use with
Netscape Navigator and Communicator, and an ActiveX control intended for
use inside Microsoft Internet Explorer and other ActiveX containers.
Splitting our efforts this way will let us take full advantage of the
capabilities offered by each container environment.
At present this is impossible, because the same plugin has to run within
Netscape Navigator and Microsoft Internet Explorer.
Using extensions only works on Windows now.
We intend to make this work on Unix and Macintosh also.
- 7.5. How can I help?
Write more Tclets! Write web pages that refer to the plugin or contain
Tclets, write articles for newsgroups and magazines about the plugin, and
- 7.6. I hate Tcl; can I do a plugin with Tk for Perl, Python, or Scheme?
We're sorry you don't like Tcl. We don't think its that bad, really :).
Because the sources are available, you can take the plugin and retarget it
for Perl, Python or other languages.
Feel free to do so.
- 7.7. First Java and now Tcl? Isn't this confusing?
Check out our integration work on Tcl and Java, at
the Java pages.
We don't think it is confusing. Yes, we love Java. We intend for
Sun is fully committed to making Java the best it can be. A lot of
resources are going into making Java *the* natural choice for any
system programming task you might undertake in the near future.
Realistically, however, Java is not the solution to all the world's
problems just like C++ was not. There are tasks for which you do
not want to use Java, medium and small sized programs. Just like
you wrote some of your code in C/C++ and some in csh or awk or sed,
you can now do some of your work on the web in Java, and some other
parts are more a suitable in Tcl and Tk. We believe that where
computational efficiency really matters, you want to use Java (e.g.
doing joins on databases) but when you just want to display
something quickly, Tk is better.
- 7.8. I want to learn Tcl; what books should I read?
A list of books is available online
- 7.9. Other relevant Plugin Information ?
- 7.10. What other information about Tcl is available?
There's lots of resources available. Check the
Tcl Resource Center.