CXXTOOLS
[See also: CXXEDITOR.txt, CXXLIBRARY.txt, CXXDIRVIEWER, CXXCURSORWINDOWS.txt, and README]
CXX TOOLKIT
============
INTRODUCTION
============
The CXX TOOLKIT is a collection of C++ source code, libraries, programs, and bourne shell
scripts that can be used as you see fit. They were designed from the start to be free
and sharable with no strings attached -- though they are all copyrighted. See the
individual files and the 'copyright' file for more details. This is basically a "use as you
see fit but don't try to claim ownership of my work or sue me or get me sued" kind of
copyright.
===========
COMPILATION
===========
Linux
-----
To compile these tools on linux using the g++ compiler, take the following steps:
1. extract CXX.zip into some directory (CXX is the preferred name)
2. cd that directory
3. make
4. make install (will copy things to $HOME/bin and $HOME/.tools_home)
5. execute $HOME/bin/editor.exe
a. press enter when prompted to allow it to create the terminfo
Microsoft Windows
-----------------
To compile these tools on windows using the CL compiler, follow these step:
mkdir c:\\temp\\CXX
cd c:\\temp\\CXX
rem either use the winzip program to unpack the CXX.zip file into the
rem c :\\temp\\CXX directory, OR, find unzip.exe on the internet, and
rem use it like this:
rem
rem unzip -o \\<path>\\CXX.zip
.\\build.bat
At this point, editor\\editor.exe will exist and is executable. Run it once and
press Enter as needed to enable it to create %HOMEPATH%\\.tools_home.
Unix
----
To install the tools on other unixes, either build using g++, or the native compilers.
The make process is set up to build using the native compilers. Notice that in the top
level directory there is a rules.<OS> file for each supported unix. To use the g++
compiler on a given host, copy the rules.Linux file over top the existing rules.<OS> file.
Make any pathname customizations needed there.
Once this is done, just follow the Linux instructions, above.
==============================
LINUX/UNIX CURSES AND TERMINFO
==============================
The libraries and applications within the toolkit that perform text cursor positioning
use CURSES (or pdcurses on windows). The standard curses development kit must be
available on linux and unix. When the first first curses based program from the toolkit
is run, it will create
$HOME/.tools_home
Within that directory, a collection of sub-directories and files will be created (see
references below) containing various configurations.
The CURSES related configurations will appear in subdirectories named for the host machines
on which you run the program. That way, if your home directory is network based, the
configurations for each machine (and therefore its os type) will be kept separate.
The TIC program (Term Info Compiler) is used during that first run on a host to create
TERMIFO for the xterm that is slightly customized. The customization involves correcting
the function key bindings for modern PC keyboards (and is done blindly, regardless of
keyboard type).
Note that ON SUSE/SLES (ONLY!) there is a BUG in the TIC program. If you are user root,
it ignores the command line options and does not in fact create a LOCAL version of the
xterm terminfo (as instructed by the CXXTOOLS) but rather modifies the SYSTEM
WIDE terminfo. This modification does not seem to cause any trouble to either VI, EMACS,
or the cursor windowing tools used to make system configurations. The CXXTOOLS copies
the modified form to the .tools_home/<host>/terminfo directory.
Ifyou are a SUSE/SLES root user concerned about this modification but still want to use
these tools, perform the following steps:
1. before executing any of the tools, make a backup copy of directory
/usr/share/terminfo/x
2. run the editor.exe program to cause the modification. Press enter numerous times
to allow it to instlal.
3. copy the saved directory back into place.
During the installation, the tools will copy the temporarily modified terminfo into the
appropriate place.
Again, this is a bug in the SUSE/SLES TIC program and not a defect in the design of the
CXX toolkit.
======
EDITOR
======
[See CXXEDITOR.txt for more details]
The program, CXX/editor/editor.exe, is combination of the following:
* A cursor window based text editor that uses PC function keys as well as
control key sequences. It is analogous to VI, in behavior, but uses function
keys and popup menus to accomplish editing tasks.
* A directory browser
* A program data base browser.
* (On unix/linux) An extensible, table oriented script language interpreter.
The program uses curses on linux and console i/o on Windows to display files and allow
the user to edit text and/or browse files and directories. The EDITOR program can be
run as a stand-alone program but is designed to run as part of a script on unix/linux
that improves the utility by allow the editor to set the user's command line current
directory contentxt -- assuming the user pressed the appropriate keys to exit the editor.
See file CXXEDITOR.txt for more details.
===
LIB
===
The directories lib and include define a library of functions and templates that can be
used for portable program development. They are often thin wrappers around existing
O/S functionality that provides a unique but portable development environment.
These tools include
* a tiled, curses based text windowing system -- used in implementing the EDITOR.
* C++ classes that wrapper various system functionality:
* file.h wraps filenames and functions performed on them and data need to make
O/S calls that act on files or are returned by O/S queries about files.
* cursorwindow.h defines the cursor windowing classes and helpers.
* cpp_token_stream.h defines a C++ template function that parses C++ language
tokens from various kinds of buffers and streams
See include/*, lib/*,
===
BIN
===
A mix of usable programs and trivial test programs used to develop LIB. Usable programs
include:
* cca.cxx A cyclomatic complexity analyzer. See the script cca for more details.
* cpptagdb.cxx A C++ source code program database generator. The output is used
by EDITOR to let you quickly browse
=======
SCRIPTS
=======
A collection of helper scripts that can simplify your life when using git and svn.
This directory is a hodgepodge of somewhat useful tools that get copied into your bin
directory, if you execute "make install"
Note that the scripts directory provide a wrapper around an etags invocation, makeTags,
that generates takes starting in the current directory down, and makes use of an optional
configuration script, makeTags.dirlist, tht lets you select subsets of the directory
tree for tagging. The EDITOR knows how to use TAGS files generated by etags (and also
by cpptagdb.exe, see below).
There is another wrapper, makeCppTags, that runs the program, cpptagdb.exe, whose source
code is found in the bin/cpptagdb.cxx file. This form of tags file is designed specifically
for C++ programs (and only them).
===
STV
===
A collection of table viewer scripts that will be copied to ~/.tools_home/stv if you
run make install. These scripts implement the various extensions to the EDITOR that
let you browse git and svn information. All of the scripts support context sensitive
help.
=============
~/.tools_home
=============
The repository of CXX TOOLKIT personal configurations and tools. This directory
contains the following:
stv The directory into which the script table viewer scripts (STV in the make
directories) are copied to make them active for the user.
<hostname*> A collection of directories specific to the names of unix hosts
that the EDITOR has been executed on.
exitDir.txt A file containing the name of the directory that was active when the
user last exited the EDITOR using ^X^J. The purpose of this file is
to enable scripts which invoke the editor to figure out where you were
when you exited with ^X^J. If you exit in other ways this file is not
created or modified in any way.
<other*> Other files that CXX tools might create (or the STV/*.sh scripts).
