This file describes how to configure, build, and use this source tree. -------------------------------------------------------------------------- COPYRIGHT / LICENSE INFO This source is copyrighted source distributed under the terms of GPL (the GNU General Public License). Parts of this code has been derived from previous GPL and/or other open-source distributions. These parts can be found in the following libraries: libgzip GZIP compression library (Jean-loup Gailly & Mark Adler). For details, see the file "libgzip/zlib.h". libmagic MAGIC file processing (Ian F. Darwin). For details, see the file "libmagic/libmagic.h". libdiff GNU DIFF program (various authors). For details, see the file "libdiff/diffsys.h". libutils REGEXP processing (Henry Spencer). For details, see the file "libutils/utregexp.c". libform FORM processing under curses (Juergen Pfeifer). This library is not used by this source, but is included to provide a complete curses implementation. For details, see the file "libform/form.h". libmenu MENU processing under curses (Juergen Pfeifer). This library is not used by this source, but is included to provide a complete curses implementation. For details, see the file "libmenu/menu.h". libpanel PANEL processing under curses (Zeyd M. Ben-Halim & Eric S. Raymond). This library is not used by this source, but is included to provide a complete curses implementation. For details, see the file "libpanel/panel.h". libxpm XPM library (XFree86 source distribution) This library is only used by libxvt if USE_XPM is defined, which allows pixmap (*.xpm) files to be specified for icons. For details, see the file "libxpm/xpm.h". Note that the code in these libraries have been seriously hacked from their original form, mostly to convert them from a single-use program to a general-use library, and to use our malloc-interface. -------------------------------------------------------------------------- GENERAL NOTES 1. All files in this source tree were created using a TabStop of 4. If you are using "vi" to view these files, use the cmd "set ts=4" to set the TabStops correctly. (You can also put that cmd in your ~/.exrc file to have it always in effect.) The only exceptions are the CHANGES file, the text files in the support directory, and the term-files in the termfiles directory, which are delivered to the user, so they have a "standard" TabStop of 8. 2. The source files in this tree are all written using ANSI C. To compile this source, your C compiler MUST be an ANSI-compliant compiler. There are enough of them out there (including GNU), and the ANSI standard has been out there long enough, that this *should* not be an issue. (Although you know the difference between theory and practice: in theory there is no difference.) If your compiler is not ANSI-compliant, join the real world and get one that is. If you don't want to pay for one, you can always download the GNU compiler source (from www.gnu.org) and build it yourself, or there are sites with pre-built versions of the GNU compiler can be downloaded. Of the platforms which I have built this source on, the only platforms I found that do not have a native ANSI compiler are SunOS and HP. I use the GNU compiler on both of these platforms. 3. You MUST set the variables BUILDER_NAM & BUILDER_EMA in bldinfo. These variables provide the name & email address of the person who built that package. In this way, we can look at a build and know who built it. This is very important when the source is available to anyone who wants to do a build & distribute it. Note that the "-ZV" option displays this information, as well as the description of the platform it was built on. -------------------------------------------------------------------------- WINDOWS BUILD NOTES 1. If you are building this tree in Windows, you MUST have the either the MKS ToolKit or the CYGWIN package installed. The make process assumes the use of a "shell" similar to the Bourne/Korn/Bash shells to execute scripts and commands in the makefiles, and uses "make" rather than "nmake". I highly recommend the MKS toolkit for anyone doing Unix/Windows cross-platform development. I could not live without it. Nuff said. The CYGWIN package can be used to do the build, but if you use the gcc system included with it instead of the Microsoft development package, you cannot access all the capabilities of Windows, such as mouse & color support and low-level file-system support. 2. This source assumes the use of the Microsoft development platform. I do not know if it will work using any other package (Borland, etc.). Specifically, I detect we are compiling in Windows by checking for the manifest constants _MSC_VER or _WIN32. If your compiler defines a different manifest constant, then put either -D_MSC_VER or -D_WIN32 in the CDEFS entry in the winx86.env file. Note that using "gcc" under "cygwin" results in compiling the source as if it were in Unix. 3. This code also assumes the use of sub-threads, so be sure to specify whatever compiler options are necessary to turn on multiple-thread support and link with any needed multi-thread libraries. -------------------------------------------------------------------------- BUILD SCRIPT Due to the differences between Unix platforms (what to speak of Windows), a "build environment" must be setup prior to running the make. To setup this environment, the script "build" must be "sourced" first: $ . build [options] <platform> The "build" script is invoked with a platform-name as the argument, which tells it which "env" script to use. The platform-specific "env" scripts are found in the env directory as "env/<platform>.env". If <platform> is not specified, then the build script will try to guess the platform, using the "guess.sh" script. See the "guess.sh" script for details. Examples: To do a "debug" build for the "Solaris" platform, do the following: $ . build -d solaris $ make To do a "release" build for the "Linux" platform, do the following: $ . build -r linux $ make The "build" script sets up various environment variables which are common for a particular operating system (Unix or Windows), and the "env" script sets up those environment variables which are particular to a specific platform. To create an "env" script for a new platform, you can start by copying the "env" script for a similar platform, and changing whatever entries are different. A suitable entry should then be added to the "guess.sh" script to use that platform. See the "build" script for more complete documentation as to what environment variables are possible/required to be set. The following platforms currently have "env" scripts: platform O/S name O/S Architecture Notes -------- ------------ ---- ------------- ------------------- aix IBM AIX SVR4* rs6000/ppc alpha Digital/ux SVR4 alpha dg88 DG/ux SVR4 88k Not tested lately dg86 DG/ux SVR4 x86 freebsd FreeBSD BSD x86 hp HP/ux SVR4 pa/risc Native cc not ANSI i386v3 generic SVR3 SVR3 x86 i386v4 generic SVR4 SVR4 x86 linux Linux SVR4* x86 ncr ATT/NCR SVR4 x86 netbsd NetBSD BSD x86 osx Mac OS/X BSD powerpc No X-Windows avail os5 SCO OpenServer SVR3 x86 sgi IRIX SVR4 mips Not tested lately solaris Solaris SVR4 sparc solaris64 Solaris SVR4 sparc 64-bit sunos SunOS BSD sparc Native cc not ANSI Not tested lately sunx86 Solaris SVR4 x86 uw SCO UnixWare SVR4 x86 winx86 Windows Win x86 Need MKS ToolKit Uses MSVC. cygwin Windows Win x86 cygwin version Uses MSVC. cygwin-gcc Windows Win** x86 cygwin-gcc version Uses gcc. * This kernel is not SVR4, but it behaves like SVR4: aix uses the "mach" kernel linux uses the "linux" kernel ** The cygwin-gcc system runs under Windows, but behaves like Unix and requires the presence of the cygwin1.dll, which provides the Unix/Windows interface. I opted for this "env-file" mechanism as opposed to the GNU "configure" mechanism, since I have experienced too many "autoconf" failures using GNU builds, and we have too many options which a "configure" would not detect. Also, very few systems have autoconf (and related binaries) installed on them. Note that, before sourcing the appropriate env file for a platform, the build script will source the file "build.pre" if found. This allows a user to set personal stuff, such as a PATH, etc, prior to the actual setup. Also, if the script "build.post" is present, it is sourced after the build script is finished. -------------------------------------------------------------------------- MAKEFILE The top-level makefile has the following targets: Build targets: all Builds everything. install Builds everything and installs all files into the $INS_DIR directory. Note that this installs all files which would be put in either the $DST_DIR or $UTL_DIR directories. deliver Builds everything and delivers all normal files to the $DST_DIR directory, the utility programs to the $UTL_DIR directory, and the ecurses library to $WIN_DIR. bundle Packages up all files in $DST_DIR and creates a deliverable package into $SKU_DIR. Linux $PROGRAM-$SKU.tar.gz All other Unixes $PROGRAM-$SKU.tar.Z Windows $PROGRAM-$SKU.zip The deliverable consists of a compressed tar file (or zip file if in Windows). It may also create a platform-specific installable. Currently, the only platform-specific installables are: pkgadd $PROGRAM-$SKU.pkg.Z for SVR4 systems rpm $PROGRAM-$SKU.rpm for Linux Also packages up all files in $UTL_DIR and creates the following deliverable: Linux termutils-$SKU.tar.gz All other Unixes termutils-$SKU.tar.Z Windows termutils-$SKU.zip (cygwin-gcc only) Also packages up all files in $WIN_DIR and creates the following deliverable: Linux libecurses-$SKU.tar.gz All other Unixes libecurses-$SKU.tar.Z Windows libecurses-$SKU.zip sku Builds & delivers everything and produces SKU bundles. (Same as "deliver bundle".) Clean targets: notarget Deletes all linked executables. clean Cleans everything (except the SKU directory). clean-dist Cleans all distribution directories (except the SKU directory). Listing targets: srclist Creates a sorted list of all source files in the tree by invoking "make srclist" in all sub-directories. Output goes to stdout. src.list Same as "make srclist >src.list" fndlist Creates a sorted list of all read-only files (presumably the actual source files) via the "find" command. Output goes to stdout. fnd.list Same as "make fndlist >fnd.list" cmslist Creates a sorted list of all source files checked-in via the CM system in use. (I use perforce, which I highly recommend for anyone doing cross-platform development. See www.perforce.com for information.) Output goes to stdout. cms.list Same as "make cmslist >cms.list" Other targets: srcsku Delivers the source as an SKU into $SKU_DIR. It delivers two different source SKUs: $PROGRAM-source-$VERSION.$RELEASE.tar.Z $PROGRAM-source-$VERSION.$RELEASE.tar.gz Note that the source is "tarred" up as if it were in the directory "$PROGRAM-$VERSION.$RELEASE". lint Runs lint on all source files (produces lots of output). xrflist Creates a cross-reference list of names in all object files. Output goes to stdout. xrf.list Same as "make xrflist >xrf.list" The final output of the build procedure are the SKU packages which are delivered to $SKU_DIR. These packages are the files distributed to users for installation. I use the targets srclist/fndlist/cmslist to create the list of all files in the tree and to validate that everything used is actually present and checked-in to the CM system. For example, I do a "make src.list cms.list" and then do a "diff src.list cms.list" to verify that everything is checked-in. You can create a tar file of the entire source with the cmd "tar cvf source.tar `make srclist`". The "xrflist" target is handy in generating a list of all names which can be easily "grepped" to locate procedure/data instances/references. See the file "bin/xrfobjs" for details on the contents of this file. -------------------------------------------------------------------------- PRODUCING A SKU The final output of building the source is an SKU ("stock-keeping-unit") which can be distributed to users. An SKU consists of a single file which contains the entire distribution for a platform and is designed to be installed via some install mechanism. Unfortunately, there is no "standard" in Unix for installing packages, so the default SKU is a compressed "tar" file which can be "extracted" into a directory using "tar" (after being uncompressed). The Windows build produces a "zip" file. For systems which have a "standard" for that system, we produce additional platform-specific SKUs for that platform (see below). To produce a SKU for a particular platform, you would do the following: $ . build -r <platform> $ make sku This will produce one of the following files in the SKU directory ($SKU_DIR): Linux $PROGRAM-$SKU.tar.gz All other Unixes $PROGRAM-$SKU.tar.Z Windows $PROGRAM-$SKU.zip The $SKU name for a particular platform is set in the "env" file for that platform. We use the standard of "<architecture-name>-<os-name>". For example, for Linux on Intel, we use "x86-linux". We use "compress" on all Unix platforms (which produces *.Z files) except Linux, where we use "gzip" (which produces *.gz files). This is because "gzip" is always present on Linux and is the standard there, but is not usually available on other platforms. Note that "gzip" will uncompress files produced by "compress". The Windows files "*.zip" can be "extracted" using any of the available Windows programs, such as "pkzip", "winzip", etc. This command will also produce a platform-specific installable for selected platforms. These are as follows: Linux $PROGRAM-$SKU.rpm uses "rpm" to install SVR4 Unixes $PROGRAM-$SKU.pkg.Z uses "pkgadd" to install Note that for testing purposes, you can "cd" to the $DST_DIR directory and run the program. The files there are the complete set of files which are packaged up. -------------------------------------------------------------------------- TERMINAL-CAPABILITIES DATABASE CONFIGURATION (Unix only) This section is to aid in figuring out how to setup the terminal-capabilities database configuration for a new platform. The biggest difference in terminal processing between various Unix platforms is in the terminal database used. There are two different terminal databases used in Unix: "termcap" and "terminfo". termcap database: The "termcap" database consists of the text file /etc/termcap or /usr/share/misc/termcap. In general, the "termcap" database is used in BSD systems. terminfo database: The "terminfo" database consists of "compiled" terminfo files kept in a terminfo directory (usually /usr/share/lib/terminfo), with all "a*" entries going into <terminfo-dir>/a/a*, etc. OS/X on the Mac uses the naming convention /usr/share/lib/<hh>/<name>, where <hh> is the hex representation of the first character in <name>. In general, the "terminfo" database is used in SYSV systems (SVR3 & SVR4). To make things more complicated, the syntax of the parameterized strings and padding information is different between the two systems, so you cannot provide your own versions of strings without knowing which type of system you are using. Currently, the only platforms which use "termcap" are *BSD, and SunOS, which are all BSD-based systems. Note that most other Unixes do provide termcap (and the /etc/termcap file), but do so by "emulating" the termcap routines via terminfo. We do not use the "standard" curses library, but use our own version of it. This is because "standard" curses varies between different platforms, and no version provides all the functionality needed (such as defining all function-keys, color capability, and mouse capability). Also, obviously, there is no "curses" library available for Windows (before now). Our version of the "curses" library is the "ecurses" (extended-curses) library. The "ecurses" library provides a super-set of the standard "curses" functionality, and *should* be plug-and-play with any program written which uses "curses". By providing this library (and all the headers included in it), you can substitute this version with the standard version (of course, you must re-compile any program using the provided headers). The "ecurses" library will support both types of databases, and can switch between them at run-time. The default behavior is to "auto-detect" which type is in use, by first trying to load a "terminfo" entry, and, if that fails, trying to load a "termcap" entry. Regardless of which database entry type was loaded, a term-file can override the type. Therefore, it is important than any term-files provided either indicate which database-type its parameterized strings are for or use the database-specific entries for the parameterized strings. The "ecurses" routines will automatically handle either syntax for padding information. See the section "Extended Curses Library" below for further details. -------------------------------------------------------------------------- TERM-FILES (Unix only) The "ecurses" library uses the appropriate terminal database (terminfo or termcap) to load initial values for a particular terminal, but then it loads a "term-file" ("$TERM.trm") in order to get extended functionality which may not be in the "standard" entry. The term-files which are delivered with the product are found in the "termfiles" directory. You can even provide a term-file for a TERM type which is not in any "standard" database. The rule is that there must be either a database entry, a term-file, or both for a given TERM type. Entries in a term-file will override any corresponding entry from the database. See the file "support/termfiles.txt" for documentation of term-files. For help in creating & testing term-files, the following programs are built in the "termutils" directory: dispbox Display boxes using the alt-char sets in all styles. dispblks Display block letter strings using alt-char sets if possible. dispchrs Display all characters (in the regular char-set). dispclrs Display all colors. dispkeys Display the names for key-strokes. Run "dispkeys -d" to get raw char data for adding key entries to a term-file. dispterm Display the all terminal configuration for a given TERM type. saveterm Write out a term-file for a given TERM type. dispsnap Display the contents of a "snap file" ("screen.snp"). A snap file is produced at any time by entering KEY_SNAP (by default KFUNC-z ("^]" "z"). Subsequent KEY_SNAP commands will append snapshots to the file. ditto Display user input on multiple terminals simultaneously. dumpterm Dump the contents of a terminal database entry (either termcap or terminfo). playback Playback a saved screen log file, one character at a time. Each key stroke will "playback" one character ("1"-"9" will display 1-9 characters at a time). Run "playback -x" to playback a text screen log file. A binary screen log file is opened with a KFUNC-< ("^]" "<") and closed with a KFUNC-> ("^]" ">"). The default binary screen log file is "scrn.log". A text screen log file is opened with a KFUNC-( ("^]" "(") and closed with a KFUNC-) ("^]" ")"). The default text screen log file is "scrn.txt". termput Display the value of a terminal entry (ala "tput"). Name can be a "termcap" name, a "terminfo" name, or a "term-file" name. -------------------------------------------------------------------------- FILE-SYSTEM DIFFERENCES Another area in which practically every Unix is different is in the library calls to read the mount-table and to get the amount of free-space for a mounted file-system, as many platforms have their own proprietory file-system access mechanism. The currently supported file-system types are: FS name O/S ------- ----------- aix IBM AIX bsd FreeBSD, OpenBSD, SunOS, & OS/X cygwin Windows (using cygwin-gcc) dg DG/ux (both dg86 & dg88) hp HP/ux linux Linux netbsd NetBSD osf Digital OSF posix Posix sgi SGI (IRIX) svr3 generic SVR3 svr4 generic SVR4 win Windows The file-system type is specified by the $FS_TYPE environment variable, which is set in the platform's "env" file. This is a REQUIRED variable to be set, and if it is not set, "posix" will be assumed. If your file-system is different from all the above types, you can add source code to support your file-system. The file must be named "libos/osmnt-$FS_TYPE.c". You can look at the other libos/osmnt-*.c files to get an idea of how to do it. See the file libos/osmnt.h for details. If you are not sure what to do or what type of file-system your Unix uses, then set FS_TYPE to "posix", which are a set of "empty" routines which do nothing. The program will still function properly, but you will not be able to view the amount of free-space available, or get the list of mounted file systems. -------------------------------------------------------------------------- PSEUDO-TTY DIFFERENCES (Unix only) Another area in which various Unixes are different is in the library calls to open a pseudo-tty. Pseudo-ttys are used in the xvt library to create a communication between a program and its display window. The currently supported pseudo-tty types are: type O/S master names slave names ----- ----------- ------------ ----------- sysv SYSV /dev/ptmx /dev/pty[p-s][0-9a-f] bsd BSD, AIX, & Linux /dev/pty[p-z][0-9a-f] /dev/tty[p-z][0-9a-f] If needed, you can add either -DPTY_SYSV or -DPTY_BSD to XVT_OPTS to indicate which is to be used. -------------------------------------------------------------------------- THREADS (Unix only) Yet another area of difference is in the way threads are used. Threads are processed by the file libsys/systhread.c. In Windows native threads are used, and in Unix POSIX threads are used. Threads are used by the libxvt routines to create an event-loop which processes events for displaying output in an X11 window. The routines are designed such that if threads are not available, they will still work, but they are much more efficient if threads are available. Note that, even if threads are supported, they may not work on a given machine, as on some platforms threads require a certain level of O/S or require certain patches to be applied. As a general rule, if the platform supports Java, then threads will work. If a given platform supports threads, then add the option "-DV_USE_THREADS" to the SYS_OPTS entry in the env file. You may have to add other options specific to a platform. -------------------------------------------------------------------------- X-WINDOWS (Unix only) The xvt library uses X11 (X-Windows) to create a window for input/output. This *should* not be a problem, since every Unix available now provides X11 support (except Mac OS/X), although many Linux and SCO users with a custom install choose not to include X11 support. The real problem is in locating the X11 header files and libraries. If they are not in the "standard" location, then the following environment variables may be set: X11_INCS Specifies where to locate the X11 headers. This variable should include any leading "-I", since it is used as an option to the C compiler. The default value for this entry is "" (which will result in looking in /usr/include/X11). X11_LIBS Specifies where to locate the X11 libraries. The default value for this entry is "-lX11". Note that only basic "xlib" functions are used. No toolkits (such as Xt, Motif, etc.) are used. If you don't have the X11 development system on your machine (i.e. the X11 headers and libraries), then set the following environment variable in your <platform>.env file: USE_X11=no -------------------------------------------------------------------------- ARCHIVE DEVICE TABLE (Unix only) Another difference between various Unixes are the names for various devices. We are interested in the devices which we can write an archive to, namely floppy-disk drives and tape drives. These are known as "raw" devices. To deal with this problem, we deliver a file $PROGRAM.dev, which contains information on various devices for a particular system. The content of this file is as follows (note that blank lines and comment lines are ignored): archive[n]=<device-path> blk-factor num-blks tape # comment where: archive[n] is the "name" of the entry. An entry with no number is the default entry. device-path is the full pathname of the device. blk-factor is the blocking factor to use. Note that archive records are 512 bytes long. This value is important if the device is a tape, as short blocks consume lots of tape. This is ignored if the path is a real file. num-blks is the number of blocks on the device. A value of 0 indicates a tape of unknown length or a real file. tape is either Y or N, indicating whether this is a tape drive. A tape drive is not considered seekable. comment is the description displayed in the menu list. If not present, the device-path is used. The syntax of this file is an extension of the file found on many Unix systems in /etc/default/tar, which can be used as a starting point for creating a new file for a new platform. To create a device table for a new platform, add the file as $PLATFORM.dev in the "support" directory. You can use an existing entry or name it differently by setting the $DEVTBL environment variable in the "env" file for that platform. Note that this file is not delivered in Windows, since Windows does not does not have the concept of "raw" devices (or device-names for them). -------------------------------------------------------------------------- EXTENDED CURSES LIBRARY This build delivers into the directory $WIN_DIR the extended curses libraries and all headers needed by programs to use it. This directory can be extracted and used by any program using curses to access the extended functionality provided. To use this library, the following commands can be used (<ldir> refers to the directory where the libecurses library is to be found and <hdir> refers to the directory where the headers are be found): compiling: cc [flags] -I<hdir> file ... linking: cc [flags] object ... <ldir>/libcurses.a ... or cc [flags] object ... -L <ldir> -lcurses ... Note that to use these headers, your compiler MUST be ANSI-compilant. There is a "man3" sub-directory in the "libecurses" directory which contains documentation (as man files) concerning the extended curses package. Files provided in this directory are: libcurses.$LIB_EXT The extended curses library. libform.$LIB_EXT The FORM library. libmenu.$LIB_EXT The MENU library. libpanel.$LIB_EXT The PANEL library. curses.h The "curses" header. Note that this header also includes the system headers <stdio.h>, <stdarg.h>, and <sys/types.h>. termcap.h A header for low-level termcap database access. This header is not normally used. term.h A header for low-level terminfo database access. This header is not normally used. form.h A header for accessing the FORM library. menu.h A header for accessing the MENU library. panel.h A header for accessing the PANEL library. eti.h A copy of the system eti.h header (included by form.h & menu.h). It is included in case your system does not have it installed. sysmem.h A header for the malloc-interface used by this library. It is made available for users who want to add malloc-debugging to their programs (A Good Thing To Do). sysopt.h A header which defines replacement routines for getopt(), which is not available on all systems. This is provided for portability purposes, although it also provides extended capabilities. systhread.h A header for the threads interface. syssig.h A header for the signal interface. TERMFILES A text-file documenting term-files. man3/ecurses Top-level man page for the extended curses library. man3/ecurs_* Supplemental man pages for all sections. man3/ecurs-funcs.sh A script to create function entries for all functions, linking them to their respective section entry: ecurs-funcs.sh -a create all entries ecurs-funcs.sh -d delete all entries By setting your MANPATH to "$SRC_DIR/libecurses:$MANPATH", you can access the provided man pages via "man". Note that the build script does this automatically. You can also just view them via any viewer such as "more" or "vi". -------------------------------------------------------------------------- LIBRARY DESCRIPTIONS The following libraries are present in this source tree: Sub-libraries for "libecurses": libsys library for basic system functions (memory allocation, cmd-line processing, & threads) libterm library for device I/O functions libtcap library for termcap/terminfo interface functions libwin library for "curses" functions The following is the replacement library for "libcurses" (built from the sub-libraries above): libecurses extended curses library & headers The following libraries are not used by this source, but are included to provide a complete curses implementation: libform library for FORM processing libmenu library for MENU processing libpanel library for PANEL processing "Standalone" utility libraries (they include only libsys for the malloc interface): libxpm library for pixmap manipulation (needs X11 hdrs) libxvt library for xterm emulation (needs X11 hdrs & libs) libos library for O/S-dependent functions libdiff library for file diff functions libgzip library for gzip functions libmagic library for magic functions Other libraries: libutils library for general-purpose utility functions (requires libos & libecurses) libftp library for FTP functions (requires libutils, libos, & libecurses) (needs network headers & libraries) libres library for resource-file processing (requires libecurses) libhelp help file creation - not really a library Program library: libprd library with actual program code (requires all sub-libraries) The libecurses library is a self-contained library with no external dependencies. The "standalone" libraries are only dependent on the libsys library for the "malloc/free" (sysmem) interface. They are all designed to be "lifted" to be used elsewhere. The following libraries have targets for "stand-alone" test programs: (The test programs are also dependent on the libsys library for the "getopt" (sysopt) interface.) library program description -------- ------- -------------------------------- libdiff diff Similar to the Unix "diff" cmd libgzip gzip Similar to the Linux "gzip" cmd libmagic file Similar to the Unix "file" cmd libxvt pcxterm Similar to the Unix "xterm" cmd libecurses * Various programs in termutils directory -------------------------------------------------------------------------- TIPS & TRICKS The following are tips in building and testing this source tree. 1. If "." is not in your path before sourcing the build script, you will have to source the build script as follows: $ . ./build [options] <platform> since otherwise it will not find "build". Note that after sourcing "build", "." will be in your path. 2. Strange things happen if you source "build" a second time. Don't do that. I use the following sequence of commands: $ cd <source-directory> $ ksh (go into a sub-shell) $ . build -d <platform> (I usually do debug builds) Then, if I change anything involving the environment (this is not very frequent, except for the version/release/build numbers), I can just do the following: $ exit (leave your sub-shell) $ ksh (create a new sub-shell) $ . build (reload the build env using param cache) This takes me back to the top-level of the source tree and "reloads" my environment. 3. Setting the environment variable "TC_IGNORE_SIGNALS" (the value is ignored) will disable at run-time the catching of signals such as SIGSEGV (illegal pointer dereference), SIGBUS (illegal alignment), etc. This will then enable a "core" file to be written, which you can then debug. Normally, these signals are caught in order to restore the terminal settings, which results in no core file being produced. Note that if you use this and the program does core-dump (highly unlikely, haha), you will then have to manually reset the terminal state, as follows: ^j (control-j, NOT a CR) stty sane^j (again, control-j, NOT a CR) Your terminal should then be in a "sane" mode, and you can then debug your core file. 4. If you seem to have problems with data on the "heap", there are a number of run-time malloc-debugging options available. See the file libsys/sysmem.h for details. At the minimum, be sure to run the program with the "-ZM" option occasionally, which will output to stderr a malloc-statistics summary line at program exit. If the number of outstanding mallocs is not zero (i.e. the number of mallocs does not equal the number of frees), you have a memory-leak somewhere. (This is something I check religiously.) If you run the program with the option "-ZMM", then, if the count of outstanding mallocs is not zero, the malloc chain will be dumped to stderr also. Note that, if you are running in a separate window, then stderr will point to that window, which "disappears" when the program exits. In this case, you should set the environment variable V_MALLOC_DBGFILE to point to a file where this debug info will written. Note also that if you set the environment variable COPTS to "-DV_MALLOC_FILEINFO" (or add that to your CDEFS variable), then all calls to MALLOC & FREE will have the source file-name and line-number included. This is a compile-time option, not a run-time option. Although this enables maximum heap-debugging abilities, it will generate a much larger executable file. Note that you can selectively set this option when compiling suspect code, and leave it off for code you know is OK. 5. The command "make xrflist" will generate a very useful cross-reference list of all data & procedure names in the source tree. This will enable you to navigate around the source tree as you become familiar with where everything is located. This command works in both the Unix and the Windows environment. 6. You will notice that most libraries have a "*common.h" file which contains all includes used in that library. This not only makes adding new source files easier, but also enables the use of pre-compiled headers if your compiler supports them (like Windows). (All compilers should have that option.) This provides a *significant* decrease in the time needed to build the source. 7. The files sysmem.[ch] and sysopt.[ch] in the libsys directory are designed to be "lifted" out so they can be used in any other code tree. They are completely "self-contained". I have done this many times myself. I can't imagine writing code without a memory-allocation interface to track memory problems (hint, hint). To use the "sysmem" package in another code tree, do the following: 1. Add the line < #include "sysmem.h" > to all files which do heap processing. The easiest way to do this is to replace all #include <malloc.h> lines with the above, or just add that if you don't use <malloc.h>. Note that some systems define malloc() & friends in stdlib.h (in fact that is the ANSI standard), in which case you may just have to add the "sysmem.h" include to the source files which use these routines. 2. Change the references to the names of the following calls: malloc -> MALLOC calloc -> CALLOC realloc -> REALLOC free -> FREE strdup -> STRDUP 3. Recompile your source and link it with sysmem.$OBJ_EXT. 4. If your code makes use of threads, be sure to also include the files systhread.[ch] and compile both with the option "-DV_USE_THREADS" (and link with systhread.$OBJ_EXT also). Most "large" programs have some kind of "base" library & headers which are included everywhere and always linked in. You can just add sysmem.[ch] to that library (and its header) to include this functionality. 8. Building on multiple platforms. The scripts "makesrc.sh" and "linksrc.sh" enable you to make "clones" of a source tree for multiple platforms. The advantage of "clones" versus normal trees is that a "clone" uses virtually no disk space, since all source files are really sym-links, and by changing the "master" source tree, all "clones" see the change immediately. For example, assume you want to build on machines "linux", "alpha", and "solaris" (and all machines have your source-directory NFS mounted). You can then use the following commands: 1. Create the "master" source tree: $ mkdir -p <source-dir>/master $ cd <source-dir>/master $ tar xvf <source>.tar 2. Make "clone" trees $ cd <source-dir> $ for i in linux alpha solaris > do > echo "===== making $i" > mkdir $i > (cd $i; ../master/bin/makesrc.sh ../master) > done 3. Build the "clones" <on local machine> $ telnet <remote-machine> <on remote machine> $ cd <nfs-source-dir>/<platform> $ . build -r <platform> $ make sku Repeat for each platform. At the end, you will have in your $SKU_DIR directory all SKUs for the various platforms. This is how I build the various platforms which are currently delivered. See the file "bin/makesrc.sh" for further details. Note that you should not do any builds in the "master" directory, as then all the "built" files (objects, etc.) will be cloned also. -------------------------------------------------------------------------- COMMENTS & QUESTIONS If you have any problems building the source or with configuring the source for a particular platform, please let me know. Also, if you add a new platform or make any other configuration changes, please let me know so I can update the "official" source. Rob Juergens robj@nano-soft.com