INSTALL: Installation instructions for XMLterm source code ---------------------------------------------------------- *NOTE* This is work in progress. User beware! *NOTE* Check the XMLterm web site for updates. 15 Mar 2000 QUICK BUILD INSTRUCTIONS (Linux/Solaris) ---------------------------------------- If you have already built mozilla from the source, then type the following commands in the "mozilla" directory to build XMLterm: a) configure --with-extensions=xmlterm b) cd extensions/xmlterm c) make [Skip step (b) for a fresh build of mozilla from the source tarball] To execute XMLterm, type one of the following commands in the mozilla/dist/bin directory: ./xmlterm OR ./mozilla -chrome chrome://xmlterm/content/xmlterm.xul DETAILED BUILD INSTRUCTIONS --------------------------- In the following discussion, file and directory names are relative to the main ("mozilla/extensions/xmlterm") directory. See the end of the README file for a brief description of the subdirectories. 1. Source tree (skip this step if XMLterm is already in the source tree) ------------------------------------------------------------------------ The XMLterm source code is distributed as a tarball "xmlterm.tar.gz" This tar file needs to be untarred in the "mozilla/extensions" directory. A subdirectory called "xmlterm" will be created there. ("mozilla" denotes the root directory of the Mozilla source tree) If you have already untarred it elsewhere, simply move the "xmlterm" directory to the right place. 2. Configuration ---------------- To recursively create all Makefiles from Makefile.in files, type the following in the "xmlterm" directory: config/makemake -r The file "config/xmlterm_config.mk" contains XMLterm specific configuration information that is needed in addition to any Mozilla configuration information. It has already been hand-configured for Linux2.0/Linux2.2, and Solaris2.6 platforms. It may need to be modified slightly to compile XMLterm on other platforms. At present, XMLterm has been tested only on Linux (RedHat6.0) and Solaris2.6 platforms, using the M11 release as the base version of Mozilla. XMLterm typically uses the UNIX pseudo-TTY interface to communicate with the shell. This interface is implemented only for Linux and Solaris platforms at the moment. XMLterm may compile on other Unix platforms, but it will use NSPR pipes, rather than a pseudo-TTY, for process communication; this means that the terminal control characters, such as Control-C for interrupting jobs, will not work on those platforms. (See the file doc/PORTABILITY for a discussion of portability issues) 3. Creating the dynamically loaded XPCOM/XPCONNECT component ------------------------------------------------------------ To create the dynamically loaded XPCOM library, type the following in the "xmlterm" directory: make all This creates the self-registering library "libxmlterm.so" and installs it in the "mozilla/dist/bin/components" directory, along with some chrome files. After this step, the following interfaces become accessible in Mozilla through XPCOM/XPCONNECT: mozIXMLTermShell (interface to XMLterm) mozILineTerm (interface to the stand-alone LINETERM) To clean up completely, type make clean 4. Running XMLterm using mozilla -------------------------------- At this time, XMLterm cannot be accessed through the menu bar. After Step 3, execute the following command in the "mozilla/dist/bin" directory: ./xmlterm "xmlterm" is shorthand for the following command, which you may also execute directly ./mozilla -chrome chrome://xmlterm/content/xmlterm.xul The above command(s) should create an XMLterm window. Click on that window with the mouse to give it focus and start typing UNIX commands. **NOTE** The command prompt is assumed to be terminated by one of the characters "#$%>?", followed by a space. If this is not the case, many features will not work. This restriction will be relaxed in the future. The command line can be edited using EMACS-style key bindings. Command completion should also work with TCSH and BASH, as should history recall. By default, blue coloring is used to indicate clickable display elements. Note that the prompt and the input command line are clickable. (Of course, the appearance of XMLterm is completely configurable using the CSS stylesheet chrome://xmlterm/skin/default/xmltpage.css) After typing one or two commands, click on the prompt string of any previous command to see what happens! Then click again on the same prompt string. Also click on "Hide all output" button at the top of the document. Double-clicking is used to activate all XMLterm features, *except* for command prompts and underlined hyperlinks, which are activated by a single click as in a browser. Double-clicking on a previous command line (to the right of the prompt) re-executes the command. Be warned that double-clicking a command line can profoundly affect your computing environment, depending upon what the command is. The sample Perl script "xls", the iconic/hypertext version of the Unix "ls" command, is in the "scripts" directory. Also in the "scripts" directory is "xcat", an XMLterm-aware version of the "cat" command. 5. Setting the path ------------------- To use XMLterm most efficiently, add the mozilla binary directory (mozilla/dist/bin) to your execution PATH variable by modifying your shell initialization file (.profile/.cshrc). This will enable you to use commands such as "xmlterm", "xls", and "xcat" easily. 6. Stand-alone mode (optional) ------------------------------ Although XMLterm resides in the Mozilla source tree, portions of it are capable of being compiled and linked completely independent of Mozilla. You may want to do this for testing purposes. The "config" directory contains make files that are used for this stand-alone mode. There is even a dumb script called "makemake" which can be used to re-create make files, if the corresponding Makefile.in files have been changed. *NOTE* The executable "lterm" requires the NCURSES include file "curses.h" To create the stand-alone executables, type make STAND_ALONE=1 all (To clean up stand-alone modules, type "make STAND_ALONE=1 clean") This creates the stand-alone library in "base/lib" and some stand-alone executables in the "linetest/lib" directory, in particular, one called "lterm". The executable "lterm" implements a line terminal (LINETERM), i.e., a non-graphical version of XMLterm. In the future, this may be implemented using NCURSES for full screen operation. At present, it only provides line-at-a-time functionality and is used only for testing. LINETERM acts as an "engine" for XMLterm, carrying out all the non-graphical tasks, completely independent of Mozilla. It is written in C and is licensed under both MPL and GPL. It provides functionality similar to the EMACS shell mode or the GNU readline package. LINETERM has various options where trace output may be redirected to a different TTY device, for debugging purposes. LINETERM may be used like the shell command "sh", e.g., prompt% lterm prompt% ls prompt% exit The "tests/escape" program can be used to generate terminal escape sequences to test the XMLterm API. In particular, the following command enables extensive trace output, if executed within an XMLterm or LINETERM: tests/escape 1 98 D -----------------------------------------------------------------------------