Getting Started Tutorial

This chapter describes the first steps with XOTclIDE. You will learn how to write your first XOTclIDE application, how to safe it and reload it.

Developing First Application - Tutorial

In this section you will learn how to manage the base tasks of programming with IDE. How to create new project (component) how to append new source, save it and reload it. It assume base knowledge in Tcl and programming tools and is was designed for normal Tcl-Programmer (or XOTcl Programmer).

Starting XOTclIDE

Change in your working directory and start XOTclIDE.tcl from it. Command line to start XOTclIDE its depending on your installation here an example for Linux RPM installation. By Windows system you can just click on XOTclIDE.tcl.

[artur@rybnik xotclIDE]$ tclsh /usr/local/lib/xotclIDE/XotclIDE.tcl
[artur@rybnik xotclIDE]$ /usr/local/lib/xotclIDE/XotclIDE.tcl
After loading two windows appear. The one it so called Transcript window with welcome message that is used for display system messages and evaluate short scripts. The second window is Component Browser the main browser using to explore and modify your system structure (program code).

Component Browser is divided visually into 4 areas (panes) : Component, Classes/Object/Tcl Procs Groups, Categories, Methods and Text Editor. Each area have its corresponding menu. The four upper list-views correspond to source code structure in XOTclIDE. The main structure is component. A Component has specific name and is a container for Classes, Objects and Tcl-Procedures-Groups. Every Class can have instance- or class methods. These methods can be group together in categories. Also standard not object oriented Tcl procedures can be a part of component. They are grouped in so called Tcl-Procedures-Groups. Tcl-Procedures can not belong to categories. In this way you can structure in 3 level system your whole code and it can be used to practice component oriented programming (More Information the Section called Building an Application in the chapter called Programming with XOTclIDE).


Select component IDECore in Components list view. In Class/Objects list view all classes contained in this component will be listed. Select class IDE::Component in Class/Objects list view. Select category _all_categories in Categories list view. Select method getObjectDefineList in Methods list view. In the editor area appear the body (source code) of this method. You should see the browser as on screen-shoot Figure 1. The blue background of the right lower button Source indicate that this method have programmer comment. Press it to see this comment. The editor changes to comment view. Press it again to change back to source view. Press button Classes in the Class/Objects list view to see another elements of this component.

Figure 1. Component Browser

Creating new Components

Programming in XOTclIDE is component oriented. Assuming that you want to write simple program as follow.

