AppliCradle 1.0
Developers' Manual

  1. Introduction

    AppliCradle is a customizable, easy and simple installer and uninstaller. No coding is needed. Just make a few lines of script file. AppliCradle asks not the full license but a license per application, which makes the installer cost much less than other installers do.

    Important features are:

    • No coding needed. Make a folder. Add your software (application) and AppliCradle files to it. Edit several lines of a script file. Compress them into a file and distribute it. The user uncompresses and runs the installer.

    • The installer creates the program menu group and adds shortcuts of the program(usually *.exe) and the manuals (Manual.htm or ReadMe.txt).

    • The user chooses whether the program shortcut also be on the desktop, in the startup menu group or in the root of Start menu. The choices are initialized by your recommendation in the script.

    • An example application is provided for you to test the installer and the uninstaller.

    • Your application needs the license to match your program binary, for the installer to run: Submit the ID the installer generates for your program, and get the license, before you compress the package.

  2. System Requirements

    OS should be Windows 95, 98, Me, 2000, XP, Vista, or 7.

  3. Getting Started

    Unzip AppliCradle (*.zip) into a folder. Let's call it "the AppliCradle folder", whatever the actual folder name is. That is all of AppliCradle installation by you as a developer, who are going to make a software package. You are reading this manual (manual.htm) contained in the folder, and it will let you understand how to make the package. The 2 more *.htm files and the image files in the folder are used by the manual. The others are described in this and the other chapters.

    Create a folder somewhere in your PC (maybe in your software project folder), into which your files and AppliCradle's files are to be copied to constitue the package. Let's call it "the package folder", whatever the actual folder name is.

    There is a folder named "package" in the AppliCradle folder. Copy all folders and files in it into the package folder. Reading this chapter and running them, you will see what they are, and will modify or replace some of them by yours.

    Later, you may compress them into a file and distribute to your users. To compress (zip or other), use your method provided by your system or other tools. After uncompressing, your user is to run the installer(Install.exe). The user may remove the uncompressed folder, since your software folder in the uncompressed package is copied into the target folder ("Program Files" or other).

    1. Folders and Files

      Now turn to the package folder, shown below.

      In this example, the "software folder" or the "application folder" is named "MyApp". You may change the folder name later, filling the folder by your files. Note that the folder name will also be the names of the following 3 things.

      Firstly the folder will be copied into the target("Program Files" folder or other the user specify). Secondly, it will also be the sofware's menu group name, to be added to the system's program menu group (open by Start button). Finally, the shortcut to the program(usually *.exe) in the software will be named the same.

      The name MyApp is chosen for you to test without any restriction. If you modify its name into your software name, the installer(Install.exe) will not work unless the license file exists corresponding to your program binary in the application folder. Details about the licenses are in the chapter App-IDs and Licenses.

      Open the folder to take a look, as shown above. This example has just 5 files, but you may replace or modify 3 of them and add more files or sub-folders when you make your real package.

      MyA.exe is the example program to be replaced by yours. The text in Agree.txt will show up on the installer window. You may fill it with your software's license agreement. If Manual.htm, ReadMe.txt or both exist, the installer will add their shortcuts to the program menu group.

      The other 2 files should not be modified. Uninst.exe is the uninstaller. The text in AppliCradle.txt is about AppliCradle and will show up on the 1st stage of installer window.

      Let's turn back to the package folder. The folder "lib" contains softbatt.dll, which is needed for the installer to run, and also is to be installed (into the system folder) for the user to run the uninstaller.

      Open install.txt, to see or modify the script, according to which the installer will run, as described in the next section.

    2. Scripting

      The syntax is simple. The installer will ignore empty lines or any line starting with a blank. The meaningful lines have meanings according to the order of appearance, as described by the comment in a meaningless line above each line in the screenshot. More about them are as follows.

      The first line specifies the name of the program file to be found in the application folder, as said in the previous section.

      The installer will let the user determine the places where the program's shorcuts should be, in addition to the program menu group. The next 3 lines let you choose the default states of check boxes on the installer window, for the 3 places, i.e., the desktop, the startup menu group and the root of Start menu, respectively: 1 means the checked state and 0 means the unchecked state.

      There is no line in the script, for the application name. The installer searches the package folder, and takes the other folder than "lib" as the application folder (MyApp in this example).

    3. Installer

      Now, let's run the installer (Install.exe). 4 windows will show up one by one. The first 3 windows let the user see information and modify options. The ESC key or Cancel buttons on them terminate the installer, after asking confirmation. The final window performs the installation and shows results.

      The first window is saying about AppliCradle, which is read from AppliCradle.txt.

      The next 3 windows are customized by your files. The title bar of them includes the application name. That is, the bar says, "MyApp Installer" in this example.

      This window shows the text in Agree.txt. You should let the user see what the text is about, because the window title bar says nothing about it. In this example, the title "MyApp License Agreement" in the text clarifies what the text is about.

      In this window, the user can change the target folder, and select more places where the program shortcuts should be. The 3 check boxes are initialized as specified by the script.

      Before the Install button starts the installation, it checks folders. If the target folder does not exist, the user will be informed by an error-box and will modify the path. If the product folder exists already, a box will ask the user to go further or stop, since files and sub-folders will be updated (replaced) by the ones with the same names from the package, which happens when the user is installing a new version of your software.

      The installation starts, showing the final window as shown below.

      The installer copies files and folders, and creates shortcuts, reporting the results (including errors) in the log, i.e., a text box in the window. The progress bar below the log proceeds by the files' size until the bar points to 90% when the copying finished, and it points to 100% after the shortcuts created.

      During the installation, there can be warning or errors, as follows.

      A warning-box asks the user to skip or replace if softbatt.dll to install is older than the one installed. All files except it will replace without such confirmation.

      An error-box asks the user whether to retry or stop, when copying a file failed. The user can check whether the disk is full, for example, and retry (Yes button). The No button on the box stops the installation (without skipping to the next file or folder). When the installer fails in creating a folder, the installation stops without a box (but reporting in the log).

      After the installation finishes, the "Close and Run Now" button will be enabled. As well as this button, check the other results of the installation as follows.

      Click the system's Start menu to see the program menu group (as shown below) and run the shortcuts, as well as program shortcuts in other places.

      Open the product folder, to see what are copied from the package. The folder should be exactly a copy of the application folder in the package, except that you find a new sub-folder, named "Uninst" where there are some files. The uninstaller will internally use those "log files" to know what (including shortcuts) are installed (created or copied) and therefore they should be there for the uninstaller to work successfully.

    4. Uninstaller

      Run the uninstaller, by the shortcut in the program menu group. If the log folder "Uninst" is not found, the uninstaller shows an error-box instead of the following window and stops.

      As this window says, the uninstaller is going to copy itself and some files to the system's temporary folder, and will be run again there, because it cannot uninstall itself when running. This window also prevent the user from uninstalling by mistake.

      After the OK button pressed, the uninstaller closes the window and spends short time in copying as commented above. If it fails in accessing folders or in copying files, it shows an error-box and stops. Otherwise it stops after running a copy of itself in the temporary folder.

      Running again there, the uninstaller will start removing folders and files installed, including shortcut menus and menu group, reporting as shown below.

      The uninstaller will ask the user whether to remove softbatt.dll or to skip, since other software can depend on it. If a file or folder fails to be removed, a retry-box (error-box such as decribed in the previous section for the installer) will show up and ask the user to see that the file or a file in the folder be not running or opened.

  4. App-IDs and Licenses

    In general, you will not name your application (software) as "MyApp". This chapter shows you what will happen and what you will need, when you use other name.

    Let's go to the package folder and change the application folder's name from "MyApp" to other. Test the installer again. Eventhough the application name is now not "MyApp", all the features of the installer will work, because there exists the correct license file, a file named "applicradle", the binary of which matches that of the program (MyA.exe in this case).

    If you replace the example program by yours, the installer will not work (will run and shortly terminate without showing any window), because the license file is not correct, i.e. the license file does not match the binary of your program. How to get the correct license file for your program is as follows.

    Delete the (wrong) license file (or change the name), and run the installer. Then the following "license input" window will show up..

    App-ID is a kind of hash or checksum of your program binary. You will submit that to SoftBattery and get the License string. The string for the example program MyA.exe is CZNT-TCSG. Entering it and pressing OK button, you will see the window closed and the license file created. The string is saved in the file. Run the installer again, to see it work normally. Of course, the license file should be there when you make a package, for the user not to see the license input window.

    Note that the App-ID and the license both are case-sensitive 9 character strings with '-' and without a blank. You are recommended to use copy/paste functions of the windows than typing. Note also that even 1 byte difference may create a different App-ID, and be sure that your program is the final version to release. Even a famouse compiler creates different binaries from the same source, everytime you run the linker.

    Generally you may develop an application (program), make the package, get the license and test the installation before releasing. During the development you may test and debug the program many times, by running it on IDE, without installing the program. If you need to include the installation in developing the program for some reason, you cannot but name the application (folder in the package) "MyApp" temporarily (not to waste in licenses).

    In summary, keep in mind, not to buy more than one license for an application and not to be too nervous, that the license depends on the program binary and only on it. The license works even if you modify the other part of the application (files, folders, their names and binaries). Even changing the program name is safe.

  5. Miscellaneous

    When the installer runs and shortly terminates without showing any window, check and see that the followings are satisfied and try again.

    • If the application (folder) name is not "MyApp", check: Is the license file correct one ? (as commented already in the previous chapter.) Is the program name in the script correct?
    • Is there one and only one more folder other than "lib", in the package? (There should be one and only one application folder.)
    • Does the script file, install.txt, have sufficient lines?
    • Finally, is the installer correct? (Did you get a correct copy of AppliCradle at a safe web site free from cracked softwares?)

    The version of AppliCradle is displayed only on unusual windows in the installer and the uninstaller, in order not to make your users confused between your application and AppliCradle. The version appears on the title bars of the two window: the license input window in the installer, and the error-box for the log folder absence in the uninstaller.

    Here is just a tip for your application you may like or may not. You may use Agree.txt not only to show up on the installer. You may also let a link to Agree.txt be in your manual or program for the user to open the file, like the link in the next section in this manual.

  6. License Agreement

    Please read AgreeAC.txt.