\begindata{text,538387104} \textdsversion{12} \template{default} \majorheading{Maintaining VUI for Andrew and the PC } \center{Mark Chance CMU-ITC 8 March 1988 } \heading{Introduction} This document describes the development and maintenance procedures currently in use for the Andrew Mail System program called VUI (Visual User Interface). Although it describes VUI, the same procedures could be used for other applications such as CUI. To successfully accomplish the tasks described here, the reader should be somewhat familiar with RCS (see \italic{help rcs}), AMS and VUI functions (see \italic{help ams} and \italic{help vui}), pcserver, Unix, and C compilers. The Andrew commands I have included here are current as of this writing, though they may change as the ITC changes software maintenance procedures. \heading{Initial Set Up } \subheading{Workstation side }Create two directories for sources. Link one directory to itc/ams/libs, the other to itc/ams/vui. \example{mkdir ~/ams/libs mkdir ~/ams/vui cd ~/ams/libs rcslink itc/ams/libs rcsupdate cd ~/ams/vui rcslink itc/ams/vui rcsupdate } \subheading{PC Side }Use pcserver to login to your home directory, /cmu/msdos/ibmpc as F: and /usr/andrew as I:. Make your home directory the current disk/directory. Establish the proper path and any environment variables so that the C compiler will run properly. \heading{Compiling} I usually build and test the program on the workstation first because of the faster building turnaround time. Then when the program has stabilized, I build a PC version. To make an executable rt version of the program issue the following command:\example{ make vuin} The RCS commands for checking out and in files are co and ci. See the Unix manual or the man pages for details. \subheading{Libraries }On your workstation, run rcsupdate in the libs directory or make any necessary changes. Run makePCbat in libs. Then on your PC make ams/libs the current directory and run the batch file generated by makePCbat. Look through the output to verify you got a valid libcuisnap.lib. \example{cd ~/ams/libs rcsupdate makePCbat} When you have a good copy of libcuisnap.lib, copy it into /cmu/msdos/ibmpc/lib. \subheading{Applications }Make any changes or updates to the files in ~/ams/vui, run makePCbat and execute the batch file on the PC. Look through the output and verify you got a valid vui.exe. Caution: the PC batch system does not stop when a program has a bad return code. Unfortunately this means that if a compile step has a problem, the link step will attempt to continue. If it happens to pick up an old object file, the changes you expect will not have been included. \example{cd ~/ams/vui makePCbat } The final step of the batch file copies vui.exe to your local disk. To assist in debugging, pressing Alt-F1 (or Esc ! on a workstation) initiates a tracing facility that writes out diagnostic messages to a file called vui.bug in the current directory. One technique I have found handy on occasion is to execute \typewriter{"tail -f vui.bug"} at a command prompt to see messages as they are put into vui.bug. Also running gdb or dbx on the workstation can be useful. A convention that has served quite well is to keep a current version number in VUIVERS.h and increment the minor version number each time a new copy is released to /usr/andy/bin or /cmu/msdos/ibmpc/exp/common. \heading{Documentation } Help files exist for use in the program. These are stored in RCS in the helptexts subdirectory of itc/ams/vui. The scheme for these files is that there is a file whose name contains a number which corresponds to a command number as found in vuimenus.h. For those situations in the program where the user is not on a command menu, there is a help file with a more descriptive name. There are also help and tutorial files in the vui directory. These should be updated whenever there are major updates to the program. \heading{Releasing }On the workstation side the release process works the same as for any other program (currently 'wash itc/ams/vui'). For the PC side, releasing means placing a copy of vui.exe in /cmu/msdos/ibmpc/exp/common. A "campus release" for the PC would mean copying into /cmu/msdos/ibmpc/common. After doing this an announcement should be put in the andrew.ms.pcmsgs and/or andrew.ms.vui bulletin boards describing the new features and bug fixes. The Academic Computing group also appreciates developers monitoring org.advisor.helpbox.ams and org.advisor.helpbox.pc.ams bboards. \heading{Notes } \subheading{error 2000: stack overflow }The PC puts all local variables on the stack. You can adjust the stack size after linking by using the exemod program on the PC. \example{exemod vui.exe /STACK xxxx }If you make the value xxxx too large you will get the stack overflow message immediately upon loading the vui program. If you reduce it slightly you may get error: insufficient environment space. This means you are very close, and should reduce the value just a bit more. \subheading{Other PC libraries }The makefile links in two libraries not previously mentioned. These are snapl.lib and unixl.lib. Currently these live in /cmu/msdos/ibmpc/lib and are maintained by Larry Raper. \subheading{Miscellaneous PC specifics } Because the PC considers int != long, you have to be careful with functions that return longs and functions that have longs as arguments. To assure these are properly declared cast any function arguments that are constants and should be pointers or longs. Also declare at the beginning of a module any library or server functions that return long. There are modifications to standard Microsoft include files that I have made. These include: \leftindent{pwd.h copied from Andrew:/usr/include sys/param.h condensed from Andrew:/usr/include sys/socket.h copied from Andrew:/usr/include/sys netinet/in.h copied from Andrew:/usr/include/netinet (1) sys/types.h got definitions added for sys/socket.h (1) sys/stat.h got '#include ' added (1) errno.h got several new codes added sys/file.h copied from Andrew:/usr/include sys/time.h from PC:include } Note 1: These modifications only for compiling snap functions. If you can use snap?.lib files, these changes are not necessary. \heading{Appendix A: Andrew Utilities } \subheading{The makePCbat shell script }This shell script currently lives in ams/vui. Its purpose is to automatically perform some conversions between file types and commands on the PC and those that Unix uses. There is an occasional problem with makePCbat in that the PC batch file interpreter only allows ~250 characters per line. The link step can be longer. To correct this I edit the batch file on the workstation and remove all the .obj and .lib file extensions. When not too many things change from compile to compile, you can just re-use the batch file or edit it slightly to do what you want. \heading{Appendix B: PC Utilities } \subheading{The addlib program }This is a simple program which accepts the syntax of the Unix ar command, and generates the proper Microsoft Library Manager operations. \heading{Document Change History }Created 12/87 by M. Chance Updated 1/88 by M. Chance - reflect status of upgrading to Microsoft C Version 5.00 Updated 3/88 by M. Chance - don't use rinsepc/PCwash, rather use makePCbat which is simpler. \begindata{bp,538210560} \enddata{bp,538210560} \view{bpv,538210560,0,0,0} Copyright 1988. Carnegie Mellon University and IBM. All rights reserved. \smaller{\smaller{$Disclaimer: Permission to use, copy, modify, and distribute this software and its documentation for any purpose is hereby granted without fee, provided that the above copyright notice appear in all copies and that both that copyright notice, this permission notice, and the following disclaimer appear in supporting documentation, and that the names of IBM, Carnegie Mellon University, and other copyright holders, not be used in advertising or publicity pertaining to distribution of the software without specific, written prior permission. IBM, CARNEGIE MELLON UNIVERSITY, AND THE OTHER COPYRIGHT HOLDERS DISCLAIM ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL IBM, CARNEGIE MELLON UNIVERSITY, OR ANY OTHER COPYRIGHT HOLDER BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. $ }}\enddata{text,538387104}