Versions and Files |
|
|
|
Versions and Files |
|
|
Versions and Files |
|
|
|
Versions and Files |
|
|
|
|
||
User's Guide - Chapter 4: Versions and Files
A version is the collection of files and folders that makes up a single release of your software. Having accurate information about your versions and the files they contain is a crucial part of performing a successful patch.
Visual Patch uses this information to analyze the differences between your versions, to determine what data needs to be included in the patch, to identify which version (if any) is actually installed on the user’s system, and to update the files in the installed version so they match the files in your target version.
Since the entire patching process depends on the information you provide, it’s important to understand how to configure all of the versions and files in your project.
This chapter will explain everything you need to know about versions and files in order to create a successful patch for your software.
Note: Patching files is the ultimate purpose of any software patching tool. As such, you are expected to be completely familiar with files and folder structures in order to use Visual Patch. If you need more information on the basics of files and hierarchical folder structures, please consult the "Windows Basics" section of the Visual Patch help file.
The project window contains a series of version tabs, each containing the lists of files that are part of each version. From these lists you can highlight specific files and view or edit their properties.
The version tabs on the project window represent each version of your software. New versions may be required to fix bugs or to introduce new features. Every version of your software that your patch will update must have a separate file list that contains all of the files that are part of that particular version. Version tabs are organized from left to right where the leftmost version tab is the oldest version and the rightmost tab is the newest version. These tabs allow you to switch between the versions in your project to view or edit their file lists.
Each time a new release of your software is created, you will need to add a new version tab to your project so you can add all of the new version’s files. The following steps can be taken to add a new version to your project:
Selecting Versions > Add from the program menu opens the New Version dialog where you can specify the name you want to give the new version.
Version numbers are normally used as the version names, but you are not limited to version numbers. You could also use a word or phrase.
Tip: If you use version numbers, whenever you add a new tab Visual Patch will automatically try to guess the next version number based on the previous versions in the project.
When you click the OK button, a new version tab with the specified name will be added to the right of all existing version tabs.
Occasionally mistakes are made that require the removal of a version from your project. To remove a version, select the version you want to remove and then choose Versions > Remove from the program menu. A confirmation dialog will be shown before the version and its referenced files are removed from your project.
Versions can be renamed in your project by choosing Versions > Rename from the program menu. This will open the Rename Version dialog where you can specify its new name.
It is also possible to duplicate a version and all of its file references in your project. To do this, simply select the version you want to make a copy of, and choose Versions > Duplicate from the program menu. This will add a new version tab with an automatically generated name containing the same file list as the copied version. After the version duplication, you may want to rename the new version to suit your project.
The order of the version tabs in your project is very important. Positioning your versions in the wrong order would result in a patch that is unable to update your software. In order to build a patch that can successfully deal with all your software versions, you need to ensure that Visual Patch "sees" the versions in the correct order, from the oldest on the left, to the newest on the right.
When you build a patch, Visual Patch analyzes the files in the newest version of your software and compares them to the files in all the other versions that are defined in the project. It uses this information to determine what changes are required to update each version to the newest.
If the order of your versions is incorrect, the following steps can be taken to reorganize them to match your software’s version history:
The organization of the version tabs in your project can be changed on the Organize Versions dialog. You can access this dialog by choosing Versions > Organize from the program menu.
The Organize Versions dialog shows a list of all the versions that are currently in your project and orders them top down, from oldest to newest.
On the Organize Versions dialog shown in step 1, you will notice that version 1.0.0.2 is in the second position while version 1.0.0.1 is in the last position. This order indicates that 1.0.0.1 is the newest version. Lets assume that this is incorrect and that 1.0.0.2 is the newest version of the software. This means that version 1.0.0.2 needs to be moved into the last position in the list.
To move version 1.0.0.2, you would first select it in the list, and then click the Move Down button (the one with the arrow pointing down).
Repeat step 2 until all the versions are in the correct order. Once you’re satisfied with the order of the versions, click OK to make the changes to your project. The version tabs in your project should now follow the order you specified on the Organize Versions dialog. For example, if you moved version 1.0.0.2 to the bottom of the list, version 1.0.0.2 would now be the rightmost version tab.
Version tabs in Visual Patch were designed to contain the lists of files that are part of each version of your software. Since a minimum of two versions is required to create a patch, your project will normally contain at least two lists of files. These lists contain references to each file on your local system or LAN where Visual Patch can access them during the build process. These lists should only contain the files that are distributed to the user.
The best strategy for managing your source files is to keep each version of your software in a separate folder. It is also best to preserve the internal folder structure for each version, i.e. to store each version complete with any subfolders relative to the main application’s folder. This greatly simplifies the process of adding the versions’ files to your project and setting their destination paths.
File lists can also be sorted and filtered so you can easily find or focus on the files you need to customize. Each file within a list has properties you can view or set such as its source and destination paths, key file property, and patch conditions.
All file lists have columns that display different information about each file in your project. You can sort the information along any of the columns by clicking on the heading for that column. If you click on the same heading again, the files will be sorted by that category in reverse order.
You can customize the columns by choosing View > Columns. This opens the Columns dialog, where you can choose which columns to display in the file list, and change the order (left to right) that the columns are listed in.
Tip: Moving a column up in the columns list moves it to the left in the file list; moving a column down in the columns list moves it to the right.
The items that appear in the Visual Patch file lists refer to files on your system. When you add a file to your project, the file is not copied into the project. It is only referenced by the project.
In other words, only the path to the file (and a few other properties, such as the size of the file) is stored in your project. If the original file is renamed, moved or deleted, Visual Patch won’t be able to build it into the patch executable. (In fact, it will show up in the file list as a missing file.)
The file itself, however, is not part of the project. If you copy your project from one system to another, you will not be able to build it unless you also copy the files, and place them in the exact same folder structure; in other words, you must place the files where the project expects them to be located.
Note: The files that your project references are commonly referred to as source files.
If your software contains many files, you might find it easier to temporarily "hide" some of them from the file list in order to focus on the files that you’re interested in at the moment. You can do this by applying a filter to the file list so it only shows files that meet specific criteria. For example, you could filter the list to only show files that are larger than 5 MB, or files that are currently missing from your system. This is all done using the Filters toolbar.
Clicking the Filters... button on the toolbar opens the filters manager, where you can configure the list of filters that appear in the drop-down selector on the toolbar. The filters manager allows you to define custom filters using a wide range of criteria.
Setting up a new filter is incredibly easy. After clicking on Add in the filters manager, you simply give the filter a name, then select the property you want to filter on, select the rule that you want to use, and finally provide the criteria.
The filters are saved on a global basis, so once a filter is defined it can be used in all of your projects. You can switch between filters by using the drop-down selector on the filters toolbar.
Folder references are similar to files, but they reference a folder on your system instead of a single file. They’re useful for including folders full of files without having to reference each file individually.
For example, if you have a folder full of documents that you need to patch, you can use a folder reference to add the entire folder to your project. This also lets you configure the settings for all of those files from a single item in the file list.
You can even choose whether or not to reference folders recursively. In other words, you can choose whether or not to include the files in any subfolders (and subfolders of subfolders, and so on) that may be in the selected folder. (This is in fact the default behavior of folder references; however, you can choose to only include the files in the immediate folder if you want by simply turning off the "Recurse subfolders" option.)
Each folder reference also has a File Mask setting that you can use to include only files that match a specific pattern. For instance, if you wanted to use different settings for the .doc files and all other files in your product’s folder, you could use two folder references-one for each type. So, for example, you could set up one folder reference to add everything beneath C:\Program Files\ProductX that matches "*.doc" and another one to add everything in that same path that are "Files that do not match" the "*.doc" file mask. You could then configure their settings differently-for example, you could set one up with a condition so it only patches the .doc files on specific operating systems.
Tip: Folder references are one of the most powerful features in Visual Patch! Be sure to use them to your advantage.
There may be cases where you want to include a folder full of files, but you want to use different settings for some of the files in the folder. Visual Patch makes this incredibly easy to accomplish because you can override a folder reference with individual file items.
The rule is simple: the settings for individual file items always take precedence over folder references. So if you have a folder reference that happens to include files A, B, and C, and you also add file B to your project on its own, the settings for the standalone file item will be used for file B, and not the settings for the folder reference.
Note: It doesn’t matter what order the files are in - individual file items always override folder references.
One method for keeping source files organized is to keep each version’s source files in a separate folder. While this strategy may take up additional hard drive space, it greatly simplifies the management of your patches.
Once you have added a new version tab to your project, the next step is to add all of its source files.
Select the version tab whose source files you want to add to the project.
This will open the Add Files to Project dialog.
Tip: You can also click the Add Files button on the toolbar, press the Insert key, or right-click on the project window and select Add Files from the right-click menu.
At the bottom of the Add Files to Project dialog is a section labeled "Add Mode." This setting controls which files in the folder structure will be added to the version’s file list. There are three add modes to choose from:
• The "Selected files only" option will only add the files that you select
• The "All files in this folder" option will add all of the files in the folder that the Add Files to Project dialog is currently displaying
• The "All files in this folder and all subfolders" option will add all of the files in the current folder, and all of the files in any subfolders as well
Depending on the add mode you chose, you either need to select one or more individual files in the browse dialog, or navigate into the folder that you want to add files from.
Once you click the Add button, the files will appear in the file list.
Tip: You can also add files to your project by dragging and dropping them onto the selected version tab in the project window.
If your software contains folders of files whose settings do not need to be individually customized, folder references are a convenient way to add those files to your project.
Assuming you have a version tab ready for files to be added, the following steps can be taken to add a folder reference to your project:
Select the version tab whose source files you want to add to the project as a folder reference.
This will open the Browse For Folder dialog.
Tip: You can also click the Add Folder Reference button on the toolbar, press Ctrl+Insert, or right-click on the project window and select Add Folder Reference from the right-click menu.
Simply browse for the folder that you want to add. When you select a folder, its name will appear in the Folder field near the bottom of the dialog.
When you click the OK button, the folder reference will appear in the file list.
Tip: You can also drag and drop a folder onto the selected version tab to add a folder reference to your project. This will open the Drag and Drop Assistant dialog to confirm its addition.
To remove files from your Visual Patch project:
Simply click on the file items that you want to remove.
Choosing Edit > Delete from the program menu will remove the selected file items.
Tip: You can also click the Remove Files button, press the Delete key, or right-click on the project window and select Remove from the context menu.
Note: Removing files from your project removes the file items from the file list, but does not delete the original files. The original files remain completely unaffected.
Removing folder references is exactly like removing files. Simply select the folder references that you want to remove and choose Edit > Delete (or press the Delete key, etc.).
You can use the File Properties dialog to view and edit the settings for any file in your project.
To access the File Properties dialog:
Simply select the file item that you want to edit.
This will open the File Properties dialog, where you can view and edit the properties of the file you selected.
Tip: There are several other ways to access the file properties as well. You can click the File Properties button, press Ctrl+Enter, right-click on the file item and select File Properties from the right-click menu, or simply double-click on a file in the list.
There are three tabs on the File Properties dialog: General, Conditions, and Notes.
The General tab is where you will find information about the file itself, such as its name and location on your system, whether it’s a key file, and where it is expected to be on the user’s system (the destination path).
The Filename field specifies the name and extension of the file being referenced.
The Local folder specifies the current location of the file on your system. This must be a folder that is within local access of your system or LAN.
Visual Patch uses the local folder in combination with the filename to retrieve the file’s information (e.g. when you open a project) and to analyze the file when it builds the patch executable (i.e. when you build the project).
Key files are a very important part of Visual Patch. Key files are used to identify what version of the software is on the user’s system and whether or not it is a valid version. Designating a file as a key file means that you want Visual Patch to verify its existence and its MD5 signature in order to fully identify the version it belongs to. If the key file doesn’t exist, or its MD5 signature doesn’t match, Visual Patch will consider that version not found.
Key files are usually files whose contents are unique to a single version. The best key files are files that change from one version to the next, such as the main executable for the software. The file names and paths don’t need to be unique, but the contents do.
Visual Patch requires at least one unique key file per version in order to uniquely identify that version. In other words, you must designate at least one key file per version whose contents are different in every other version.
Key files must also not change after being installed or patched since Visual Patch relies on their MD5 signature for validation. Files that are normally changed after they are installed (for example, .ini files) should not be designated as key files. If a key file has been changed in any way from the original file that is referenced in your project, it will prevent the version from being identified.
A version can contain as many key files as you like; however, only one key file must be unique between versions. If your software contains mission critical files whose existence and integrity must be checked, you can set them as key files as well, even though they haven’t changed between versions. Again, only one unique key file is required to identify a version.
The Install to (or "destination") property specifies where the file is expected to exist on the user’s system. Though this seems simple enough, it is complicated by the fact that you can’t predict the layout of the folder structure on the user’s system.
For instance, if you want to patch a file located in the user’s "My Documents" folder, how do you know what the full path to that folder is? It could be anything from "C:\Documents and Settings\JoeUser\My Documents" to "F:\Joe’s Docs."
Visual Patch gets around this uncertainty by providing you with a number of built-in session variables for common system folders. These are essentially placeholders (like %MyDocumentsFolder%) that you can use in your file paths, and that will be replaced by the corresponding path on the user’s system at run time. You simply use the appropriate placeholder, and Visual Patch will take care of investigating what the actual path is when your user runs the patch file.
For more information on session variables, see Chapter 7.
%AppFolder%
In most cases you know the directory structure of your software, however the user is often given the choice of where they would like to install. For this reason, the exact folder path is not known until run time. Visual Patch uses a special session variable to represent the main folder that your software was installed to. The name of this session variable is %AppFolder%, which is short for Application Folder, i.e. the folder where your software application is installed. At run time, this variable is populated with the folder path from a Registry value, file search, or some other method implemented using action script. (By default, the setting of %AppFolder% is handled in the On Startup event by the VisualPatch.CheckFolderVersion action.)
The Force install check box is for files that you always want installed as part of the patching process for a given version. It instructs Visual Patch to include the whole file in the patch and to overwrite any existing version of the file that it finds on the user’s system.
You should only enable this option when you’re sure that it’s okay for a file to have been modified after it was installed, and you want to overwrite the modified version with the new file. (Generally you will want to leave this option unchecked.)
The Conditions tab is where you can edit settings that affect whether the file will be included in the patch executable, and whether it will actually be used when the patch is run. In other words, it is used to conditionally include or exclude a file from the patch at build time or run time.
The list of build configurations allows you to select the build configurations that the file will be included in. The file will only be included in the patch if it is included in the build configuration that is selected when you build the project.
The list of operating systems allows you to specify which operating systems the file will be patched on. The file will only be patched on an operating system if it is marked with a check in this list. So, for example, if you uncheck Windows 95 and Windows 98 for a file, it will not be patched on a system running Windows 95 or Windows 98.
The script condition is a short expression written in Lua script. It must evaluate to a Boolean value of either true or false. At run time this result will determine whether or not the file will be patched. For example, if you have a variable used in your project called MyNum and you want to check to see if its value is 5, the script condition would be MyNum == 5. If the contents of the variable is 5, the condition evaluates to true and the file will be patched. If the variable contains some other value, the condition evaluates to false, and the file will not be patched.
The Notes tab is where you can type any notes that you want to keep about the file. These are not used by the patch, and are not included in the patch executable. The Notes tab is simply a convenient place for you to keep notes about the file for your own purposes. For example, you could list any special instructions involved in preparing the file for the build process, or you could keep track of who last edited the file’s properties.
For the most part, Folder References have the same properties as files do. In fact, the Conditions and Notes tabs are exactly the same. However, there are a couple differences on the General tab worth mentioning:
Folder references have a "Recurse subfolders" option that controls whether files in subfolders (and their subfolders) should be included as well. This allows you to include full folder trees if you wish.
Folder references also have a File mask setting that allows you to include or exclude a range of files that match a filename pattern, e.g. "*.exe". This allows you to use custom settings for different file types.
You can use the Multiple File Properties dialog to edit the properties of more than one file (or folder reference) in your project at a time.
To access the Multiple File Properties dialog:
1. Select more than one file on a version tab. (You can select multiple files by pressing and holding the Ctrl key or the Shift key while you click on the files.)
2. Choose Versions > File Properties from the menu.
(You can also click the File Properties button, press the Ctrl+Enter key, or right-click on the files and select File Properties from the right-click menu.)
This will open the Multiple File Properties dialog, where you can view and edit the properties of the files you selected.
The Multiple File Properties dialog is similar to the File Properties dialog, but there are some important differences:
• There is no Notes tab.
• You cannot enter text in a field directly; instead, you must click the Edit button to the right of the field, and use the Edit Multiple Values dialog to change the text. Note that the Edit Multiple Values dialog allows you to completely replace the text for all selected files, append (or prepend) some text to the value for each selected file, or search and replace among the values for all selected files.
• Check boxes on the Multiple File Properties dialog have three states: enabled, disabled, and mixed. The mixed state preserves the settings for that check box in all of the selected files.
For more information on using the Multiple File Properties dialog, please consult the Visual Patch help file.
Since Visual Patch only records an informational link to each file, and doesn’t actually maintain a copy of the file itself, it’s possible for files to go "missing" from Visual Patch’s point of view. For example, if a file in your project has moved to another folder, Visual Patch will no longer be able to find it at its original location. The same thing happens when a file is renamed or deleted. Visual Patch only knows to look for a file at the place where it was when you "showed" the file to Visual Patch by adding it to your project.
Although Visual Patch might not know where a missing file has ended up, it definitely knows when a file is missing. Whenever a file in your project can’t be found at its original location, Visual Patch displays the file’s information in red instead of black. The red color makes it easy for you to see which files in your project are missing.
The file’s status will also show as "Missing" instead of "OK" in the Status column on the list view, if that column is enabled. You can enable the Status column from the column settings dialog found by choosing View > Columns from the program menu.
Tip: A quick way to determine which files are missing in your project is to click on the Status column heading to sort the files in the list view according to their status.
If you find that your files are suddenly playing hide-and-seek with Visual Patch, try to remember if you’ve made any changes to your files recently. If you moved the files, you can try moving them back. If you renamed the files, you can restore the original names. If you deleted the files, you’ll have to replace them.
If Visual Patch still shows the files in red after you’ve corrected the situation, you probably just need to refresh the display. To do so, simply choose View > Refresh from the program menu, or press the F5 key. Refreshing the display causes Visual Patch to re-examine the location of every file in your project.
Note: Visual Patch automatically refreshes the display for you when you open a project or initiate the build process.
If you moved, renamed, or deleted the files on purpose, and you want Visual Patch to use the files at their new locations, remember the files by their new names, or just forget about the past and move on, you’ll need to change the local source path on the File Properties dialog for each file. This can easily be done by selecting all the files and then modifying their properties using the Multiple File Properties dialog.
Primer files get extracted from the patch executable before the patch process begins. This means you can use primer files at the very start of the patch process, right after the user runs the patch executable. Primer files are useful in situations where changes need to be made before the normal patching process begins.
One use of primer files is to run a program on the user’s system before the rest of your files are patched. For example, you might need to execute a custom program or DLL function before your software is patched-perhaps to perform some product-specific, low-level pre-patch tests on the user’s hardware and write the results to the Registry. By adding your custom program or .dll to the list of primer files, you could distribute it "inside" your patch executable and still be able to run it before any of the "normal" files in your project are patched.
Primer files are automatically extracted to a temporary folder at run time. The path to this folder is stored in a session variable named %TempLaunchFolder%. You should use this session variable in actions when you need to access your primer files.
Any type of file can be added as a primer file simply by adding it to the Primer Files tab on the Resources dialog. All files on this tab will be included in the patch executable when you build your patch, but are not part of any version of your software.
Tip: Another way to access files at the start of the patch is to distribute them "alongside" your patch. For instance, you could store the files "externally" on the same CD-ROM, and access them directly; or, you could download the files from your web site using an HTTP.Download action in the On Startup project event.
Learn More: Indigo Rose Software - Visual Patch - Buy Now - Contact Us