Tcl Plugin Frequently Asked Questions

FAQ Index

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 installed already.

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: -->
<font size="-1">
Are you ready to view these pages ? 
<embed type="application/x-tcl" 
src="/software/tcltk/plugin/javascript/upgrade.tcl"
align=absbottom bg="#ffffff" height=22 width=22>
<tt>&lt;-</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>
it!
</font>
<!-- End update checking section -->

1.7. How much does it cost?

The Tcl Plugin is available free of charge for any use, including commercial use.

1.8. Is source code available?

Yes, you can download the source code from our download pages.

1.9. Can I really use it in commercial applications?

Yes.

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 tclplugin-core@lists.sourceforge.net

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 tclplugin-core@lists.sourceforge.net.

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 tclplugin-core@lists.sourceforge.net 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!

Check whether your browser has Javascript enabled. This page is generated by a Javascript script, hence if it's disabled you'll see the blank page. In Netscape Communicator pull down the Edit menu, choose Preferences and click on Advanced. Make sure the check box for enabling Javascript 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 2.9 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 update 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 directly.

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:

• <yourHomeDirectory>/.netscape/plugins.
• /usr/local/lib/netscape/plugins.
• It also searches the directories specified in the NPX_PLUGIN_PATH environment variable.

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 libraries.

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?

Very simple:

• Write the Tcl program in a file, let's call it simple.tcl.
• Write an HTML file, let's call it simple.html, with whatever you want to appear in the page, plus one special statement:

  <embed src=simple.tcl width=120 height=35>
  

• Now visit the simple.html page with your browser, and you should see your very 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 version!

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 executed. 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 dangerous commands.

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 relax security.

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 language. 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 Man Pages.

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 your system. On Unix, this directory is most likely to be found in yourHome/.netscape/tclplug/2.0/config. On Windows, the directory is likely to be at c:\tclplug\2.0\config.

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 we provided. 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 policies section.

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. Check out how we do this for the Javascript policy.

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. Extensibility.

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 program.

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, below.

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 Macintosh soon!

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 so forth.

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 the plugin to be able to talk to Java and Javascript, real soon. 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 here.

7.9. Other relevant Plugin Information ?

• Ajuba Solutions' plug-in pages
• Laurent Demailly's plug-in pages
  Laurent was one of the original plug-in developers.
• Known problems list

7.10. What other information about Tcl is available?

There's lots of resources available. Check the Tcl Resource Center.

This is the main Tcl Developer Xchange site, www.tcl-lang.org .    About this Site | webmaster@tcl-lang.org
Home | About Tcl/Tk | Software | Core Development | Community | Documentation