The content of this article was incorporated into the ManageSoft reference library at release 6.5 and can be found in the ManageSoft Packaging Guide. As a result, this article will not be further updated in the knowledge base. This version will remain as a reference for earlier releases of the product.Published September 27, 2002 Release 6.1.3 edition CONTENTS Introduction AppDir is the variable that represents the location into which the user installs their application. This is useful when you provide users with the option to override your recommended install location, or install applications distributed with ManageSoft to locations other than the ManageSoft application cache. Before you proceed This document assumes the following knowledge:
You are familiar with, and understand the use of, registry keys You have read and understand the Overview section of the ManageSoft warehouse online help You understand the concepts of Packaging with ManageSoft. AppDir behaviors ManageSoft Technical Note #12 This document provides detailed reference material on the special behaviors associated with AppDir settings.
Introduction ......................................................................................................... 1
When to use AppDir .......................................................................................... 2
Configuring the $(AppDir) symbol .................................................................. 2
Examples of AppDir usage .............................................................................. 3
Example 1: Creating a Registry key for the software ................................... 3
Example 2: Create Groups and Icons ............................................................ 3
Example 3: Files and All Files .......................................................................... 4
Example 4: Packaging and versioning ........................................................... 5
Scenario: AppDir and installing a package ................................................... 6
Installing a package ........................................................................................... 6
Receive Package into the Warehouse server ............................................... 8
Reviewing the package in the software library .............................................. 8
Review the Acrobat Reader.osd file ................................................................10
Review the Adobe Acrobat.ndc file....................................................................10
Appendix:Using the ManageSoft $(AppDir) project variable in callouts ... 12
When to use AppDir ManageSoft Technical Note #12 TN12-2 ©2002, ManageSoft Corporation When to use AppDir ManageSoft recommends that, where possible, absolute path names be replaced with internal symbols (variables) that represent the directory structure. ManageSoft uses variables to represent locations on the managed device. The package is installed into the appropriate location by substituting the variable for the value that is defined on the managed device.
For example, $(AppDir) represents the directory into which the application is installed. $(AppDir) is the location into which the user installs the application. This is useful when you allow users to override the recommended install location. It defaults to Launcher\Cache\Common\[PackageName]\. Configuring the $(AppDir) symbol The AppDir symbol is used to determine where a package is installed on the managed device, and whether the user can change the install location. AppDir is also used to allow shortcuts to the application install location for easy reference when packaging. To configure the AppDir symbol you can utilize the following two methods.
METHOD ONE
1 On the ManageSoft Warehouse server, open ManageSoft.
2 Expand the Packaging node.
3 Expand the Project - Packages node.
4 Browse to the Install Location node and expand the All Install Locations node.
5 Right click Launcher Application Cache in the right-hand pane and select Properties from the menu.
6 Change the Base location to Program Files.
7 In the In subfolder field, enter MyKey and click OK.
8 De-select Allow the location to be changed by installing user if you do not want users to be able to change the installation location.
METHOD TWO
1 Navigate to the Install Location node and expand the All Install Locations node.
2 Right click Launcher Application Cache in the right-hand window and select Properties.
3 Change the Base location to Program Files.
4 In the In subfolder field, enter Example and click OK. This configures the ManageSoft symbol $(AppDir). For example, $(Program Files)\Example.
5 De-select Allow the location to be changed by installing user if you do not want users to be able to change the installation location. This value is recorded as an absolute path.
Note: This configures the ManageSoft symbol $(AppDir). Examples of AppDir usage AppDir behaviors TN12-3 Examples of AppDir usage
Example 1: Creating a Registry key for the software A pre-defined AppDir symbol is used so Registry entries refer to the directory where the application is installed, regardless of whether the user has changed the install location.
1 From the ManageSoft Warehouse, expand the Packaging node.
2 Expand the Registry Entries node.
3 Expand the All Registry Entries node.
4 Right click on the HKEY_LOCAL_MACHINE key and select New Key.
5 In the Key Name field, enter: Software and click OK.
6 Right click on the Software key in the right-hand pane of the screen and select New Key.
7 In the Key Name field, enter: MyKey.
8 Right click the MyKey key and select New Entry.
9 In the Name field, enter: Install Base.
10 Set the Value to: $(AppDir) and click OK.
Example 2: Create Groups and Icons A pre-defined AppDir symbol is used so groups and icons refer to the directory where the application is installed, regardless of whether the user has changed the install location. The following are basically used from within the ManageSoft package to customize the application properly.
CREATE GROUPS
1 From the ManageSoft Warehouse, expand the Packaging node.
2 Navigate to the Groups and Icons node, expand the All Groups and Icons node and then right-click on the Program Group entry and select New Group.
3 In the Group Name field, enter: Example and click OK.
4 Right click on Example and select New Icon.
5 Enter the following information in the relevant fields:
Note: This is an example only and is not intended as a definitive method of creating a registry key.
Note: Because this package has not been packed by a any install utility software, it may require a registry entry to tell the application where its program files are located. Use the internal ManageSoft symbol $(AppDir) to set the value of this key.
Note: The structure of any Registry keys you create here for the package must reflect the structure of the Registry keys on the managed device. If a Registry key does not exist, ManageSoft creates it. For example, if you are trying to update a key in HKLM\Software\X you need to create all the keys to get to X. Consequently, the key you have just created is HKEY_LOCAL_MACHINE\Software. Examples of AppDir usage AppDir behaviors TN12-4 Icon Label: Example Target: $(AppDir)\Example.exe Start in: $(AppDir) Icon is in file: $(AppDir)\Example.exe Icon number: 0
6 Click OK.
7 Right click on Example and select New Icon. Enter the following information: Icon Label: Example Help Target: $(AppDir)\Example.hlp Start in: $(AppDir) Icon is in file: $(AppDir)\Example.hlp Icon number: 0
8 Click OK
CREATE ICONS
1 From the ManageSoft Warehouse, expand the Packaging node.
2 Navigate to the Groups and Icons node, expand the All Groups and Icons node and then right-click the Desktop node.
3 Select New Icon and enter the following information: Icon Label: Example Target: $(AppDir)\Example.exe Start in: $(AppDir) Icon is in file: $(AppDir)\Example.exe Icon number: 0
4 Click OK.
Example 3: Files and All Files A pre-defined AppDir symbol is used to customize where the files go, and to refer to the directory where the application is installed, regardless of whether the user has changed the install location. The following example assumes that you have already packaged the Adobe Acrobat product.
1 From the ManageSoft Warehouse, expand the Packaging > Project node
2 Navigate to the Files > All Files node.
3 Expand the Install Folder.
4 Right-click on the Reader folder.
5 Select Properties. Note: The Install Folder maps to $(AppDir) and is, in essence, the AppDir. Examples of AppDir usage AppDir behaviors TN12-5 The destination in the Located in: field, is $(AppDir).
6 Click OK.
7 On the right-hand screen, right-click the AcroRd32.exe file and select Properties. The AcroRd32.exe Properties dialog is displayed. In the Source field the following is displayed: Source Files\C\Program Files\Adobe\Acrobat 5.0\Reader\AcroRd32.exe.
8 In the How should the file be distributed field, ensure the Distribute the file to deployment server as button is selected. The text should display: AppDir/Reader/AcroRd32.exe.
9 Click OK.
10 Navigate to the Files > All Files > Program Files > Common Files > Adobe folder.
11 Right-click the Acrobat 5.0 folder and select Properties. The Properties dialog is displayed. The destination in the Located in: field should be: $(Program Files)\Common Files\Adobe.
Example 4: Packaging and versioning There are various mechanisms that control package versioning. Where an application, installed on a managed device, is to be upgraded by version numbering, the new package will be installed into the original installation directory regardless of the instructions in the newer package. This occurs because ManageSoft treats this as an upgrade to an application, not a new installation, and uses the original installation directory. For example: ApplicationX 1,0,0,0 installed into $(AppDir):$(ProgramFiles)\ApplicationX has been installed on a computer. The upgrade to the package is defined as: ApplicationX 2,0,0,0 installed into AppDir:$(ProgramFiles)\Company Z\Application X. When the upgrade package is installed onto the computer, based on the version number 2,0,0,0, the package will be installed into the directory defined for the existing application rather than into the new directory structure. To illustrate, if the application Acrobat Reader (version 4,0,0,0) was installed into C:\Program Files\Adobe\Acrobat and the upgrade package (version 5,0,0,0) was configured to install into C:\Program Files\Adobe\Acrobat 5.0\ the version 5,0,0,0 files would be installed into the original location, C:\Program Files\Adobe\Acrobat because the upgrade has been invoked by changes in the version number.
Note: In the following example Company Z has decided to package version 2 of its Application X so it is installed into a <Company Z> sub-directory of Program Files, instead of directly under Program Files, which is where version 1 of Application X was intended to be installed.
Note: Once an application is installed, it retains its original AppDir on that specific machine through any upgrades, rather than picking up the new value of AppDir from the upgrade package. Scenario: AppDir and installing a package AppDir behaviors TN12-6
Scenario: AppDir and installing a package This scenario assumes that you have already created a package. As the application is installed, you can view the information you entered into the Applications Detail node of the software warehouse: the manufacturer, copyright message and any comments you entered about the package. The installation process gives you the option to designate where you want the package to install the software. This provides an opportunity, if required, to change the location contained in the symbol ($AppDir). Installing a package Having created a package for Acrobat Reader, install that application on a managed device and review the actions of ManageSoft during the installation.
1 On the ManageSoft Warehouse computer, select Start >Run.
2 Enter ndautocw and click OK. The New Project Wizard is launched.
3 Click Next. The Application Name dialog is displayed.
4 Type Acrobat Reader in the Enter the application's name field.
5 Type Acrobat Reader in the Enter the name for the package field.
6 In the Enter the version number of your application boxes, enter 2,1,5,0. Each digit should be assigned to one text box in the given order.
7 Click Next. The Save your package dialog is displayed. Take note of the location of the .ndp file.
8 Click Next. The Installer Information dialog is displayed
9 Browse to the following application installer: [CD Drive]\Third party\rp500enu.exe.
10 Click Open.
11 Click Next. The Configuring Includes and Excludes dialog is displayed.
12 Click Next. The Directories to Watch dialog is displayed.
13 Click Watch... The Browse for Folder dialog is displayed.
14 Browse to C:\Program Files.
15 Click OK.
16 Repeat Step 14 for adding the directory C:\Winnt. Scenario: AppDir and installing a package AppDir behaviors TN12-7
17 Click Next. The Directories to Ignore dialog is displayed. Do not ignore any directories.
18 Click Next. The Registry trees to Watch dialog is displayed.
19 Click Next. The Registry trees to Ignore dialog is displayed.
20 Click Next. The Files to Ignore dialog is displayed. Do not ignore any files.
21 Click Next. The Environments dialog is displayed.
22 Select only Windows 2000. 23 Click Next. The Your current settings dialog is displayed.
24 Click Next.
25 Complete the Acrobat Reader installation. Take note of the Destination Folder: C:\Program Files\Adobe\Acrobat 5.0. Once the Wizard finishes recording the system state, the Pre-installation snapshot complete dialog is displayed.
26 Click Next. Once the installation is complete, the External installer complete dialog is displayed.
27 Click Next. The Wizard snapshots the state of the system now that the application has been installed. Once the Wizard finishes recording the system state, the Your current settings dialog is displayed.
28 Click Next. The New Project Wizard Complete dialog is displayed
29 Click Finish. Note: The Wizard invokes rp500enu.exe to install Adobe Acrobat Reader. Install the product as you want it installed on your managed devices. Warning: The location noted in the text box specifies the location where you installed Adobe Acrobat Reader. If it is incorrect, browse to the correct location. Note: The Wizard generates the ManageSoft project based on the difference between the two snapshot images of the system. Scenario: AppDir and installing a package AppDir behaviors TN12-8 A new project for Adobe Acrobat Reader is displayed in the Packaging feature of the ManageSoft software warehouse.
30 Open Windows Explorer.
31 Navigate to folder containing the .ndp package as per Step 7.
32 Share the folder. Receive Package into the Warehouse server
You must now go to the Warehouse server machine to receive the package into the Warehouse.
1 On the Warehouse server, expand ManageSoft Warehouse.
2 Right-click on the Software Library node.
3 Select Receive into Software Library... The Receive package Wizard is invoked.
4 Click Next. The Application Type dialog is displayed.
5 Select the A ManageSoft project file option.
6 Click Next. The Source Location dialog is displayed.
7 Under Where is the project file (.ndp) located? click Browse.
8 Browse to the location of the Adobe Acrobat.ndp file at \\\ as noted on Step 7 in the Installing a package section on page 6.
9 Select the file and click Open.
10 Click Next. The Destination Package dialog is displayed.
11 Select the Training folder.
12 Click Next. The Receiving Your Application dialog is displayed, followed by the Complete the Receiver Wizard dialog.
13 Click Finish. The package has now been received into the software warehouse.
Reviewing the package in the software library
1 Expand the Software library node.
2 Expand the Training folder. The package will be visible in the Adobe directory?the icon indicates that the directory contains a package.
3 Right click on the Packaging node and select Open Project. Warning: If you edit the package you must save it before you exit the console.
Scenario: AppDir and installing a package AppDir behaviors TN12-9 The Select package to open dialog is displayed.
4 Select the Adobe package and click OK.
5 Expand the Project > Packaging node to view the components of the package.
6 Expand the Registry Entries > All Registry Entries node. This node contains a record of all the registry entries that were changed on the baseline machine during the application installation.
7 Pay careful attention to these entries and determine which entries are appropriate to the application and which entries can be considered "noise" from the operations of the Windows operating system in the background.
8 Remove any Registry entries that appear to be irrelevant to the application installation. For example, the following will have no relation to the Adobe product HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Explorer\Discardable HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Explorer\MountPoints HKEY_LOCAL_MACHINE\Software\Microsoft\Cryptography
9 Expand the Preference Files > All Preferences Files node. If you did not tell the wizard to ignore C:WINNT\Temp, remove any temporary preference files placed here by the installer as well as any other preference files that do not seem relevant?for this exercise there should be no preference files set.
10 Expand the Install Locations > All Install Locations node.
11 Right click on the install location ($(ProgramFiles)\Adobe\Acrobat 5.0)in the right-hand panel and select Properties.
12 Choose the Program Files option (a relative path) from the Base location dropdown list. Adobe\Acrobat 5.0 should exist in the In subfolder field.
13 Click OK.
14 From the Project node, expand the Files > All Files node.
15 Check that the C:\Windows\Temp directory has not been captured.
16 Ensure that the package complies with Windows standards and does not place any files into the C:\Windows\Profiles directory, which do not comply with those standards.
17 Expand the Groups and Icons > All Groups and Icons node. Ensure that the icons and groups are appropriate for this application.
18 Right click on the Project node and select Save.
19 Right click on the Project node and select Pack. This invokes the project validation dialog.
20 Click OK. The wizard validates the package, displays a validation complete screen and automatically packs the project. After packing, the .osd and .ndc files are placed in the staging directory C:\Warehouse\Staging\Common\Packages.
Note: The path to the icon has been replaced with the ManageSoft symbol $(AppDir). This variable records the value of the installation location set in the Autocreate wizard. The path to will be $(AppDir)\Reader\AcroRd32.exe. After installation, $(AppDir) will be replaced with C:\Program Files\Adobe\Acrobat 5.0.
Scenario: AppDir and installing a package AppDir behaviors TN12-10 Review the Acrobat Reader.osd file
1 Using Windows Explorer, navigate to C:\Warehouse\Staging\Common\Packages\Adobe Acrobat Reader 5.0 and check for the presence of Adobe Acrobat Reader 5.0.osd and Adobe Acrobat Reader 5.0.ndc.
2 Open Acrobat Reader.osd using Wordpad. A version of the following is displayed:
3 Take note of the following: The name and version of the package to be installed. The MANAGESOFT::USERDOMAIN tag records whether the package is installed using public (machine) or private (user) privileges. DEFAULT is the default value for package context, such as "public", "private" and "highest" (whatever the user's privileges will allow). USERSELECT determines whether or not the user has the option to select to install for private or public, if that user has the necessary privileges. INHERIT determines whether or not this package inherits the context of the parent package where there is a dependency. The Implementation tag displays the location of the .ndc file, the value of the MD5 checksum and the platform(s) onto which the package will be installed. If the Acrobat Reader.ndc file is changed in any way, ManageSoft aborts the installation assuming that, as the MD5 values do not match, the Acrobat Reader.ndc file has been corrupted. Review the Adobe Acrobat.ndc file
1 Using Windows Explorer, navigate to C:\Warehouse\Staging\Common\Packages\Adobe Acrobat Reader 5.0 and check for the presence of Adobe Acrobat Reader 5.0.osd and Adobe Acrobat Reader 5.0.ndc.
2 Open Acrobat Reader.ndc using Wordpad.
Note: Each time a .ndc file is re-packed a new MD5 checksum is calculated.
Scenario: AppDir and installing a package AppDir behaviors TN12-11 A version of the following is displayed (please note that this is a short example, as the file itself can be very large):
Format: 5.1 Application: "Adobe Acrobat Reader 5.0" Copyright: "(C) 2001 Adobe Systems Incorporated" Creator: "Adobe Systems Incorporated" Comment: "PDF file viewer for Windows workstations"
Title: "Adobe Acrobat Reader 5.0"
Version: "5,0,0,2" UserDomain: highest; userSelect; inherit PackageType: Package #if (($(OS) == "Win95" && $(OSVERSION) == "4,10,0,0"))
Registry: set; root = HKLM; key = SOFTWARE Registry: set; root = HKLM; key = "SOFTWARE\Classes"
Registry: set; root = HKLM; key = "SOFTWARE\Classes\Interface"
Registry: set; root = HKLM; key = "SOFTWARE\Classes\Interface\{3EFAA421-272F-11D2-836F- 0000F87A7782}"
Registry: set; root = HKLM; key = "SOFTWARE\Classes\Interface\{3EFAA421-272F-11D2-836F- 0000F87A7782}";
value = IDOMDocumentType;
type = SZ Registry: set; root = HKLM;
key = "SOFTWARE\Classes\Interface\{3EFAA421-272F-11D2-836F- 0000F87A7782}\ProxyStubClsid"
Registry: set; root = HKLM; key = "SOFTWARE\Classes\Interface\{3EFAA421-272F-11D2-836F- 0000F87A7782}\ProxyStubClsid"; value = "{00020424-0000-0000-C000-000000000046}"; type = SZ 3 Note the following:
The name of the catalog. This is the name displayed in Add/Remove Programs after the application has been installed The version of the package The registry entries, file entries and groups and icon referred to in the file. The use of ManageSoft symbols resolved on the managed device during installation, for example, $(AppDir), $(WinDirectory), $(ProgramFiles). Appendix: Using the ManageSoft $(AppDir) project variable in callouts ManageSoft Technical Note #12 TN12-12 ©2002, ManageSoft Corporation Appendix: Using the ManageSoft $(AppDir) project variable in callouts The AppDir variable represents the location into which the application will be installed. This variable is only set after the Install. Process. Archive Components.Parse Archive.Components event. If your callout runs prior to this event, it cannot use this variable. This variable is only set if it is referenced directly in the software package. For details about using project variables in a package, see Technical note #6, Using project variables. Please refer to page 3 in this document for real-world example that utilize the AppDir variable.
Comments