vUpdate v1.503 - User Manual

Table of Contents...
Introduction
Stuff about this manual What is vUpdate? Why was it built? How does it work? Execute Ready Connect to server Check for self upgrade List updates User makes selections Download Install Done
Reference
The Update Scripts The basics The vUpdate script Field Reference Announcements Description DownloadTo EntryCode Execute FileName FileSize MessageBox Mirror* PreviewPic Title Type Version
Misc
Contact

Stuff about this manual... up
Please note that this manual will make frequent references to the free version of vUpdate bundled with the open source Dev-C++ IDE (very popular win32 front end for GCC). It is highly recommended that the reader downloads Dev-C++, as this is an excellent way for them to see vUpdate in action. All the graphics on this page are encoded in .png format. If they look messed, it is probably because your browser is too old and crappy. I have noticed that Konqueror, Opera, Mozilla, and Netscape 4.x seem to work just fine. This manual assumes that the reader has a basic knowledge of the Winblows operating system. Developer knowledge is not required, but it will be an asset. Note that the pictures in here may not reflect what vUpdate really looks like. vUpdate gets better and better every day so some things may be different in the version you have.

What is vUpdate? up
vUpdate is a portable, flexible, and extremely powerful "web updater". By portable I mean it is a stand alone component that can be wired into virtually any existing software package, and as far as I am aware, the only one of its generation in existence. It allows everything from patches and documents to third party plugins to become available to all your end users through a simple, logical and aesthetically pleasing interface. For the developer, this means that one minute after you compile your latest release, it can be made available to everyone in a place where it will naturally be expected. If you are in the marketing field, you of all people understand how rapidly the computer scene is changing. vUpdate gives your application a gift, a port hole to unlimited expansion. Please read on if you are interested. This is what it looks like...

Why was it built? up
vUpdate began with the notion that most software is far more annoying than need be. I realized one day how frustrated I had become with keeping my compiler updated with the latest libraries, docs, binaries, and whatever else. This always involved going deep into Source Forge and finding some archive I needed. Then I would have to worry about whether or not I got the right one because the file names are always insanely long (but informative once you know how to read them). Next would come the installation (if it even came with one). This would always involve reading docs that were over worded and gave you far too much information than need be. Especially when all you wanted to know was which directory this file goes in. I figured, I don't have time for this, and neither does anyone else I know. After thinking about this for a while, I came to the conclusion that the entire process behind application expansion is almost always the same for everyone using that particular application. Computers love long boring repetitive tasks, so why not show it how to do all this for me...

How does it work? up
As stated above, the process for upgrading an application is usually the same as it ages. For example, when I need to update my compiler, there is a procedure that is always followed for that specific compiler. I download the latest libraries and dump them in the library directory. I take the headers and put them with the others and do the same for any new binaries. This process has become a regular for me, yet it is still very time consuming. The only dynamic part of the process is the updated files, their destination, and possibly a few other things. Because of this, both logic and data in vUpdate have carefully been separated which leaves you with enough exposed to accurately describe what you want it to do and leaving the rest to automation. Here is a step by step example of a typical vUpdate scenario with the Dev-C++ IDE...
Step One - Execute vUpdate is executed from within its parent program. The URL to an update script is passed as its first parameter.
Step Two - Ready vUpdate is opened and the user is immediately presented with a well organized self-explanatory interface. Note: The logo you see in the picture box on the top right can be, as with many other parts, modified to suit your needs.
Step Three - Connect to server When the user hits the start button, vUpdate downloads an update script (see step one). It will then analyze the script and do as it is told (I will show you how the update script works later. Just note the differences in the above picture with the following one for now).
Step Three (and a half) - Check for self upgrade Like your software, vUpdate is also self-upgradable. When a bug is found or a feature requested, I can quickly implement it and redistribute the newer vUpdate to everyone with it. This means that the possibilities of vUpdate, like your software, will also become unlimited.
Step Four - List updates The user is now presented with a list of qualified packages available on the update server. They can scroll through the list as they please to check them out. When they find one they like, they simply position the cursor over it and an optional package description / preview picture is displayed (see the screen shot below). You can use this to notify the user of special precautions, or possibly last minute release information. Use the preview pictures to your advantage too. 3rd party plugin? No problem, stuff their logo in there. You may also choose to use the announcements window to display to your clients anything from the latest news to the bad joke of the day.
Step Five - User makes selections The user may check as many items as they wish. Those checked are marked for download and will be handled as specified in the script.
Step Six - Download All marked files are downloaded off the server and into a location on the clients machine (specified in the update script). The progress of the operation is visually displayed with a progress bar on the bottom.
Step Seven - Install Certain tasks may need to be performed after a file is downloaded and put where it needs to go. In this case, PackMan (the Dev-C++ package installer) is being run because the update the user selected is a special add on for Dev-c++.
Step Eight - Done vUpdate is now done downloading and installing all the items that were requested. Any errors that may have occurred during the process are clearly marked in the status window. The status window is invaluable when it comes to finding out what went wrong, and lets face it, occasionally shit happens. At this point the user can, if they wish, hit start again and begin the whole process all over again if they want more updates.

