User's Guide - Chapter 10: Building and Distributing
Once you have designed your update system, you need to build and distribute it. Fortunately, TrueUpdate makes this as seamless as the actual design process.
From automatically uploading to your chosen TrueUpdate Server locations, to a handy list describing what you need to do after the build, TrueUpdate makes building your project fast and easy.
Once you have finished creating your TrueUpdate project, you must use it to generate the actual TrueUpdate Client application and server configuration files. This is similar to a programmer compiling source code into a working executable.
When building your update, TrueUpdate will go through the following steps in the order listed below:
1. Run any pre-build programs that have been specified.
2. Collect all of the fonts needed for the screens in your update.
3. Convert all of the images used by the screens.
4. Collect all of the required language files.
5. Collect all includes (external script files) that have been specified.
6. Collect all action plugins that have been specified.
7. Collect any external files that have been specified (e.g. a custom icon).
8. Copy the run-time engine into the specified output directory.
9. Create the client data file by compressing all of the collected files and saving all necessary client information.
10. Create the server configuration files (*.ts1, *.ts2, and *.ts3).
11. Upload the server configuration files and the server information file (*.tsx) to any automatic upload locations you’ve defined in the project.
12. Run any post-build programs that have been specified.
Note: When TrueUpdate uploads the files to your automatic upload locations, it only uploads the files that it needs to (the ones that have changed since the last time your project was built). For instance, the .ts2 file will only be uploaded if it differs from the .ts2 file that is already on the server, and the .ts3 file will only be uploaded if its file version is newer than the file version of the .ts3 file on the server.
With the goal of making the build process as seamless as possible, TrueUpdate includes a publish wizard to assist you. The publish wizard can be accessed by choosing Build from the Publish menu.
The first step in the publish wizard allows you to specify three important items: the output folder, the name of the TrueUpdate Client executable, and the server files prefix.
The output folder is simply the location where your TrueUpdate Client and server configuration files will be generated on your local system.
The TrueUpdate Client filename determines the name of the client executable that you will distribute to your users.
The server files prefix is the name that will be used for the server configuration files, i.e. the name that will be used for the .ts1, .ts2, and .ts3 files.
Note: The first time you build your project, you will be able to edit the server files prefix directly. However, on all subsequent builds the server files prefix field will be disabled; to edit the server files prefix, you will need to click the Change button. Clicking the Change button displays a warning before allowing you to change the value, because changing the server files prefix will "break" an existing distribution. The TrueUpdate Client needs to know what the server files prefix is in order to download the server files. If you change the server files prefix, you will need to redistribute the TrueUpdate Client application to all of your users.
The second step in the publish wizard prompts you to configure your upload locations. You can use this feature to automatically upload the server configuration files to your TrueUpdate Server locations. You can also use it to upload the files to other locations, such as a backup file server or a folder on your network for testing.
Note that you can add and edit upload locations in this step, and you can enable or disable the individual upload locations by checking or unchecking the corresponding checkbox.
Once you’ve selected the locations that you want to upload the server files to, you can click the Build button to start the build process.
Once the build process is complete, the publish wizard will display a summary of the build process and any errors or warnings that occurred during the build.
There are two options below the summary that control what happens after you click Finish. One determines whether TrueUpdate will automatically open the output folder for you (for example, if you wanted to immediately test the update, you won’t have to navigate to the output folder yourself). The other controls whether to display a publish report listing the files that have been output by the build process and what you need to do next.
When you’re finished reading the summary, you can click Finish to exit the publish wizard.
The Build Settings dialog allows you to specify default settings for the publish wizard and to configure additional features that affect the build process or the generated files. You can access the Build Settings dialog by choosing Publish > Settings from the program menu.
The Output tab is where you can set the output folder, the TrueUpdate Client filename, and the server files prefix.
The output folder is where all of your update files will be built to. This can be any location on a local hard drive or on the local network. All of the files that TrueUpdate uses are built to this location, including both client files and server configuration files.
There are two client files that get built: an executable file (the "client executable") and a data file (the "client data file"). The name that you enter in the TrueUpdate Client filename field is the full name that will be used for the executable file.
TrueUpdate automatically chooses a name for the client data file based on the executable file’s name. For example, if you were to specify "Update.exe" in the TrueUpdate Client filename field, the data file would be named "Update.dat." If you were to specify "myupdate.exe," the data file would be named "myupdate.dat."
A great new feature in TrueUpdate is the ability to have your server configuration files automatically uploaded for you. This can save you a lot of time when distributing your updates, especially if you have more than one server to upload to.
You can configure as many or as few upload locations as you want, but in general each upload location will correspond to a TrueUpdate Server used in your project.
Note: When specifying upload locations it is not necessary to specify any file names. You only need to specify the folder where the files will be uploaded to.
Upload locations come in three different varieties that correspond to the upload methods used: FTP, SFTP, and File Copy.
FTP
Uses the File Transfer Protocol to upload your server files to a specific folder on an FTP server.
SFTP
Uses the Secure File Transfer Protocol to upload your server files to an FTP server. The SFTP upload method is very similar to the FTP upload method except that it encrypts the transfer of data between the client and server.
File Copy
Copies the server files to a writable folder on a local storage device (e.g. hard drive, floppy drive, USB key) or a LAN location (i.e. a folder on the local area network). Normally used with LAN/Local TrueUpdate Servers or internal Web/FTP servers.
Constants are essentially design time variables. They are similar to session variables, but instead of being expanded as the user runs the update, they are expanded when you build the project. In other words, when you build your project, all of the constants are automatically replaced by the values assigned to them.
You can define constants on the Constants tab of the Build Settings dialog, which you can access by choosing Publish > Settings.
Clicking the Add button on the Constants tab displays a dialog where you can name the new constant and give it a value.
Each constant has a name that will be replaced by this value throughout the project when the project is built. It’s exactly like a big search-and-replace operation that happens whenever you build the project.
Since each constant is essentially just a name that gets replaced with different text, you can use them just about anywhere. You can use them on screens, in file paths, in actions…pretty much anywhere that you can enter text.
Note: Design-time constant names can be in any format you like. One recognizable format which we recommend is to write the constant name in all capitals, using underscores in place of spaces between words, like so: LATEST_FILE_VERSION.
An unattended build is when a project (in this case a TrueUpdate project) is built with little or no developer interaction, often by another software process. Unattended builds are usually used when many different tasks need to be accomplished in sequence with the TrueUpdate build process. In these cases a software application or a simple batch file is used to automate the tasks. An example would be using a program to compile the source code for an application, building that application’s installer using Setup Factory, and then building the update using TrueUpdate.
Constants are extremely useful for performing unattended builds because they can be changed using a command line argument. You can even use constants to specify the output location, and the server file prefix. The possibilities are endless.
For example, you could create a batch file that would generate a unique update for every one of your customers, with the customer’s name showing up on one or all of the screens during the update.
For more information on performing unattended builds of your project, search for "Unattended Build Options" in the TrueUpdate help file.
There may be instances where you want to run a program either before or after your project has been built. TrueUpdate makes this process easy. On the Pre/Post Build tab of the Build Settings dialog, you can set a program to Run Before Build, and a program to Run After Build.
The uses of this feature are limited only by your imagination. You could, for example, chain several builds together by having one project call another through the Run After Build option. Or you could run an "automated backup" batch file that compresses all of the server files into a single zip file, and then copies the zip file to a folder on your network. The possibilities are limitless.
You can specify the path to the desired program in either of the Run Program fields. Any command line arguments that are needed should be specified in the Command Line arguments fields. If you want the design environment to pause while the other program is open, check the Wait for program to finish running checkbox.
TrueUpdate includes a number of preferences that affect how TrueUpdate handles the build process. You can find these preferences by choosing Preferences from the Edit menu and selecting the Build category.
The build preferences allow you to control whether TrueUpdate opens the output folder, whether it shows the publish report by default, whether it displays the publish wizard before building, and (when not using the wizard) whether a confirmation dialog is displayed before the build process begins.
You can also specify a list of fonts to exclude from the build process. Fonts take up additional space in your update so it is often a good idea to exclude any fonts that you know your end user will already have. By default this field includes Arial, Courier New, and Times New Roman.
Once you’ve built the TrueUpdate Client, you need to integrate it into your software. Integrating the client simply means including it with your software distribution and providing one or more ways for your users (or your software) to initiate an update.
Note: The TrueUpdate Client can be thought of as the client executable and the client data file.
Integrating TrueUpdate can be as simple as putting a shortcut on the Start menu that will launch the client executable, or it can be as sophisticated as having your main application run the client executable every 15 days. You could provide an item in your application’s menu to initiate an update, or even a button on your application’s toolbar. The level of integration is up to you.
Note: The TrueUpdate Client program is an executable that can be run normally from Windows.
Integrating TrueUpdate into your application involves two basic steps: adding the client files to your software distribution, and providing one or more ways to initiate an update.
The TrueUpdate client consists of two files: a client executable, and a single data file. By default the client executable is named TrueUpdateClient.exe and the data file is named TrueUpdateClient.dat. Both files are generated when you build your update.
Note: A complete list of files that you need to distribute can be found in the publish report that is generated each time your build your update.
Exactly how you add the client files to your distribution depends on the distribution method you use. It can be as simple as including the two files in a zip archive, or as sophisticated as using a professional installation tool like Setup Factory.
You can install the files anywhere on the user’s system, but it’s usually best to install them in the same place as your application. This way the location of your software can easily be determined at run time by using the built-in variable _SourceFolder, or the built-in session variable %SourceFolder%.
If you’d prefer to have the client files in a different folder, remember to provide some way for the TrueUpdate client to determine the path where your software was installed. For example, you could write the path to a Registry key or INI file with your installer and then use actions to read that information into a variable.
Initiating an update is simply a matter of running the TrueUpdate client. In fact, your users could check for an update simply by double-clicking on the client executable.
Of course, there are several more sophisticated ways to initiate an update. Here are some of the different ways TrueUpdate could be started:
Using a Start Menu item
Install a shortcut to the TrueUpdate client in the user’s Start menu.
Using an icon on the Desktop
Give your users the option to install a shortcut on their Desktop so they can initiate an update at any time. You could use the standard TrueUpdate client icon for this purpose, or perhaps the same icon you use for your application.
Using a menu item in your program
Provide an item in a program menu like Help > Check for Updates that will launch the client executable.
Using a toolbar button in your program
Provide a "Check for Updates" button on one of your program’s toolbars.
Automatically on starting Windows
Install a shortcut in the user’s Startup folder to automatically run the TrueUpdate Client every time the user’s system is started. You could also create a small "launcher" program that checks the number of times the system has been booted since the last update was performed and only launch TrueUpdate periodically. You could even set up an event with the Windows scheduling service if it’s active on the user’s system.
Automatically when your program starts
Launch TrueUpdate silently from your program when it’s started. You could check the system date and only launch the client if your application was last started more than a certain number of days ago. Or keep a counter of "application starts" in the Registry, and only check for an update after a certain amount of times that the user launches your program. You can even let your user specify how often they want the checks to be performed.
As a stand-alone executable, the TrueUpdate client gives you plenty of freedom to initiate the update process in a way that fits the style of your application. Which method (or methods) you choose to provide is entirely up to you.
Here are some source code samples using ShellExecute to call the TrueUpdate Client from Visual Basic, C/C++, and C#.
Private Declare Function ShellExecute Lib "shell32.dll"
_
Alias "ShellExecuteA" (ByVal hwnd As Long, _
ByVal lpOperation As String, ByVal lpFile As String, _
ByVal lpParameters As String, ByVal lpDirectory As String, _
ByVal nShowCmd As Long) As Long
Private Const SW_NORMAL = 1
Private Sub RunTrueUpdateClient()
' Execute the program
Dim lReturn As Long
lReturn = ShellExecute(Me.hwnd, "open", _
"C:\\Program Files\\Widget Designer\\TrueUpdateClient.exe",
_
"", 0, SW_NORMAL)
If lReturn <= 32 Then
MsgBox "Error executing client"
End If
End Sub
BOOL RunTrueUpdateClient()
{
HWND hWindow;
int nResult;
hWindow = GetSafeHwnd();
nResult = ShellExecute(hWindow, "open"
,"C:\\Program Files\\Widget Designer\\TrueUpdateClient.exe"
,"", NULL, SW_NORMAL);
if(nResult > 32) // values above 32 indicate
success
{
return TRUE; // update executed
}
else
{
return FALSE; // update not executed
}
}
using System;
using System.Diagnostics;
using System.ComponentModel;
public bool RunTrueUpdateClient()
{
bool bReturn = true;
try
{
Process UpdateProcess = new Process();
UpdateProcess.StartInfo.FileName =
"C:\\Program Files\\Widget
Designer\\update.exe";
UpdateProcess.StartInfo.WindowStyle =
ProcessWindowStyle.Normal;
//The Start method returns true on success
and
//false on failure
bReturn = UpdateProcess.Start();
}
catch (Win32Exception e)
{
//An error has occurred
bReturn = false;
}
return bReturn;
}
One of the most important and often overlooked steps when creating an update is testing it after it has been built. You should test your update on as many computers and operating systems as possible. Try it on every operating system that your product supports. Windows 95, Windows 98, Windows 2000, Windows ME, Windows NT, Windows XP, Windows Vista and later all have both slight and major differences between them and should be thoroughly tested. It is also important to test the way that your update responds to different OS configurations, different service packs, monitor resolutions, color depth, and font sizes. If your update needs a lot of hard drive space, be sure to test it on systems with a very limited amount of hard drive space.
If you have made use of TrueUpdate’s multilingual support, be sure to test out each language in your update. If you are using multiple TrueUpdate servers, be sure to test each update server individually to ensure that they are all working properly.
It is very important to test before you distribute. An ‘internal build’ of your update is much easier to recall than is a public release should a problem arise.
Tip: For information related to tracking down script-related issues, see Debugging Your Scripts in Chapter 11.
TrueUpdate’s built-in logging function can quickly become a developer’s best friend. It is enabled by default, and contains all the information that you as a developer will need to diagnose an update gone bad. Everything that happens during the update is logged, from which screens were displayed to what version of the update engine is being used.
Beyond its basic components, the update log file is fully customizable; as the developer, you can choose what information is logged and what information is not. If you require even more detail than what the built-in logging capabilities provide, you can add custom lines to the log at any point during your update.
Using log files is invaluable to developers for diagnosing problems. Let’s face it, no matter how much testing is done, there will always be one end user who hits a snag. Utilizing log files, you can find out exactly where that snag occurred, and fix the problem. As a result, you save on support costs and keep your customer happy.
Ultimately, the choice of whether or not to use the log file, and how much information should be in that log file, is up to you.
Here is an example of what a log file might look like:
[12/28/2004 16:38:11] Success
Update started: C:\output\tu\TrueUpdateClient.exe
[12/28/2004 16:38:11] Notice
Update engine version: 1.0.0.0
[12/28/2004 16:38:11] Notice
Product: Your Product, version %ProductVer%
[12/28/2004 16:38:11] Success
Language set: Primary = 9, Secondary = 1
[12/28/2004 16:38:11] Success
Include script: _TU20_Global_Functions.lua
[12/28/2004 16:38:11] Success
Language set: Primary = 9, Secondary = 1
[12/28/2004 16:38:12] Success
Run client data event: Client Script