═══ 1. SFX Installer ═══ The SFX Installer is made up of two parts. The setup tool [SFXSetup.exe] and the actual Installer which is put together when the setup is complete. The setup tool will help you easily put your package together by letting you select items and fill in the blanks. This saves you the trouble of cryptic commands or scripts that need to be filled out. The toughest part will be getting your setup strings together (for desktop objects) but most of you should be familiar with that. The SFXSetup tool will allow you to:  Select files to archive  Set the archive name  Set the destination directory  Toggle - use installer  Toggle - make self-extracting  Select a bitmap for the splash screen  Setup unlimited object strings  Customize the color scheme  Personalize the installer with your program name  Set special commands by way of plugins  Set readme or license files to show the end user  Toggle dll & help path windows  Save or reload your archive setup information The installer is based on the same installer used for WarpZip. It leads your user through the installation page by page. It installs your app and if you have used the SFX option will clean up back to it's original file. It will:  Slide your bitmap into the splash screen  Personalize a few spots in the text  Allow users to set the installation directory  Create the installation directory if needed  Allow users to select an existing dll directory or modify the LIBPATH  Allow users to select an existing help directory or modify SET HELP  Backup config.sys if needed  Skip dll & help pages if you don't need them  Create unlimited objects  Write a log file of the install  Write an Uninstall script specific to the installation  Show your License or readme  Run your plugin (Rexx .cmd file) at installation time It will not:  Create directories more than one deep  Package archives with subdirectories Here are some other Notes and tips ═══ 2. Notebook pages ═══ Notebook pages A blow by blow description of each page. [terse]  Directory container  Program files  Archive name  Install settings  Objects  Colors  Plugins  Finish  Zip Location ═══ 2.1. Directory container ═══ Directory container The directory container attempts to show every available drive and is used in two different ways depending on what window is open in the notebook.  When the Program files page is showing, selecting directories aids in locating the files you want to add to your archived package. Each time a directory is chosen, the listbox on the "Program files" page is updated with the contents of that directory.  When the Archive name page is open, you can use the directory container to aid in choosing your directory for the "Archive location" entry field. ═══ 2.2. Program files ═══ The Program files page The Program files page shows a listbox and three radio buttons. Here you will choose what files to add to your archived distribution. When you select a directory from the directory container on the left side, the files contained in that directory are automatically listed in the listbox on this page. The "Directory" radio button is automatically highlighted when you start. If you select a file in the listbox the "Selected files" radio button will be automatically highlighted and only the selected files will be added to your archive. Be sure to check if this is the setting you want before leaving this page. It is also possible to delete files from the directory by highlighting the files you want removed and hitting the [DELETE] key on your keyboard. This may be desirable when you have changed the bitmap you will be using or wish to drop some files from the distribution and still want to archive by "Directory". Again, check to see if the correct radio button is selected for the type of file listing you want to archive before leaving this page. Note: Building your archive with the "Directory" choice is much faster than doing it by "Selected files" because of the way it is processed by zip.exe but the progress indicator will not be incremented as well for the same reason. ═══ 2.3. Archive name ═══ The Archive name page The Archive name page consists of two entry fields for your archive's new name and location.  Archive name - This is the actual name you want for the zip file or self-extracting exe if you use that option. The name will be automatically adjusted (zip or exe) depending on selections made elsewhere in the program. Warning: Previously you could not use the same name as a file in your archive may have. For example, if your widget program was called "Widget.exe" you could not use "Widget.exe" for the archive name. We have added an automatic renaming scheme but it still needs a thorough testing. Please be sure it is working properly before sending your archive out.  Archive location - This is where you want the archive to reside when it is built. You can use the directory container to aid in choosing your directory. Because of the nature of this program, older archives in are overwritten by default. If you wish to save an old archive you must move or rename it or it will be lost. This shouldn't be an issue for most as it is much less of a pain to save one once in a while rather than always having to confirm an overwrite. ═══ 2.4. Install settings ═══ The Install settings page The Install settings page has these choices:  Program name the installer should use - Enter the name you want the installer to use to identify your program in the text fields during the installation. Be sure to test run the installer and check the locations your name is used to be sure the context is correct for the name. Usually a simple title will work best. A long name will push other text out of their allotted space. Don't, for example use a name like, "Joe's Black Book version 3.1 revision 2". Keep it short and check the context.  Suggested directory name the installer should use - This will be the initial directory shown in the directory field of the installer. Your suggested name will be appended to the root of the boot drive's name. Example: Your suggested name is "Widget" and the users boot drive is "C". The installer will list "C:\Widget" as the suggested directory. The user may, and most likely will, change it to a location that they prefer.  Bitmap to use for the splash screen - Enter the bitmap name here or click the "Browse" button to locate it. This field must have the fully qualified name of the bitmap. Your bitmap must also be an OS/2 .BMP file. Best results will be with bitmaps measuring 335x200 (pixels) or less. (from my tests this size allows it to fully display on a 640x480 resolution system. Experiment with this until you've found what you want. If this field is left empty the installer will show a generic "SFX Installer" bitmap. Large bitmaps can be used to good effect too but the weight they carry in filesize is usually to much to bear.  Use dll page - If this checkbox is selected, the installer will use the dll page that gives a listing of current LIBPATH entries. If the user chooses to place your dlls in one of the listed directories it will avert the need to modify the LIBPATH statement in the config.sys. If you don't need to place your dlls in the LIBPATH you may leave this unchecked and they will be handled just like your other files.  Use help page - If this checkbox is selected, the installer will use the help page that gives a listing of current SET HELP entries. If the user chooses to place your help file in one of the listed directories it will avert the need to modify the SET HELP statement in the config.sys. If you don't need to place your help file in the SET HELP path you may leave this unchecked and it will be handled just like your other files. ═══ 2.5. Objects ═══ The Objects page Add any setup strings for objects you need to create in this field. These are Rexx "SysCreateObject" calls and you can add as many as you want as long as they are on separate lines. The variable "InstDir" can be used in your setup string to denote the installation directory name without the trailing slash.  First line - one setup string (a folder maybe)  Second line - another string (your program object/icon)  Third line - another string (your readme.1st object/icon)  and so on...  and so on... I'm sure most of you are familiar with them but... just in case... Example setup strings are included and loaded when the program is started and will continue to load at startup until such time that new default settings are saved. When you save default settings you will be saving any setup strings in the entry field over the top of the old ones. If the original strings are in the entry field they will be saved otherwise your changed strings will become the defaults loaded at startup. In order for the uninstall script to work, all of your creations will need an OBJECTID included in the setup string. The setup tool will warn you if an OBJECTID is missing but will still build the archive. The three example strings included at program start show how to create a folder and two program objects. Feel free to modify the examples to fit your installation requirements. Remember to do them in the proper order. You'll need to create the folder (if you need one) before you can place program objects in it. A one line string isn't as pretty as a nicely formatted one in a cmd file but it will work this way. The installer doesn't know what your strings are but can execute them if they are formatted properly. Take a look at the examples, the ini.rc file in your \os2 directory or the OS/2 Procedures Language 2/Rexx for some further insight into setup strings. Remember: Choose OBJECTID's carefully. Do not use the same ones anyone else may use. This will only cause trouble between applications. Your OBJECTID's should be something no one else will use so be sure to choose wisely. Also, be sure to change or delete the examples before you build an archive. You won't want any of them to go with your application. ═══ 2.6. Color Scheme ═══ The Color Scheme Page  The Color Scheme page has three buttons on it. Pressing either of the top two will open a mockup of either your install.exe splash screen or one representing the rest of the pages. It will also open the OS/2 color palette so you can drag any color selections to the mockup to customize your color scheme.  A simple drag and drop from the palette will change the background color.  Holding the key down while dropping a color will change the foreground color. (text color)  If you make no changes the installer will use it's own defaults or  If you've made changes and wish to return to the program defaults just press the "Return to default scheme" button.  If you have selected a bitmap to use on the Install settings page, it will be used in the mockup.  Pressing the "Next" button on the Splash screen mockup or the "Back" button on the "Pages" mockup will open the other window for color editing. Check the Tips page setting background color when using large bitmaps. ═══ 2.7. Plugins ═══ The Plugins Page The plugin page allows you to select files from your archive that will do two things. You can:  Write a cmd file that can be processed while the install program is running.  Have the installer show a text file (maybe a readme.txt or a license) to the user. If it is important for you to display your license agreement before installation be sure to use the word "License" in the name of the file. If the installer loads any file with "License" in it's name it will show an "Accept" or "Do not accept" button. The installer will automatically close and clean up if the "Do not accept" button is pressed. I am not sure of all the legalities but would think that this would confirm the entrance of a contract between you and your user since he cannot use the software without going around the installation. Any other file (a readme.txt etc) will be loaded normally when using the text window and will only show a "Close" button. Plugin selection The listbox carries the file listing that you are using for the archive. To select a file and assign it for the installer you need to:  Highlight the file you wish to use/display  Click the button that refers to how you want it used After clicking the button, the filename will appear above the button that refers to it. To make it a bit more flexible, you can choose whether to have it process these files at the start of the installation or at the end. The "PRE" type files will always show or run immediately after your bitmap has finished sliding onto the splash page. The "POST" type files will run after all the installer processing has finished and the program is ready to close and clean up. While the possibilities and usage of the text files will be obvious to most of you, the cmd files may need a bit more explanation. Suffice it to say that it lends you as much power during the installation as Rexx provides in OS/2 and that is darn near limitless. You might, for example want to:  Create directories  Jockey files around  Add information to the os2.ini file  Make adjustments to your program ini files  Get system information  Show the user a messagebox with info You decide what you want to do and the installer will execute it. The sample supplied with this program shows a simple messagebox just to show you how and at what time in the installation it works. You will probably not want to be so intrusive with your plugins. You can (and probably "should") have them run without the user even realizing that it is even there. Like the setup strings, the variable "InstDir" is available to be used in your plugin to help find the installation directory for any work you may need to do. The "InstDir" variable is always without the trailing slash. ═══ 2.8. Finish ═══ The Finish page The Finish page has three radio buttons, a "Build" button and a process indicator. The radio buttons help select the type of archive you wish to build and the "Build" button will begin the process of gathering all of your information and building the archive accordingly. Here are the choices:  Standard zip no installer - Will build a common "zip" archive with a "zip" extension. All self-extractor and installer options are ignored.  Standard zip with installer - Will build a common "zip" archive with a "zip" extension. The installation program is configured and placed in the zip archive. The installation program does not start automatically.  Self extractor no installer - Will build a self extracting "zip" archive with an "exe" extension. This will build your archive in the common self-extracting zip format but will not add the installer to the archive.  Self extractor with installer - Will build a self extracting "zip" archive with an "exe" extension that will automatically run the installer when it is executed. All files that were extracted from your archive will be removed by the installer once the installation is finished. Once you have made your selections and are satisfied that it is as you like it you may press the "Build" button and let it work. The text over the progress indicator will keep you abreast of what is happening and there will be a small beep when the build is completed. ═══ 2.9. Zip Location ═══ The Zip Location page The Zip Location page has two entry fields for the locations of InfoZip's zip.exe and unzipsfx.exe. SFX tries to locate them on startup so they may already be entered for you but if they are not, you'll need to "browse" for them. Be sure you are using version 2.2 of the InfoZip "Zip" utilities. If the version that is found or the one you browse for is not version 2.2, the entry field will remain blank and you will not be able to use the setup tool to build archives. The reason it needs to be 2.2 has to do with the way the archives are adjusted when they are built. ═══ 3. Menu items ═══ Menu items Here are a few short menu item explanations that are not part of the obvious ones every program has.  Load archive setup  Save archive setup  Save default setup ═══ 3.1. Load archive setup ═══ Load archive setup When using "Load archive setup" a dialog will open with an entry field, a combobox and two buttons. To select a setup to load you will open the combobox, make a selection and click the "Open" button. All information from the chosen setup will be imported to the program and should, at that time, be set up just as you had it configured when you saved the setup. Please check the individual pages for accuracy before building from the configuration. There may have been changes in your directories etc. since you saved the setup that will make some entries invalid. ═══ 3.2. Save archive setup ═══ Save archive setup When using "Save archive setup" a dialog will open with an entry field, a combobox and two buttons. Enter the name you wish to save the setup under or select an existing setup from the combobox. To select an existing setup from the combobox, you will open the combobox and click on the name you are looking for to make the selection. After the name is entered or the selection has been made you may click the "Save" button to have the program process and save all of the setup information. Please check the individual pages for accuracy before saving any configuration. ═══ 3.3. Save default setup ═══ Save default setup When using "Save default setup" the program will process and save all of the setup information that is currently loaded. After saving a default setup, the program will always load it at each startup. This is handy if you want a certain set of colors, setupstrings, a certain build directory etc to be loaded and ready to go every time without having to set them manually. ═══ 4. Notes and tips ═══ Notes and tips I never was very good at taking notes...  General Installer Notes  SFX Installer Notes  SFX UnInstaller Notes  Tips ═══ 4.1. General Installer Notes ═══ General Installer Notes  Try to keep your bitmaps as small as possible. The OS/2 BMP format is not known for it's compression. Try indexing your bitmap to 256 colors and use RLE/Huffman encoding to save some space. I have seen some bitmaps that do not seem to want to work using RLE/Huffman encoding though. YMMV  By default the installer will scroll your bitmap to the center of the form and vertically centered just above the centerline. You can offset your image with white space if you want your bitmap to appear left of center for example. (to balance it out with the buttons) So you might draw a 200x100 bitmap all the way to the left inside a 300x100 bitmap that is all white. The installer will see it as a 300x100 and scroll it to the center, the extra white space on the right doesn't show up on the white background and your offset part of it will appear left of center. If you're wondering what is meant by all of this, you can see an example by dropping some color on the splash screen of the sfx.exe archive this program came in.  Although a 450 pixel wide bitmap will fill the splash page in 1024x768 resolution, try to keep your bitmaps less than 335 pixels wide and 200 pixels high. This will allow the full bitmap to fit on the splash screen for the people using a lower resolution like 640x480. It is possible to use larger bitmaps to fill the background on all resolutions with good effects by keeping the important parts of it on the middle 335x200 area and if the file size doesn't become to much to bear. Note: If you want to avoid the buttons with your bitmaps when the user is in 640x480 resolution you may want to stay under 183 pixels high.  Large bitmaps can be used to show a fancier background if you care to attempt it. Try to keep your title information in the middle 335x200 area of the bitmap or it may not appear properly on low resolutions. We have tried a 500x350 bitmap that seems to give a nice effect this way.  The bitmap may smear across the screen for some users. Most video cards shouldn't do this but it has been noticed happening sporadically on an older machine with an old cirrus card in it. If anything else was going on it would smear. I guess that's the price we pay for all this glitz. ═══ 4.2. SFX Installer Notes ═══ SFX Installer Notes  After an SFX installation, the installer will always delete all the files it has unarchived while leaving any files that were pre-existing intact.  Because of the nature of the self-extracting installer and it's clean up of temporary files, the user will not be allowed to install into a directory that the installer is started from. There will be a message to that effect if the situation arises but it might be something that you mention in your readme.  The SFX Installer will check free space on the current hard drive when it is about to unarchive and if it is marginal will ask for a new drive to place temporary files in. It will keep asking if the followup drives are marginal also. You can force it to try anyways by using the F parameter. We are considering whether to find space automatically instead of asking which drive to use but a decision has not been made relating to that yet.  Previously you could not use the same name on an SFX Installer archive as a file inside your archive may have had. For example, if your widget program was called "Widget.exe" you could not use "Widget.exe" for the archive name. We have added an automatic renaming scheme but it needs a thorough workout to be sure it is mistake free so please make sure your archive works properly before you send it out. There are some reserved names that are not allowed as they will conflict with names used by the installer. That should not be a problem for the most part though. They are:  Install.exe  Install.dat  Install.log  UnInstal.cmd These files are deleted (if they already exist) and are rewritten each time an archive is built or when it is installed depending on the files usage. ═══ 4.3. SFX UnInstaller Notes ═══ SFX UnInstaller Notes  All we are actually doing for an uninstaller is writing a rexx script (and it is pretty simple) when the installation is finished but just before the program closes. It is written using information from the users installation choices so if they put dll's in c:\bin\dll for example, we add a line in the script for every dll that is put there. Using a rexx script also means that after deleting all the files and destroying any objects that the installer created, it can back out of the directory and delete it too leaving no trace of the installation... with some minor exceptions... - Nothing is added to remove info from the config.sys if the user had the installer change it. There is just a message for the user to do that manually. - It doesn't account for any subdirectories that may have been created. - It doesn't account for deleting read only files.  Some of the script writing is conditional... IF there were dll's written to another directory THEN add warnings about deleting them etc. We could add the config.sys info removal also but because it is put together dynamically, without our actual reviewing of it when it is finished, we need to be sure it works EVERY time with NO mistakes before we add something of that nature. The UnInstall script is actually pretty simple and is always customized to the specific installation. You can see exactly what it is by taking a peek at the script after you install a program using it. It is also possible for you to modify the uninstall script also via a plugin if you need to. Let's suppose that you have written a plugin to do some extra work. You might:  Create another directory under the program directory  Unzip a zipfile that was installed with the program into the new directory  Delete the zipfile  Find the line with the zipfile name in the uninstal.cmd file and remove it  Add lines to the uninstal.cmd file to delete the files you just unarchived  Add a line to the uninstal.cmd file to remove the directory you just made These may be great lengths to go to but they will help overcome the limitations of what this installer can do for you. The uninstall script also makes the user confirm that any dll's are looked over first if there were dll's installed outside of the program directory. It will not run until the user reads the warnings and affirms the deletion. ═══ 4.4. Tips ═══ Tips  If your bitmap covers all of the splash screen mockup when you are dropping a background color onto it, the dropped color will not be seen by the background at all. To be able to do this you will need to: - Go back to the "Install settings" page - Select and copy the bitmap name into the clipboard - Delete the bitmap name from the entry field - Return to the "Color schemes" page and set your background color - Paste the bitmap name back into the entry field on the "Install settings" page ═══ 5. Distributing your application ═══ Distributing your application Warning At this time there is a problem with self-extracting installations done on Warp4 machines with fixpack 10 and Object Rexx installed. Apparently there are some issues that need to be resolved so you need to be aware of the situation and possibly make a "standard zip with installer" available to those who fit into this catagory. Please do not distribute archives built with this beta until it is pronounced ready. Besides your License agreement, there still may be things we need to make adjustments to that will save both you and I some trouble. If anyone tries your archive before the installer is fully tested and encounters a problem they will be giving you a call wondering why it doesn't work and you, myself and the installer will look bad in their eyes. The Hobbes FTP site allows "zip" files only to be placed on their site. That means most of you will archive using the "Standard zip with installer" option when building your archives. Using "Self-extractor with installer" will be something you may want to do for archives that are downloaded from your own website or distributed on disk or CD depending on the distribution method or the distributor. Normally Hobbes will only allow archivers and some compressed media files to be uploaded in anything other than a zip file. The rest of the archives must be in "Zip" format. When we release this program for example, it will probably be in a zip file. If you have a special situation that you want or need it for right away, please ask and we will let you know where we stand. Otherwise, we will let you know as soon as it is ready for public usage. ═══ 6. License ═══ Licensing The license agreement may sound a bit different than a standard one might as we'd like to help any freeware authors if we can because of all the unselfish things they have done and are doing for OS/2. It seems to us that this is a fair and just way of doing that and yet still staying on level ground with a commercial or shareware developer. For purposes of this License agreement the following terms shall apply. Commercial software - Software distributed through retail outlets, commercial vendors, commercial catalog sales. "Boxed" software is generally considered commercial. Shareware - Software not falling under the category of Commercial software that is distributed with a suggested, expected or required value that is paid for it's use. Shareware is considered electronically distributed with allowances made for distribution on disk or CD when required by the user or distributed on a publicly recognized and publicly available collection of shareware. Shareware does not include software that is "packaged in and packaged for" a commercial or government environment. Freeware - Software distributed at no cost to the end user. No renumeration is asked for, no renumeration is expected and no donations are suggested for it's use. Freeware does not include software that is "packaged in and packaged for" a commercial or government environment. Software generally considered to be "Postcardware" or "Emailware" will fall under this category. Program status - The determination of whether a program is in the Commercial, Shareware or Freeware categories. Developer - The author, developer, publisher or authorized agent for the program in question. License Agreement  The SFX Installer is not free. It is a publicly marketed program that allows any user to freely test and decide if it fits their needs before they make a purchase decision. PillarSoft also offers this program to FreeWare authors under strict guidelines for their personal use at no cost and at the pleasure of PillarSoft.  Freeware authors may seek a license from PillarSoft for the use of SFX, the distribution of archives packaged with SFX and distribution of self-extracting installers built with SFX at no cost when their product qualifies as a product that is distributed as Freeware and until such time that the program has a monetary value attached to it's usage.  For FreeWare licensees, the license will be rendered null and void upon the first distribution of a package that calls for a registration fee, donation or any other form of financial renumeration.  No archive or self-extracting archive packaged with, or from parts of, the SFX Installer and it's packaged contents may be used to distribute or package software or data for profit without prior licensing and the expressed written consent of PillarSoft.  The SFX Installer may not be used by any commercial or governmental agency without prior licensing and expressed written consent of PillarSoft.  The copyright notice (or banner) on the splash page must remain plainly visible at all times. (It is is not presently configurable)  The SFX Installer may not be used or distributed as part of any other program other than to perform the archiving or assist in the installation of said program as was intended by PillarSoft.  PillarSoft reserves the right to withdraw this program, the use of the program or a particular license for this program at any time and at the disgression of PillarSoft.  Determination of program status for the purposes of this license will be at the sole disgression of Pillarsoft.  Disagreements concerning PillarSoft's determination of the program status and the status represented by it's developer automatically void the program license.  Site licensing will be determined on a case by case basis.  Do not bend, fold or mutilate.  Objects may be closer than they appear. The long and short of it... The reason the license agreement gets a bit detailed is to prevent someone (there's always a rotten apple) from obtaining a license for his (or her) program claiming it is freeware or dirt cheap just to get a free or an unrealistically cheap license and then decide that it is worth $30 when it is actually released. This may seem like no big deal to most but personally, I have a hard time being nice to people that try to take advantage of others. I'd rather spell everything out ahead of time and avoid any problems in the future. We would like to be as helpful as possible to freeware authors. There are people that give so much to the OS/2 community in the way of free software (some of it is Great software) and never ask for anything in return. In some small way, PillarSoft would like to say "Thanks" and to see them receive the same treatment they have given to everyone else. For Shareware authors may contact BMT Micro for licensing. Commercial and governmental agencies may contact us directly at: support@pillarsoft.net We can be found on the web at: http://www.pillarsoft.net ═══ 7. InfoZip ═══ InfoZip The SFX Installer incorporates compression code from the Info-ZIP group into your archive. There are no extra charges or costs due to the use of this code, and the original compression sources are freely available from http://www.cdrom.com/pub/infozip/ or ftp://ftp.cdrom.com/pub/infozip/ on the Internet. SFX searches for Infozip's "Zip.exe" and "Unzipsfx.exe" upon program startup on new installations and are version checked for version 2.2. If you wish to relocate them you will need to update the "Zip location" notebook page with their new path in order to build any archives.