The Update Scripts up
The basics Before I started writing vUpdate I had a pretty good idea what I wanted. I knew that who ever was going to be maintaining the update scripts, like everyone these days, would have little time. So I figured I should keep the syntax as similar as possible to something they are already familiar with, the .ini format. In reality though, there isn't really a standardized format, but there is a certain "generalishness" that they all have...
; I am a comment. Everything after the semi colon on this line is ignored... [Key A] field = "stuff" ; More comments... foo= "more stuff" [Key B] field = "The value" Field = "another value" moreFields ="values and stuff" ; Some more comments... ; Note that fields under each key are unique. i.e. Key A's field is not ; equal to Key B's field. Think of the fields as being part of a set of the ; key above it. Fields are also case sensitive so Key B's field and ; Field are not equal. Also remember that both keys and fields are both ; case sensitive. Any who, If you still don't get it, try this... [Phantom] ; Really sweet paintball gun... Bolt = "Closed Bolt" Action = "Pump Action" Manufacturer = "CCI" Caliber = "68" ; .68 of an inch... Velocity = "270" ; 270 feet per second... Class = "Stock Class" ; No loader, takes paint tubes... [Model98] ; Another cool paintball gun... Manufacturer = "Tippmann" Velocity = "290" ; Optimal velocity... Action = "Semi Auto" ; for those who can't aim ;)... Bolt = "Open Blow Back" Caliber = "68" ; I hope that clarified things for you. Note that each key's fields do ; not necessarily have to be declared in the same order. Also note ; that Model98 does not have all the same fields as the Phantom's key. ; When vUpdate reads in a key in the script, it looks for certain ones ; and keeps track of the fields specified. It will also fill in fields ; that are optional that you did not specify. Also, take close note of how ; much more readable the second example is over the first. vUpdate doesn't ; care how you do it, just as long as there is a field name, an equal sign, ; and then the data surrounded by quotation marks all on one line.
The vUpdate script This is a sample update script. Tailor it to your needs and place it on your update server. Simply pass the url to vUpdate as its first parameter when linking it into your application... i.e. "vUpdate.exe http://192.168.1.2/update.ini"
; This is a server side file called update.ini... ; This is a mandatory key. This is where vUpdate grabs basic settings.... [SETTINGS] ; This specifies the url to the directory on the update server containing ; all the files we will need for the rest of this session. You can specify ; up to 32 different mirrors. To balance your bandwidth load, vUpdate ; selects a random one for you. You can specify up to 32 different ; mirrors, but you must always specify at least one. Mirror1 = "http://192.168.1.2/devfiles/" Mirror2 = "http://www.someserver.com/files/" Mirror3 = "http://www.anothermirror.com/" ; Look at this. The text in the announcements window comes from this field. ; Anywhere vUpdate sees "\n", it will display the following characters on a ; new line if applicable. Announcements = "Greetings...\n\nWelcome to vUpdate, enjoy =)" ; Each update you saw listed has all its information encapsulated under ; its own key. The first package you define is called PACKAGE1, the next ; PACKAGE2, then PACKAGE3, and so forth. For simplicity, I will just list a ; single sample package. Please note that for a complete list of available ; fields, please check the Field Reference. [PACKAGE1] ; Name, as you want it to appear when listed... Title = "cryptoAPI" ; The version of this item... Version = "1.0" ; Identifier of item as you want it logged in the install database... EntryCode = "cryptoapi" ; File name on server. Assuming we are using Mirror1, this gets expanded ; later to "http://192.168.1.2/devfiles/cryptoAPI.zip". FileName = "cryptoAPI.zip" ; The item's description as you want it to appear in the description window. Description = "Microsoft cryptoAPI for Dev-C++. \n(zipped package)" ; This is where vUpdate will download the file to. In the case of Dev-c++, ; there are many macros (i.e. $TEMP) that are available here. Some include ; $ROOT, $BIN, $HELP, $ICONS, $TEMP, $INCLUDE, $LIB, $LANG, $WINDOWS, ; $THEMES, $SYSTEM, and $SYSTEM32. You are probably beginning to realize the ; potential vUpdate has now on your product. Also, if the path you specified ; does not exist, vUpdate will create it and any necessary parent ; directories. DownloadTo = "$TEMP\Downloaded Packages\" ; This is the file name of this package's preview picture. This is optional. ; If you don't want to use one, simply specify "NA", "", comment it out, or ; just don't type it in. If you do use one, it should be a bitmap (.bmp) of ; 130 by 70 pixels in dimension. I recommend a maximum of 256 colors as this ; calculates to only 10 kilobytes per preview and much less if you use an ; even smaller color palette. More graphic formats will most likely be ; supported in the future (i.e. .png). PreviewPic = "cryptoapi.bmp" ; This is a flag. It can either be "TRUE" (or "1") or "FALSE" (or "0"). Set ; it to true if you want this file to be executed after it is downloaded. Execute = "TRUE" ; This flag (for the Dev-C++ IDE) operates the same as above. Set it to ; true if you wish Dev-C++ (the parent application) to be closed. This is ; useful when upgrading the parent applications main exe seeing that you ; cannot write to a file that is locked. CloseDev = "FALSE" ; You are probably wondering what I was smoking when I put this lonely key ; here. This is actually the first thing vUpdate checks. Put it at the very ; end of your script to tell it that this file is complete and didn't ; come in corrupt (because every now and then http goes stupid). [END]

