[ Main Table Of Contents | Table Of Contents | Keyword Index ]

linenoise_install_guide(n) 1 doc "Tcl Line Editor"


linenoise_install_guide - Linenoise - The Installer's Guide

Table Of Contents


Welcome to Linenoise, a binding to Antirez's linenoise minimal line editor library, as modified and extended by Steve Bennet of Workware.au

The audience of this document is anyone wishing to build the package, for either themselves, or others.

For a developer intending to extend or modify the package we additionally provide

  1. Linenoise - License.

  2. Linenoise - The Developer's Guide.

Please read Linenoise - How To Get The Sources first, if that was not done already. Here we assume that all the sources are already available in a directory of your choice.


Before Linenoise can be build and used a number of requisites must be installed. These are:

  1. The scripting language Tcl. For details see Tcl.

  2. The critcl package (C embedding) for Tcl. For details see CriTcl.

  3. The kettle package and application for Tcl. For details see Kettle.

This list assumes that the machine where Linenoise is to be installed is essentially clean. Of course, if parts of the dependencies listed below are already installed the associated steps can be skipped. It is still recommended to read their sections though, to validate that the dependencies they talk about are indeed installed.


As we are building a Tcl package that should be pretty much obvious that a working Tcl installation is needed, and I will not belabor the point.

Out of the many use whatever you are comfortable with, as long as it provides Tcl 8.5, or higher.

This may a Tcl installation provided by your operating system distribution, from a distribution-independent vendor, or built by yurself.

Myself, I used ActiveState's ActiveTcl 8.5 distribution during development of the binding, as I am most familiar with it.

(Disclosure: I, Andreas Kupries, work for ActiveState, maintaining ActiveTcl and TclDevKit for them).

This distribution can be found at http://www.activestate.com/activetcl. Retrieve the archive of ActiveTcl 8.5 for your platform and install it as directed by ActiveState.

Assuming that ActiveTcl got installed I usually run the command

    teacup update

to install all packages ActiveState provides, and the kitchensink, as the distribution itself usually contains only the ost important set of packages. This ensures that the dependencies for Critcl are all present, and more.

If that is not to your liking you have to read the sections for Critcl to determine the exact set of packages required, and install only these using

    teacup install $packagename

Both teacup commands above assume that ActiveState's TEApot repository at http://teapot.activestate.com is in the list of repositories accessible to teacup. This is automatically ensured for the ActiveTcl distribution. Others may have to run

    teacup archive add http://teapot.activestate.com

to make this happen.

For those wishing to build Tcl/Tk on their own, their sources can be found at






To build the linenoise binding the tool critcl is required.

The build system accept it either as an application found in the PATH, or as a Tcl package available to the tclsh used to run their build & installation processes.

We must have version 3.1 or higher.

Its github repository can be found at http://andreas-kupries.github.com/critcl.

At the above url is also an explanation on how to build and install CriTcl, including a list of its dependencies.

Its instructions will not be repeated here. If there are problems with their directions please file a bug against the critcl project, and not tcl-linenoise.


To build Linenoise the build support package kettle is required.

This package must be available to the tclsh used to run Linenoise's build & installation process, and the tclsh used to run scripts requiring Linenoise.

Kettle's fossil repository can be found at http://chiselapp.com/user/andreas_kupries/repository/Kettle/home.

The relevant repository branch is trunk.

Kettle has a build and installation guide much like this one for Linenoise, which can be found at the above site and explains how to retrieve its sources and build the package, which dependencies are required, etc. The direct link to this guide is http://chiselapp.com/user/andreas_kupries/repository/Kettle/doc/tip/embedded/www/doc/files/kettle_installer.html

Its instructions will not be repeated here. If there are problems with their directions please file a bug against the kettle project, and not Linenoise.

Build & Installation

To install linenoise simply run

    /path/to/tclsh /path/to/tcl-linenoise/build.tcl install

where "/path/to/tclsh" is the tclsh of your Tcl installation, and "/path/to/tcl-linenoise" the location of the binding's sources on your system. The linenoise sources on the other hand are expected to be either a sibling directory to the binding's sources, or a sub-directory in it. Regardless of location, this directory has to be named "linenoise".

This builds the package and then places it into a directory where the tclsh will find them.

On Windows you can invoke the file "build.tcl" with a double-click. This will pop up a small graphical interface for entering the destination and performing the installation. This handling of a double-click is restricted to Windows only however.

On unix the same GUI is acessible by invoking "build.tcl" with the argument gui.

To get help about the methods of "build.tcl", and their complete syntax, invoke "build.tcl" with argument help, i.e., like

    /path/to/tclsh /path/to/tcl-linenoise/build.tcl help

Build Variations

The previous section assumes that the underlying linenoise C library sources were taken from http://github.com/andreas-kupries/linenoise. If the C library came from http://github.com/msteveb/linenoise instead then hidden input, i.e. password prompts and the like are not supported. To disable the support in the binding simply edit the file "linenoise.tcl" and change the setting of the flag variable hashidden to false. The remainder of the binding adapts automatically.


Andreas Kupries (Tcl Binding), Steve Bennett (extended linenoise C library), Salvatore Sanfilippo (Antirez, original linenoise C library).

Bugs, Ideas, Feedback

This document, and the package it describes, will undoubtedly contain bugs and other problems. Please report them at the Issues tracker. Ideas for enhancements you may have for either package, application, and/or the documentation are also very welcome and should be reported at the Issues tracker as well.


console, edit line, line editor, line reading, linenoise, raw mode, read line, terminal, tty