0707070000020030711006440001460001440000010300730355330157700000500000000004Size120 0707070000020030451007770001460001440000010300760355330133300001000000001042InstallNAME=INSTALL.DOC FOLDER=/u/$LOGNAME/Filecabinet/DOCS if [ -d $FOLDER ] then message -i "A new file called $NAME will be created in your Filecabinet/DOCS folder. The document you are installing will be placed there.\n\nTouch to continue." else message -i "A folder called DOCS is being created in your Filecabinet. A file called DOCS/$NAME will then be created to hold the document you are installing.\n\nTouch to continue." mkdir $FOLDER chown $LOGNAME $FOLDER fi DEST=${FOLDER}/$NAME ln $NAME $DEST chown $LOGNAME $DEST 0707070000020031111006660001460001440000010306610355330033300000500000000076NameDOCUMENT: How to Make Installable Floppies - from THE STORE! 0707070000020031251007770001460001440000010300520355330037100000700000000136RemoveNAME=INSTALL.DOC FOLDER=/u/$LOGNAME/Filecabinet/DOCS rm -rf ${FOLDER}/$NAME > /dev/null 2>&1 0707070000020031161006440001460001440000010300550355330154300000600000000132Files./Size ./Install ./Name ./Remove ./Files ./MAKEcpio ./MAKEflop ./INSTALL.DOC ./install.mm 0707070000020025261007770001460001440000010300720355330053000001100000000047MAKEcpiocat Files | cpio -ocBv > INSTALLDOC+IN 0707070000020031261007770001460001440000010300510353663415000001100000000044MAKEflopcat Files | cpio -ocBv > /dev/fp021 0707070000020017601006440001460001440000010306730355330026700001400000071117INSTALL.DOC AAAATTTT&&&&TTTT IIIInnnnffffoooorrrrmmmmaaaattttiiiioooonnnn SSSSyyyysssstttteeeemmmmssss subject: The Creation of date: October 11, 1985 Application Software Packages for the AT&T from: Fred Hicinbothem PC7300 - case 39065 FJ 43111 FJ-1G106 x5256 500-01311 houxn!4341fah _A_B_S_T_R_A_C_T The PC7300 offers the user an administration tool which will allow them to install application software packages from a floppy disk within the menu structure of the Office. This memo will provide an outline of the installation procedure and a detailed set of instructions for the creation of floppy disk sets which may be installed using the PC7300 administration tools. The intended audience is the software developer who has written a tool suitable for use on the PC7300 - it is assumed that the reader has knowledge of UNIX, shell programming, and the structure of the /usr/lib/ua directory which enables the window manager to function. Once a developer has packaged their application on an installable floppy disk, it is trivial to also create a file which may be installed on the 7300. This makes possible the entire operation of THE STORE! because these "installable files" may now be transmitted between machines via uucp without the need for physical media. - 2 - _M_E_M_O_R_A_N_D_U_M__F_O_R__F_I_L_E 1. SSSSppppeeeecccciiiiaaaallll pppprrrreeee----ddddooooccccuuuummmmeeeennnntttt iiiinnnnsssseeeerrrrttttiiiioooonnnn .................... This document has been prepared for distribution via THE STORE! in the hopes that all you PC7300 hackers will package the goodies on installable floppy disks, and then send the floppy disks to me so that I can make your software available through THE STORE! If you want to have your software distributed through THE STORE!, just send an installable floppy disk to Fred Hicinbothem at: AT&T IS Fred Hicinbothem - room 1J-100 Route 9, Juniper Plaza Freehold, NJ 07728 I'm looking forward to a deluge of super tools, games, documents, and whatever ....... 2. IIIInnnnttttrrrroooodddduuuuccccttttiiiioooonnnn aaaannnndddd SSSSccccooooppppeeee In order to install software on the PC7300, the user will be instructed to enter the Administration menu from the Office window, "Software Setup" selection, "Install Software From Floppy" selection. The user will then be instructed to insert the floppy disks which constitute the delivery, in order, until all have been read. At this point, the contents of the floppy disk have been read into a temporary area. An executable program supplied on the floppy disk (named Install) is now executed to move the software from the temporary area into the final locations, and to modify the system files such that the software may be used by the customer. This document will outline the actual procedure executed at installation time (/usr/bin/Install.sh) and provide a listing in the appendices. Further, the document will provide the developer with sufficient details regarding the structure of several required files to actually create an installable floppy set for the PC7300. Lastly, some broad guidelines for the installation and removal programs are provided. - 3 - To all this, we have added some special considerations which will enable users of THE STORE! to investigate a little further by examining the packaging of the stuff currently on THE STORE! 3. TTTThhhheeee AAAApppppppprrrrooooaaaacccchhhh The bottom line transfer mechanism will be cpio. The floppy disk will be created with a "cpio -ocB" call and read in with a "cpio -icBdum" call. The key that allows the scheme to be somewhat user friendly and allows a modicum of error protection is the inclusion of several special files created by the software developer. These files MUST appear on the cpio list. An ennumeration of these special files is in order: 1. Size : this file contains information which will allow the Install.sh program to determine the total size of the floppy set. The precise format of this file is contained in a later section. It should be the first file in the cpio set. 2. Install : this file is executable - it will be executed AFTER the files are cpio'ed in from the floppy set and BEFORE they are moved from the temporary installation directory. The content of Install is entirely under the control of the software developer but AT&T will reserve the right of review to insure that the procedure is non-destructive and non- interfering. A good deal of the document which follows deals with the rules and tools you will need to be aware of in order to set up the Install file. 3. Name : contains descriptive information regarding the application which can be made available to the user at installation time. The Name file format and content is described in a later section. 4. Remove : This is an executable file that will be executed should the customer choose to remove the software package. The intent is that the Remove script leaves the system in the same state it was in BEFORE your tool was installed. A later section will deal with the specification of the Remove executable file. 5. Files - this file contains a list of full relative pathnames. Although this is not a mandatory file, it is extremely useful when going through the packaging - 4 - process to drive a shell script which actually does the cpio to floppy disk. It should list the relative pathname of each file contained on the floppy set separately with no wildcarding. Once again, it is hoped that these files provide sufficient flexibility for our software developers - should this prove NOT to be the case, please contact AT&T and we will try to suggest ways to accommodate your special circumstances. 4. AAAAnnnn OOOOuuuuttttlllliiiinnnneeee ooooffff tttthhhheeee IIIInnnnssssttttaaaallllllllaaaattttiiiioooonnnn PPPPrrrroooocccceeeedddduuuurrrreeee The creation of the floppy disk set containing the application tool is done by /usr/bin/Install.sh. It's function is to read in the floppy set and kick off the Install program supplied on the floppy set. The flow is very similar to the /usr/bin/Instcpio.sh program which will install a file with the suffix "+IN". The form of this "installable file" with suffix "+IN" is simply a file created with cpio -ocB > FILE+IN as opposed to output which goes to a floppy disk. The installation procedure will be available to all users through the Administration Software From Floppy". On selection of the menu item, the executable shell script Install.sh in /usr/bin will be run. The following steps serve to outline this program from a user's point of view: 1. The first operation will be to determine if there is sufficient space on the file system to read in the entire floppy set. For early releases, this will likely take the form of simply asking the user how many floppy disks are in the application package and checking the maximum possible content against available space. For later releases, the procedure will read the "Size" file from the first floppy disk and make decisions based upon it's content before proceeding. If there is insufficient space, the procedure will be aborted. 2. The user is presented with an introductory window and asked to insert the first floppy disk and touch the Return key. 3. The entire floppy set is read in with a "cpio -icBdu" call after creating and moving to directory /tmp/installed. Note that this directory is created exclusively for the installation and will be removed following completion of the operation. Note also that - 5 - the pathnames on the cpio floppy MUST be relative (not begin with a "/") so that other filesystems are not effected at this stage. 4. If some specific files cannot be found, the user is advised that the floppy set cannot be installed using this procedure. The files which are required are ./Install, ./Name, ./Remove, and ./Size, the specific required formats are documented elsewhere in this document. 5. The vendor supplied program in ./Install is now executed. This program is now executed - it must do whatever is necessary to move the application out of /tmp/installed and into the real world. Suggestions come later in the document. 6. The Install.sh script will now update a few key files in /usr/lib/ua so that the menus needed for listing or removing installed software are kept up to date. The CONTENTS file in /usr/installed is also updated and the Remove script is renamed and located there. All this stuff will allow the user to find out what applications they have installed and remove them if desired. 7. The directory /tmp/installed and whatever remains of it's contents are now removed. 8. The user is told that everything succeeded and told to enjoy their new application. 5. CCCCrrrreeeeaaaattttiiiioooonnnn ooooffff tttthhhheeee FFFFllllooooppppppppyyyy SSSSeeeetttt 5.1 TTTThhhheeee ffffoooorrrrmmmmaaaatttt ooooffff tttthhhheeee ffffllllooooppppppppyyyy ddddiiiisssskkkk The output of your operations will be a floppy disk which is created via the cpio -ocB command (see manual pages for the specific meanings of the ocB options). This is non-negotiable since the program which reads the floppy (/usr/bin/Install.sh) assumes this form. The list of pathnames which drives the cpio has three restrictions: o+ All pathnames MUST be relative (NOT begin with a "/"). This is because the files will first be cpio'ed into the /tmp/installed directory before they are linked into their permanent locations by your Install procedure. - 6 - o+ The first entry on the list must be "./Size" o+ The entries immediately following Size should be "./Name", "./Remove", and "./Install". Following these special files should be the pathnames (without leading "/") for all files to be placed on the floppy. The floppy set should be clearly labeled with the name of the product (as it appears in the Name file), the version of the product (which may include the date), and the floppy number (e.g: number 2 of 5) showing the total number in the package. 5.2 TTTThhhheeee ....////NNNNaaaammmmeeee ffffiiiilllleeee The Name file is simply a file containing the name of the product as it is to appear during the installation and removal stages of the PC7300 operation. It is a single line which may contain the product name as well as version information - note that only the first 65 characters will be displayed in the menus which are kept by the Install.sh and Uninstall.sh programs. The content of this file does not effect the Suffixes file or anything outside of the installation procedure - although consistency tends to be less confusing than random naming conventions. For applications to be distributed by THE STORE!, we have adopted the convention that the name ends with the words: "from THE STORE!". 5.3 TTTThhhheeee ....////SSSSiiiizzzzeeee ffffiiiilllleeee The contents of the Size file should be the number of blocks required by the application program package once it is installed. The number is contained in a one line flat file. A block is defined as 512 bytes - the total size may be derived using the du command if the files are situated correctly or by calculating an approximate value based on the ls -l listings of the individual files which constitute the package. (Note - do not use the number of characters, use the number of blocks.) NOTE - the current version of the Install.sh program in Release 2.0 does not make use of this file, the version of Install.sh which is delivered to customers in Release 3.0 WILL make use of this file as follows: o+ The file will be extracted from the FIRST position on the floppy. - 7 - o+ The amount of free space in the system will be computed (using df or the equivalent). o+ If the number in the Size file is greater than the number of available blocks the user will NOT be allowed to install the package. For earlier releases, the user will be asked to provide a floppy count and total size will be estimated based on 300,000 bytes per floppy. When calculating the number to put in the Size file, it is generally a good idea to round up and to include any work area that may be needed during the install procedure (e.g. - you delivered source code which is compiled during your Install execution - you would want to insure there was sufficient space to hold the a.out file). If you have a disk-size intensive application (say a database or spreadsheet) you may wish to require more space be free to accomodate potential user files. The actual number is up to you - but be sure you don't let the user run their file system out of space while installing your tool - there is no protection beyond the Size file which would prevent this. 5.4 TTTThhhheeee ....////FFFFiiiilllleeeessss ffffiiiilllleeee The notion of this file has changed. At present it is NOT required, but it is an extremely useful file to use when actually performing the process of floppy or "installable file" creation. On all packages that I create, I always maintain an up-to-date Files file containing relative pathnames of all the pieces of the application. I use this file to drive two shell scripts, MAKEflop and MAKEcpio, which are one line shortcuts to create the floppy disk or "installable file". A typical MAKEflop shell script might be: cat Files | cpio -ocB > /dev/rfp021 while a typical MAKEcpio for the application XYZ might be: cat Files | cpio -ocB > XYZ+IN The Files file itself can be created by reordering the file which results from the execution of: find . -print > Files I highly recommend the inclusion of the Files file and it's - 8 - use as described above. 6. WWWWhhhhaaaatttt SSSShhhhoooouuuulllldddd tttthhhheeee IIIInnnnssssttttaaaallllllll PPPPrrrrooooggggrrrraaaammmm CCCCoooonnnnttttaaaaiiiinnnn???? The Install program contained on your floppy should do everything necessary to get the files that were read into /tmp/install (and sub-directories) fixed up and ready to use out in the real file system. You can do anything that a shell script can do in the Install program. Take a look at the Install programs for any of the applications from THE STORE! or any of the floppy disks to get ideas. The real important thing is to try the installation out on a PC7300 without your application to make sure it works the way you intended it to. 6.1 WWWWhhhhaaaatttt tttthhhheeee uuuusssseeeerrrr sssshhhhoooouuuulllldddd sssseeeeeeee The Install program will run as a shell program from within the Install window created when you choose the "Install Software from Floppy" choice in the "Software Setup" menu. Note the size of this window - unless you play some games from within Install (like running C programs which you bring in off the floppy) your output will go to this window and you will get input from this window - be aware of the size window you have to work with. Probably the simplest thing is simply to put up a short message saying "Installing XYZZY - Please wait ...". 6.2 GGGGeeeettttttttiiiinnnngggg tttthhhheeee pppprrrrooooggggrrrraaaammmmssss oooouuuutttt ooooffff ////ttttmmmmpppp When the Install program begins, you can assume that all the programs and stuff on the floppy has been cpio'ed into /tmp/install and that you are cd'ed there. After modifying them as you wish (if at all) you will be ready to move them into the "real" file system. Some issues to watch out for are in the following paragraphs: Permissions: your best bet is to make sure they were OK when you created the cpio, and then use "ln" rather than "cp" or "mv". Make sure the executables are executables and that read-write permissions are such that the normal user(s) can use them as appropriate. Don't forget the setuid bit if appropriate. Ownership: don't supply files which are owned by local users on the machine which created them - make sure they are owned by root or bin in general. Moving them: Don't use the "cp" command (you will double the space requirements needed during the install - 9 - phase). The /tmp/install directory will eventually be trashed by Install.sh after you are done with it, but the recommended procedure is "ln". If any intermediate files are created, use the /tmp or /tmp/install directory for them to insure remnants aren't left around. 6.3 MMMMooooddddiiiiffffyyyyiiiinnnngggg tttthhhheeee SSSSuuuuffffffffiiiixxxxeeeessss FFFFiiiilllleeee The /usr/lib/ua/Suffixes file is worth using if your application ever references or creates files unique to itself. The mechanism provides the ability to define a file suffix (like .c, or :W, or .bits) and a set of rules which are to be applied if the file is ever used from within the Office and Filecabinet environment. The Suffixes file is one of several special files located in /usr/lib/ua. In order to modify these special files, a simple tool called "uaupd" has been written which takes input from a provided file and appends it to these special files as appropriate. Documentation on uaupd has been provided in the manual pages- the simplest way to see how it works though is to examine it's use in some sample Install scripts. Any suffixes you define should be limited to some non- alphanumeric character followed by a small number of alphameric characters. Check the /usr/lib/ua/Suffixes file you have on your machine now for form, and to see what suffixes have already been taken. We have not yet worked out the way in which we will insure that different vendors use different suffixes, so I'd suggest that you examine the Suffixes file on the target machine to insure that you are not trashing somebody else's suffix. 6.4 MMMMooooddddiiiiffffyyyyiiiinnnngggg tttthhhheeee mmmmeeeennnnuuuussss You have the ability to modify the contents of the window menus if appropriate. Check out uaupd on the way to change them, and take a peek at some Install scripts that use the facility to see how to use uaupd to change the Office menu. 6.5 MMMMooooddddiiiiffffyyyyiiiinnnngggg tttthhhheeee uuuusssseeeerrrr eeeennnnvvvviiiirrrroooonnnnmmmmeeeennnntttt The environment of your user is controlled through the use of Environment files in assorted directories. The global environment for the Office is controlled through /usr/lib/ua/Environment and the login specific environment is controlled by /u/logname/Environment where /u/logname is - 10 - the standard home directory for a user called "logname". Environment variables which are needed may be set here - do not attempt to reset any system environment variables. Deal exclusively with environment variables unique to your application, and name them such that the likelihood of overlap with other applications is slim. 6.6 IIIInnnnssssttttaaaalllllllliiiinnnngggg lllliiiibbbbrrrraaaarrrriiiieeeessss,,,, iiiinnnncccclllluuuuddddeeee ffffiiiilllleeeessss,,,, eeeettttcccc.... The biggest issue here is "DO NOT OVERWRITE ANYTHING THAT IS THERE ALREADY". Do NOT redefine any libraries or include files for your customer - they won't appreciate it. The same goes for any standard UNIX file or executable. In your procedures, feel free to supplement what is there now, but please don't replace anything. 6.7 NNNNoooottttiiiiffffiiiiccccaaaattttiiiioooonnnn ttttoooo uuuusssseeeerrrr If there is any input required from the user along the way, use stdin and stdout (echo and read) to communicate from within your Install script. BE NON-UNIXY, keep the user informed if things are going to take a while. Ask the user for verification along the way if necessary (use message(1) if you want to). Inform the user of any problems and offer solutions or allow for choices to be made. Tell the user when it's all done. 7. RRRReeeemmmmoooovvvvaaaallll ooooffff IIIInnnnssssttttaaaalllllllleeeedddd SSSSooooffffttttwwwwaaaarrrreeee Choosing the "Remove Installed Software" menu item from the "Software Setup" within Administration will kick off the Uninstall.sh program (see /usr/bin/Uninstall.sh). The Uninstall.sh program will offer the user a list of the installed software and ask them to pick the one they want to remove. Once a valid choice is made, the Remove script that was originally supplied on the floppy disk is dredged out of it's storage place in /usr/installed where it has resided lo these many years. After finding it and executing it, the Installed software menus are adjusted to reflect the deletion. Note that the Remove script is run AS IS - how good it is and how safe it is depends on it's author. AT&T of course, will reserve the right to audit the remove script to insure it looks safe and sound and leaves things the way they were originally found. - 11 - 8. WWWWhhhhaaaatttt SSSShhhhoooouuuulllldddd tttthhhheeee RRRReeeemmmmoooovvvveeee PPPPrrrrooooggggrrrraaaammmm CCCCoooonnnnttttaaaaiiiinnnn???? Your Remove program, once executed, should leave the system in the same state it would have been in had your application never been installed. This is not easy. The Install program should contain explicit path names of all files on the system which need to be removed (Full path names). Recall that the Files file will not be available when Remove is executed, and it may have contained different information anyway. Any suffixes and menu items you put in have to be removed. Depending on the situation - you may want to ask the users if they want to remove files in the system with your suffix on them - but DON'T DO THIS UNLESS THE USER SAYS OK - these files belong to them. Err on the side of safety when removing files - but do your best to be complete and make sure you get rid of stuff that the user would see. The user interface to the removal process is provided through the /usr/bin/Uninstall.sh program. Again, your best bet is to examine existing Remove programs now on floppy disks or in "installable files". 9. HHHHoooowwww ttttoooo PPPPEEEEEEEEKKKK aaaatttt FFFFllllooooppppppppyyyy DDDDiiiisssskkkkssss oooorrrr IIIInnnnssssttttaaaallllllllaaaabbbblllleeee FFFFiiiilllleeeessss Since the floppy disks or installable files were created with cpio, it is possible to look at them without the aid of the user-friendly installation tools. To do so, create some temporary directory, cd to that directory, and then execute: cpio -icBvdu < /dev/rfp021 for a floppy disk, or for an installable file from THE STORE! do: cpio -icBvdu < /usr/spool/uucppublic/STORE/XYZ+IN since this is the directory the stuff shows up in after your order to THE STORE! is delivered (but before you install it). As a result of this manual cpio, you will get a bunch of files in your temporary directory. Among them will be the Install and Remove files for this application - something not normally visible or saved. The best way to write your files is to copy from an application which does similar things to what you want to - 12 - do. There is a way to encrypt things such that the user will need to know a password to install them, and no amount of playing will allow a hacker to decode the files. If you have a need for this kind of operation, contact THE STORE!keeper for details. (Note that the tool is used in the installation of the TRWRITER package available from the most recent version of THE STORE!) 10. CCCCoooonnnncccclllluuuuddddiiiinnnngggg RRRReeeemmmmaaaarrrrkkkkssss It's all really pretty simple, and the intent of the whole thing is to make it easy for the customer. If however, as unlikely as it may be, you have any questions about how to do all this stuff - please contact THE STORE!keeper. And last but not least, try to install the floppy set on a virgin system and ask yourself if you're happy with the way it looks when you're all done. Fred Hicinbothem 0707070000020030741006440001460001440000010306570355327673200001300000053065install.mm.TL The Creation of Application Software Packages for the AT&T PC7300 - case 39065 .AU "Fred Hicinbothem" FAH FJ 43111 5256 FJ-1G106 "500-01311" "houxn!4341fah" .nr Pt 1 .nr Cl 3 .SA 1 .AS 0 10 .P The PC7300 offers the user an administration tool which will allow them to install application software packages from a floppy disk within the menu structure of the Office. This memo will provide an outline of the installation procedure and a detailed set of instructions for the creation of floppy disk sets which may be installed using the PC7300 administration tools. The intended audience is the software developer who has written a tool suitable for use on the PC7300 - it is assumed that the reader has knowledge of UNIX, shell programming, and the structure of the /usr/lib/ua directory which enables the window manager to function. .P Once a developer has packaged their application on an installable floppy disk, it is trivial to also create a file which may be installed on the 7300. This makes possible the entire operation of THE STORE! because these "installable files" may now be transmitted between machines via uucp without the need for physical media. .AE .MT 1 .H 1 "Special pre-document insertion ....." .P This document has been prepared for distribution via THE STORE! in the hopes that all you PC7300 hackers will package the goodies on installable floppy disks, and then send the floppy disks to me so that I can make your software available through THE STORE! .P If you want to have your software distributed through THE STORE!, just send an installable floppy disk to Fred Hicinbothem at: .DS AT&T IS Fred Hicinbothem - room 1J-100 Route 9, Juniper Plaza Freehold, NJ 07728 .DE I'm looking forward to a deluge of super tools, games, documents, and whatever ....... .H 1 "Introduction and Scope" .P In order to install software on the PC7300, the user will be instructed to enter the Administration menu from the Office window, "Software Setup" selection, "Install Software From Floppy" selection. The user will then be instructed to insert the floppy disks which constitute the delivery, in order, until all have been read. .P At this point, the contents of the floppy disk have been read into a temporary area. An executable program supplied on the floppy disk (named Install) is now executed to move the software from the temporary area into the final locations, and to modify the system files such that the software may be used by the customer. .P This document will outline the actual procedure executed at installation time (/usr/bin/Install.sh) and provide a listing in the appendices. Further, the document will provide the developer with sufficient details regarding the structure of several required files to actually create an installable floppy set for the PC7300. .P Lastly, some broad guidelines for the installation and removal programs are provided. .P To all this, we have added some special considerations which will enable users of THE STORE! to investigate a little further by examining the packaging of the stuff currently on THE STORE! .H 1 "The Approach" .P The bottom line transfer mechanism will be cpio. The floppy disk will be created with a "cpio -ocB" call and read in with a "cpio -icBdum" call. .P The key that allows the scheme to be somewhat user friendly and allows a modicum of error protection is the inclusion of several special files created by the software developer. These files MUST appear on the cpio list. An ennumeration of these special files is in order: .AL .LI Size : this file contains information which will allow the Install.sh program to determine the total size of the floppy set. The precise format of this file is contained in a later section. It should be the first file in the cpio set. .LI Install : this file is executable - it will be executed AFTER the files are cpio'ed in from the floppy set and BEFORE they are moved from the temporary installation directory. The content of Install is entirely under the control of the software developer but AT&T will reserve the right of review to insure that the procedure is non-destructive and non-interfering. A good deal of the document which follows deals with the rules and tools you will need to be aware of in order to set up the Install file. .LI Name : contains descriptive information regarding the application which can be made available to the user at installation time. The Name file format and content is described in a later section. .LI Remove : This is an executable file that will be executed should the customer choose to remove the software package. The intent is that the Remove script leaves the system in the same state it was in BEFORE your tool was installed. A later section will deal with the specification of the Remove executable file. .LI Files - this file contains a list of full relative pathnames. Although this is not a mandatory file, it is extremely useful when going through the packaging process to drive a shell script which actually does the cpio to floppy disk. It should list the relative pathname of each file contained on the floppy set separately with no wildcarding. .LE .P Once again, it is hoped that these files provide sufficient flexibility for our software developers - should this prove NOT to be the case, please contact AT&T and we will try to suggest ways to accommodate your special circumstances. .H 1 "An Outline of the Installation Procedure" .P The creation of the floppy disk set containing the application tool is done by /usr/bin/Install.sh. It's function is to read in the floppy set and kick off the Install program supplied on the floppy set. The flow is very similar to the /usr/bin/Instcpio.sh program which will install a file with the suffix "+IN". The form of this "installable file" with suffix "+IN" is simply a file created with cpio -ocB > FILE+IN as opposed to output which goes to a floppy disk. .P The installation procedure will be available to all users through the Administration Software From Floppy". On selection of the menu item, the executable shell script Install.sh in /usr/bin will be run. The following steps serve to outline this program from a user's point of view: .AL .LI The first operation will be to determine if there is sufficient space on the file system to read in the entire floppy set. For early releases, this will likely take the form of simply asking the user how many floppy disks are in the application package and checking the maximum possible content against available space. For later releases, the procedure will read the "Size" file from the first floppy disk and make decisions based upon it's content before proceeding. If there is insufficient space, the procedure will be aborted. .LI The user is presented with an introductory window and asked to insert the first floppy disk and touch the Return key. .LI The entire floppy set is read in with a "cpio -icBdu" call after creating and moving to directory /tmp/installed. Note that this directory is created exclusively for the installation and will be removed following completion of the operation. Note also that the pathnames on the cpio floppy MUST be relative (not begin with a "/") so that other filesystems are not effected at this stage. .LI If some specific files cannot be found, the user is advised that the floppy set cannot be installed using this procedure. The files which are required are ./Install, ./Name, ./Remove, and ./Size, the specific required formats are documented elsewhere in this document. .LI The vendor supplied program in ./Install is now executed. This program is now executed - it must do whatever is necessary to move the application out of /tmp/installed and into the real world. Suggestions come later in the document. .LI The Install.sh script will now update a few key files in /usr/lib/ua so that the menus needed for listing or removing installed software are kept up to date. The CONTENTS file in /usr/installed is also updated and the Remove script is renamed and located there. All this stuff will allow the user to find out what applications they have installed and remove them if desired. .LI The directory /tmp/installed and whatever remains of it's contents are now removed. .LI The user is told that everything succeeded and told to enjoy their new application. .LE .H 1 "Creation of the Floppy Set" .H 2 "The format of the floppy disk" The output of your operations will be a floppy disk which is created via the cpio -ocB command (see manual pages for the specific meanings of the ocB options). This is non-negotiable since the program which reads the floppy (/usr/bin/Install.sh) assumes this form. .P The list of pathnames which drives the cpio has three restrictions: .BL .LI All pathnames MUST be relative (NOT begin with a "/"). This is because the files will first be cpio'ed into the /tmp/installed directory before they are linked into their permanent locations by your Install procedure. .LI The first entry on the list must be "./Size" .LI The entries immediately following Size should be "./Name", "./Remove", and "./Install". .LE Following these special files should be the pathnames (without leading "/") for all files to be placed on the floppy. .P The floppy set should be clearly labeled with the name of the product (as it appears in the Name file), the version of the product (which may include the date), and the floppy number (e.g: number 2 of 5) showing the total number in the package. .H 2 "The ./Name file" The Name file is simply a file containing the name of the product as it is to appear during the installation and removal stages of the PC7300 operation. It is a single line which may contain the product name as well as version information - note that only the first 65 characters will be displayed in the menus which are kept by the Install.sh and Uninstall.sh programs. The content of this file does not effect the Suffixes file or anything outside of the installation procedure - although consistency tends to be less confusing than random naming conventions. .P For applications to be distributed by THE STORE!, we have adopted the convention that the name ends with the words: "from THE STORE!". .H 2 "The ./Size file" The contents of the Size file should be the number of blocks required by the application program package once it is installed. The number is contained in a one line flat file. A block is defined as 512 bytes - the total size may be derived using the du command if the files are situated correctly or by calculating an approximate value based on the ls -l listings of the individual files which constitute the package. (Note - do not use the number of characters, use the number of blocks.) .P NOTE - the current version of the Install.sh program in Release 2.0 does not make use of this file, the version of Install.sh which is delivered to customers in Release 3.0 WILL make use of this file as follows: .BL .LI The file will be extracted from the FIRST position on the floppy. .LI The amount of free space in the system will be computed (using df or the equivalent). .LI If the number in the Size file is greater than the number of available blocks the user will NOT be allowed to install the package. .LE For earlier releases, the user will be asked to provide a floppy count and total size will be estimated based on 300,000 bytes per floppy. .P When calculating the number to put in the Size file, it is generally a good idea to round up and to include any work area that may be needed during the install procedure (e.g. - you delivered source code which is compiled during your Install execution - you would want to insure there was sufficient space to hold the a.out file). If you have a disk-size intensive application (say a database or spreadsheet) you may wish to require more space be free to accomodate potential user files. .P The actual number is up to you - but be sure you don't let the user run their file system out of space while installing your tool - there is no protection beyond the Size file which would prevent this. .H 2 "The ./Files file" The notion of this file has changed. At present it is NOT required, but it is an extremely useful file to use when actually performing the process of floppy or "installable file" creation. On all packages that I create, I always maintain an up-to-date Files file containing relative pathnames of all the pieces of the application. I use this file to drive two shell scripts, MAKEflop and MAKEcpio, which are one line shortcuts to create the floppy disk or "installable file". .P A typical MAKEflop shell script might be: .DS cat Files | cpio -ocB > /dev/rfp021 .DE while a typical MAKEcpio for the application XYZ might be: .DS cat Files | cpio -ocB > XYZ+IN .DE .P The Files file itself can be created by reordering the file which results from the execution of: .DS find . -print > Files .DE I highly recommend the inclusion of the Files file and it's use as described above. .P .H 1 "What Should the Install Program Contain?" The Install program contained on your floppy should do everything necessary to get the files that were read into /tmp/install (and sub-directories) fixed up and ready to use out in the real file system. You can do anything that a shell script can do in the Install program. Take a look at the Install programs for any of the applications from THE STORE! or any of the floppy disks to get ideas. The real important thing is to try the installation out on a PC7300 without your application to make sure it works the way you intended it to. .H 2 "What the user should see" The Install program will run as a shell program from within the Install window created when you choose the "Install Software from Floppy" choice in the "Software Setup" menu. Note the size of this window - unless you play some games from within Install (like running C programs which you bring in off the floppy) your output will go to this window and you will get input from this window - be aware of the size window you have to work with. Probably the simplest thing is simply to put up a short message saying "Installing XYZZY - Please wait ...". .H 2 "Getting the programs out of /tmp" When the Install program begins, you can assume that all the programs and stuff on the floppy has been cpio'ed into /tmp/install and that you are cd'ed there. After modifying them as you wish (if at all) you will be ready to move them into the "real" file system. Some issues to watch out for are in the following paragraphs: .P Permissions: your best bet is to make sure they were OK when you created the cpio, and then use "ln" rather than "cp" or "mv". Make sure the executables are executables and that read-write permissions are such that the normal user(s) can use them as appropriate. Don't forget the setuid bit if appropriate. .P Ownership: don't supply files which are owned by local users on the machine which created them - make sure they are owned by root or bin in general. .P Moving them: Don't use the "cp" command (you will double the space requirements needed during the install phase). The /tmp/install directory will eventually be trashed by Install.sh after you are done with it, but the recommended procedure is "ln". .P If any intermediate files are created, use the /tmp or /tmp/install directory for them to insure remnants aren't left around. .H 2 "Modifying the Suffixes File" The /usr/lib/ua/Suffixes file is worth using if your application ever references or creates files unique to itself. The mechanism provides the ability to define a file suffix (like .c, or :W, or .bits) and a set of rules which are to be applied if the file is ever used from within the Office and Filecabinet environment. .P The Suffixes file is one of several special files located in /usr/lib/ua. In order to modify these special files, a simple tool called "uaupd" has been written which takes input from a provided file and appends it to these special files as appropriate. Documentation on uaupd has been provided in the manual pages- the simplest way to see how it works though is to examine it's use in some sample Install scripts. .P Any suffixes you define should be limited to some non-alphanumeric character followed by a small number of alphameric characters. Check the /usr/lib/ua/Suffixes file you have on your machine now for form, and to see what suffixes have already been taken. We have not yet worked out the way in which we will insure that different vendors use different suffixes, so I'd suggest that you examine the Suffixes file on the target machine to insure that you are not trashing somebody else's suffix. .H 2 "Modifying the menus" You have the ability to modify the contents of the window menus if appropriate. Check out uaupd on the way to change them, and take a peek at some Install scripts that use the facility to see how to use uaupd to change the Office menu. .H 2 "Modifying the user environment" The environment of your user is controlled through the use of Environment files in assorted directories. The global environment for the Office is controlled through /usr/lib/ua/Environment and the login specific environment is controlled by /u/logname/Environment where /u/logname is the standard home directory for a user called "logname". Environment variables which are needed may be set here - do not attempt to reset any system environment variables. Deal exclusively with environment variables unique to your application, and name them such that the likelihood of overlap with other applications is slim. .H 2 "Installing libraries, include files, etc." The biggest issue here is "DO NOT OVERWRITE ANYTHING THAT IS THERE ALREADY". Do NOT redefine any libraries or include files for your customer - they won't appreciate it. The same goes for any standard UNIX file or executable. In your procedures, feel free to supplement what is there now, but please don't replace anything. .H 2 "Notification to user" If there is any input required from the user along the way, use stdin and stdout (echo and read) to communicate from within your Install script. BE NON-UNIXY, keep the user informed if things are going to take a while. Ask the user for verification along the way if necessary (use message(1) if you want to). Inform the user of any problems and offer solutions or allow for choices to be made. Tell the user when it's all done. .H 1 "Removal of Installed Software" Choosing the "Remove Installed Software" menu item from the "Software Setup" within Administration will kick off the Uninstall.sh program (see /usr/bin/Uninstall.sh). The Uninstall.sh program will offer the user a list of the installed software and ask them to pick the one they want to remove. Once a valid choice is made, the Remove script that was originally supplied on the floppy disk is dredged out of it's storage place in /usr/installed where it has resided lo these many years. .P After finding it and executing it, the Installed software menus are adjusted to reflect the deletion. Note that the Remove script is run AS IS - how good it is and how safe it is depends on it's author. AT&T of course, will reserve the right to audit the remove script to insure it looks safe and sound and leaves things the way they were originally found. .H 1 "What Should the Remove Program Contain?" Your Remove program, once executed, should leave the system in the same state it would have been in had your application never been installed. This is not easy. The Install program should contain explicit path names of all files on the system which need to be removed (Full path names). Recall that the Files file will not be available when Remove is executed, and it may have contained different information anyway. .P Any suffixes and menu items you put in have to be removed. Depending on the situation - you may want to ask the users if they want to remove files in the system with your suffix on them - but DON'T DO THIS UNLESS THE USER SAYS OK - these files belong to them. Err on the side of safety when removing files - but do your best to be complete and make sure you get rid of stuff that the user would see. .P The user interface to the removal process is provided through the /usr/bin/Uninstall.sh program. Again, your best bet is to examine existing Remove programs now on floppy disks or in "installable files". .H 1 "How to PEEK at Floppy Disks or Installable Files" .P Since the floppy disks or installable files were created with cpio, it is possible to look at them without the aid of the user-friendly installation tools. To do so, create some temporary directory, cd to that directory, and then execute: .DS cpio -icBvdu < /dev/rfp021 .DE for a floppy disk, or for an installable file from THE STORE! do: .DS cpio -icBvdu < /usr/spool/uucppublic/STORE/XYZ+IN .DE since this is the directory the stuff shows up in after your order to THE STORE! is delivered (but before you install it). .P As a result of this manual cpio, you will get a bunch of files in your temporary directory. Among them will be the Install and Remove files for this application - something not normally visible or saved. .P The best way to write your files is to copy from an application which does similar things to what you want to do. .P There is a way to encrypt things such that the user will need to know a password to install them, and no amount of playing will allow a hacker to decode the files. If you have a need for this kind of operation, contact THE STORE!keeper for details. (Note that the tool is used in the installation of the TRWRITER package available from the most recent version of THE STORE!) .H 1 "Concluding Remarks" It's all really pretty simple, and the intent of the whole thing is to make it easy for the customer. If however, as unlikely as it may be, you have any questions about how to do all this stuff - please contact THE STORE!keeper. And last but not least, try to install the floppy set on a virgin system and ask yourself if you're happy with the way it looks when you're all done. .SG 0707070000020030741006440001460001440000010306570355327673200001300000000000TRAILER!!!grams now on floppy disks or in "installable files". .H 1 "How to PEEK at Floppy Disks or Installable Files" .P Since the floppy disks or installable files were created with cpio, it is possible to look at them without the aid of the user-friendly installation tools. To do so, create some temporary directory, cd to that directory, and then execute: .DS cpio -icBvdu < /dev/rfp021 .DE for a floppy disk, or for an installable file from THE STORE! do: .DS cpio -icBvdu < /usr/spool/uucppublic/STORE/XYZ+IN .DE since this is the directory the stuff shows up in after your order to THE STORE! is delivered (but before you install it). .P As a result of this manual cpio, you will get a bunch of files in your temporary directory. Among them will be the Install and Remove files for this application - something not normally visible or saved. .P The best way to write your files is to copy from an application which does similar things to what you want to do. .P There is a way to encrypt things such that the user will need to know a password to install them, and no amount of playing will allow a hacker to decode the files. If you have a need for this kind of operation, contact THE STORE!keeper for details. (Note that the tool is used in the installation of the TRWRITER package available from the most recent version of THE STORE!) .H 1 "Concluding Remarks" It's all really pretty simple, and the intent of the whole thing is to make it easy for the customer. If however, as unlikely as it may be, you have any questions about how to do all this stuff - please contact THE STORE!keeper. And last but not least, try to install the floppy set on a virgin system and ask yourself if you're happy with the way it looks when you're all done. .SG 0707070000020030741006440001460001440000010306570355327673200001300000000000TRAILER!!!grams now on floppy disks or in "installable files". .H 1 "How to PEEK at Floppy Disks or Installable Files" .P Since the floppy disks or installable files were created with cpio, it is possible to look at them without the aid of the user-friendly installation tools. To do so, create some temporary directory, cd to that directory, and then execute: .DS cpio -icBvdu < /dev/rfp021 .DE for a floppy disk, or for an installable file from THE STORE! do: .DS cpio -icBvdu < /usr/spool/uucppublic/STORE/XYZ+IN .DE since this is the directory the stuff shows up in after your order to THE STORE! is delivered (but before you install it). .P As a result of this manual cpio, you will get a bunch of files in your temporary directory. Among them will be the Install and Remove files for this application - something not normally visible or saved. .P The best way to write your files is to copy from an application which does similar things to what you want to do. .P There is a way to encrypt things such that the user will need to know a password to install them, and no amount of playing will allow a hacker to decode the files. If you have a need for this kind of operation, contact THE STORE!keeper for details. (Note that the tool is used in the installation of the TRWRITER package available from the most recent version of THE STORE!) .H 1 "Concluding Remarks" It's all really pretty simple, and the intent of the who