# This procedure dump elements of global array Tcl_platform
# to file with name specified by parameter "file"
proc generateTclPlatformProtocol {file} {
    global tcl_platform
    set fhandler [open $file w]
    foreach key [array names tcl_platform] {
       puts $fhandler "$key = $tcl_platform($key)"
    close $fhandler

generateTclPlatformProtocol tclPlatform.log
A regular Tcl-Programmer would open his favorite editor type a text and save it as Tcl script. Perhaps he would not create the procedure generateTclPlatformProtocol but program it directly in global context as follow
set fhandler [open  tclPlatform.log  w]
foreach key [array names tcl_platform] {
    puts $fhandler "$key = $tcl_platform($key)"
close $fhandler
It can be good for small scripts but if you want to program bigger systems or reuse your code you will prefer as good programmer to write a Tcl-package like this
package provide PlatformLogDumper 0.1
# This procedure dump elements of global array tcl_platform
# to file with name specified by parameter "file"
proc generateTclPlatformProtocol {file} {
    global tcl_platform
    set fhandler [open $file w]
    foreach key [array names tcl_platform] {
       puts $fhandler "$key = $tcl_platform($key)"
    close $fhandler
You need also to create a file pkgIndex.tcl and place the directory of it in Tcl auto_path global variable. You can use the package as follow
package require PlatformLogDumper
generateTclPlatformProtocol tclPlatform.log
consider the package is only the functions library the function call will be done in higher level.


XOTclIDE Components act for Tcl as normal packages. They contains additional XOTclIDE special meta informations that are handled by XOTclIDE.

Lets make make a first Component. Choose menu Component->New from Component Browser. In the dialog enter the name of component "PlatformLogDumper" and apply dialog. After this your new component would appear in the list of component. Read next section to find out how to add procedures to this component.

Adding Tcl procedures

Your new created component appear in the Components list view. Select it. Now create new Tcl-Procedures-Group with menu Class->Tcl Procs Group->New Group. Type in the dialog the name of the group.

The name of new created Tcl-Procedures-Group appear in the Class/Objects list view. Select it. New you can create a your procedure. Select menu Method->New Method Template In the editor window appear the template of Tcl procedure as follow.

proc procName {args} {
  # enter the body here
Please type your procedure. If you are ready you must apply the procedure to the interpreter. Use menu or key accelerator Edit->Save/Apply (Control-s) You should see your Component Browser as follow Figure 2

Figure 2. Create Component

If you want to set comment for this procedure press the button Source in the right lower edge of edit area. The editor change the view to comment view. You can type the command and apply it with Edit->Save/Apply (Control-s)

Interactive work with procedures

The main advantage of XOTclIDE is that it is not only editor for Tcl scripts but it "sit" directly on Tcl-Interpreter. Tcl for XOTclIDE is the same as Lisp for Emacs. So you can try (invoke, call) procedure just after you define it. So select the procedure and choose the menu Method->Invoke You will be ask to specify the parameters of procedure call. In Tcl everything is string so it is not problem just to type the parameters in the dialog as Tcl words (e.g "2 {2 3}" are two parameters)

Figure 3. Invoking Procedures

The result of this invocation is returned as result text. If the result is XOTcl object or XOTcl objects lists when object inspector will be displayed. If the result is an empty string then special message box is shown.

Saving Component in File System

To save a component in file system you can use menu in Component Browser Component->Save Components. In the dialog box select your component and check the button create pkgIndex (see Figure 4).

Figure 4. Saving Components

After accepting dialog one package file PlatformLogDumper.xotcl is saved in actual directory. The file should look as follow.
# automatically generated from XOTclIDE
package provide PlatformLogDumper 0.1
@ tclproc generateTclPlatformProtocol idemeta struct \
PlatformLogDumper MyGroup
proc generateTclPlatformProtocol file {
    global tcl_platform
    set fhandler [open $file w]
    foreach key [array names tcl_platform] {
       puts $fhandler "$key = $tcl_platform($key)"
    close $fhandler
The component was saved as "regular" Tcl package. The one difference is the line beginning with @. It is XOTcl notation for meta-data and it is used in XOTclIDE to code additional structure information. If you want to use this package from pure Tcl you can check the button no meta data @ before saving component or define dummy proc to ignore this line as follow
proc @ args {}
The checked option create pkgIndex have caused the generation of pkgIndex.tcl in this directory
# Tcl package index file, version 1.1
# This file is generated by the "pkg_mkIndex -direct" command
# and sourced either when an application starts up or
# by a "package unknown" script.
 It invokes the
# "package ifneeded" command to set up package-related
# information so that packages will be loaded automatically
# in response to "package require" commands.
 When this
# script is sourced, the variable $dir must contain the
# full path name of this file's directory.
package ifneeded PlatformLogDumper 0.1 \
[list source [file join $dir PlatformLogDumper.xotcl]]
In this index file appear all packages from directory with filename pattern *.xotcl.

Using Components without XOTclIDE

For Tcl XOTclIDE components are normal Tcl packages. To use them from Tcl scripts you need first to register the package in Tcl package system by setting auto_path global variable and if you do not use XOTcl to define dummy procedure to ignore @ lines. Here a sample usage from tcl shell.

[artur@localhost own_oxtcl]$ tcl
tcl>proc @ args {}
tcl>lappend auto_path .
/usr/share/tcl8.3 /usr/share /usr/lib /usr/share/tclX8.3 .
tcl>package require PlatformLogDumper
tcl>generateTclPlatformProtocol out.log

Loading Component from File System

To load a component into XOTclIDE use menu. Component->Load Package If you do not see the your component in package list than you must assure that Tcl can find the package. The list is generated by using package names command. XOTclIDE add current working directory to auto_path at start time. Also if you want to load the your package change into the directory with your packages before starting XOTclIDE.

In normal case you do not need to worry about how the components are save or load in file-system and also how is the text representation of whole component (component as script). You can install you component in Tcl distribution subdirectory. Read Tcl package command manual to get more about package mechanism in Tcl.


It can be quite tricky to force Tcl to find and load package you need. Some people say even about "Package Hell". The package list are also build only once and can not be rebuild if you change package dynamic. You need to restart XOTclIDE to load packages you have just created. You would not have this problems if you use Version Control.

Creating Configuration Map and distribute program

The components in XOTclIDE have a characteristic of function- or class libraries in another system. You can build your application as one or set of components. To specify a application you need not only definition scripts but also the application starting script also a line like this

generateTclPlatformProtocol out.log
you can of course write you own start script as follow and save it as file
lappend auto_patch $pathToComponentFile
proc @ args {}
package require PlatformLogDumper 
generateTclPlatformProtocol out.log
To group components together and specify start script you can used so called configuration maps. The configuration map specify

  • Components to load (the order to load and how they should be loaded from file-system or version control system)

  • preStartScript - a script that will be evaluated before loading component

  • startScript - a script that start the application

The configuration map can be also used to deploy an application


In another IDEs "configuration map" correspond to project or "solution map".

To specify configuration map you use the Configuration MapBrowser that can be started per menu System->Configuration Map Browser.

Figure 5. Configurations Map Browser

Do not forget to apply start script per Edit->Save/Apply (Control-s). After defining ca configuration map you can safe it as configuration map file (with extension cfmap).

You can set this configmap file as start parameter of XOTclIDE so all components from this configuration map are loaded at starting time.

[artur@localhost own_oxtcl]$ XotclIDE.tcl -- -configmap platformLogDumper.cfmap
If you develop big application it is good idea to define a configuration map and use it as start parameter. (see the Section called Configuration Management and Deploying in the chapter called Programming with XOTclIDE for more informations)

Evaluating Short Tcl Scripts

Tcl is often used by short ad hoc programs called scripts (Scripting Language). Scripts are often sequence of simple Tcl commands that are evaluated in global context. Often no procedures are defined in such scripts.

Every Editor Text Area in XOTclIDE have ability to evaluate short scripts. To run (evaluate) the script just select the script text and invoke the evaluation with pop-down menu (Right mouse-button) or menu Editor.

You can load and manage your scripts be using so called Workspaces. To open a Workspace use menu System->Workspace It is simply text area (simple Editor) that can be used to type scripts save or load them from file system. It can be also used as a temporary "scratch pad", to enter and evaluate expressions during the process of testing new method definitions.

Figure 6. Workspace

Advanced Usage: Overview

The tutorial above describes how to get first result with XOTclIDE. But the main advantages of this system can be seen by using advanced techniques of XOTclIDE. That are:

Version Control System

integrated object oriented version control system let you track all changes in project and restore old versions (the Section called Version Control System in the chapter called Extended Features).

Object orientation with XOTcl

XOTclIDE was developed primary to support object oriented development with XOTcl. Many futures as object inspector are XOTcl specific

System Introspection

XOTclIDE let your to inspect and change all object and variables in system


With extended debugger extension you can debug you program with professional system. Conditional breakpoints, program stepping, program stack introspection are possible (the Section called Debugging in the chapter called Extended Features).