Field Reference up
This section of the manual is useful for finding out what fields are available to you and what they do. You may wish to bookmark this section as it doubles as both a guide and a reference. Note that the * character is a wild card. It means that anything can be there, but in this case it is probably an integer. By the way, if you see a new field here that just came out, you can use it. vUpdate is self upgrade able so anything I add here will immediately become available to you.
FIELD: | Announcements
KEY: | SETTINGS
DESCRIPTION: | This is an optional field. When specified, its data will be placed in the announcements window. Use the '\n' characters to tell vUpdate that the following text belongs on a new line.
EXAMPLE: | Announcements = "Hello world.\n\nNew line"
FIELD: | Description
KEY: | PACKAGE*
DESCRIPTION: | This is an optional field. The description string is what is displayed when the user positions the mouse over this package's item. The text will go in the description box on the mouse over.
EXAMPLE: | Description = "Hey there!\n\nThis is a description!" ; Use the '\n' characters to put stuff on a new line.
FIELD: | DownloadTo
KEY: | PACKAGE*
DESCRIPTION: | This is a mandatory field. The field specifies where this packages file will be downloaded to. You could specify a path if you really wanted to, but its not recommended because everybody's machine is different. So, you may choose to use the macros provided. The vUpdate that ships with Dev-C++ has several that include...
$ROOT | Dev-C++ root directory.
$BIN | Compilers binary directory
$HELP | Dev-C++ Help directory
$ICONS | Dev-C++ Icons directory
$INCLUDE | Compiler include directory
$LIB | Compiler library directory
$LANG | Dev-C++ language file directory
$TEMPLATES | Dev-C++ project templates directory
$TEMP | Temporary directory created by vUpdate at runtime. Put stuff here if you are just going to be needing it for a short time (such as an installer). vUpdate will delete it on exit.
$THEMES | Dev-C++ interface themes directory
EXAMPLE: | DownloadTo = "$HELP" ; This means that this packages file will be downloaded into ; the help directory overwriting any other file with the same ; name. ; You also can place it in a sub directory if you wanted to ; instead... DownloadTo = "$HELP\some stuff\more stuff\" ; If that path and all its parent directories do not exist, ; vUpdate will create them for you.
FIELD: | EntryCode
KEY: | PACKAGE*
DESCRIPTION: | This is a mandatory field. The entry code is how you want to identify this item in the installation database. When vUpdate scans each package tag, it checks to see if this entry code is already logged in the installation database. Think of it as a signature. If it is found, then it will check the package version. If the package version in your script is newer than the one they have installed, it will be made available to them. Otherwise it will be skipped.
EXAMPLE: | EntryCode = "OnlineTutorial"
FIELD: | Execute
KEY: | PACKAGE*
DESCRIPTION: | This is an optional field. It is a flag that accepts boolean values (TRUE, FALSE, 1, 0). Set it to true if you want vUpdate to execute this item after it is downloaded. This is useful if you are distributing an installer such as Nullsoft's NSIS.
EXAMPLE: | Execute = "TRUE" ; If this is some kind of an installer, I recommend you ; DownloadTo $TEMP.
FIELD: | FileName
KEY: | PACKAGE*
DESCRIPTION: | This is a mandatory field. It is the file name of the package as it appears on the server.
EXAMPLE: | FileName = "LatestTutorials.hlp" ; so, assuming the selected mirror was declared as... ; Mirror* = "http://192.168.1.2/stuff" ; this will resolve to... ; http://192.168.1.2/stuff/LastestTutorials.hlp
FIELD: | FileSize
KEY: | PACKAGE*
DESCRIPTION: | This is an optional field. This is the file size of the package. It can be just an estimate if you wish. It will be displayed in the package description windows just above your description. If you don't specify a value, vUpdate will just use a '?' character. Note: vUpdate will pay no attention to this value because it has nothing to do with how the file is downloaded.
EXAMPLE: | FileSize = "30 Megabytes" ; Top of description window will now look like this... ; Size: 30 Megabytes
FIELD: | MessageBox
KEY: | PACKAGE*
DESCRIPTION: | This is an optional field. Use this to have vUpdate popup a message box containing a string of your choice. Useful for installation reminders or whatever else you may want.
EXAMPLE: | MessageBox = "Note:\n\nDon't forget to read the readme!"
FIELD: | Mirror*
KEY: | SETTINGS
DESCRIPTION: | This is a mandatory field. It specifies the complete URL to the location of all files to be reference for an update session. The * is a number starting at 1 and can range all the way up to 32. This means you can have up to 32 file mirrors. vUpdate will select a random one for you each time the start button is pressed. This is useful for balancing your bandwidth load.
EXAMPLE: | Mirror1 = "http://192.168.1.2/update" Mirror2 = "http://www.someserver.com" Mirror3 = "http://192.168.1.3/files/"
FIELD: | PreviewPic
KEY: | PACKAGE*
DESCRIPTION: | This field is optional. Use it if you want a preview picture displayed in the picture box every time there is a mouse over of this packages list item. The picture must be a bitmap of 130x70 pixels in dimension. You can use any color depth you wish, but I recommend 256 colors max because that leaves it at around 10 kilobytes per preview pic. In the future, there will probably be more support for other formats (png, jpg, etc.).
EXAMPLE: | PreviewPic = "help.bmp"
FIELD: | Title
KEY: | PACKAGE*
DESCRIPTION: | This is a mandatory field. It is the name of the package as you want it to be displayed when listed. It is recommended that you keep your title as short and descriptive as possible.
EXAMPLE: | Title = "Online Tutorial Updates"
FIELD: | Type
KEY: | PACKAGE*
DESCRIPTION: | This is an optional field. Use this to tell vUpdate how you want your update classified. Valid entries totaly depend on your distribution of vUpdate. With Dev-C++ though, you can use package, patch, language, and help identifiers. If vUpdate comes across a type it does not recognize, it will be classified under the other category. This also goes for if you didn't declare a type. Please note that the "type" field's data is not case sensitive.
EXAMPLE: | Type = "help"
FIELD: | Version
KEY: | PACKAGE*
DESCRIPTION: | This is a mandatory field. This is the version of the package you are releasing. You may use any integer or float. It is recommended that the reader checks out the EntryCode field for more information.
EXAMPLE: | Version = "3.644" or Version = "2" ; Don't do this... ; Version = "4.43 Alpha Release 6" ; vUpdate will have no way of quantifying that information.

Contact up
E-Mail: kip@zero47.com Website: http://www.zero47.com ICQ: 29008229