Installer VISE User Guide

Transcription

User Guide
MindVision Installer VISE
release 8.4
© 2003-2012 DR MyCommerce, Inc. All rights reserved.
Installer VISE User’s Guide
This manual, as well as the software described in it, is furnished under license and may be used or
copied only in accordance with the terms of such license. The content of this manual is furnished for
informational use only, is subject to change without notice, and should not, in and of itself, be construed as a commitment by DR MyCommerce, Inc. DR MyCommerce, Inc. assumes no responsibility
or liability for any errors or inaccuracies that may appear in this book. The copyrighted software that
accompanies this manual is licensed for use by the Licensee only in strict accordance with the Software License Agreement, which the Licensee should read carefully before commencing use of the software. Except as permitted by such license, no part of this publication may be reproduced, stored in a
retrieval system, or transmitted, in any form or by any means, electronic, mechanical, recording, or
otherwise, without the prior written permission of DR MyCommerce, Inc.
Contact Information
MindVision
826 P Street
Suite 300
Lincoln, NE 68508
USA
Phone:
Fax:
E-mail:
Web:
(402) 323-6600
(402) 323-6611
[email protected]
http://www.mindvision.com
.
Contents–i
Table of Contents
Table of Contents
Section 1 Getting Started
Chapter 1-About Installer VISE
Why Use Installer VISE? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
About the Compression Utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Localization Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
New features in Installer VISE 8.4. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
More changes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1-1
1-1
1-1
1-2
1-2
Chapter 2-Getting Started with Installer VISE
System Requirements for the Installer VISE Builder. . . . . . . . . . . . . . . . . . . . . . . . . .
Contents of the Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Installing Installer VISE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Choosing Easy Install or Custom Install . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Completing the Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
About the Installer VISE and Updater VISE Extensions Folders . . . . . . . .
Registering Installer VISE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Installer VISE Version Checking. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2-1
2-1
2-1
2-2
2-2
2-3
2-3
2-3
Chapter 3-Designing an Installer
About Installers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
About Installer VISE. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Sample Options for Files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Sample Options for Packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Sample Options for General Installer Information . . . . . . . . . . . . . . . . . . .
A Customer’s Perspective . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3-1
3-2
3-2
3-2
3-2
3-3
Chapter 4-Installer Tutorial
Getting Ready . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-1
Creating an Archive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-1
Contents–ii
Getting Started. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-1
About the Add Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-2
Saving the Archive. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-4
Creating Packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-4
Creating a Simple Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-4
Creating Sub-Packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-7
Creating a Separator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-8
Rearranging the List of Packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-9
Assigning Files to Packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-11
Creating an Action Item. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-12
Moving the Action Item to the Correct Location in the Archive . . . . . . . 4-15
Assigning the Action Item to SimpleText . . . . . . . . . . . . . . . . . . . . . . . . . . 4-16
Adding a Splash Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-18
Generating an Archive Report. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-18
Setting Installer Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-19
Building the Installer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-21
Testing Your Installer. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-21
Chapter 5-Updater Tutorial
Before You Start.... . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-1
About this Tutorial . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-1
About Building Updaters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-2
Getting Started. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-2
About the Updater VISE Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-3
Identifying Source and Target Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-4
About Source and Target Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-4
Identifying the Source Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-4
Identifying the Target Files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-5
Saving Your Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-6
Identifying the Resource Exceptions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-6
About the Resource Exceptions List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-6
Modifying the Update Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-8
Setting the File Options (“Delete Original” and “New File Name”) . . . . 5-11
Stand-alone Updater Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-11
Completing the Update File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-12
Testing the Update File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-12
Saving the Update File as a Stand-Alone Application . . . . . . . . . . . . . . . . 5-14
Section 2 Building Installers
Chapter 6-Creating an Archive
About Archives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Creating a New Archive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The Extended Add Dialog Box . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Displaying Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Selecting Items. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Shortcuts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Adding Files to the Archive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Creating an Installation Folder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Catalog Only . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Saving an Archive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Changing File Names in the Archive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6-1
6-1
6-2
6-3
6-3
6-3
6-3
6-4
6-4
6-4
6-4
Contents–iii
Removing Files from the Archive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Modifying Archive Preferences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Verifying and Updating an Archive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Verifying the Archive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Bringing the Archive Up-To-Date . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6-5
6-5
6-6
6-6
6-6
Chapter 7-Creating Packages And Assigning Files
About Packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-1
About Sub-Archive Packages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-2
About Sub-Packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-2
Package Dependencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-3
List Packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-7
Creating a Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-7
Edit Package options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-8
Creating Package Separators and Mutual Exclusive Groups. . . . . . . . . . . 7-10
Restarting After Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-10
Creating a Sub-Archive Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-11
Creating a Sub-Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-12
Creating a List Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-13
Assigning a Gestalt to the Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-15
Language and Region Gestalts for Packages . . . . . . . . . . . . . . . . . . . . . . . . 7-16
Package Build Directives. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-18
Setting the Package Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-23
Adding an Icon to a Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-23
Rearranging the List of Packages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-24
Deleting a Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-25
Assigning Items to Packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-25
Assigning Items in the Packages popmenu . . . . . . . . . . . . . . . . . . . . . . . . . 7-26
Assigning Items to Packages in the Archive Window . . . . . . . . . . . . . . . . 7-26
Chapter 8-Creating Action Items
What Are Action Items? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-1
Basic Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-2
Creating an Action Item. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-2
Entering General Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-4
Entering <Action> If Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-4
Entering What to <Action> Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-6
Items Found Using Search Criteria . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-7
Find Action Item . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-7
Archive Item . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-7
Action Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-17
Find Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-18
Delete Options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-19
Copy Options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-20
Move Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-21
Rename Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-22
Alias Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-23
Message Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-25
Display Form Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-27
Set Variable Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-28
Test Variable Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-29
Jump Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-31
Stop Installation Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-32
Contents–iv
Sub-launch Action Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Launch URL Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Edit Text File Options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Comment Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
UNIX Script Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Saving an Action Item. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Replace Options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Assigning External Codes to Action Items . . . . . . . . . . . . . . . . . . . . . . . . .
Identifying Action Items In the Archive Window . . . . . . . . . . . . . . . . . . . . . . . . . . .
Duplicating Action Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Renaming Action Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Correct Placement of Action Items. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Assigning Action Items to Packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8-33
8-35
8-37
8-40
8-40
8-42
8-42
8-44
8-45
8-47
8-47
8-47
8-47
Chapter 9-Assigning External Code
About External Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Adding External Code to an Installer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Declaring External Code in an Installer . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Editing External Code Information. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Deleting External Code Information. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Specifying When to Call External Code . . . . . . . . . . . . . . . . . . . . . . . . . . . .
9-1
9-2
9-4
9-6
9-7
9-7
Chapter 10-Creating and Editing Gestalt Calls
About Gestalt Calls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-1
Creating and Modifying Gestalts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-1
Creating a Gestalt Call . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-3
Chapter 11-Setting Up Disk Information
Setting Up Disk Information. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-1
Chapter 12-Setting File and Folder Options
Changing File and Folder Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-1
Setting File and Folder Options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-1
Using the Archive Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-2
Using the Get Info Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-2
Shadow Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-3
Notes on Shadow Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-4
Item Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-4
Changing an Item’s Long Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-4
Changing a File’s Language . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-4
Changing a File’s Region . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-4
Changing a File’s Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-4
Changing a File’s Creator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-5
Installing the Item Based on an Action Item . . . . . . . . . . . . . . . . . . . . . . . 12-5
Install To Location . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-5
Domain Location . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-6
Merging Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-11
Installing a File or Folder To Another Folder in the Archive . . . . . . . . . 12-11
Replacing Existing Items on the Target System . . . . . . . . . . . . . . . . . . . . 12-12
Assigning Build Directives to Files and Folders . . . . . . . . . . . . . . . . . . . . 12-13
Storing the Item Uncompressed in a Disk Image or Folder . . . . . . . . . . 12-15
Installing the Item Based On a Gestalt Check. . . . . . . . . . . . . . . . . . . . . . 12-15
Contents–v
Setting Fat Binary Install Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Assigning an Item to Packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Calling External Codes Associated with an Item . . . . . . . . . . . . . . . . . . .
Open After Installing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Deleting the Item During Uninstalls . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Installing an Update File as a Normal File . . . . . . . . . . . . . . . . . . . . . . . .
Restarting After Installing an Item . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Don't Install Folder (Placeholder) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Don't Retain Icon Position. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Synchronizing Dates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Installing Application Packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Installing Application Bundles on Mac OS X . . . . . . . . . . . . . . . . . . . . . .
Cancel If Update Fails . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Symbolic Link . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Including an Uninstall Function in the Installer . . . . . . . . . . . . . . . . . . . . . . . . . . .
Setting Up Your Archive For Uninstalls. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Folder Default Settings. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
About Folder Default Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Setting Group and Permissions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Setting Group for an Install Item. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Setting Permissions for an Install Item . . . . . . . . . . . . . . . . . . . . . . . . . . .
Setting the Owner of an Install Item to Root . . . . . . . . . . . . . . . . . . . . . .
12-16
12-17
12-17
12-18
12-18
12-18
12-18
12-19
12-19
12-19
12-19
12-21
12-22
12-22
12-22
12-22
12-23
12-24
12-25
12-25
12-26
12-26
12-27
Chapter 13-Setting Icon Locations
Standard Icon Positioning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-1
Set Icon Locations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-1
Capture Icon Position and Catalog Only . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-4
Chapter 14-Setting Installer Options
Installer Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-1
Installer Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-1
Designing the Interface Display. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-2
Choosing the Default Language . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-2
Setting the Default Installer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-2
Choosing the Installer Interface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-2
Choosing the Default Install Location. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-5
Adding Text for Display During Easy Install . . . . . . . . . . . . . . . . . . . . . . . 14-7
Adding an Uninstall Feature to Installers . . . . . . . . . . . . . . . . . . . . . . . . . . 14-9
Preventing Shutdown of Running Applications on Uninstall . . . . . . . . . 14-9
Adding Text for Display During an Uninstall . . . . . . . . . . . . . . . . . . . . . 14-10
Adding Read Me and License Agreements to the Installer . . . . . . . . . . . . . . . . . . . 14-10
Assigning a Read Me File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-10
Attaching a License Agreement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-11
Extra Installer Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-13
Installer Log File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-13
On-line Registration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-14
Adding a Splash Screen. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-15
Designing the Installer's Behavior. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-16
Including or Excluding Warnings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-16
Choosing Installation Destinations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-17
Miscellaneous Behavior Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-18
Sub Launch Locks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-19
Contents–vi
Installer Attributes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Assigning a Custom Icon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Changing the SIZE Resource . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Setting Finder Flags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Assigning Minimum Requirements for Installation . . . . . . . . . . . . . . . .
Setting an Installer Password . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Adding Advanced Features to Your Installer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Compressing Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Adding Files to an Existing Archive. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Assigning a Resource File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Assigning a Localization File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Assigning External Codes to an Installer. . . . . . . . . . . . . . . . . . . . . . . . . .
Installer Settings for Web Installers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Saving Installer Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Selecting Installer Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Defaulting Installer Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Deleting Installer Settings. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Installer Launches. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Supporting Multiple Users Accounts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
14-20
14-20
14-20
14-21
14-22
14-23
14-25
14-25
14-26
14-27
14-27
14-28
14-29
14-30
14-31
14-31
14-34
14-35
14-37
Chapter 15-Adding Billboards to an Installer
Billboards. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Installer Settings Billboard Display Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Billboard Display Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Assigning Billboards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
15-1
15-2
15-2
15-3
Chapter 16-Generating Archive Reports
Archive Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-1
Generating Archive Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-3
Report Output Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16-4
Chapter 17-Finding Items in an Archive
Find Feature . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17-1
Chapter 18-Building the Final Installer
Before the Final Build. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Build Targets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Building a Debug Installer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Building the Release Installer. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
18-1
18-1
18-4
18-7
Chapter 19-Creating CD Installers
Creating a CD Installer. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The Catalog Only Question . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Create a CD Installer Build Destination . . . . . . . . . . . . . . . . . . . . . . . . . . .
Set Installer Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Building the CD Installer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Capture Icon Locations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
File Compression Options for CD-ROM Installations . . . . . . . . . . . . . . .
19-1
19-1
19-3
19-5
19-5
19-5
19-5
Chapter 20-Maintaining Archives
Bringing the Archive Up To Date . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-1
Verifying an Archive. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-5
Contents–vii
Validating Paths . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20-5
Section 3 Building Updaters
Chapter 21-About VISE Updaters
Why Use an Updater?. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-1
Why Use VISE Updaters? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-1
The Customer’s Perspective: A Sample Session. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21-3
Chapter 22-Designing an Updater
Basic Components of an Updater . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Handling Multiple Versions and Formats . . . . . . . . . . . . . . . . . . . . . . . . .
Designing Your Updater . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Options for Updating PowerPC and Fat Binary Files . . . . . . . . . . . . . . . .
Sample Update Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Placing Files in the Update Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Updates With A Single Format Source and Target . . . . . . . . . . . . . . . . . .
For FAT Source and FAT Target Files... . . . . . . . . . . . . . . . . . . . . . . . . . . .
For Updates Where There Are Multiple File Formats... . . . . . . . . . . . . . .
22-1
22-1
22-2
22-3
22-4
22-5
22-5
22-7
22-8
Chapter 23-Building Updaters
General Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-1
Stand-alone vs. Multi-file updaters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-2
Before You Start . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-2
Creating a New Update File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-2
Modifying an Existing Update File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-3
About the Updater VISE Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-4
Adding Files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-5
Adding Source Files to the Updater. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-5
Adding Target Files to the Update File . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-6
Removing Files from the Update File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-6
The Update File Information Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-6
Identifying Resource and Data Fork Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-7
Data Fork Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-9
Identifying Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-9
Modifying Resource Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-10
Deleting a Resource. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-10
Modifying Update Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-11
Modifying File Options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-12
Update Settings for Stand-alone updater applications . . . . . . . . . . . . . . 23-13
Adding a Read Me File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-14
Entering Header Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-15
Choosing Whether To Search For Matching Files . . . . . . . . . . . . . . . . . . 23-15
Using a Standard File Dialog Box Instead of the Updater Window . . . . 23-15
Generating A Log File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-16
Opening the Application’s Folder After Updating . . . . . . . . . . . . . . . . . . 23-16
Modifying PowerPC and Fat Binary Options. . . . . . . . . . . . . . . . . . . . . . 23-16
Saving Default Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-18
Building the Update File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-18
Testing the Update File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-18
Testing Your Update File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-19
Saving the Update File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-19
Contents–viii
Data Fork Exceptions for PowerPC and FAT Files . . . . . . . . . . . . . . . . . . . . . . . . . 23-20
PowerPC Data Forks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-20
The cfrg Resource . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23-20
Chapter 24-Including Update Files in an Installer
About Updater VISE and Installer VISE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Application Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Installer Memory Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
How It Works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Including Update Files in an Installer. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Ignored Updater Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Creating Action Items to Find Files to Update. . . . . . . . . . . . . . . . . . . . . .
Interface Options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
24-1
24-1
24-2
24-2
24-2
24-2
24-3
24-4
Chapter 25-Auto-Create Updater Archive
Multi-file Updater Archives. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Installer VISE Automates the Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The AutoCreate Updater Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Auto-Create Updater . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
25-1
25-1
25-1
25-2
Section 4 Advanced Features
Chapter 26-Customizing the Archive Window
Archive Window Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
User-definable Archive Window Layouts . . . . . . . . . . . . . . . . . . . . . . . . . .
Archive Window Balloon Help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Defining an Archive Window Layout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Layout Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Customizing the Layout Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Layout Samples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Archive Window Shortcuts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
26-1
26-1
26-3
26-3
26-5
26-6
26-6
26-8
Chapter 27-Advanced Project Management
Build Directives. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27-1
Build Directive Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27-3
Project Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27-6
Build Sources. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27-7
Build Targets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27-8
Attributes tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27-9
Calling the MindVision Shared Library . . . . . . . . . . . . . . . . . . . . . . . . . . 27-11
Directives tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27-15
Post processing tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27-16
Scripts tab. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27-17
Dates tab. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27-17
eSeller tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27-19
Learning About eSellerate. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27-21
Active Build Target . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27-21
Archive Links . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27-22
Read Me Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27-26
Viewing a Read Me File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27-26
License Agreements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27-26
Viewing a License Agreement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27-26
Contents–ix
Resource Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Billboard Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Shared Libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Scripts (Mac OS X only) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Installer VISE and Source Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
27-27
27-27
27-28
27-29
27-29
Chapter 28-Using Runtime Variables
Runtime Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Using Variables for Text Substitution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Declaring a Variable and Setting Initial Value . . . . . . . . . . . . . . . . . . . . . .
Entering Variables in Text Areas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Valid text areas for variable substitution. . . . . . . . . . . . . . . . . . . . . . . . . . .
Special Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Using Variables for Install Logic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
28-1
28-1
28-1
28-2
28-6
28-7
28-7
Chapter 29-Localization
Creating Installers in Different Languages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29-1
MindVision Installer and Updater Language Files. . . . . . . . . . . . . . . . . . . 29-1
Supported Languages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29-2
About the Localization Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29-2
Single-language Installers Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29-2
Multi-language Installers Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29-3
Single-Language vs. Multi-Language Installers . . . . . . . . . . . . . . . . . . . . . 29-3
Creating Single-Language Installers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29-4
Create a Translator Application. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29-5
Enter Localization Information in the Translator Application. . . . . . . . . 29-6
Create a Localization File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29-8
Import Translator Application Resources . . . . . . . . . . . . . . . . . . . . . . . . . 29-9
Select Installer Language. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29-10
Select Language for Build Target(s). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29-11
Creating Multi-Language Installers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29-12
Create a Translator Application. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29-13
Enter Localization Information in each Translator Application . . . . . . 29-14
Create a Localization File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29-16
Import Multiple Translator Application Resources. . . . . . . . . . . . . . . . . 29-17
Import Multiple Installer VISE Language Files . . . . . . . . . . . . . . . . . . . . 29-19
Select Installer Default Language . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29-20
Select Languages for Build Target(s) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29-21
Select Mac OS X Options for Build Target(s). . . . . . . . . . . . . . . . . . . . . . 29-22
About Multi-Language Installers on Mac OS X . . . . . . . . . . . . . . . . . . . . 29-22
About Localized External Code in Localized Installers . . . . . . . . . . . . . . 29-22
Localized-at-Install Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29-24
Overriding Dynamic Localization. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29-25
Language Codes for Installer VISE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29-26
Region Codes for Installer VISE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29-27
Languages as Defined in Apple’s Script.h File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29-28
User Defined Languages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29-30
Chapter 30-Scripting Installer VISE with AppleScript
Scripting Installer VISE and Installers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Including AppleScript Scripts Within an Installer . . . . . . . . . . . . . . . . . . . . . . . . . .
Installer VISE and AppleScript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Opening an Archive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
30-1
30-1
30-3
30-4
Contents–x
Saving an Archive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30-4
Closing an Archive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30-4
Bringing an Archive Up to Date. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30-4
Setting the Validate Paths flag before Bringing an Archive Up To Date . 30-5
Setting the Intelligent Update Flag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30-5
Setting the Assign Parent Package to New Files Flag . . . . . . . . . . . . . . . . . 30-5
Performing a Regular Archive Update . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30-6
Performing a Full Update . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30-6
Performing an Update on One Root Level Item Only. . . . . . . . . . . . . . . . 30-6
Performing an Update on One Item Only . . . . . . . . . . . . . . . . . . . . . . . . . 30-7
Extracting an Archive Item. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30-7
Setting Billboard Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30-7
Setting the Current Build Target . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30-7
Turning Build Directives On . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30-8
Turning Build Directives Off . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30-8
Turning Build Targets On . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30-8
Turning Build Targets Off . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30-9
Building an Install Set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30-9
Setting the value of an existing Variable . . . . . . . . . . . . . . . . . . . . . . . . . . . 30-9
Editing an existing Download Site. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30-10
Setting the Localization File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30-10
Validating an Update File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30-10
Setting the Disk Sizes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30-11
Removing Compressed Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30-12
Chapter 31-Controlling an Installer with AppleScript
Setting Easy Install. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Setting Custom Install. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Selecting a Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Deselecting a Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Installing the Software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Installing the Software With No User Intervention . . . . . . . . . . . . . . . . . .
Updating the Drive List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Selecting the Install Location. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Selecting a Hard Drive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Selecting a Folder. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
31-1
31-1
31-2
31-2
31-2
31-2
31-3
31-3
31-3
31-4
Chapter 32-Creating External Code
General External Code Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32-1
When Codes Can Be Called . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32-1
Resource IDs and Reference Constants. . . . . . . . . . . . . . . . . . . . . . . . . . . . 32-1
Using More Than One Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32-2
Nonexistent or Misidentified Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32-2
External code for 68K, PowerPC or Carbon. . . . . . . . . . . . . . . . . . . . . . . . 32-2
About the Samples folder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32-3
Creating External Code for Installer VISE Installers . . . . . . . . . . . . . . . . . . . . . . . . . 32-3
Setting Installer VISE Internal Variables. . . . . . . . . . . . . . . . . . . . . . . . . . 32-16
Helpful Hints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32-17
Creating External Code Resources for VISE Updaters . . . . . . . . . . . . . . . . . . . . . . 32-18
About External Code Resources. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32-18
Requirements for External Code Resources . . . . . . . . . . . . . . . . . . . . . . . 32-18
Using External Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32-19
Helpful Hints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32-20
Contents–xi
Keeping a Debugger from Quitting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Executing UNIX scripts from the installer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Including shell scripts as plain text files . . . . . . . . . . . . . . . . . . . . . . . . . .
Including shell scripts as resource files . . . . . . . . . . . . . . . . . . . . . . . . . . .
Sending information to sub-launched installers . . . . . . . . . . . . . . . . . . . . . . . . . . .
Installing Text Encoding Converters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
32-21
32-22
32-23
32-24
32-25
32-26
Chapter 33-Gestalts for Minimum Install Requirements
Modifying Gestalts for Minimum Install Requirements. . . . . . . . . . . . . . . . . . . . . .
How the GLST Resource is Handled . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Warnings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Adding a Gestalt Selector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Modifying a Gestalt Selector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Sample Gestalt Selector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
33-1
33-1
33-1
33-2
33-3
33-4
Chapter 34-Installer VISE Forms
Installer VISE Forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34-1
Sample Layout. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34-2
Creating a New Form . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34-2
Configuring a Form Action to Display a Form . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34-5
Form Editor Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34-6
Undo. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34-6
Select All . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34-6
Duplicate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34-6
New Button . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34-6
New Static Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34-9
New Edit Text… . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34-10
New Checkbox… . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34-12
New Radio Button. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34-14
New Radio Group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34-15
New Picture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34-16
Expand Right . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34-17
Reduce Right . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34-17
Get Info… . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34-17
Edit “Field Name”…. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34-17
Set Background Color. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34-18
Set Tab Order. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34-18
Save . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34-18
Test… . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34-18
Close . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34-18
Item Order in Dialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34-18
Keyboard Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34-19
Chapter 35-On-Line Registration
Using Online Registration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35-1
Create Registration Destination. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35-2
Creating a Registration Form . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35-4
Create Form . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35-4
Include Online Registration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35-8
Including Registration by Installer Settings . . . . . . . . . . . . . . . . . . . . . . . . 35-8
Including Registration by Form Action . . . . . . . . . . . . . . . . . . . . . . . . . . . 35-9
Registration Output Samples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35-12
Custom Mailers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35-13
Contents–xii
Chapter 36-Extended Install Locations
Extended Install Locations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Setting Install Locations With Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Creating Custom Install Locations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Getting Started. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Creating an Install Location External Code . . . . . . . . . . . . . . . . . . . . . . . .
Adding Install Location Items with 4 Character Codes . . . . . . . . . . . . . . .
Editing an Existing Install Location Item from an INL# Resource. . . . . .
Important Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
36-1
36-3
36-3
36-4
36-4
36-5
36-5
36-5
Chapter 37-Active Web Installers
Active Web Installers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37-1
Active Web Installer Setup. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37-1
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37-2
Designating Download Sites. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37-10
Verify Files on Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37-12
The User’s Initial Experience. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37-13
The User’s Subsequent Experiences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37-16
Chapter 38-USB Installers
USB Installers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38-1
Creating USB drivers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38-1
Building USB installers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38-1
Section 5 Special Topics
Chapter 39-Frequently Asked Questions
Creating Uncompressed Files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Adding Help to an Installer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Installation to System Folders of Remote Volumes . . . . . . . . . . . . . . . . . .
Bring Up To Date . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Installer Disk Space Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Package Sizes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Canceling an Install. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Forcing a Restart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Handling Fat Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Version Checking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Checking for Cancellations and Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Creating an "Installation Folder” . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Install To Location . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Skipping File Replacement in CD-ROM Install Sets . . . . . . . . . . . . . . . . .
Replacing the VISE Installer Icon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
39-1
39-1
39-1
39-2
39-2
39-2
39-2
39-2
39-2
39-3
39-3
39-3
39-3
39-4
39-4
Chapter 40-Shortcuts and Keyboard Commands
Archive Window Keyboard Shortcuts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Extended Add Dialog Keyboard Shortcuts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Drag and Drop Shortcuts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Changing Multiple File Attributes Shortcuts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
40-1
40-2
40-2
40-3
Index
Section 1
Getting Started
1–1
Chapter 1
About Installer VISE
Why Use Installer VISE?
Installer VISE provides an easy-to-use graphical interface for building a master installation set for CD-ROM or web delivery. The Installer VISE system maximizes the storage
capacity of your media and minimizes the necessary bandwidth by efficiently compressing the pieces of a product.
Although custom code can easily be added to handle complicated situations, Installer
VISE does not require programming expertise for writing installation scripts. You can
make gestalt calls, evaluate the operating environment, check for the existing files, applications and System Extensions, and choose to install platform-specific or fat binary versions of your fat binary applications, without ever having to write custom external code!
You can also display license agreements, splash screens, billboards and custom dialogs
during an installation.
To your customers, installing the software is as easy as reading the information that you
provide, and clicking the Install button.
About the
Compression Utility
The Installer VISE compression and decompression engine provides an extremely efficient means of storing and retrieving data. Not only are disk space and bandwidth conserved, but in many cases installations occur faster because the amount of data which
must be read from CD or web is reduced.
If you wish to use your own custom installation application, the Installer VISE decompression code library is available from MindVision as a separate product.
Localization Features
Installer VISE supports localization of installers for several different languages. Installer
VISE also contains a translator feature which lets you easily change file names, disk
names, package names and information, Easy Install text, Uninstall Text, and Action
Item prompt text for 37 supported languages. Additionally, you can create a multi-language installer based on the language of System in use on the customer’s computer.
1–2
New features in
Installer VISE 8.4
New features in Installer VISE 8.4
With the enhancements available in Installer VISE 8.4, you can define non-standard filename extensions for bundles, save Find action results as POSIX paths and more.
New features for Installer VISE include:
More changes
■
Define non-standard filename extensions for bundles. To define non-standard
filename extensions that Installer VISE should use to recognize bundles, you
can add the desired extensions to the text file “Bundle Extensions.txt” in the
Installer VISE Extensions folder. Installer VISE will then treat folder structures
with these extensions as bundles when you add them to the archive or use them
to set search criteria. For more information, see “Installing Application Bundles
on Mac OS X” on page 12-21 and “How Installer VISE Checks For Bundle Version” on page 8-15.
■
To allow passing Installer VISE runtime variables as paths in UNIX Script
actions, Find action items can now save their results as POSIX-based (slash-separated) paths. See “Find Options” on page 8-18 and “UNIX Script Options” on
page 8-40.
■
You can now control whether an installer allows installations to UNIX File System (UFS) volumes. Blocking these installations can be useful when you want to
avoid the slower searching of UFS volumes (compared to traditional Mac OS
Extended volumes), or when you haven’t tested your application on UFS. A new
checkbox in the Behavior tab of Installer Settings controls this option. See
“Choosing Installation Destinations” on page 14-17.
■
For installs on Mac OS X, Installer VISE now supports copying files and folders that
have long filenames (longer than 31 characters).
■
To extend the types of external code that can be used with installers, Installer
VISE now supports adding data-fork based resource files to the Project window.
The previous version supported adding traditional resource-fork based
resource files only. For information on how to add resource files to the Project
window, see Chapter 9-Assigning External Code.
For a listing of other changes in this release, see the Read Me in the Installer VISE
installer.
One of the changes in Installer VISE 8.4 required a file revision. As a
result, you will need to update older archives before you can work with
them in Installer VISE 8.4. The program will display a prompt when an
update is required, as shown in the following illustration. Be sure to
back up older archives before updating them to the new format.
Illustration 1-1: Prompt for updating old archives
Chapter 1 About Installer VISE
2–1
Chapter 2
Getting Started with Installer VISE
This chapter contains information and instructions for installing Installer VISE on your
system.
System Requirements
for the Installer VISE
Builder
The Installer VISE builder requires the following:
■
Mac OS 9.1 or greater with CarbonLib 1.5 or greater
■
Mac OS X v10.1 or greater
Installer compatibility ranges from System 7.0 through Mac OS X, depending on the
platform selected for the installer build. (In order to run Carbon installers on Mac OS 8.1
through OS 9.x systems, CarbonLib 1.1 or greater must be installed. )
Contents of the
Installation
The following packages are contained in the Installer VISE installer:
Package
Contents
Application
The Installer VISE application, as well as a Read Me file and the
SimpleText application.
Documentation
The Installer VISE User’s Guide in Adobe Acrobat Reader
format (.pdf).
Tutorial and
Sample Files
A folder of sample VCTs, sample AppleScripts and sample
external code, complete with source code so that you can adapt
the examples to suit your needs.
Table 2-1: Installer VISE Installation Packages
Installing Installer VISE
To begin installation of Installer VISE, follow these steps:
1. Double-click the Installer VISE installer icon. A splash screen will display license
information for Installer VISE.
2–2
Installing Installer VISE
2. If you wish to print the license file, click Print. If you wish to save the file to a location of your choice, click Save As. If you do not accept the terms of the license,
click Decline to cancel the installation.
3. If you accept the terms of the license, click Accept. (This button is enabled once
you scroll to the bottom of the license.) The Read Me file will be displayed. This
file will be included in the installation folder when you install Installer VISE.
4. If you wish to print the Read Me file, click Print. If you wish to save the file to a
location of your choice, click Save As.
5. To continue installation, click Continue or press <Return>.
Choosing Easy Install or
Custom Install
Installer VISE can be installed to your hard disk using either the Easy Install or Custom
Install options. The Easy Install option, which is the default, will install all files to the
location of your choice. If you wish to install all the files, go to the next section.
The Custom Install option allows you to install only the parts of the Installer VISE software package that you choose. You can choose as many packages in the Custom Install
option as you wish.
To choose the packages you wish to install, follow these steps:
1. Choose Custom Install from the popmenu in the upper left corner of the Easy
Install window.
2. Select the desired packages.
Illustration 2-1: Installer VISE Custom Install Packages
Completing the
Installation
1. From the Install Location popmenu select the location to which you wish to
install Installer VISE.
2. Click Install to install the files to the designated drive.
3. The installer will offer to automatically register your software from a previously
registered version of Installer VISE. Click Yes to accept or click No to advance to a
Registration dialog.
Chapter 2 Getting Started with Installer VISE
Registering Installer VISE
2–3
4. If you chose “No” for the previous step, a Registration dialog will display. You may
enter your registration information here. When you are finished, click Register. If
you have already registered your copy of Installer VISE on the MindVision web
site, click Skip to continue.
5. Next, the installer will offer to install Sample Archive Window Layouts. You can
choose to rename the existing layout file, replace it, or leave it intact. When you
have selected an option, click OK.
6. An installer log file containing information about the installation will be created
at the root of the install folder.
About the Installer VISE
and Updater VISE
Extensions Folders
When you install the Installer VISE application, the Installer VISE Extensions folder and
the Updater VISE Extensions folder will be included in the same folder as the application
itself. These two folders must remain in the same folder as the application to ensure that
the program functions correctly.
Registering Installer
VISE
If you create an installer with an unregistered copy of Installer VISE, the installer will:
■
Display the Installer VISE splash screen to the customer before your splash
screen, alerting them that you used unlicensed software; and
■
Expire three days from the date that the unlicensed installer was built.
If your copy of Installer VISE is registered, then the Installer VISE splash screen will never
be visible to the user, and the installer will not automatically expire.
To register your copy of Installer VISE:
1. From the File menu, select Register...
2. The following dialog appears:
Illustration 2-2: Installer VISE Registration dialog
3. Enter your name or the name of your company.
4. Enter the serial number of your copy of Installer VISE.
5. Click Register.
If you do not register your copy of Installer VISE now, you’ll be asked to register each
time you build an installer.
Installer VISE Version
Checking
If you have Internet access from your computer, you can quickly check to see if you are
using the most current version of Installer VISE. MindVision is constantly working to
improve our product and add new features. As a result, we release a newer version several
times each year.
2–4
Installer VISE Version Checking
To check the MindVision Server for the newest version of Installer VISE:
1. Select the Query MindVision Server command from the Extras menu.
Illustration 2-3: Query MindVision Server Menu Item
2. Installer VISE will attempt to establish an Internet connection with our server and
compare your version of Installer VISE with the newest version available.
3. If you are not using the latest version, you may always obtain it directly from our
World Wide Web site at <http://www.mindvision.com>. If you do not have an
Internet connection, you can call our support line at (402)323-6600 to check for
the latest version.
Chapter 2 Getting Started with Installer VISE
3–1
Chapter 3
Designing an Installer
This chapter contains information about planning and designing an installer to be created with Installer VISE.
About Installers
Just as you carefully plan and execute the development of your software, you should
spend some time planning your installer, as it’s the first direct contact customers will
have with your software package. Although Installer VISE provides an easy and flexible
environment for developing installers, only you can take into account the requirements
of your customers and your product.
If you’ve never designed an installer before, here are some issues to consider:
■
What are the different combinations of applications and files customers may
wish to install to customize their installation of your software?
■
What system extensions, control panels, etc. do you wish to distribute with your
software?
■
Do you wish to discourage or disallow certain kinds of multiple installations?
■
What are the minimum processor, RAM, and operating system requirements?
■
Do you wish to check for specific situations on the target machine such as different kinds of architecture or the presence of duplicate files and how do you
want to handle them?
■
Will your product require custom code to evaluate the target system or perform
additional functions?
■
How do you wish to phrase informational text that will inform customers of
their options?
■
Do you wish to start or stop installations, or launch a browser to install new
software based on the presence of certain files or programs?
It’s strongly recommended that you develop a design document for the installer outlining how you intend to build it. The following section contains more details about how
the functionality of Installer VISE can shape the way you develop your installer.
3–2
The basic building blocks of an Installer VISE installer are archives and packages.
The archive for an installation set contains every file that may need to be installed. For
each item in the archive, you may set a variety of options, some of which are described in
the section “Sample Options for Files.”
Packages for the installation are defined within the archive, and contain different combinations of files that the customer may choose to fully customize the installation of your
software. The customer may choose between the Easy Install option, which by default
will install every file in the archive, and the Custom Install option, which lets the customer choose from the customized packages. Packages for the installation are defined
within the archive and contain different combinations of files. You create each package,
and the customer may choose to fully customize the installation of your software.
Sample Options for Files
Below is a sample of some of the information you may specify for each file or folder in an
archive. For complete information about available options, please see Chapter 12-Setting
File and Folder Options.
For each file in an archive, you can identify:
Sample Options for
Packages
■
To which package it will be assigned
■
The location on the target system where the item will be installed
■
Whether gestalts should be checked or custom code should be run before or
after installing the item
■
What to do in case there is a duplicate of the item on the target system
Below is a sample of some of the kinds of information that you may specify for each
package in an archive. For complete information about available options, please see
Chapter 7-Creating Packages And Assigning Files.
For each package, you can identify:
Sample Options for
General Installer
Information
■
A text description of the contents of the package, which may include information to help the customer decide whether to include it if a Custom Install is
available.
■
Whether the customer will be prompted to restart after installing the package
■
If the package is specifically designed for computers with 680x0 processors,
PowerPC processors, or processors that can handle fat binary applications
■
Whether the package is part of a mutually exclusive group, so that only one item
within the group can be installed
■
Whether certain gestalt conditions must be met in order for the package to be
part of an installation
■
Whether the package is available for install after a successful online transaction.
This option applies when you build your installer to integrate with the eSellerate e-commerce system (an optional service).
Below is a sample of some of the kinds of information you may specify for the installer in
general. For complete information about available options, please see Chapter 14-Setting
Installer Options.
For any installer, you can identify:
■
Chapter 3 Designing an Installer
A Read Me file to be displayed to the customer when the installer is launched,
3–3
and a license agreement that must be accepted before they can continue with
the installation
A Customer’s Perspective
■
A splash screen
■
Whether to force or recommend restarts following installation
■
Minimum installation requirements such as CPU, operating system, and gestalt
information
■
Informational text to be displayed to describe the Easy Install package
■
A Help file that’s available to the customer at the click of a button, providing
additional information and guidance
The following is a sample of what a customer might encounter when using an installer
created with Installer VISE.
1. After launching the installer and dismissing your custom splash screen, the Read
Me file containing product and installation information is displayed.
2. The text for the Easy Install option is presented, letting the customer know what
files will be installed.
3. If packages other than Easy Install have been defined, the customer may switch to
Custom Install with the click of a mouse, and view descriptive information for
each package.
4. After choosing Easy Install or selecting the desired packages under Custom Install,
the customer selects the disk where the items should be installed and begins the
installation.
5. While the files are being installed, custom “billboards” containing product and
registration information are displayed, along with a progress dialog that provides
information about the progression of the installation.
6. When the installation is complete, the customer can choose to install more packages or to quit the installer. If system extensions were installed, the computer is
automatically restarted upon quitting the installer.
3–4
Chapter 3 Designing an Installer
4–1
Chapter 4
Installer Tutorial
This chapter contains a brief tutorial to acquaint you with the process of building installers with Installer VISE. For complete information about the procedures in this chapter,
and for features not described in this chapter, see the chapters in Section 2 - Building an
Installer.
Getting Ready
Before you start this tutorial, make sure that you have installed the Installer VISE Tutorial
folder that came with Installer VISE. The Installer VISE Tutorial folder contains all the
materials that will be used in this tutorial.
If you performed an Easy Install, the folder will be in the Installer VISE folder. If you performed a Custom Install and did not choose the Tutorial package, launch the Installer
VISE installer, select Custom Install, and install the Tutorial package.
Creating an Archive
Complete information on this topic can be found in Chapter 6-Creating an Archive.
Getting Started
The first step in creating an installer is to create an archive containing all the files that
need to be installed.
To create an archive:
1. Launch Installer VISE.
2. From the File menu, select New Archive... to create a new archive. A standard save
dialog box will be displayed, containing a default name for the archive. Replace the
4–2
Creating an Archive
default archive name with MyApp.vct. (.vct is the default extension for Installer
VISE archives, and will make it easy to identify archives at the Finder.)
Illustration 4-1: Save Archive dialog
3. After navigating to the save location, click Save. An archive window will be displayed.
4. From the Edit menu select Preferences and select Use Extended Add File Dialog
Box. Select the OK button to close Preferences.
Illustration 4-2: Preferences
5. In the archive window, click Add. The Extended Add window will be displayed.
About the Add Window
The list of files in the dialog box reflects the file and directory structure of your hard
drive; you will need to navigate through the files until you locate the Installer VISE Tutorial folder.
To display the contents of a folder, click the triangle to the left of the folder. The contents
will be displayed beneath it. If you display the contents of the Installer VISE Tutorial
folder, you’ll see that it contains a file called 1bitSplashPict, Read Me (tutorial), and
another folder called Sample Archive materials.
Chapter 4 Installer Tutorial
Creating an Archive
4–3
Files and folders are added to the archive by selecting them at the Add window. To select
an item, click the box to the left of the item’s name. When an item has been selected, an
“x” is displayed in the box at the left, and the item’s name appears in boldface type.
If you select a file, only the file is selected; if you select a folder, all the contents of the
folder are automatically selected as well. If desired, you may deselect individual items
within a selected folder.
To deselect an item, click the check box. The “x” will be removed from the checkbox and
the item will be displayed in regular type.
In the following illustration, the contents of the Sample Archive Materials folder have
been displayed and are selected:
Illustration 4-3: Files Selected within the Extended Add Window
To add the files for this tutorial to our archive:
1. Locate and display the contents of the Sample Archive Materials folder.
2. Select the Sample Archive Materials folder by clicking the line on which it appears.
This automatically selects all the files within the folder as well.
3. To add the selected files to the archive, click Add.
4–4
Creating Packages
4. To indicate that you are finished adding files to the archive, click Done. You will
return to the archive window, where the Sample Archive Materials folder will be
displayed, as in the following illustration:
Illustration 4-4: Archive Window with Tutorial Files
Saving the Archive
To save the archive:
1. From the File menu, select Save.
2. Installer VISE will compress the selected files into an archive. Depending on your
computer, this may take a few seconds.
Creating Packages
The next step in this tutorial is to create packages of files. Packages contain subsets of all
files in the install set, and allow the user to select which files or sets of files will be
installed. By default, all files in the archive are part of the Easy Install package; if the user
selects Easy Install, then all the files in the archive will be installed.
If a user chooses Custom Install instead of Easy Install, the list of packages is displayed.
As the creator of the installer, you create a description of the package and a custom icon
for it that are visible to the end users if they click the Information button. You also
choose the order in which the packages will be displayed and where to include optional
“separators” that create a visual distinction for the user among the different kinds of
packages.
In this tutorial, we will create a simple package; a package that contains sub-packages;
and a separator. Other kinds of packages that you might create are list packages and subarchive packages.
For complete information about this topic, please see Chapter 7-Creating Packages And
Assigning Files.
Creating a Simple Package The first package that we will create is an Application package. This package will simply
contain the sample application and no other materials.
Creating Packages
4–5
To create a package:
1. From the Archive menu, select Packages... The Package List window will be displayed.
Illustration 4-5: Package List
4–6
Creating Packages
2. Click the New button. The Edit Package window will be displayed.
Illustration 4-6: Edit Package window
3. For this tutorial, enter the information in the fields as it appears in the following
illustration. Use the Tab key to move between fields, or click the mouse in the
desired location.
Illustration 4-7: Application Package setup
4. To return to the Package List window, click OK.
Creating Packages
Creating Sub-Packages
4–7
In addition to creating packages, you may also create sub-packages. Sub-packages are
packages that are a part of another package. If the customer chooses to install a package
that contains sub-packages, he may also choose which of the associated sub-packages
should also be installed.
In this tutorial, we will create a package called Samples, which will contain the sub-packages “Database Samples,” “Word Processing Samples,” and “Spreadsheet Samples.” When
we run this installer and choose Custom Install, the Samples package will be displayed
with an expandable arrow, indicating a set of sub-packages from which to choose.
Creating the Parent Package
To create the parent package:
1. At the Packages window, click New.
2. Enter information in the fields as it appears in the following illustration:
Illustration 4-8: Samples Parent Package setup
3. Click OK.
Creating the Sub-Packages
To create the sub-packages:
1. At the Packages window, click New.
2. Enter information in the fields as it appears below:
Illustration 4-9: Database Sub-package setup
3. Click OK to return to the Package List window.
4–8
Creating Packages
4. With Database Samples selected in the Package List, click the » button to indent
Database Samples under the Samples Package. Indented packages are sub-packages of the package above them in the Package List. Your Package List should look
like the illustration below:
Illustration 4-10: Indenting a Sub-package in the Package List
5. Repeat steps 1-4 as above, creating the following sub-packages:
Name
Description
Spreadsheet Samples
This package contains samples of spreadsheets
Word Processing Samples
This package contains samples of word processing.
Table 4-1: Tutorial sub-package setup
Creating a Separator
A separator is a visual device that you use to show the logical organization of your packages. It appears to the customer as a line that separates sets of packages from each other.
Separators can also be used to create mutually exclusive groups of packages; for complete
information about separators, see “Edit Package options” on 7-8.
To create a separator:
1. At the Packages window, click New Package.
2. Check the Separator checkbox.
You don’t need to enter any more information in the Edit Package window, as any
text you enter will be discarded.
3. Click OK.
Creating Packages
Rearranging the List of
Packages
4–9
If you followed the instruction in this tutorial, the Packages window should look like this:
Illustration 4-11: Package List displaying separator
The organization of the packages in this window determines how the packages will be
displayed to a user who selects the Custom Install option.
Sub-packages are associated with the first regular package that appears above them. In
this case, all the sub-packages correctly appear beneath the Samples package, so there is
no need to rearrange them.
For this tutorial, we’ll move the separator line so that it appears between the Application
package and the Samples package.
4–10
Creating Packages
To reorder the list of packages:
1. Move the mouse over the separator line’s grab handle and hold down the mouse
button. The pointer will turn into a hand as soon as you move the cursor with the
mouse button held down.
Illustration 4-12: Moving Separator Packages
2. With the mouse button held down, drag the separator so that the line appears
between the Application package and the Samples package.
3. Release the mouse. The separator will remain in the location where you dropped
it.
Assigning Files to Packages
4–11
When you are finished, the Packages List window should look like this:
Illustration 4-13: Package List displaying final package arrangement
To return to the archive window, click OK.
Assigning Files to
Packages
The next step in creating the installer is to assign all the files in the archive to the appropriate packages. Files can be assigned to packages in a variety of ways; for this tutorial,
we’ll select each item at the archive window and assign packages using the Packages popmenu at the top of the archive window. For complete information about assigning files to
packages, see “Assigning an Item to Packages” on page 12-17.
By default, all items in the archive are assigned to the Easy Install package. Items that are
part of the Easy Install package will be installed on the customer’s system if they select the
Easy Install option. If the customer chooses the Custom Install option, they may select
which individual packages they wish to install.
In this tutorial, we will assign the items in the archive to additional packages, but will not
make any changes to the Easy Install package.
To assign the contents of the archive to packages:
1. If the contents of the Sample Archive Materials folder are not displayed in the
archive window, click the triangle to the left of the folder’s name to show the items
in the folder.
2. Click the item you wish to assign to a package. (For example, to assign the Database Samples folder to a package, click Database Samples.) The line containing
the item will be highlighted to indicate selection.
3. At the top of the archive window, hold down the mouse over the Packages popmenu. The names of all the packages assigned for the archive will be displayed.
4. Select the name of the package to which you want to assign the file. For example, if
you selected the Database Samples folder, select the Database Samples package
from the Packages popmenu.
4–12
Creating an Action Item
5. For this tutorial, assign items to packages as in the illustration below:
Illustration 4-14: Tutorial Package Assignment
You may have noticed that we assigned the various Samples folders to packages, not their
individual contents. Items inside folders are automatically assigned to the same packages
as their parent folders; you may change the settings if you wish, but it was not necessary
for this tutorial.
You may also have noticed that we did not assign the SimpleText application to a package
other than Easy Install. We will work with the SimpleText application in the next section,
“Creating an Action Item.”
Creating an Action
Item
Action items are objects that you create within an archive to perform common functions,
such as deleting an items (Delete action item), locating an item (Find action item), moving an item (Move action item), renaming an item (Rename action item), creating an
alias of an item in the archive (Alias action item), or displaying a custom message dialog
(Message action item or Form action item), which will conditionally install files based on
a user's response.
For this tutorial, we’ll create a Find action item that checks for the presence of SimpleText
on all available disks of the target system. We’ll then associate that action item with the
copy of SimpleText in the archive; if the search for SimpleText fails, the copy in the
archive will be installed; however, if SimpleText is found on the target system, SimpleText
will not be installed again.
4–13
To create the Find action item that will locate SimpleText:
1. At the upper right corner of the archive window, select Find from the New Action
popmenu.
Illustration 4-15: New Action popmenu
4–14
2. The Find Action window will be displayed:
Illustration 4-16: Find Action
3. In the Name field, type Find SimpleText.
Illustration 4-17: Find Action name
4–15
4. In the What to Find section, select All Disks from the Search Location popmenu.
When the installer is run, it will check all available disks for the item you identify.
5. In the Search Criteria Name field, type SimpleText. Your window should now
look like this:
Illustration 4-18: Tutorial Find Action
6. Click the Close box at the upper-left corner of the window.
7. When asked if you wish to save the changes to the action item before closing, click
Save.
When you return to the archive window, the SimpleText Find action item will be displayed in the window.
Moving the Action Item to Action items whose result affect the installation of items in the archive must take place
the Correct Location in the before the items are installed. To make sure that the action item we just created is performed before the installer attempts to install SimpleText, it must appear before the SimArchive
pleText application does in the archive.
If the Find action item you just created appears after the Sample Archive Materials folder
in the archive window:
4–16
Place the mouse over the icon for the Find action item and hold down the button. When
you move the mouse, an outline of the item and a fine line indicating the position will
move with it
Move the mouse so that the black line appears above the Sample Archive Materials folder.
When you release the mouse, the action item will appear as the first item in the archive.
Assigning the Action Item
to SimpleText
The action item that you just created simply returns the information about the presence
of SimpleText on the local drives of the target system. The next step is set up the installer
so that it uses the information for some purpose. For this tutorial, we’ll associate the
action item with the copy of SimpleText in the archive so that it is only installed if SimpleText can not be found on the target system.
To assign the action item:
1. If the contents of the Sample Archive Materials folder are not displayed, click the
triangle at the left of the folder’s name to display them.
2. Select the entry for SimpleText in the archive window.
3. At the top of the archive window, click Get Info. The Get Info window for the
SimpleText item in the archive will be displayed.
Illustration 4-19: SimpleText Get Info window
4–17
4. Click the mouse next to Install If in the box labeled (Click to assign). The Select
Find Action window will be displayed:
Illustration 4-20: Select Action Item window
5. Select the Find SimpleText item.
6. Click Select. You’ll return to the Get Info window, where the name of the selected
action will be appended in the Install If field.
7. Hold down the mouse over the popmenu containing the words succeeds and
select fails. The Install If: portion of the Get Info window for SimpleText should
now look like this:
Illustration 4-21: Tutorial SimpleText Get Info window
8. Click the close box in the upper-left corner of the Get Info window.
9. When asked if you want to save the changes to SimpleText info, click Save.
When the installer is run, it will check for the presence of SimpleText on all disks. Before
attempting to install the copy of SimpleText in the archive, the installer will check the
4–18
Adding a Splash Screen
result of the Find SimpleText action item we created. If the action item failed because
SimpleText could not be found, the copy of SimpleText in the archive will be installed. If
the action item succeeded and SimpleText was found on the target system, the copy in
the archive will not be installed.
Adding a Splash
Screen
Splash screen are displayed to the customer as soon as the installer is launched. You may
use 1-bit or 8-bit splash screens for your installer. For this tutorial, we’ll add the 1-bit
graphic called “1bitSplashPict” to our archive as a splash screen.
To add the splash screen:
1. At the Finder, double-click the 1bitSplashPict file to open it with SimpleText.
2. From the Edit menu in SimpleText, choose Select All.
3. From the Edit menu, choose Copy to copy the picture to the Clipboard.
4. Quit SimpleText.
5. In Installer VISE, select Installer Settings... from the Archive window. Click on
the Extras tab.
6. Click on B & W.
7. Press Command-V to paste the screen into the window.
8. Since the splash graphic has a white background you may want to check Use white
background for Billboards and Splash in the Installer Settings Interface tab.
9. Click OK to return to Installer Settings.
10. Click OK to save changes and return to the Archive window.
Generating an Archive
Report
You can use archive reports as a diagnostic tool to make sure that your archive is set up
the way you want. A variety of different archive reports are available that organize the
information in different ways; for this tutorial, we’ll generate an archive report that lists
all the packages we created and all the files included in each package. For complete information about archive reports, see Chapter 16-Generating Archive Reports.
To generate the archive report for this tutorial:
1. From the File menu, choose Page Setup…
2. Change the orientation to landscape and click the OK button to close Page Setup.
3. From the File menu, select Print Archive Report... The Archive Report window
will be displayed.
4. Make sure that the item selected in the Report to Print popmenu is the Packages
report.
5. Make sure that the item selected in the Report Kind popmenu is Print to Screen.
6. Click Print...
Setting Installer Options
4–19
The report that you generated should look like the illustration below (all the information
does not appear in this picture):
Illustration 4-22: Tutorial Archive Report
Setting Installer
Options
After generating an archive report and ensuring that everything is assigned to the correct
packages, the last step is to set general options for the installer. Installer VISE allows you
to set a wide range of options related to the general behavior of the installer; however, for
this tutorial, we will only enter text to be displayed to the user during Easy Install, and
assign a Read Me file to be displayed to the user after the splash screen is dismissed. For
complete information on setting installer options, please see Chapter 14-Setting Installer
Options.
Assigning a Read Me
To set installer options:
1. From the Archive menu, select Installer Settings. The Installer Settings window
will be displayed.
2. Click on the Text Files tab.
4–20
3. In the Read Me Files section of the Installer Settings Text Files tab, click Add. A
standard file dialog will be displayed.
Illustration 4-23: Select Read Me file and Language
4. Locate and select the Read Me (tutorial) file in the Installer VISE Tutorial folder.
5. Click Select. When you return to the Installer Settings window, the path to the
Read Me (tutorial) file will be displayed in the window next to the Read Me button.
Illustration 4-24: Tutorial Read Me setup in Installer Settings
Adding Easy Install Text
6. Click on the Interface tab.
7. Locate Easy Install and click Edit Easy Install Text. A text entry box will be displayed.
Building the Installer
4–21
8. Enter the following text:
Illustration 4-25: Adding Easy Install text
9. Click OK to return to the Installer Settings window.
Building the Installer
For complete information on this topic, see Chapter 18-Building the Final Installer.
If the reports that you generated in the previous step show that there are no problems,
you’re ready to create the final installer.
To create the installer:
1. Select Build Installer... from the File menu.
2. If you are using an unregistered copy of Installer VISE, fill in your name and serial
number and click Register to register, or click Later to bypass registration. If the
copy of Installer VISE used to create the installer is not registered, the Installer
VISE splash screen will be displayed to the user before your splash screen is displayed. Installers created with unregistered copies of Installer VISE will expire
three days from the date of creation.
Register your copy of Installer VISE and follow the prompts on the screen to do so,
or click Later... to register at another time.
After registering or choosing to register later, a Save dialog box will be displayed.
3. Select a destination for the installer executable file.
4. Select Single File from the Target popmenu.
5. From the Platform popmenu, select a platform that will allow the installer to run
on the computer you’re using for this build.
6. Click Save.
Testing Your Installer
To make sure that your installer works correctly, launch the installer on your computer
system. Try an Easy Install as well as a Custom Install, and consider removing copies of
SimpleText from local drives to test the performance of the action item.
4–22
Testing Your Installer
5–1
Chapter 5
Updater Tutorial
This chapter will familiarize you with the process of building an updater by guiding you
step-by-step through building an updater for a sample product. For complete information about the steps described in this chapter, and for information on features not
described in this tutorial see:
Before You Start...
■
Chapter 21-About VISE Updaters
■
Chapter 22-Designing an Updater
■
Chapter 23-Building Updaters
■
Chapter 24-Including Update Files in an Installer
■
Chapter 25-Auto-Create Updater Archive
In this tutorial, we will create a sample updater using the materials contained in the
Tutorial folder. Before you start, make sure that you have installed the Tutorial folder and
that it contains the following items:
Illustration 5-1: Updater Tutorial Applications
These files are specially designed for use with this tutorial.
About this Tutorial
In this tutorial, we will create an application to update all formats of MyApp 1.0 to
MyApp 1.1. This section contains information about the kind of updater that we will
build.
5–2
About Building Updaters
About the File Formats
Both MyApp 1.0 and MyApp 1.1 are available in 68K, PowerPC, and Fat Binary formats.
For this tutorial, we will let the format of the source file (MyApp 1.0) determine the format of the target file (MyApp 1.1) that will be installed. In other words, MyApp 1.0 (68K)
will be updated to MyApp 1.1 (68K); MyApp 1.0 (PPC) will be updated to MyApp 1.1
(PPC); etc.
About the Resource
Exceptions
Updater VISE allows you to identify any resources which may differ between the source
and target files, and choose whether to always use the old resource, always use the new
resource, or only copy the old resource if it exists in the source file. For this tutorial, the
resource STR# with ID number 128 contains registration information. Both MyApp 1.0
(68K) and MyApp 1.0 (PPC) contain this resource (the applications are registered to
John or Jane Doe). We will place the resource in the “Keep Old If Exists” field, so that registration information for any registered copy of MyApp 1.0 will be carried over to
MyApp 1.1.
About the PowerPC Options
If you launch MyApp 1.0 (PPC) on a 68K Macintosh, you’ll see a System-generated message that an error of type -192 has occurred. In MyApp 1.1, we will replace this with a
friendlier and more informative message that identifies the cause of the error.
About Building
Updaters
The following steps are the general procedure for creating a stand-alone
updater application with Installer VISE.
1. Launch Installer VISE and create a new update file.
2. Identify the source files to be updated and the target files.
3. Identify any possible differences between the resource and data forks of the source
files and the resource and data forks of the target files.
4. Modify the updater’s settings to customize the final appearance and behavior of
the updater application.
5. Build the update file.
6. Test the update file.
7. Build the stand-alone updater application.
Individual update files are the basis for any type of updater you might create. Once you create and test an update file, you may do one of the following: build a stand-alone updater application, save as an eSellerate Update
file or include the update file (and any others) in an Installer VISE installer.
Getting Started
To begin creating the updater:
1. At the Finder, launch the Installer VISE application.
2. From the File menu, select New Archive…. Name and save your new archive.
3. In the Archive window click the New Updater button.
Chapter 5 Updater Tutorial
About the Updater VISE Window
5–3
4. In the Name field, replace Update Item with Update MyApp.
Illustration 5-2: Name for New Update Item
5. Click Create. A window will open displaying “MyApp” in the banner.
About the Updater
VISE Window
All actions for creating an updater application are performed in the Updater VISE window, pictured below:
Illustration 5-3: Update window
The following is a brief description of each item in the window.
■
The 68K, PPC and FAT rows contain the fields where you’ll identify the source
files for updating and the target files to update them to.
■
The Resource Exceptions item displays the fields where you’ll identify the
resource and data fork information that may have been modified by the application, operating system, or customer, and the action that should be taken by
the updater when encountering those resources.
■
The Trash Can lets you remove items from the source and target file lists by
dragging them over the icon.
■
The Add File... button lets you add a file to the currently-selected field.
■
The Settings... button displays the Update Settings window, where you can
make several choices regarding the appearance and actions of the updater application.
■
The Show Info button displays an Update File Info window.
■
The Save As ... button allows you to create a stand-alone updater application, or
an eSellerate Update file.
5–4
Identifying Source and Target Files
■
The Test button becomes active after you have built an updater. It allows you to
test the actions of the updater you have designed without quitting Installer
VISE.
■
The Compare button becomes active when you have added at least one source
and target file to the same row in the updater. It builds a functional update file
which uses the files and options that you have identified.
Identifying Source and
Target Files
In this section, we will identify the source and target files to be used in the updater application. For complete general information about working with source and target files, see
Chapter 23-Building Updaters.
About Source and Target
Files
Source files are the files which we wish to update; in this tutorial, the source files are all
versions of MyApp 1.0. Target files are the new files that the source files will be updated
to; in this tutorial, the target files are all versions of MyApp 1.1. All source and target files
must be identified in the Updater VISE window.
If your source and target files are available in more than one format (68K, PowerPC, or
Fat Binary), the placement of the source and target files in the rows of the Updater VISE
window determines the format of the target file that will be placed on the customer’s system. For detailed information about the correct placement of source and target files to
ensure that the desired target file format is used in the update, please read Designing an
Updater.
For this tutorial, we will let the format of the source file determine the format of the target file. In other words, MyApp 1.0 (68K) will always be updated to MyApp 1.1 (68K);
MyApp 1.0 (PPC) will always be updated to MyApp 1.1 (PPC); and MyApp 1.0 (FAT)
will always be updated to MyApp 1.1 (FAT).
Identifying the Source
Files
You may add source files to the Updater VISE window by using Drag and Drop (if it’s
available on your machine) or by using a standard file dialog box.
No matter which method you use, the Updater VISE window should look like the following after you complete this section:
Illustration 5-4: Update window after adding source files
Using Drag and Drop
To add files using Drag and Drop:
1. Drag the MyApp 1.0 (68K) application from the Finder and drop it over the 68K
Source Files field. The file name should appear in the field.
Identifying Source and Target Files
5–5
2. Drag the MyApp 1.0 (PPC) application from the Finder and drop it over the PPC
3. Drag the MyApp 1.0 (FAT) application from the Finder and drop it over the FAT
Before identifying the target files, make sure that your Updater VISE window looks like
the one pictured above.
Using a Standard File Dialog
If you do not have the Drag and Drop extension installed, or if you simply wish to use a
standard file dialog to locate and identify source files.
1. Select the 68K field in the Source Files column.
2. Double-click the field or click the Add File... button. A standard file dialog will be
displayed.
3. Locate and select MyApp 1.0 (68K).
4. Click Add.
5. Click Done. The file name will appear in the selected field of the Updater VISE
window.
To add the other files, follow the same steps, placing MyApp 1.0 (PPC) in the PPC Source
Files field and MyApp 1.0 (FAT) in the FAT Source Files field.
Before identifying the target, make sure that your Updater VISE window looks like Illustration 5-4: Update window after adding source files.
Identifying the Target Files Like source files, you may add target files to the Updater VISE window by using Drag and
Drop (if it’s available on your machine) or by using a standard file dialog box.
No matter which method you use, the Updater VISE window should look like the following after you complete this section:
Illustration 5-5: Update window after adding target files
Using Drag and Drop
To add files using Drag and Drop:
1. Drag the MyApp 1.1 (68K) application from the Finder and drop it over the 68K
Target Files field. The file name should appear in the field.
2. Drag the MyApp 1.1 (PPC) application from the Finder and drop it over the PPC
5–6
Identifying the Resource Exceptions
3. Drag the MyApp 1.1 (FAT) application from the Finder and drop it over the FAT
Before continuing, make sure that your Updater VISE window looks like the one pictured at the beginning of this section.
Using a Standard File Dialog
If you are using a standard file dialog to locate and identify target files:
1. Select the 68K field in the Target Files column.
2. Double-click the field or click the Add File... button. A standard file dialog will be
displayed.
3. Locate and select MyApp 1.1 (68K).
4. Click Select. The file name will appear in the selected field.
To add the other files, follow the same steps, placing MyApp 1.1 (PPC) in the PPC Target
Files field and MyApp 1.0 (FAT) in the FAT Target Files field.
Before continuing, make sure that your Update MyApp window looks like
Illustration 5-5 : Update window after adding target files on page 5-5.
Saving Your Changes
To save the changes that you have made so far, press Command-S or select Save from the
File menu.
Identifying the
Resource Exceptions
Updater applications created with Updater VISE identify files on the customer’s system
by comparing them to the source files that you included in the updater. If a resource in
the customer’s source file has been modified, Updater VISE will not update the file unless
that resource has been flagged as an acceptable modification.
For complete information about working with resource and data fork exceptions, see
“Identifying Resource and Data Fork Exceptions” on 23-7.
About the Resource
Exceptions List
Resource exceptions are identified in the Resource Exceptions lists in the Updater window. To display the Resource Exceptions lists, click the triangle to the left of Resource
Exceptions so that the lists are displayed and the Updater VISE window appears as below:
Illustration 5-6: Update window showing Resource Exceptions
Identifying the Resource Exceptions
5–7
The following is a brief explanation of the options available in the Resource Exceptions
lists.
■
Always Use New. If the updater finds a resource identified in this column in the
customer’s source file, the updater application will always use the target file’s
version of the resource when it creates the updated application on the customer’s system.
■
Always Keep Old. If the updater finds a resource identified in this column in the
customer’s source file, the updater application will always copy this resource
from the customer’s source file into the newly-updated application on the customer’s system.
■
Keep Old If Exist. If the customer has modified or added this resource to the
source file, the updater application will copy this resource from the customer’s
source file into the newly-updated application. If the resource has not been
added or modified, the updater application will use the corresponding resource
from the target file identified in the updater.
For your convenience, the Always Use New and Keep Old If Exists fields contain
several commonly-modified resources by default.
How Resources are Identified Resources are identified by their four-character name and their range of associated ID
numbers. For this tutorial, we will use the STR# resource, which contains registration
information for the MyApp applications. The STR# resource has the same starting and
ending ID number (128), so the entry in the Resource Exceptions list will be STR# 128
128.
For complete information about identifying resources, see “Identifying Resource and
Data Fork Exceptions” on 23-7.
Adding the Registration
Resource to the Exceptions
List
To add the STR# resource to the Optional Copy field in the Resource Exceptions list
1. Make sure that the Resource Exceptions list is displayed.
2. Click the mouse in the Keep Old If Exist list.
3. Press the Tab key to move through the existing entries until a new, blank row is
added at the bottom of the list.
4. In the first field of the new row (at the far left), type STR# to identify the name of
the registration resource.
5. Press Tab. The cursor will move to the middle of the row.
6. In the middle of the row, type 128 to identify the starting ID number of the
resource.
7. Press Tab. The cursor will move to the end of the row.
8. At the end of the row, type 128 to identify the ending ID number of the resource.
5–8
Modifying the Update Settings
The Resource Exceptions lists will now look something like this:
Illustration 5-7: Update window with Resource Exceptions
Saving Your Changes
To save the changes that you have made so far, press Command-S or select Save from the
File menu. When you close the Update MyApp window the update item will be displayed
in the Archive window.
Illustration 5-8: Update item saved in Archive window
Modifying the Update
Settings
For complete information about options available in Update Settings, see “Modifying
Update Settings” on 23-11.
5–9
To open Update Settings:
1. Select the update item in the Archive window and click the Get Info button to display the Get Info window for the update item.
Illustration 5-9: Update item Info window
2. To display the Update window, click on the Show Files button in the top right corner of the Update MyApp Info window.
- Or Option-double click on the update file in the Archive window to bypass the Get
Info window.
5–10
3. In the Update MyApp window, click the Settings button.
4. Settings for the updater can then be modified in the Update Settings window.
Illustration 5-11: Update Settings
Several options are available to customize the appearance and behavior of your updater
application. However, for the purpose of this tutorial, we will only perform the following
operations:
■
Set the updater so that the original source file on the customer’s drive is not
deleted after the update is complete.
■
Set the updater to ask the customer to name the newly-updated file, and pro-
5–11
vide an appropriate file name to use as a default.
Setting the File Options
(“Delete Original” and
“New File Name”)
■
Add the Sample Read Me file included in the Tutorial folder.
■
Modify the PowerPC Options so that an alert is installed in MyApp 1.1 (PPC) to
warn the customers if the application is mistakenly launched on a 68K machine.
For this tutorial, we will set the updater so that it doesn’t delete the original source file on
the customer’s system after updating it, and so that it asks the customer to enter a name
for the newly-updated file. For complete information on other available options, see
“Modifying Update Settings” on 23-11.
To modify Update Settings:
1. Next to Delete Original, make sure that Do Not Delete Original After Update is
selected from the popmenu. If another item is selected, hold down the mouse over
Delete Original and select Do Not Delete Original After Update from the popmenu.
2. Hold down the mouse over New File Name and select Use Default Name from the
popmenu. The Default Name field will become visible as the next item in the window.
3. In the Default Name field, type MyApp 1.1.
The File Options section of the Update Settings window should look like this:
Illustration 5-12: Update Settings File Options
Stand-alone Updater
Options
The Update Settings window’s Stand-alone Updater Options Only contains items which
will be in effect ONLY for updaters which are saved as stand-alone updater applications.
Illustration 5-13: Stand-alone Updater Options Only
When an updater is saved as an eSellerate Update file or included as an item in an
installer, the settings from this section of the Update Settings are disregarded.
5–12
Adding a Read Me File
The Read Me file that you identify in Update Settings will be displayed after the updater
application is launched. Your Read Me file should contain any information that your customer should know about the update that will be performed. For complete information
about the requirements of Read Me files, see “Adding a Read Me File” on 23-14.
For this tutorial, we will use the Sample Read Me file in the Tutorial folder.
To add the Sample Read Me file to the updater:
1. In the Stand-alone Updater Options Only section of the Update Settings window,
click Read Me... A standard file dialog will be displayed.
2. Locate and select the Sample Read Me file in the Tutorial folder.
3. Click Select. The pathname for the Sample Read Me file will be displayed in the
field to the right of the Read Me... button in the Update Settings window.
Adding a PowerPC Alert
To add a PowerPC alert to the PPC-only application:
1. At the Update Settings window, click PowerPC Options... The PowerPC Options
dialog box will be displayed.
2. Beneath “If Target File is PowerPC Format...”, select Install “PowerPC Only” Alert.
3. Click OK to return to the Update Settings window.
Leaving Update Settings and To leave Update Settings and return to the regular update window, click OK at the lower
right of the Update Settings window.
Saving Your Changes
To save your changes, press Command-S or select Save from the File menu.
Completing the Update
File
When you have identified the source and target files, identified resource exceptions, and
chosen update settings, the next step is to complete the update file by performing the
compare operation. Completing an update file makes it ready for use within an installer
but is not the same as building a stand-alone updater application. Installer VISE lets you
create an update file for use within an installer or for building as a stand-alone updater
application or eSellerate Update file. In any case, it’s necessary to complete the update file
by comparing the resources of the source and target files before you can create the standalone application.
To complete the update file:
1. Make sure that the update file is set up as described so far in this tutorial.
2. Click Compare. The Comparing Files... window will appear, displaying a series of
progress gauges as the updater is built.
As soon as the update file is built, the Test... button will become active.
Testing the Update File
Once you have completed an update file, you may test its functions from within Installer
VISE without creating a separate updater application. The Test... feature does not display
the same user interface as the stand-alone application would; instead, it simply prompts
you to select a file to update; performs the update; and creates a target file on your system
that you must name.
For complete information about what occurs when you test an update file, see “Testing
the Update File” on 23-18.
5–13
To test the sample updater:
1. Make sure that you have build the update file as described in the previous section.
(The Test Update... button should now be active.)
2. Click Test... The application will ask you to select a file to update.
Illustration 5-14: Test Update Select File to Update
3. Select MyApp1.0 (68K), MyApp 1.0 (PPC) or MyApp 1.0 (FAT), as desired. You
will be asked what to name the new application and where it should be saved
before the update begins.
Illustration 5-15: Test update file Save New File dialog
4. If the update was successful, a message like the one below will be displayed.
Illustration 5-16: Test update success dialog
5–14
The update file is now ready for use in the installer. For complete information on using
updater items within Installer VISE archives, see Chapter 24-Including Update Files in an
Installer.
At this point, the update file is identical to an update file created with Updater VISE 1.4.
If desired, the update file may be extracted from the archive and used with Updater
VISE 1.4.
Saving the Update File as a An updater built with Installer VISE can also be saved as a stand-alone updater application.
Stand-Alone Application
To save the update file as a stand-alone updater:
1. In the update item window, click the Save As… button.
Illustration 5-17: Save Stand-alone updater application
5–15
2. Name the application “Tutorial.updater.” (Note that the default File Type setting is
“Stand Alone Updater,” which is correct for our purposes.)
Illustration 5-18: Saving a stand-alone updater application
3. Click Save. A progress gauge will be displayed as the new application is created.
For complete information on this topic, including instructions on changing the updater’s
default language, See “Saving the Update File” on page 23-19.
5–16
Section 2
Building Installers
6–1
Chapter 6
Creating an Archive
About Archives
An archive is the building block of any installer you create. In an archive, you:
■
Identify all the files that are part of the installation set.
■
Set options for each file (if appropriate), such as where they should be installed.
■
Assign files to different installation packages.
■
Set general preferences for the way that files are displayed to you.
Creating and adding files to an archive is always the first step in building your installer.
The files you place in an archive will maintain their Finder appearance after they are
installed by the customer. For example, if the files are arranged in View by Icon, the customer who installs the files will see them set up in the same way that they were arranged
on the computer you used to create the archive.
Creating a New Archive
To create a new archive:
1. After launching Installer VISE, select New Archive…from the File menu.
Illustration 6-1: New Archive Menu Item
Section 2 Building an Installer
6–2
The Extended Add Dialog Box
2. After saving, a blank archive window similar to the one below will be displayed.
Illustration 6-2: Archive Window for new archive
3. Click the Add button at the upper left corner of the archive window. The
Extended Add dialog box will be displayed, allowing you to select files to include
in the archive.
The Extended Add
Dialog Box
When you begin adding files to an archive, a dialog box similar to the one following is
displayed.
Illustration 6-3: Standard Add Dialog
Installer VISE preferences are set to display the Standard Add Dialog Box by default. If
you wish to use the Extended Add Dialog Box, which has more features and options,
press the Option key on the keyboard while clicking the Add button in the archive window or change the setting in Preferences. (For information about changing preferences,
see “Modifying Archive Preferences” on 6-5.)
Chapter 6 Creating an Archive
Adding Files to the Archive
6–3
The Extended Add Dialog appears below. (In this example, several files have already been
selected). The list of files in the dialog box reflects the file and directory structure of your
hard drive.
Illustration 6-4: Extended Add Dialog Box
By default, items are displayed alphabetically by name. To find a file quickly, type the first
few letters of its name.
Displaying Items
To display the contents of a folder, click the triangle to the left of the folder. The contents
will be displayed beneath it.
To display the contents of another drive, hold down the mouse over the name of the current drive (at the top right corner of the window) and select the desired volume from the
pop-up menu.
Selecting Items
Files and folders are added to the archive by selecting them. To select an item, click in the
box to the left of its name, or anywhere on the line where its name appears. When an
item has been selected, an “x” is displayed in the check box and the name of the item
appears in boldface type.
To deselect an item, click the line where its name appears or click the check box to
remove the “x” and the boldface type.
Shortcuts
For complete information about shortcuts for navigation and file selection, see
“Extended Add Dialog Keyboard Shortcuts” on 40-2.
Adding Files to the
Archive
To add files to the archive:
1. Click the mouse on the line containing the name of the file you wish to select. If
you select a folder, the entire contents of the folder will be selected. You may select
as many files as you wish. If you wish to deselect a file, click its name again.
2. When you’ve selected all the files you wish to add to the archive, click Add.
3. If there are no more files to add to the archive, click Done. The Add dialog box will
be removed and the archive window will be displayed, containing the files that you
selected.
You may drag files directly from the Finder into the archive if you have Drag and Drop
installed.
6–4
Creating an Installation Folder
If you’re making last-minute changes to an existing archive and are adding or replacing
only a few files, you might wish to use the Bring Up To Date feature. For a complete discussion of Bring Up To Date, see Chapter 20-Maintaining Archives.
Creating an
Installation Folder
Sometimes the items in your archive are from several different locations on your computer and on your local network, so there isn’t a single folder at the root of the archive
containing all of the files. Installer VISE can create an “installation folder” that will be
created on the customer’s system and store all the materials that get installed.
To create an “installation folder”:
1. Select Installer Settings... from the Archive menu, and click on the Behavior tab.
2. Click on the Create Installation Folder Named checkbox.
3. Type in the name of the folder you wish to have created during the install.
Illustration 6-5: Create Installation Folder
When the installer is run, all the items that are installed will be placed in a folder
with the same name that you entered.
Catalog Only
Special Information for CD-ROM Installers
If desired, you may set up your archive so that only a catalog of files is stored in the
archive. This saves the time of compressing the files into the archive and decompressing
them for the installer. However, this feature requires that you select Only Store Catalog
of Files in Advanced Settings before you save your archive.
For information on using this feature, ”see “Only Store Catalog of Files” on 14-25.
Saving an Archive
After adding the files you wish to include in your installation to the archive, you should
save the archive.
To save the archive:
1. From the File menu, select Save.
2. Installer VISE will compress the files into an archive, which may take a few
moments, depending on the size of the archive and the speed of your computer.
Changing File Names
in the Archive
If desired, you may change the names of files and folders within the archive. Although
this will not affect the source files that you used to create the archive, any installation of
those files from the archive will contain the new name.
Changing file name in the archive is similar to changing it at the Finder.
Removing Files from the Archive
6–5
To change the name of a file:
1. At the archive window, click the name of the file you wish to change. An editing
box will appear around the file’s name, and the name will be highlighted.
2. Change the name as desired.
3. Save the modified archive.
Removing Files from
the Archive
To remove a file from the archive:
1. Select the file or files you wish to delete.
2. Click the Delete button in the archive window. The file will be deleted. (If you
wish to be warned before a file is deleted from the archive, change the “Confirm
Before Deleting Files” preference setting as described below.)
3. Save the modified archive.
Modifying Archive
Preferences
To change preferences:
1. In the Edit menu, select Preferences...
Illustration 6-6: Archive Preferences
2. Change preferences as desired.
3. Click OK.
Changes to the preferences file affect the application, not just the archive
that you’re creating. Any changes that you make to the Preferences will
remain in effect for this archive and any other archives that you work with
unless you change the Preferences file again.
6–6
Verifying and Updating an Archive
You can change many features of how archives are handled by changing Installer VISE’s
preferences.
Item
Purpose when selected
Default
Display Invisible Files
in Add Dialog Box
Invisible files (such as the Icon file in a
folder) are listed in Add dialog box.
Selected
Archive Original
Instead of Alias
Allows you to archive original file even
when you select the file's alias.
Not Selected
Use Extended Add
File Dialog Box
Allows more options when selecting files
for an archive
Not Selected
Confirm Before
Deleting Files
Prompts you to confirm whether files
should be deleted
Selected
Confirm before
Saving Get Info or
Action Item Changes
When changes are made to a file’s or action
item’s options in the item’s Info window,
confirms changes before saving.
Selected
Check for Duplicate
Names when Adding
New Files
Alerts you that two files of the same name
are in a sub-directory. If selected, allows
you to replace the file or skip replacing if
desired. If not selected, you may add as
many files of the same name as you wish.
NOTE: This feature is only functional if
you add files at the Extended or regular
Add File dialog; Check for Duplicate does
not apply to files added using Drag and
Drop.
Selected
Table 6-1: Archive Preferences
Verifying and
Updating an Archive
The verify command performs a number of checks including one which makes sure the
compressed files in an archive are valid and have not become corrupt. (This feature is
useful when recovering archives after a system or a hard drive crash.)
The steps below describe a simple verification and update procedure. If you are updating
an archive to include new or changed files, see Chapter 20-Maintaining Archives.
Verifying the Archive
To verify an archive, select Verify Archive from the Extras menu. If you receive an error
message, you should bring the archive up to date.
Bringing the Archive UpTo-Date
To update all files in an archive:
1. From the Archive menu, select Bring Up To Date. An Update window will be displayed.
2. Locate and select the source folder for the archive.
3. Select all items that should be part of the archive.
4. Click Update.
The archive will be recreated from the original files, and retain the settings for the files
from your original archive.
6–7
If you moved the positions of the icons at the Finder level for the files in the source
folder, you can update that information quickly using the Bring Up To Date feature. If
the only thing that’s changed for an item is the position of its icon, its checkbox will not
be selected, though its status will be <FInfo Changed>.
6–8
7–1
Chapter 7
Creating Packages And Assigning Files
About Packages
Packages are groups of files to be installed together that you specify when you create an
installer. The customer who installs the program chooses from the list of package names
to customize the installation process.
For example, you might create an Application package, a Demo package, and an Additional Tools package. When customers run your installer, they can use the Easy Install
option to install all the materials, or they can use the Custom Install option to install only
the packages that meet their needs. (If no additional package names are entered, the Custom Install option will not be available.)
Every archive created with Installer VISE contains one package by default: the Easy Install
Package, which normally contains every item in the archive. The Easy Install Package will
be installed if the customer chooses the Easy Install option when the installer is run. (If
desired, you may disable the Easy Install option so that customers must choose which
packages to install.)
When you create packages, you can:
■
Add informational text to each package or sub-package to aid the customer
choosing what to install.
■
Determine which version of a Fat binary application will be installed, depending on the processor of the target system.
■
Create “sub-archive packages,” which lets you create an installer where the customer can choose to install an additional product from a separate Installer VISE
installation diskette, which they might or might not possess.
■
Create “sub-packages,” which are packages that are components of a larger
package (also known as hierarchical packages). If customers chose to install a
package that contains sub-packages, they may select any of the sub-packages
associated with it.
■
Create “list packages,” which contain several files from which the customer may
choose as many individual files as desired.
■
Assign a custom icon to each package.
7–2
About Sub-Archive Packages
■
Create mutually exclusive groups of packages, in which the customer may only
install one of the packages in the group.
■
Assign Gestalts to packages to determine whether or not they are displayed to
the customer as part of the installation.
■
Specify which packages are available for install after a successful online transaction. This option applies when you build your installer to integrate with the
eSellerate e-commerce system (an optional service).
Installer VISE allows you to create up to a total of 255 packages of any kind. The total
includes the Easy Install package as well as any other packages, including sub-archive
packages, sub-packages, and list packages that you create.
An archive report can list any package that you create which does not have files assigned
to it. This information will also be displayed if you start to build an installer in which
you’ve defined packages that don’t contain any files.
About Sub-Archive
Packages
You may wish to create an installer that gives your customer the option to install a product that is not necessarily part of the regular install set. For example, a company which
sells a small utility package in addition to a large application package might wish to let a
customer install the utility software as well as the regular application from within the
regular application’s installer.
Installer VISE lets you create an installer that asks for the install disks for another product. If the install disks for the second product are not available, the customer may choose
to skip the installation of the second product and continue with the installation of the
first product.
About Sub-Packages
In addition to creating packages, you may also create sub-packages. Sub-packages are
packages that are a part of another package. If the customer chooses to install a package
that contains sub-packages, he may also choose which of the associated sub-packages
should also be installed.
For example, if your product includes different sets of sample files, you can set up your
installer to include a single package called “Samples,” from which the customer can
choose the desired samples (such as “Word Processing Samples,” “Spreadsheet Samples,”
or “Database Samples.”)
Illustration 7-1: Sub-packages displayed in Package List
Chapter 7 Creating Packages And Assigning Files
Package Dependencies
7–3
If the customer chooses Custom Install, the Samples package will be displayed with an
expandable arrow, indicating a set of sub-packages from which you can choose. The following illustration shows an installer in which the customer has displayed the sub-package contents of the “Samples” package:
Illustration 7-2: Installer with sub-packages displayed
Package dependencies can be used to tie packages together so that when one package is
selected another is automatically selected or when one package is deselected another
package is automatically deselected.
To set up package dependencies:
1. From the Archive menu select Packages… The Package List will be displayed. The
Dependencies button is not enabled until more than one package is defined.
Illustration 7-3: Package List
7–4
2. Define the packages for your installer.
3. When you have defined all packages you are now ready to assign dependencies.
Click the Dependencies… button in the Package List window.
Illustration 7-4: Package List Dependencies button
4. In the Package Dependencies dialog select from the Package popmenu the package upon which other packages will be dependent.
The Package popmenu at the top of the Package Dependencies dialog displays the
current package for which dependencies will be set. It is automatically set to the
package you have selected in the Package List dialog, but you can change it to
other packages at any time. The current package is disabled in the lists since you
cannot set dependencies for itself.
In the example below, we have an application which has on-line help available in
7–5
two formats, pdf and html. First, we will set dependencies for the Help.pdf package.
Illustration 7-5: Package Selection in Package Dependencies
The list on the left contains the packages that you wish to turn on/off when the
current package is turned ON. The list on the right contains packages that you
wish to turn on/off when the current package is turned OFF.
The Clear button clears all dependencies for the current package.
The Clear All button clears all dependencies for every package.
In the installer, these dependencies come into effect in the Custom Install window
when the user clicks on and off packages. Simple logic is used when turning on
and off dependent packages so that packages will follow normal default behavior.
If you turn on a dependent package that is a parent hierarchical package, it will
automatically turn on all of its child packages. If you try to turn on multiple
mutually-exclusive packages, only the last one will be turned on.
When a user clicks on a sub-package to turn it on, it will automatically
turn on all its dependent packages. However, if instead the user clicks on a
package which automatically turns on this same sub-package, the dependencies of the sub-package will not be in effect.
Package Dependencies are ignored when using the Select and Deselect
AppleScript commands to check and uncheck package checkboxes in a
built installer. For more information on the Select and Deselect AppleScript commands, see Chapter 31-Controlling an Installer with AppleScript.
7–6
5. Based upon the settings we have made in the example below, when the Help.pdf
package is selected at installer runtime the Help Reader for pdf will automatically
be checked on and the html help components will automatically be checked off.
Illustration 7-6: Setup for Help.pdf package
6. When dependencies for one package have been completed, select a different package from the Package popmenu to set up dependencies for that package. In our
example, we have switched the Packages popmenu to the Help.html package.
Based upon the settings we have made in the example below, when the Help.html
package is selected at installer runtime, the Help Reader for html will automatically be checked on and the pdf help components will automatically be checked
off.
Illustration 7-7: Setup for Help.html
List Packages
List Packages
7–7
If you wish to allow customers to choose among several different files to install, you may
create a list package, which presents the files as a list from which any or all of the files may
be selected.
For example, if your installation includes a large set of items, such as several PostScript
Printer Define files, it’s likely that customers will only want to install the files that are relevant to their needs. By placing those files in a list package, customers may select which
of the files they wish to install.
You may add custom header, footer and help text to assist the customer in making a decision. The list from which the customer selects will appear like this:
Illustration 7-8: Installer with list packages displayed
You can also attach a PICT containing help information about the list package.
Creating a Package
To create a package:
1. From the Archive menu, select Packages... The Packages List window will be displayed.
2. Click the New Package button. The Edit Package dialog box will be displayed.
3. Enter information in the appropriate fields. For more information about the
kinds of information you an enter in the Edit Package dialog box, see the following section, “Edit Package options” on page 7-8.
4. Click OK to return to the list of packages.
7–8
Edit Package options
Creating a Package
The following is a sample Edit Package dialog box:
Illustration 7-9: Edit Package dialog box
The following items are available from within the Edit Package dialog:
Name
Description
Name
The name of the package that will be visible to the customer.
Package names may have up to 63 characters.
Description
A text description of the package that will be visible to the
customer after clicking the Information button. The
Description field can contain up to 255 characters. If you do
not enter text in this field, the default text “This option installs
the <Package Name> package” will be displayed, with the name
of the package in the blank.
Size (Bytes)
Only available when Sub Archive Package checkbox is checked.
Used to calculate disk space requirements for the install when
using sub archive packages.
Separator
Used to create a separator line that you can move around in the
packages list to create a visual barrier between packages. If you
create a package as a separator, no other information can be
entered in the window for that package.
Table 7-1: Edit Package Options (Sheet 1 of 3)
Creating a Package
7–9
Name
Description
Mutual Exclusive
Group
Selecting Separator enables the Mutual Exclusive Group option.
Selecting Mutual Exclusive Group for a separator means that
only one of the packages that appears between the separator
lines may be installed. For more information, see “Creating
Package Separators and Mutual Exclusive Groups” on 7-10.
Version
The version number that you assign to your software. The
Version field can contain up to 9 characters.
If you enter the unique ID of a file in the archive, at installer
runtime the version field will be filled with the version of the
file designated by #uniqueID#. The unique ID of a file is
available in its Get Info window. When entering a unique ID it
must be entered as #uniqueID#.
Icon ID
The resource ID number of icon.
User Flag
Special field available to developers for identifying a package
through external code.
Sub-Archive
Package
Creates a package which asks the customer to insert the installer
diskette for another product. (For more information about
sub-archive packages, see “Creating a Sub-Archive Package”
on 7-11.)
List Package
Creates a package whose contents will be displayed to the
customer in the form of a list. The customer may select any or
all of the items in a list package. (For more information about
list packages, see “Creating a List Package” on 7-13.)
Show in Install
Menu
The package name will be one of the options available in the
popmenu at the upper left of the Install window. If a package is
set to show in install menu, it will not be listed for Custom
Install.
Restart after
Installing
Forces the customer to quit all open applications before
beginning the installation, and allows the customer to restart
the computer after installing the package.
Default Package
On
When checked, the package will be selected by default when
shown in the Custom Install list. The user can override the
default.
List Header and
List Footer
These fields let you enter explanatory text that appears above
and below the list of files in a List Package.
Gestalt
Adds a gestalt call to the package. If the conditions of the gestalt
are met on the customer’s system, then the package will be
available for installation; if the conditions of the gestalt are not
met, the package can not be installed by the customer.
7–10
Creating a Package
Name
Description
Build Directives
Allows Build Directives to be assigned to packages. When the
installer is built, packages which do not meet the build
directives are not included in the installer. (For more
information about package build directives, see “Package Build
Directives” on 7-18.)
Package Type
The Package Type popmenu allows you to specify packages
specific to a type of processor. For more information, see
“Setting the Package Type” on 7-23.
Purchase
This setting works in conjunction with the optional eSellerate
e-commerce system. The Purchase popmenu allows you to
specify whether the package should be shown or hidden as the
result of an online purchase. If you are not using eSellerate with
this package, the default setting, Has No Effect, is correct. For
more information on eSellerate and the Purchase popmenu,
see“eSeller tab” on page 27-19.
Choose Icon...
Allows you to assign a custom icon to the package. This icon is
visible to the customer after clicking the Information button for
that package. The Icon ID field contains the resource ID of the
icon. If you choose not to assign a custom icon, then the
package will display Installer VISE’s default icon for packages.
For more information on adding a custom icon to a package,
see “Adding an Icon to a Package” on 7-23.
Creating Package
Separators and Mutual
Exclusive Groups
Separators are used to create a visual barrier between sets of packages in the list. A mutually exclusive group separator means that the customer will only be able to install a single
package from the selection of packages that appears between the separator lines. (Information about arranging the order and location of packages can be found later in this section, in “Rearranging the List of Packages.”)
For example, to ensure that the customer can install the desired version of a Fat Binary
application, create a package for each format as described later in this section. Then,
place the packages in a mutually exclusive group. Customer who choose Custom Install
can then choose which version of the application they wish to install.
To create a separator:
1. Create a new package.
2. Place a check in the box next to Separator.
3. If you wish to create a mutually exclusive separator, click Mutual Exclusive
Group.
You don’t need to enter any more information in the Edit Package window, as any
text you enter will be discarded.
4. Click OK.
Restarting After
Installation
If you want the customer to have the option to restart the computer after the installation
of this package, select Restart After Installing. This also forces all running applications to
be quit before the installation begins (after the customer clicks the Install button).
Creating a Package
7–11
In conjunction with other factors, the selection of this item for a package determines
whether a restart will be suggested or forced after the installation of the package. (Other
factors include the installation options of files, and the options chosen at the Installer
Settings window.)
After-Install Restarts
The following conditions determine whether a restart should occur at the end of the
installation process.
■
The Restart After Installing item in the Edit Package window has been selected,
and that package is being installed by the user; or
■
The Restart After Installing item in the Get Info window has been selected, and
that file or folder is being installed by the user; or
■
An active, non-deletable file such as QuickTime is being replaced; or
■
Resources are being written into the active System file.
This chart displays the circumstances where meeting one of the above conditions will
suggest or force a restart
Force Restart Where Appropriate is selected in
Installer Settings/Behavior Tab
Then restart is...
Not Selected
Suggested
Selected
Forced
Table 7-2: After-Install Restarts
Creating a Sub-Archive
Package
To successfully create a sub-archive package in an installer, you must:
■
Create a separate installer for the additional product using Installer VISE.
■
Choose a name for the diskette on which the additional product will be
shipped.
■
Create a sub-archive package in the regular installer that calls for the diskette
containing the additional product by name.
To add a sub-archive package to the installer you are currently building:
1. After you have identified the name of the diskette for the additional product, create a new package and select Sub-archive package.
2. In the Description field, type Disk=diskname, where diskname is the exact name
of the diskette containing the other installer.
When setting up a sub-archive installer, you can specify not only a disk, but
a path on the disk as well as an installer name. For example you can enter
“Disk=Disk1:Folder A:Segment.1”. This enable you to have different localized sub-installers in a folder but from the package specify a different subinstaller based on the language or region.
3. Press Return. (It’s crucial that a carriage return appear after the name of the diskette.)
4. If you wish to enter additional descriptive text for the package, you may type it on
the lines beneath the diskname identifier.
7–12
Creating a Package
5. If you want the size of the files installed by the sub-archive package to appear in
the installer, enter the size of the package (in bytes) in the Size (Bytes) field.
(Because the package isn’t part of the archive, Installer VISE can’t determine how
large the files are.)
For example, to create a sub-archive package for a diskette titled “Utilities Installer Disk,”
the Edit Package window would look like the following illustration (notice that the
descriptive text appears beneath the diskname identifier, because of the required carriage
return).
Illustration 7-10: Setup for Sub Archive Package
Creating a Sub-Package
Sub-packages are complete packages of files which are part of another package.
To create a sub-package:
1. Create the package as described in the rest of the section.
2. Close the Edit Package window and save changes.
3. In the Package List window, arrange the packages vertically such that the package
which is going to become a sub-package is below the parent package.
Creating a Package
7–13
4. Select the name of the package you wish to designate as a sub-package and click
the right arrow below the package list.
Illustration 7-11: Creating a sub-package
The sub-package that you created will appear indented.
A sub-package is associated with the first regular package above it in the
Packages window. To change the package that a sub-package is associated
with, rearrange the items in the Packages window. For information about
rearranging packages, see “Rearranging the List of Packages” on 7-24.
Creating a List Package
List packages are packages from which the customer may select individual files for installation. The list displays all files that are associated with that package, allowing the customer to select the individual files they wish to install.
To create a list package:
1. Create the package as described in the rest of the section.
7–14
Creating a Package
2. Select List Package.
Illustration 7-12: Setting up a package as a list package
Attaching Header and Footer You may enter text that will appear above and below the list of items from which the customer can choose. You are limited to 255 characters in each field.
Text
To enter list header and footer text:
1. In the List Header field, enter the text that you wish to appear above the list.
2. In the List Footer field, enter the text that you wish to appear below the list.
When your customer clicks the Install button in your installer, a List dialog
appears. The text you entered in the Header and Footer fields is displayed as in the
example below:
Illustration 7-13: List package with header and footer text
Creating a Package
7–15
You may wish to attach header and footer text or the Help PICT feature to
the list of items (described below) to inform your customers that they can
select discontinuous items by holding down the Command key on the keyboard while clicking the mouse.
Assigning a Help PICT to a
List Package
If you wish to provide your customers with more information than you can place in the
List Header and List Footer, you may attach a PICT containing additional information
for the package. If the customer clicks the Help button at the dialog box for the list package, the PICT will be displayed.
To attach a Help PICT to a list package:
1. At the application used to create the Help PICT, copy the Help PICT to the Clipboard.
2. Click List Help. The Edit List Package Help window will be displayed.
3. In the Edit List Package Help window, select Black and White if the picture is 1bit, or Color if the picture is 8-bit.
4. Press Command-V to paste the screen into the window. Although the image
appears scaled within the dialog box, it will appear correctly to the customer.
To remove a Help PICT, click Remove or paste a new screen into the window.
Assigning a Gestalt to the
Package
You may assign a gestalt call to a package. If the conditions of the gestalt are met on the
customer’s system, then the package will be displayed as part of the software being
installed in the Easy Install window, and that package will be available for the customer
to choose on the Custom Install window.
For example, if you have a package containing PowerPC extensions, you can assign the
PowerPC Architecture gestalt to the package. If the customer is using a PowerPC, then
the package will be part of the regular installation. If the customer is not using a PowerPC, the package will not be part of the Easy Install and will not be visible in Custom
Install.
Assigning a gestalt call to a package in this way will only determine
whether the package is visible in the Easy Install list of packages and the
Custom Install list of packages. To ensure that individual files are only
installed under certain circumstances, you must also either a) attach
gestalts to each file or b) ensure that each package containing the files has a gestalt
attached to it.
To assign a gestalt to the package, hold down the mouse over the Gestalt popmenu and
select the desired gestalt(s) from the list.
7–16
Language and Region
Gestalts for Packages
Creating a Package
Installer VISE has built in gestalt selectors which enable packages to be displayed only for
specific Languages or Regions.
To create a Language or Region Gestalt for Packages:
1. Select Gestalts… from the Archive menu.
Illustration 7-14: Gestalts menu item
2. Click the New button in the Gestalt List.
Illustration 7-15: Gestalt List
Creating a Package
7–17
3. In the Edit Gestalt dialog enter a name, selector and value for this new gestalt
check.
Illustration 7-16: Edit Gestalt
Option
Description
Selector
Region = InRg
Language = InLg
Value
For Region values, see “Region Codes for Installer VISE” on
page 29-27.
For Language Codes, see “Language Codes for Installer
VISE” on page 29-26.
Table 7-3: Special Setup for Region and Language Gestalts
7–18
Creating a Package
4. In the Edit Package window of a package which should only be available in a specific region (in this case, Germany), select the newly created gestalt from the
Gestalt popmenu.
Illustration 7-17: Selecting a Package Gestalt
When the installer is executed on a user’s machine, if the gestalt check for Germany returns false, this package will not be available for install. The installer
determines which language and region the user is in by accessing information
provided by the operating system that the user is running.
Package Build Directives
Package Build Directives enable the exclusion or inclusion of packages in an installer at
installer built time. When the installer is built, packages which do not meet the build
directives are not included in the installer.
For more information on setting up build directives, see “Build Directives” on page 27-1.
Creating a Package
7–19
To assign a build directive to a package:
1. Set up Build Directives by selecting Build Directives… from the Archive menu.
Illustration 7-18: Build Directives menu item
2. In the Build Directives dialog, enter your build directive names and check one or
more as the active build directive(s).
Illustration 7-19: Build Directives setup
3. Click OK to close the Build Directive dialog.
7–20
Creating a Package
4. From the Archive menu select Packages…
Illustration 7-20: Packages menu item
5. From the Package List, define the packages that will be in all installer builds from
this VCT.
6. To limit the inclusion of a package to specific installer build, select the package in
the Package List, and click the Edit button.
Illustration 7-21: Package List with Package Selected for Edit
Creating a Package
7–21
7. Assign this package to one or more build directives by selecting items from the
Build Directives popmenu.
Illustration 7-22: Selecting Build Directive for a Package
8. In the Archive window, if packages are being displayed in the current layout, the
package titles are grayed if they do not match the build directives.
Illustration 7-23: Archive Window with Disabled Packages
7–22
Package Build Directive
Guidelines
Creating a Package
Build Directives serve as limiting agents for packages. If no build directives are checked,
the inclusion of the package in an installer build will not be limited. Another way to say
the same thing would be that if no items are checked in the Build Directive popmenu,
this package will always be included when an installer is built.
Illustration 7-24: Setting Build Directives
The Build Directives popmenu will display any build directive that has been set up in the
Build Directive window as well as the Any Match item.
If only one build directive item is checked, as in the example below, this package will be
included in the built installer only when that build directive is in effect.
Checking multiple items in the Build Directive popmenu will result in an AND condition. In the example below, this package will be included in the installer when the Debug
Build AND the English Release build directives are in effect.
The Any Match item causes an OR condition to be in effect for any other checked items.
In the example below, this package will be included in the installer when Debug Build
OR English Release is in effect.
If Any Match is the only item checked in the Build Directive popmenu, this package will
never be included when an installer is built.
If no items are checked in the Build Directive popmenu, this package will always be
included when an installer is built.
Files must have build directives set also if you do not wish to have them
included in the an installer. Because a package is not included in an
installer does not mean that any associated files are not included also.
Hierarchical sub-packages and package build directives - If a parent
package does not meet the build directives then any of its children packages will also be disabled, regardless of their build directive setting.
Creating a Package
Setting the Package Type
7–23
Installer VISE lets you set up packages that install the 68K, PowerPC or fat binary version
of fat binary applications placed in the package.
The Package Type popmenu contains the following options:
Install Option
Install Effect
Use Files’ Settings
Installs fat applications as designated in the file options
for that application. (For more information, see “Setting
Fat Binary Install Options” on page 12-16.
68K Architecture
Installs the 68K version of fat applications in the
package.
PowerPC Architecture
Installs the PowerPC version of fat applications in the
package.
Both 68k and PowerPC
Installs the fat version of the fat applications in the
package
Table 7-4: Package Type 68K, PowerPC and Fat Options
The default for this item is Use Files’ Settings.
To change the package type, hold down the mouse over the Package Type popmenu and
select the desired setting.
To ensure that the customer is able to install the desired version of a Fat
Binary application, create a package for each format using this feature, and
make the packages mutually exclusive. (For information about creating
mutually exclusive packages, see “Creating Package Separators and Mutual
Exclusive Groups” on 7-10.)
Adding an Icon to a
Package
Packages which do not have custom icons assigned to them will be listed in a diagnostic
report (for more information, see Chapter 16-Generating Archive Reports); if you
choose not to assign a custom icon, then the package will display Installer VISE’s default
icon for packages. Icons attached to packages are visible when the installing customer
clicks the Information button for the package in the installer. You may add both a 1-bit
and an 8-bit icon to the package, as the icons use different resource types.
You can add an icon in three ways: by locating the item at the Finder from within
Installer VISE using the Choose Icon... button; by copying and pasting the icon from a
file’s Get Info window at the Finder; or by copying the icon for an item in the archive
from that item’s Get Info window in Installer VISE.
To locate an icon at the Finder from within Installer VISE:
1. Click Choose Icon...
If you have just created the archive, a window containing the icons for all the files
in the archive will be displayed. If you have closed and reopened the archive, the
icons for the files in the archive will no longer be visible.
2. If the icon you wish to assign to the package is displayed, click the icon.
If no icons are displayed, or if you wish to assign an icon which is not assigned to
an application in the package, click Add File... to display a standard file dialog box,
and locate the application with the desired icon.
7–24
Rearranging the List of Packages
3. If you want the archive to temporarily remember the location of an icon so that it
is visible if you return after closing the archive, select the file in the dialog box and
click Remember File. (To toggle this option on and off, click the button again or
press Command-R.) This information will be lost when you quit Installer VISE.
To see which icons are in the file that is selected at the bottom of the screen, press
the Option key. The icons that are part of the selected file will display a gray border.
4. Click OK. You will return to the Edit Package window, and the icon you selected
will be displayed at the bottom left of the screen. If you selected a 1-bit icon, only
the box on the left will be filled. If you selected an 8-bit icon, the box on the right
will be filled.
To paste an icon from a file’s Get Info window at the Finder:
1. At the Finder, copy the desired icon from the Get Info window for the application.
2. At the Edit Package window, press Command-V. The icon will be pasted into the
correct location.
To paste an icon from an item’s Get Info window within Installer VISE:
1. At the archive window, select the file whose icon you wish to use.
2. Click Get Info.
3. In the item’s Info window, click on the icon.
4. Press Command-C to copy the icon.
5. Return to the Edit Package window for the package you’re editing, and press
Command-V to paste the icon.
Rearranging the List of
Packages
Packages will be displayed in the Packages window in the order in which you created
them.
To reorder the list of packages:
1. Hold down the mouse button on the package or on the separator. The pointer will
turn into a hand as soon as you move the cursor with the mouse button held
down.
2. With the mouse button held down, drag the package or separator to the desired
location.
3. Release the mouse. The package or separator line will remain in the location
where you dropped it.
Sub-packages, which appear indented, will be associated with the first regular package
that appears above them. In the following illustration, the sub-packages “Database Sam-
Deleting a Package
7–25
ples,” “Spreadsheet Samples,” and “Word Processing Samples” are associated with the
regular package “Samples.”
Illustration 7-25: Package List Window
When the customer runs the installer, those sub-packages will be displayed in that order
beneath the Samples package. However, you must assign files that are part of sub-packages to both the parent package and appropriate sub-package to be installed correctly;
changes that you make in this window only affect the appearance and behavior of the
Custom Install window, not the installer in general.
Deleting a Package
The Easy Install package can not be deleted from the list.
To delete any other package:
1. At the Packages window, select the name of the package.
2. Click Delete.
Assigning Items to
Packages
You may assign items in the archive to as many packages as you wish. Packages which
have no files assigned to them will be identified by archive reports. Files may be assigned
to packages in three ways:
■
Through a Packages popmenu in the archive window detail
■
By selecting the desired packages in the packages column of the archive window
■
Through the Packages popmenu in the item’s Get Info window
If you’ve created sub-packages, you must assign items to the appropriate
sub-package and to the parent package. For example, if your installer
includes a parent package called “Samples” and sub-packages called
“Database samples” and “Spreadsheet samples,” you must assign the
desired contents of the “Database samples” and “Spreadsheet Samples” packages both
to the appropriate sub-package and to the Samples package.
7–26
Assigning Items in the
Packages popmenu
Assigning Items to Packages
To assign items to packages using the Packages popmenu:
1. In the archive window, select the item you wish to assign to a package.
2. Hold down the mouse over the Packages popmenu in the archive window detail
area. A list of the packages you created will be displayed.
3. Select the package to which you wish to assign the item.
If you wish to assign the item to more than one package, highlight the name
of the desired package in the list and press the Space bar. A check will be displayed next to the name of the package, and the popmenu will remain displayed so you can select more packages. You can then drag the mouse to the
next package you wish to assign, and use the same procedure to select the package.
Removing Items From
Packages
To remove an file or folder from a package, follow the steps as described above. When
you select a package that has a check next to it, the check will be removed and the file will
no longer be part of that package.
As in the preceding section, you can toggle between selecting and deselecting
a package without releasing the mouse by highlighting the name of the package in the popmenu and pressing the Space bar.
Creating New Packages on
the Fly
To create a new package on the fly, select New Package... from the Packages popmenu.
The Packages window will be displayed, and you may create a new package as described
in the preceding section.
Assigning Items to
Packages in the Archive
Window
If you are using the Standard archive window layout (or any layout which has packages in
the column area) you can expand the archive window so that the names of the packages
to which the items are assigned is displayed right.
Illustration 7-26: Archive window displaying package assignments
7–27
To see more or less of the package names, drag the double-line that separates the headings from the items in the archive up or down.
To assign an item to a package in the archive window:
1. Place the mouse on the same line as the file or folder you wish to assign to a package.
2. Move the mouse to the column for the desired package. As a visual aid, the name
of the package will be highlighted when the mouse is in its column.
3. When the name of the desired package is highlighted, click the mouse. An X will
appear in the column for the package.
7–28
8–1
Chapter 8
Creating Action Items
What Are
Action Items?
Action items are objects you create within an archive that perform common functions
for which you might otherwise have to write external code. Action items allow you to do
the following:
■
Delete items on the customer’s system.
■
Copy items on the customer’s system to a new location.
■
Move items on the customer’s system to a new location.
■
Rename items on the customer’s system.
■
Find items on the customer’s system. You may use the result of the action item
to move existing files or install new files to the location where the item you
looked for was found.
■
Create aliases of items in the archive and place them in a specific location on the
customer’s system.
■
Display message dialogs that can conditionally install, delete, or rename files
based on a user's response.
■
Display forms that can query the user for information and set runtime variables
based on the user’s response.
■
Set and Test runtime variables.
■
Move backward or forward in the install sequence, so the installer can execute
an install item one or more times, or bypass it entirely.
■
Conditionally stop the installation.
■
Sub-launch applications or other Installer VISE installers.
■
Launch the default web browser on the customer’s system and open a specified
URL.
■
Edit text files on the customer’s system. These edits can include adding, deleting
and replacing text.
8–2
■
Execute UNIX shell scripts to perform various actions on the user’s system.
You may set up the action items to be performed on installations and/or on removals.
Additionally, you may set them up so that if the action item fails, the installation or
removal is canceled. (The exception to these conditions is the Comment action item,
whose sole function is to note logic in the installer archive.)
Basic Steps
The basic steps for working with action items are:
1. Create the Action item.
2. Name the Action item.
3. Set options for the Action item, such as whether the action takes place as a result
of a Gestalt check.
4. Close and Save the Action item.
5. Assign the Action item to packages.
Creating an Action
Item
To create an action item:
1. At the top right of the archive window, select an action item from the Action Item
popmenu. Or, select an action item from the Archive menu.
Illustration 8-1: Action Item popmenu
Chapter 8 Creating Action Items
8–3
2. The Action Item window will be displayed. For illustration purposes we have chosen an Alias Action item.
Illustration 8-2: Example Action Item Window
Action items are divided into four sections:
■
Name and general information
■
<Action> If
■
What to <Action>
■
<Action> Options
8–4
Entering General
Information
For each action item created you will need to enter an action item name and general
information about when the action item should be performed and whether installations
and removals should be halted if the item fails.
Illustration 8-3: Action Item General Information Area
To enter action item general information:
1. Enter a name for the action item.
2. If you want the action item to be performed during an installation, select Perform
on Installs. By default, this item is selected.
3. If you want the action item to be performed during a removal, select Perform on
Uninstall. By default, this item is not selected.
4. If you want the installer’s action to stop if the selected action fails, select Stop
Install if <Action> Fails, where <Action> is the kind of action that you identified.
By default, this item is not selected.
When executed, a Stop Install if <Action> Fails will stop the installation
and delete any files installed up to that point. However, it will not undo
any other changes made by the installer, such as items deleted, copied,
moved or renamed, aliases created and text files edited.
Entering <Action> If
Information
Settings in this area let you determine the circumstances under which the action item
will be executed.
To enter <Action If> Options:
Assigning Build Directives to
Action Items
1. If you have opted to use the Advanced Project Management feature Build Directives and you want to limit the inclusion of the action item to specific installer
builds, hold down the mouse over the Build Directives popmenu.
Build Directives serve as limiting agents for action items. If no build directives are
checked, the inclusion of the action item in an installer build will not be limited.
Another way to say the same thing would be that if no items are checked in the
Build Directive popmenu, this action item will always be included when an
installer is built.
Illustration 8-4: <Action> If Options
8–5
The Build Directives popmenu will display any build directive that has been set up
in the Build Directive window as well as the Any Match item.
If only one build directive item is checked, as in the example below, this action
item will be included in the built installer only when that build directive is in
effect.
Checking multiple items in the Build Directive popmenu will result in an AND
condition. In the example below, this action item will be included in the installer
when the Debug Build AND the English Release build directives are in effect.
The Any Match item causes an OR condition to be in effect for any other checked
items.
In the example below, this action item will be included in the installer when
Debug Build OR English Release is in effect.
If no items are checked in the Build Directive popmenu, this action item will
always be included when an installer is built.
Any item in the Archive Window item list, including action items, which
has no build directives specified will always be included in the built
installer.
Gestalt
2. If you wish the action to be performed based on a gestalt check, hold the mouse
over the Gestalt popmenu. The Gestalt popmenu lets you select the gestalt calls
that will be made to evaluate the target system. During installation, if the requirements of the gestalt call(s) are not met, the action item will not be executed.
Languages
3. If you wish the action to be performed based on a language check, hold the mouse
over the Language popmenu. During installation, if the user’s computer is not of
the language specified, the action item will not be executed.
Region
4. If you wish the action to be performed based on a region check, hold the mouse
over the Region popmenu. During installation, if the user’s computer is not of the
region specified, the action item will not be executed.
When there are check marks on items in both the Language and the
Region popmenus it represents an AND condition. Multiple check marks
within one popmenu act as an OR condition.
Action Results
If you wish the action to be performed based upon the success or failure of
8–6
Entering What to <Action> Information
another action item, click the button titles Click to Assign. Action Results allow
the action item to be executed based upon the result of another action item. When
the Click to Assign button is clicked, the Select Action Item window allows the
selection of any action item already defined within the archive.
Illustration 8-5: Select Action Item for Action Result
If a Test Variable action item is selected, you can then choose between true and
false. If a Message action item is selected, you can choose between button names
in the message dialog. For all other action items, you choose between success or
failure.
Entering What to
<Action> Information
The What to <Action> section of the action item window determines what items will be
acted upon. The information in this section is relevant for all action items except Message, Form, Set Variable, Test Variable, Jump, Stop, Launch URL, Comment and UNIX
Script action items.
What to <Action> has three search options.
Switching between these options switches other corresponding options and, in the case
of the Find Action Item and the Archive Item, resizes the action item window itself.
Items Found Using Search
Criteria
8–7
When Items Found Using Search Criteria is selected in the What to <Action> popmenu, the Search Location and Search Criteria areas are expanded so that the search for
the action can be completely defined.
Illustration 8-6: What to <Action> with Items Found Using Search Criteria
Find Action Item
When Find Action Item is selected in the What to <Action> popmenu, the Search Location and Search Criteria areas are collapsed because the search will be defined by the Find
action selected. When Find Action Item is selected in the What to <Action> popmenu,
the Find Action Item popmenu will contain a list of all Find actions currently defined
within the archive. When set up in this manner, one Find action can be used to set the
search criteria for a number of other actions minimizing the need to perform the same
search multiple times.
Illustration 8-7: What to <Action> using Find Action Item
Archive Item
When Archive Item is selected in the What to <Action> popmenu, the Search Location
and Search Criteria areas are collapsed because the action will be performed on the
archive item specified after that item is installed.
Illustration 8-8: What to <Action> using Archive Item
8–8
When using the What to <Action> with an Archive Item, make sure the
action item is after the Archive Item in the Archive window. An action set
up in this way will perform correctly only if the installation of the Archive
Item precedes the action item execution.
To use Items Found Using Search Criteria:
1. If you wish to change the beginning search location and other identifying information to search for a file of folder, select Items Found Using Search Criteria.
2. If your search is for a file or folder installed on a Mac OS X volume, make the
appropriate selection from the Domain popmenu (see “Selecting Domain for
Search Location (Mac OS X only)” on page 8-10).
3. Select search location from the Search Location popmenu.
Illustration 8-9: Default Search Locations
The default Search Location menu is shown above. A number of additional items
may also appear in this popmenu, depending on your setup. For complete
instructions on how to add or remove these extended locations, see Chapter
36-Extended Install Locations.
8–9
From the Search Location popmenu, select one of the following items:
Popmenu Item
Search Location
Installer Volume
Searches the volume where the installer is located.
Startup Disk
Searches the boot volume of the customer’s system
Selected Disk
Searches the destination volume selected by the customer
for the installation. (If you want to limit the customer to
installing only on local disks, you must make sure that
Allow Installation to Mounted Servers is deselected at
the Installer Settings/Behavior tab. Also, to prevent the
customer from installing on UNIX File System disks,
make sure that Allow Installation to UFS Volumes is
deselected at the Installer Settings/Behavior tab.)
All Disks
Searches all mounted drives if the Allow Installation to
Mounted Servers option is selected at the Installer
Settings/Behavior tab. (UNIX File System disks can be
included in the search only if the Allow Installation to
UFS Volumes option is selected at the Installer Settings/
Behavior tab.) If Allow Installation to Mounted Servers is
not selected, then only local volumes will be searched
Current Folder
The current folder is the enclosing folder of the action
item in the archive.
Install Folder
The install folder is the location in the folder hierarchy
selected by the customer for the installation.
Ask User
Searches the location indicated by the users selection in a
dialog.
Find Action Result…
Searches the location indicated by the designated Find
Action item.
Root of Startup Disk
Searches the root level of the startup volume
Table 8-1: Action Item Search Locations
The remaining items search the folders of that name.
When installing System Folder items, Action items determine the target
System folder according to the setting of the Install System Folder Items
popmenu in the Installer Settings, Behavior tab, Destinations panel.
Some locations do not exist under older Mac OS versions. If you plan to
use a location that is not supported on an OS version your customers
may be using, you should create a gestalt check to ensure that these
locations exist, or deselect the Stop Install if “<type of action>“ Fails
item at the top of the Action Item window.
8–10
If the item you’re searching for is a file, make sure File is selected to the right of the
Search Location popmenu. If the item you’re searching for is a folder, select Folder to the
right of the Search Location popmenu. If the item you’re searching for is a Mac OS X
bundle, select Bundle to the right of the Search Location popmenu.
Selecting Domain for Search
Location (Mac OS X only)
When your search is for an item that resides on a Mac OS X volume, you should select a
Domain in conjunction with the Search Location. Your options for selecting a domain
are:
■
On System Disk
■
On Appropriate Disk
■
System Domain
■
Local Domain
■
Network Domain
■
User Domain
■
Classic Domain (This domain enables installers launched on Mac OS X to
install files to the Classic environment. It is not required for non-Carbon
installers, which will ignore domain settings.)
By selecting domains in conjunction with install locations, you can find items that are
specific to a given domain. For example, you could select the User Domain, Components
folder, which would search a different location than if you select Local Domain, Components folder.
For important information regarding Mac OS X install locations under the
various domains, see the Mac OS X Install Locations document included
in the Installer VISE folder.
Configuring Search Options
After selecting an item to be searched for there are a number of other options which you
may want to set. From the checkboxes below the file/folder radio buttons select from the
following options:
Option
Description
Match Can be Alias
If checked, the search will find aliases which match the
search criteria. If the Match Can be Alias is not checked,
only files or folders will be found.
Search Locked Volumes
Allows locked volumes such as CDs to be included in the
search.
Illustration 8-10: What to <Action> Search Options
8–11
Option
Description
Search Subfolders
If checked, searches for items matching the search criteria
will continue through subfolders. If Search Subfolders is
not checked, searching will not take place in subfolders.
Find Multiple
Occurrences
If checked, Find Multiple Occurrences allows the search to
return multiple matches to the search criteria. If Checking
Find Multiple Occurrences is not checked, the first item
matching the search criteria will be used. When Find
Multiple Occurrences is checked, other options in the
<Action> Options area are available which can allow you
to present a list of found items to the user for their choice
or to present an action confirmation dialog to the user. For
a complete discussion of the Confirm options and the User
Prompt option “Confirm Delete” on page 8-19, “Confirm
Move” on page 8-21, “Confirm Rename” on page 8-22,
“Confirm Copy” on page 8-20, and “Confirm Creating
Alias” on page 8-24.
Illustration 8-10: What to <Action> Search Options
Identifying Search Criteria
If you are searching for a folder, you may only identify the name of the folder. If you are
searching for a bundle, you may identify the name and version number of the bundle. If
you are searching for a file, you may work with any or all of the following criteria:
Item name
Description
Name
The name of the item.
Type
The four-character type identifier of the file.
Creator
The four-character creator identifier of the file.
Version
The version number of the file. You may specify the version
number up to two decimal places. You may also identify
whether the file is a development, alpha, beta, or final version,
based on the contents of the file’s vers resource. (If desired, you
may search for a range of version numbers.)
Date Created
The creation date of the file. (If desired, you may search for a
range of creation dates.)
Date Modified
The modification date of the file. (If desired, you may search for
a range of modification dates.)
Table 8-2: Action Item Search Criteria
The action item will search for items that meet all of the criteria that you identify in the
Search Criteria section.
8–12
Because a customer may have changed the name of an item at the Finder,
consider using additional criteria such as type, creator, and version number rather than name to identify specific items on the target system.
Drag and Drop Support in
Action Item windows
If you have Drag and Drop installed, the following shortcuts are available:
■
Dragging an item from the Finder onto an Action Item window (except Message, Form, Set Variable, Test Variable, Jump, Stop, Launch URL, Comment and
UNIX Script actions) will assign that item’s attributes.
■
Dragging an item from the archive window onto an Action Item window
(except Message, Form, Set Variable, Test Variable, Jump, Stop, Launch URL,
Comment and UNIX Script actions) will assign the attributes of the item.
Dragging a bundle onto an Action Item window (using either of the two
shortcuts above) will set the action to search for the name of the executable
inside the bundle (in case the end user has changed the bundle name). An
installer executing the action will search by the executable name and display found items by the current bundle name.
Identifying the Name (Files
Folders and Bundles)
To specify information about the name of the item you wish to search for:
1. Make sure that the Name checkbox is checked.
2. Hold down the mouse over the popmenu to the right of the Name item and select
one of the following items:
Name
Search Criteria
Searches for items that contain the character string
entered in the Name field anywhere in their name.
Searches for items whose names begin with the
character string entered in the Name field.
Searches for items whose names end with the
Searches for items with the exact character string
entered in the Name field. (This is the default
setting.)
Searches for items whose names are not the exact
Table 8-3: Action Item Search Criteria-Name
3. In the Name field, enter the character string of the name. (For bundle searches,
this should be the name of the executable inside the bundle).
Specifying File Type
Information (Files Only)
8–13
To specify search information about the file type:
1. Select the Type item.
2. Hold down the mouse over the popmenu to the right of Type and select one of the
following:
Type
Search Criteria
Searches for files whose type matches the file type
entered in the Type field. (This is the default setting.)
Searches for files whose type does not match the file
type entered in the Type field.
Table 8-4: Action Item Search Criteria-File Type
3. In the Type field, enter the four-character file type you wish to search for.
Specifying File Creator
To specify information about the creator of the file:
1. Select the Creator item.
2. Hold down the mouse over the popmenu to the right of Creator and select one of
the following:
Creator
Search Criteria
Searches for files whose create matches the creator
type entered in the Creator field. (This is the default
setting.)
Searches for files whose creator does not match the
creator type entered in the Creator field.
Table 8-5: Action Item Search Criteria-File Creator
3. In the Creator field, enter the file’s four-character creator identifier.
Specifying Version
Information (Files and
Bundles Only)
To specify the version number of the file or bundle:
1. Select Version.
8–14
2. Hold down the mouse over the popmenu to the right of the Version item and
select one of the following:
Version
Search Criteria
Searches for items whose version numbers exactly
match the numbers that you enter in the version
number fields. (This is the default setting.)
Searches for items whose version numbers are less
than the numbers that you enter in the version
number fields.
Searches for items whose version numbers are less
than or equal to the numbers that you enter in the
version number fields.
Searches for items whose version numbers are greater
number fields. (This option lets you search for a
range of version numbers.)
Searches for items whose version numbers are greater
number fields. (This option lets you search for a
range of version numbers.)
Searches for any items whose version numbers are not
the numbers that you enter in the version number
fields.
Table 8-6: Action Item Search Criteria-Version
3. In the version number fields, enter the item’s version number. For example, to
search for an item with version number 3.1.5, the fields would look like this:
4. If you wish to specify additional information based on the vers resource of the target item:
■
Hold down the mouse over the popmenu to the right of the version number entered in the previous step.
■
As desired, select Final, Development, Alpha, or Beta.
■
In the field to the right of the vers resource identifier, enter the version
number.
For example, to search for a file with version number 3.1.5 that’s designated as
beta 6, the fields would look like this:
8–15
In version comparisons, the highest possible value for a vers resource
number is zero. For example, version number 3.1.5 beta 6 would be less
than 3.1.5 beta 0.
5. If you selected Is greater than or Is > or equal, you may specify the range of
version numbers to search. The item that you entered in Step 4 identifies the low
end of the search range; in this step, you’ll identify the high end of the range.
To specify the high end of the range:
■
Click AND. (This item becomes active if you selected Is greater than or Is >
or equal for the Version item in the Search Criteria panel.)
■
To set the range to include version numbers that are less than the numbers
you will enter in the version number fields, select Is less than; to search for
items whose version numbers are less than or equal to the number you
enter in the version number fields, select Is < or equal.
■
In the version number fields, enter the version numbers that signify the
high end of the range to search for. Use the same format to enter the version numbers as you did in Step #4.
For example, to search for an item with version number between 3.1.5 beta 6 but
less than version 4.2, the fields would look like this:
When searching for bundle version, installers use the bundle version
inside the .plist file in addition to the older-style 'vers' resource.
How Installer VISE Checks For To automatically recognize folder structures as bundles when they are added to the
archive, Installer VISE checks that the items meet at least one of the following criteria:
Bundle Version
■
■
The folder has one of the following filename extensions:
■
.app
■
.bundle
■
.framework
The folder has a bundle bit set (kHasBundleBit).
To have Installer VISE recognize your item as a bundle for this drag and drop scenario,
you can do one of the following:
■
Change the filename extension to one of the three previously listed.
■
Use a resource editor such as Resorceror to turn on the folder flag
kHasBundleBit for the bundle.
■
Add your bundle’s filename extension to the text file “Bundle Extensions.txt” in
the Installer VISE Extensions folder. Installer VISE will then treat folder structures with your specified extension as bundles.
8–16
Though you can add a folder structure to the archive and then set its kHasBundleBit with the Application Package checkbox, this approach will not
allow Installer VISE to read version information for the structure. To
enable proper version checking for actions such as Find and Replace, you
should set up your folder structure as described here (if needed) before adding it to
your archive.
When you add a recognized bundle to the archive or drag it into the Search Criteria area
of an action item window or the Default Install Location window, Installer VISE checks
for bundle version as follows:
1. The program makes an Apple API call to CFBundleGetVersionNumber. That API
call returns the value of the CFBundleVersion string from the Info.plist file inside
the bundle. (To be valid, the string data needs to be in “##.#.#” format as defined
in Apple Technical Note TN1132.)
2. If CFBundleGetVersionNumber returns a zero, Installer VISE will try calling
CFBundleGetValueForInfoDictionaryKey, passing CFBundleShortVersionString
to obtain the bundle’s version. We have noticed CFBundleGetVersionNumber
returns a zero when the CFBundleVersion field is three or more digits (as is the
case with AddressBook.app and Mail.app).
3. If both of these checks return zero, Installer VISE sets the bundle version to zero.
Specifying Creation Date
To specify information about the creation date of the file:
1. Select Date Created.
2. Hold down the mouse over the popmenu to the right of the Date Created item
and select one of the following:
Creation Date
File Type Search Criteria
Searches for files whose creation dates exactly match
the date that you enter in the date created fields. (This
is the default setting.)
Searches for files whose creation dates are less than
the date that you enter in the creation date field.
Searches for files whose creation dates are less than or
equal to the date that you enter in the creation date
fields.
Searches for files whose creation dates are greater
than the date that you enter in the creation date fields.
(This option lets you search for a range of creation
dates.)
Table 8-7: Action Item Search Criteria-Creation Date
Action Options
8–17
Creation Date
File Type Search Criteria
Searches for files whose creation dates are greater
than the date that you enter in the creation date fields.
(This option lets you search for a range of creation
dates.)
Searches for any files whose creation date are not the
dates that you enter in the creation date fields.
Table 8-7: Action Item Search Criteria-Creation Date
3. In the fields to the right of the popmenu, enter the creation date you wish to
search for, in the month/day/year format. (Today’s date will appear in the field by
default.) For example, to specify a creation date of May 1, 1997, the fields would
look like this:
4. If you selected Is greater than or Is > or equal, you may specify the range of dates
to search. The item that you entered in Step 3 identifies the low end of the search
range; in this step, you’ll identify the high end of the range.
To specify the high end of the range:
■
Click AND. (This item becomes active if you selected Is greater than or Is >
or equal for the Date Created item in the Search Criteria panel.)
■
To set the range to include creation dates that are less than the numbers you
will enter in the creation date fields, select Is less than; to search for files
whose creation dates are less than or equal to the number you will enter in
the creation date fields, select Is < or equal.
■
In the creation date fields, enter the creation dates that signify the high end
of the range to search for. Use the same format as you did in Step #3.
Specifying Modification Date To specify information about a modification date, select Date Modified and follow the
steps for “Specifying Creation Date Information,” described above, entering modification
date information the appropriate fields. You may use the same procedure to specify a
range of dates, using the Modification Date fields in the Search Criteria panel.
Action Options
The options area contains items specific to that type of action. Below are illustrations of
the options area for each Action item.
8–18
Action Options
Find Options
Illustration 8-11: Find Action Item - Find Options
Option
Description
Return Parent of Found
Item
When checked on, the Find action will return the
parent, or enclosing item, of the found item rather than
the item itself.
Open/Launch Found
Items
When checked on, the Find action will open or launch
the found items.
User Prompt
Text entered here will be used in the confirmation
dialog presented to the user when running the installer.
Set Variable
A runtime variable assigned here will be used to store
the full path to the found items. The variable can then
be tested with Test Variable actions, and used in various
ways to control install logic. For more information on
variables, see Chapter 28-Using Runtime Variables.
Save as POSIX Path
NOTE: This option is applicable for installs on Mac OS
X only.
By default, a Find action set to store its results in a
runtime variable will return a colon-separated full path
to the found item. This is the correct type of path for
access to files and folders on Mac OS X. However, if you
use variable substitution to pass a path in a UNIX
Script action, the variable must be set with a POSIXbased (slash-separated) path to conform to UNIX
standards. This is the purpose of the Find action’s Save
as POSIX Path setting. (Also see “UNIX Script
Options” on page 8-40.)
Table 8-8: Find Options
Action Options
8–19
Delete Options
Illustration 8-12: Delete Action Item - Delete Options
Option
Description
Delete Parent of Found
Item
When checked on, the Delete action will delete the
the item itself.
Delete Folder Only If
Empty
When checked, a found folder will only be deleted if it
is empty.
Confirm Delete
Before the Delete action takes place on the item(s)
found using the settings in What to Delete, the user is
asked to confirm the action. If Find Multiple
Occurrences is also checked, the confirmation is
effective for all items found. The text for the
confirmation message can be entered in the User
Prompt text field.
Display Found Items
Display Found Items can only be checked on if
Confirm Delete is also checked on. When both are on,
during an install the user will be presented with a list
containing item(s) found using the settings in What to
Delete. The items selected by the user in the list will
then be deleted. The text for the confirmation message
can be entered in the User Prompt text field.
User Prompt
Table 8-9: Delete Options
8–20
Action Options
Copy Options
Illustration 8-13: Copy Action Item - Copy Options
Option
Description
Copy Parent of Found
Item
When checked on, the Copy action will copy the
the item itself.
Confirm Copy
Before the Copy action takes place on the item(s)
found using the settings in What to Rename, the user is
Prompt text field.
Display Found Items
Confirm Copy is also checked on. When both are on,
Copy. The items selected by the user in the list will then
be renamed. The text for the confirmation message can
be entered in the User Prompt text field.
User Prompt
Copy To Location
Designates the location to which the found item will be
copied.
Replace
Replace options determine the action to be taken when
renaming would result in a name collision. For a
complete discussion of action item replace options see
“Replace Options” on 8-42.
New Name
This text field is used to determine the new name of the
item being acted upon.
Table 8-10: Copy Options
Action Options
8–21
Move Options
Illustration 8-14: Move Action Item - Move Options
Option
Description
Move Parent of Found
Item
When checked on, the Move action will move the
the item itself.
Confirm Move
Before the Move action takes place on the item(s)
found using the settings in What to Move, the user is
Prompt text field.
Display Found Items
Confirm Move is also checked on. When both are on,
Delete. The items selected by the user in the list will
then be deleted. The text for the confirmation message
can be entered in the User Prompt text field.
User Prompt
Move To Location
moved.
Replace
moving would result in a name collision. For a
Table 8-11: Move Options
8–22
Action Options
When moving items across volumes the original is left in its original location. It functions the same as dragging the item in the Finder. If the item is
being moved from one location on a volume to another location on the
same volume, the item is copied to the new location and the item at the
original location is removed. If the item is being moved from one location on a volume to a location on a different volume, the item is copied to the new location and the
item at the original location remains.
Both Move and Copy action items will copy files to a drive without
checking for available space. If a disk fills up during a Move or a Copy
action, the installer will incorrectly display a message that nothing
needed to be installed.
Rename Options
Illustration 8-15: Rename Action Item - Rename Options
Option
Description
Rename Parent of Found
Item
When checked on, the Rename action will rename the
the item itself.
Confirm Rename
Before the Rename action takes place on the item(s)
found using the settings in What to Rename, the user is
Prompt text field.
Table 8-12: Rename Options (Sheet 1 of 2)
Action Options
8–23
Option
Description
Display Found Items
Confirm Rename is also checked on. When both are
on, during an install the user will be presented with a
list containing item(s) found using the settings in What
to Rename. The items selected by the user in the list
will then be renamed. The text for the confirmation
message can be entered in the User Prompt text field.
User Prompt
New Name
item being acted upon.
Replace
renaming would result in a name collision. For a
Table 8-12: Rename Options (Sheet 2 of 2)
Alias Options
Illustration 8-16: Alias Action Item - Alias Options
8–24
Action Options
Option
Description
Alias Parent of Found
Item
When checked on, the Alias action will alias the parent,
or enclosing item, of the found item rather than the
item itself.
Confirm Creating Alias
Before the Alias action takes place on the item(s) found
using the settings in What to Rename, the user is asked
to confirm the action. If Find Multiple Occurrences is
also checked, the confirmation is effective for all items
found. The text for the confirmation message can be
entered in the User Prompt text field.
Display Found Items
Confirm Creating Alias is also checked on. When both
are on, during an install the user will be presented with
a list containing item(s) found using the settings in
What to Alias. The items selected by the user in the list
will then be aliased. The text for the confirmation
message can be entered in the User Prompt text field.
User Prompt
Alias Location
aliased.
Replace
aliasing would result in a name collision. For a
Alias Name
alias being created.
Special Notes for Alias Name:
If the Name field is left blank in an Alias action, the
name for the created alias will be the name of the item
designated in the What to Alias area suffixed with the
word “alias”.
For the Alias action, you can also use a “^0” in the
Alias Name field to represent the found filename. For
example, if you put “Bob’s ^0” in the name field and
the found file was named MyApp, the alias name would
be “Bob’s MyApp”.
Add to OS X Dock
When checked on, the alias created will be added to the
Mac OS X Dock.
Table 8-13: Alias Options
Action Options
8–25
Message Options
Illustration 8-17: Message Action Item - Message Options
Option
Description
Icon ID
The icon ID will determine the icon displayed in the
Message dialog. See Table 8-15, “Icon Options for
Message Action dialogs,” on page 8-25.
Message text
The text which will be displayed in the Message dialog.
Button 2
Name for button 2
Button 1
Name for button 1
Table 8-14: Message Options
The Message Action allows you to display a message dialog to the user. You can display 1
or 2 buttons in the dialog. You can then conditionally install, delete, or rename a file
depending upon which button the user selects. You can also display a one button alert
message.
In the Icon ID field different icons can be selected for use in the message dialog.
Icon ID
Icon Displayed
0
Table 8-15: Icon Options for Message Action dialogs
8–26
Action Options
Icon ID
Icon Displayed
1
2
Table 8-15: Icon Options for Message Action dialogs
For additional icon options in Message action dialogs, add cicn resources
to the archive through an external resource file. If there are cicns in an
external resource file connected to the archive, the id for other cicns may be
used. All cicns used by Message actions will be included in the installer at
build.
This message action can also be displayed depending upon the result of a Find Action. An
example would be to find an old version of an application, and ask the user if they want
to install a newer version. Depending upon the users choice, install or not install the
newer version.
To optionally display the message depending on the result of another action
item,
1. Click on the Execute If box, select a Find Action, and then select whether to show
the message if the Find Action succeeds. To display the message always, simply do
not select an Action Item.
2. Type in an Icon ID. You may use one of the default icons (0 = Stop, 1 = Note, 2 =
Caution) or type in the ID of one of your own icons. When you tab out of the ID
field, the icon should appear. You can also paste an icon into this window.
3. Type in the text of the message you wish to display.
4. Type in the names of Buttons 1 and 2. If you only wish to display one button, leave
the other button text blank.
5. Click on Stop If User Selects Button 2 if you wish the install to stop if the user
selects Button 2.
To assign a file to the result of a message action, do a Get Info on the file you want to conditionally install, and then click on the “Install If ” box and choose the Message action
you want. Also choose the button from the popmenu to the right of the “Install If ” box.
Action Options
8–27
In the Illustration below a Message action is being set up.
Illustration 8-18: Message Action window
When the action item above is executed in the installer, the message dialog below will be
displayed to the user.
Illustration 8-19: Message dialog as displayed in the installer
Display Form Options
Illustration 8-20: Form Action Item - Display Form Options
8–28
Action Options
Option
Form Name
Description
Select the name of the Form to be displayed by this
action item.
Table 8-16: Display Form Options
Form actions without a form assignment will stop a build and display an
error stating that a form has not been assigned.
Set Variable Options
Illustration 8-21: Set Variable Action Item - Set Variable Options
Option
Variable to assign
Description
Click the button which reads (Click to assign) for a list
of variables.
Table 8-17: Set Variable Options
The Set Variable Action item allows variables to be set based on criteria which are available at installer runtime. Runtime variables can be conditionally set by selecting items in
the Set Variable If section of the Set Variable Action window. Set Variable Action items
can be set to be included in an installer according to build directive and can be set to execute conditionally based on Gestalt, Language, Region and/or the result of another
action item. In the example below, the following conditions effect the Set Variable
Action’s execution:
1. This action item will only be included in a built installer when the Debug Build
build directive is on.
2. During an install, this action item will only be executed if:
■
The gestalt check on the users machine indicates that Open Transport is
present; AND
■
The language check on the users machine indicates that the French language is
being used; AND
■
The region check on the users machine indicates that the French or the French
Canadian region is being used; AND
Action Options
8–29
■
The user clicked on Yes in the dialog presented by the Message Action asking if
MyApp should be installed.
Illustration 8-22: Set Variable Action item
When the action item above is executed the runtime variable MyVar will be set to “MoveOld.” A Test Variable Action item can then be used to test the value of the MyVar variable
with other actions based upon the test.
Test Variable Options
Illustration 8-23: Test Variable Action Item - Test Variable Options
8–30
Action Options
Option
Description
Variable to assign
Click the button which reads (Click to assign) for a list
of variables. Selecting a variable from the list
determines the variable that will be tested by this action
item.
Perform Numeric
Comparison
When checked, the variable value and the comparison
value are converted to numeric values before
comparison (10 is greater than 1). When unchecked,
the variable value and the comparison value are
compared as strings (“10” is not greater than “1”). This
option applies only to Test Variable action items.
Table 8-18: Test Variable Options
The Test Variable Action item allows the value of runtime variables to be tested.Runtime
variables can be conditionally tested by selecting items in the Set Variable If section of the
Test Variable Action window. Test Variable Action items can be set to be included in an
installer according to build directive and can be set to execute conditionally based on
Gestalt, Language, Region and/or the result of another action item.
In the example below, the runtime variable MyVar is being tested for a value equal to
“MoveOld.” Other action items could then be set to execute based upon the success or
failure of this Test Action.
Illustration 8-24: Test Variable Action item
Action Options
Jump Options
8–31
Complex installer logic is much easier to construct and maintain with the use of Jump
actions. Jump actions enable an installer to move forward or back in the install sequence
without executing items in between. Jump actions can be executed conditionally by
selecting items in the Jump If section of the Jump Action window. Jump Action items can
be set to be included in an installer according to build directive and can be set to execute
conditionally based on Gestalt, Language, Region and/or the result of another action
item.
Illustration 8-25: Jump Action Item - Jump Options
Option
Description
Jump If
By selecting items in the Jump If section of the Jump
Action item, the jump can be set to execute
conditionally.
Jump To
Clicking the (Click to assign) button allows any item
(action item, file or folder) in the archive to be chosen
as the destination of the jump.
Table 8-19: Jump Action Options
In the following illustration, the jump action has been set to execute only if a previous
Find action fails.
Illustration 8-26: Jump Action Item
8–32
Action Options
The use of Jump Actions can cause an installer to have an inaccurate
“Number of Files to install” display in the installer progress.
Stop Installation Options
Stop Installation actions enable an installer to be programmatically stopped. Stop actions
can be executed conditionally by selecting items in the Stop Install If section of the Stop
Action window. Stop Installation Action items can be set to be included in an installer
according to build directive and can be set to execute conditionally based on Gestalt,
Language, Region and/or the result of another action item.
Illustration 8-27: Stop Action Item - Stop Options
Option
Stop Install If
Description
By selecting items in the Stop Install If section of the
Stop Install Action item, the stop can be set to execute
conditionally.
Table 8-20: Stop Action Options
In the following illustration, the Stop action has been set to execute only if a previous
Find action succeeds.
Illustration 8-28: Stop Action Item
If you turn on the Stop Install With Error checkbox, the installer will delete any files it
had installed before the Stop action was performed. You may want to include a Message
Action before this Stop action, telling the user why the installation failed.
Action Options
8–33
Sub-launch Action Options Complete control over sub-launched applications (including other installers) is now possible through the Sub-launch Action. Since the Sub-launch item is an Installer VISE
action item, it has all of the power of conditional execution and searching of the other
action items with added options specifically tailored to launching and controlling other
installers.
Illustration 8-29: Sub-launch Action Item
8–34
Action Options
In the preceding illustration, our parent installer is set to sub-launch a QuickTime
installer if a gestalt test for the existence of QT6 on the user’s machine indicates that QT6
is not present. The parent installer will search the installer volume (in our case a CD and
therefore a locked volume) for a specific application. The parent installer is set to wait for
the sub-launched installer to finish before progressing. Since the sub-launched installer is
an Installer VISE 6 or greater installer the sub-launched QT6 installer will be sublaunched displaying Splash Screen, License Agreement, Read Me and Billboards while
suppressing the Main Window, the Progress Stop and the Success. Packages 1, 2, and 3
will be automatically chosen for the user.
Option
Description
Sub-launched item is a
VISE Installer
If the sub-launched item is a VISE installer, the VISE
Options become available.
NOTE: VISE Options will only work with installers
created with Installer VISE 6.0 or greater.
VISE Options in the parent installer will not override
Sub-launch locks set in the sub-launched installer
Behavior tab of Installer Settings. For more
information on Sub-launch locks see “Sub Launch
Locks” on page 14-19.
Wait for sub-launched
item to complete
If checked, the parent installer will wait for the sublaunched item to complete before progressing.
Show Splash Screen
If unchecked, the Splash Screen of the sub-launched
installer will not be displayed.
NOTE: VISE Options in the parent installer will not
override Sub-launch locks set in the sub-launched
installer Behavior tab of Installer Settings. See “Sub
Launch Locks” on page 14-19.
Show Read Me
If unchecked, the Read Me of the sub-launched
Show License Agreement
If unchecked, the License Agreement of the sublaunched installer will not be displayed.
Show Billboards
If unchecked, the Billboards of the sub-launched
Table 8-21: Sub-launch Action Options (Sheet 1 of 2)
Action Options
8–35
Option
Description
Suppress
Select from the Suppress popmenu to suppress the sublaunched installer’s Main Window, the Progress Stop
and/or Success.
Packages
Select from the Packages popmenu to pre-select sublaunched installer packages for installation.
NOTE: Installer VISE counts Separators in the
Packages List as individual packages. For instance,
“Package 2” in the Packages popmenu could refer to a
Separator. For more information on Separators, see
“Creating Package Separators and Mutual Exclusive
Groups” on page 7-10.
Send Install Location
If checked, the parent installer will send the sublaunched installer the location the user chose for the
main install. The sub-launched installer will then use
that install location as the default. NOTE: When using
this option with a sub-launched installer that requires
Mac OS X authentication, the parent installer also must
require authentication. Otherwise, when the sublaunched installer authenticates it will lose the install
location sent by the parent. With both the parent and
the sub-launch installer set to require authentication,
the user will only be prompted to authenticate once.
Also note that on Mac OS X v10.1.5 and earlier
versions, the “Send Install Location” option will not
work because the sub-launched installers will need to
re-authenticate. For information on setting installers to
require Mac OS X authentication, see “Assigning
Minimum Requirements for Installation” on
page 14-22
Hide Progress Bar
If checked, the sub-launched installer will use the
progress bar of the main installer, rather than display
its own progress bar.
Table 8-21: Sub-launch Action Options (Sheet 2 of 2)
You can use external code to send information from the parent installer to
the sub-launched installer. See “Sending information to sub-launched
installers” on page 32-25.
Launch URL Options
You can use the Launch URL action item to launch the default web browser on the customer’s system and open a specified URL. Launch URL actions can be executed conditionally by selecting items in the Launch URL If section of the Launch URL Action
window. Launch URL action items can be set to be included in an installer according to
8–36
Action Options
build directive and can be set to execute conditionally based on Gestalt, Language,
Region and/or the result of another action item.
Illustration 8-30: Launch URL Action - Launch URL Options
Option
Description
Launch URL If
By selecting options in the Launch URL If section of
the Launch URL action item, the launch can be set to
execute conditionally.
Launch URL Path
This text area should contain a single URL, such as
http://acompany.com or www.mindvision.com.
Table 8-22: Launch URL Action Options
Action Options
8–37
In the following illustration, the Launch URL action has been set to execute only if a previous Message action returned “OK.”
Illustration 8-31: Launch URL Action Item
Edit Text File Options
The Edit Text File action item allows you to edit text in the data fork of Macintosh files,
including hidden files. This action can perform the following edits:
■
Add text to the beginning or the end of the file.
8–38
Action Options
■
Search for text and delete it, replace it or insert text before or after it.
Illustration 8-32: Edit Text File Action - Edit Text Options
Action Options
8–39
Option
Description
Edit If
By selecting options in the Edit If section of the Edit
Text action item, the edit can be set to execute
conditionally.
What to Edit
This section specifies the search criteria for the text file
that requires edits.
Confirm Edit File
Before the Edit Text action takes place on the item(s)
found using the settings in What to Edit, the user is
Prompt text field.
User Prompt
Display Found Items
Display Found Items can only be checked on if Corfirm
Edit File is also checked on. When both are on, during
an install the user will be presented with a list
Edit. The items selected by the user in the list will then
be edited. The text for the confirmation message can be
entered in the User Prompt text field.
Add text to the
beginning of file
Adds the text specified in the Text to Add/Append area
to the beginning of the file.
Add text to the end of file
Adds the text specified in the Text to Add/Append area
to the end of the file.
Delete search text
Deletes the text specified in the Search for Text area.
Insert before search text
Inserts the text specified in the Text to Add/Append
area immediately before the text specified in the Text to
Add/Append area.
Insert after search text
Inserts the text specified in the Text to Add/Append
area immediately after the text specified in the Text to
Add/Append area.
Replace search text
Replaces the text specified in the Search for Text area
with the text specified in the Text to Add/Append area.
Search for Text
Text in this area specifies what to edit in the text file.
Variable substitution is allowed. The maximum
number of characters is 255.
Text to Add/Append
Text in this area specifies what to use in adding or
replacing text in the file. Variable substitution is
allowed. The maximum number of characters is 255.
Table 8-23: Edit Text File Action Options
8–40
Action Options
The Edit Text File action does not support inserting text at the beginning or the end of a file of type RTF. This restriction also applies to
some Microsoft Word format documents, such as those of type W8BN.
To search through a file for an Edit Text File action, Installer VISE will
read the entire file into available system memory. (This procedure does
not use memory allocated to the installer.) If not enough memory is
available, a 109 error will be returned. One workaround for such memory limitations is for the installer to shut down running applications
before it executes the Edit Text File action.
The Replace Search text function of the Edit Text File action item only
handles the first occurrence of its search text. To ensure that all occurrences of search text are replaced, use a Jump action to loop back to the
Edit Text File action until it fails.
Comment Options
You can use the Comment action item to note logic in your installer archives. This item
displays any text you would like to appear in your archive’s display. It has no effect on the
installers you build.
Text that you enter in the Name field of a Comment action will appear in the archive
window under any layout.
The Extended Comment can be up to 255 characters long. It is visible only when you
choose Get Info for the Comment action.
Illustration 8-33: Comment Action Item
UNIX Script Options
The UNIX Script action item offers a simple way to execute UNIX shell scripts from your
installer. This action supports the use of Installer VISE runtime variables, and is a good
choice for when you don't need to perform actions on installed items. (For access to
standard UNIX parameters such as $1, you'll need to use the more advanced method
described in “Executing UNIX scripts from the installer” on page 32-22.)
Action Options
8–41
UNIX Script actions can be executed conditionally by selecting items in the Execute
Script If section of the UNIX Script Action window. UNIX Script action items can be set
to be included in an installer according to build directive and can be set to execute conditionally based on Gestalt, Language, Region and/or the result of another action item.
Illustration 8-34: UNIX Script Action - Execute Script Options
Option
Description
Execute Script If
By selecting options in the Execute Script If section of
the UNIX Script action item, the edit can be set to
execute conditionally.
UNIX Script
This text area should contain shell commands. Variable
substitution is allowed.
Table 8-24: UNIX Script Action Options
If you use variable substitution to pass a path in a UNIX Script action, be
sure to set the variable with a POSIX-based (slash-separated) path to conform to UNIX standards. One way to do this is with a Find action set to
Save as POSIX Path. See “Find Options” on page 8-18 for more information.
In the following illustration, the UNIX Script action has been set to execute only if a previous Find action succeeds in locating a specified folder. If successful, the Find action will
store the full path to the folder in the runtime variable InstallPath. The UNIX Script
8–42
Action Options
action references the InstallPath variable in quotes so that the value will be substituted at
install time.
Illustration 8-35: UNIX Script Action Item
Saving an Action Item
To save the action item and return to the archive window: clicking the close box in upper
left corner, or press Command-W. If Confirm Before Saving Get Info or Action Item
Changes in Preferences is checked on, you will be prompted to save the changes to the
action item.
Replace Options
Replace Options allow you to determine the outcome of file or folder name conflicts
resulting from a move, rename, alias or copy action.
Illustration 8-36: Action Item Replace Options
Action Options
8–43
The correct replace option for your install situation can be built using multiple selections
within the replace options menu. A selected item within one section will interact with a
selected item in another section. The table below describes each replace option selection.
Replace Option
Description
If Newer
If Newer or Equal
If Older or Equal
If Older
These four items in the topmost section of the
replace options popmenu determine the
comparison range between the existing item and
the new item. The type of comparison being done
(modification date, creation date or version) is
determined by the settings in the next section of
the popmenu.
If Different
If Different compares file type, creator, dates,
resource and data fork sizes, and finder flags. The
Compare Modification Dates, Compare Creation
Dates, and Compare Version options are disabled
when If Different is selected.
If Exists
When If Exists is selected the item will only be
installed if it already exists on the user’s machine.
Compare Modification Dates
Compare Creation Dates
Compare Version
Items in the compare section of the replace
options popmenu determine the type of
comparison that will be done to resolve name
conflicts between existing and new items.
Comparison can be based upon modification
date, creation date, or version.
Always
Never
Ask User
Always, Never, and Ask User supersede any
selection in the topmost section of the replace
options popmenu.
Checking Always will cause an existing item to
always be replaced if there is a conflict.
Checking Never will cause an existing item to
never be replaced if there is a conflict.
If there is a conflict and Ask User was checked, the
user will be given the opportunity to accept or
decline the item’s replacement.
Table 8-25: Action item Replace Options (Sheet 1 of 2)
8–44
Action Options
Replace Option
Description
Ask If False
Ask If False is a conditional ask user. If the
condition specified above was met, no user
interaction will take place. However, if the
condition was not met, a dialog will be displayed
asking the user if the item should be replaced.
Rename Existing
Rather than being replaced, the existing file will be
renamed using a.1,.2,.3, etc. naming sequence.
For example, suppose we created a Move Action
which will search for an application named
MyApp and move it to a backup folder. If there
already exists a MyApp application in that backup
folder, the pre-existing MyApp will be renamed to
MyApp.1.
Table 8-25: Action item Replace Options (Sheet 2 of 2)
When adding new files to an archive, if the file has a version number (vers
resource), the replace options for that file will be set to Replace If Newer
Version.
Assigning External Codes
to Action Items
If extended functionality is required, some action items can be set to execute external
codes.
To assign external code to be executed by the action item:
Hold the mouse over the external code popmenu of your choice. If no custom
code has been added to the archive, then the external code popmenus will be disabled.
For step-by-step instructions on adding custom code to your archive, see Chapter
9-Assigning External Code. For instruction on writing your own external code,
see Chapter 32-Creating External Code.
Some action items have two or three options for external code execution, while
some action items have no such options. See the table below for a complete listing
of external code execution options within action items.
Action item
External Code Execution
Find Action
Before Find
After Find
Delete Action
Before Search
Before Delete
After Delete
Copy Action
Before Search
Before Copy
After Copy
Table 8-26: Action Item External Code Execution Options (Sheet 1 of 2)
Identifying Action Items In the Archive Window
8–45
Action item
External Code Execution
Move Action
Before Search
Before Move
After Move
Rename Action
Before Search
Before Rename
After Rename
Alias Action
Before Search
Before Creating Alias
After Creating Alias
Message Action
Before Message Appears
After Message Appears
Form
Before User Input
After User Input
Set Variable Action
Before Setting Variable
After Setting Variable
Test Variable Action
Before Testing Variable
After Testing Variable
Jump Action
Does not execute external code.
Stop Action
Sub-launch Action
Before Search
Before Sub-launch
After Sub-launch
Launch URL
Action
Before Launch URL
After Launch URL
Edit Text File
Action
Before Search
Before Edit
After Edit
Comment Action
Table 8-26: Action Item External Code Execution Options (Sheet 2 of 2)
Identifying Action
Items In the Archive
Window
In the Archive Window, each kind of action item can be identified by a unique icon:
Icon
Action Item
Find Action
Delete Action
Table 8-27: Action Item Icons (Sheet 1 of 3)
8–46
Identifying Action Items In the Archive Window
Icon
Action Item
Copy Action
Move Action
Rename Action
Alias Action
Message Action
Form Action
Set Variable Action
Test Variable Action
Jump Action
Stop Installation Action
Sub-launch Action
Launch URL Action
Edit Text File Action
Correct Placement of Action Items
8–47
Icon
Action Item
Comment Action
UNIX Script Action
Duplicating Action Items
If you need to create several similar action items, you might find it easier to create a
single action item and duplicate it several times than to set up each action item individually.
To duplicate an action item at the archive window:
1. Select the action item you wish to duplicate.
2. Click the Duplicate button in the Archive Window. The item will be duplicated.
3. For each new action item, change the attributes as desired.
Renaming Action Items
If you wish, you may change the name of an action item at the archive window.
To rename an action item in the archive window:
1. At the archive window, click the mouse to the right of the icon for the action item.
A name field will be displayed.
2. Enter the new name for the action item.
Correct Placement of
Action Items
Action items whose results affect the installation of an item in the archive must be performed before the item is installed. To ensure that an action item is performed before an
item is installed, move the action item so that it appears before the entry for the file or
folder in the archive window.
Action items who act on an item in the archive must be performed after the item is
installed. To ensure that an action item is performed after an item is installed, move the
action item so that it appears below the entry for the file or folder in the archive window.
Assigning Action Items
to Packages
Like any other item in an archive, action items may be assigned to packages. By default,
all action items are part of the Easy Install package. You may add action items to other
packages (so that they’ll be performed during Custom Installs) or remove them from the
Easy Install package, see Chapter 7-Creating Packages And Assigning Files.
8–48
Assigning Action Items to Packages
9–1
Chapter 9
Assigning External Code
If you created external code for an earlier version of Installer VISE, you
may need to recompile the code for use in the latest version. (The Read
Me file in the Installer VISE folder will specify this when required.) In
this case, be sure to use the new header files that are included with the
latest version of Installer VISE.
About External Code
Installer VISE extensively supports the addition of custom code to perform additional
functions required by your installer. This custom code can be in the following forms:
■
Code resources
■
Shared libraries
■
UNIX scripts
For information on how to create custom code to use with Installer VISE, see Chapter
32-Creating External Code.
Once your custom code is ready, your options for assigning it depend on the installer
platform. The platforms available for creating Installer VISE installers, along with the
custom code that each platform can call, are as follows:
Installer
platform can call
this custom
code:
68K
Code
PPC
Code
Classic (68K)
✓
✓
PowerPC
✓
✓
Carbon
PPC
Shared
Lib
Carbon
Code
Carbon
Shared
Lib
Script
✓
✓
✓
✓
Table 9-1: Custom code options by installer platform
9–2
About External Code
Installer
platform can call
this custom
code:
68K
Code
PPC
Code
PPC
Shared
Lib
Carbon
Code
Carbon
Shared
Lib
Script
Unified*
✓
✓
✓
✓
✓
✓
PowerPC Shared
Lib Data
✓
✓
✓
✓
✓
✓
Carbon Shared
Lib Data
Table 9-1: Custom code options by installer platform
*To call external code from a Unified installer, you will need to
use two versions of each external code–one version designed for nonCarbon platforms and one designed for Carbon. You should declare
both versions of your code under one name and call that name when
appropriate (see “Declaring External Code in an Installer” on page 9-4
and “Specifying When to Call External Code” on page 9-7).
At install time, the Unified installer will execute the appropriate installer and external
code for the OS in use. On Mac OS X or OS 8.1 - 9.x with CarbonLib version 1.1 or
newer, the installer will execute Carbon code. Otherwise, the installer will execute
non-Carbon code.
Overview of the steps to implement custom code in an installer:
1. Add the custom code to the installer.
2. Declare the code so that it is available in the installer.
3. Specify when the installer will call the code.
A description of each step follows.
Adding External Code to
an Installer
To add custom code to an installer:
1. From the Archive menu, select Show Project Window.
Illustration 9-1: Show Project Window menu item
Chapter 9 Assigning External Code
About External Code
9–3
2. If you want to add a code resource, select the Resource Files item in the Project
Window. To add a shared library or script, select the Scripts/Shared Libs item.
Illustration 9-2: Project Window Resource Files
3. Click the Add button and navigate to the code resource, script or shared library
containing your custom code.
Illustration 9-3: Select resource, script or shared library to add to the project
4. Click the Select button.
5. A dialog appears (either Resource File or Shared Library) showing the path to the
file containing your custom code. If you are using Build Directives you can make
9–4
About External Code
these assignments here so that this custom code file will only be included in a built
installer if the build directive settings match.
Illustration 9-4: Resource File dialog
6. Click the OK button.
7. The custom code is now attached to the archive. Save the changes to your archive.
Another way to add an external code resource is to paste it into the
archive’s resource fork using a resource editor such as ResEdit or Resorcerer. A disadvantage of this method is that the code resource does not
appear in the Project window, which prevents the use of build directives.
Declaring External Code in After you add custom code to an installer, the next step is to declare the code to make it
available in the installer. (If you are working with resource files, you will want to have
an Installer
their resource ID numbers handy.)
External codes will be called in the order that you declare them. (This
ordering appears in the External Code List dialog box.) When you set up
your installer to call more than one external code at a time (after installing
an item, for example), be sure to declare those codes in the proper order.
To let the installer know it should look for custom code:
1. From the Archive menu, select External Codes... The External Code List dialog
box will be displayed.
About External Code
9–5
2. Click New Code. The Edit External Code dialog box will be displayed. (The illustration below shows a sample Code Resource entry.)
Illustration 9-5: Edit External Code, Code Resource
The following illustration shows a sample Shared Library entry.
Illustration 9-6: Edit External Code, Shared Library
Whether you’re working with external code resources or shared libraries,
you have the option to declare two different external codes under one
name. This practice is necessary for Unified installers, and may also be useful if you plan to build installers for various platforms from your archive.
The benefit is that at runtime, Installer VISE will execute whichever code matches the
platform.
9–6
About External Code
3. Enter the appropriate information for each field listed below:
Field Names
Enter
Name
The name you’ll use to identify the code. Example: “Get
Password”
RefCon
If desired, enter a 32-bit number to be passed to the code
resource so it can identify from where it was called.
For more information about the uses of a RefCon, see
“Resource IDs and Reference Constants” on page 32-1.
Table 9-2: External Code Name and RefCon Fields
Next, complete either step 4 or step 5, according to your external code type.
4. If you want to declare external code resources, click the Code Resource radio button and enter the appropriate information for either Non Carbon, Carbon or
both resource types.
Field Names
Enter
Type
The resource type of your code.
Example: Xcod
ID
The resource ID number of the code resource. Valid numbers
are 5000 to 9999, inclusive.
Table 9-3: External Code Resource Fields
OR
5. If you want to declare scripts or shared libraries, click the Scripts/Shared Libs
radio button and select a file from either Non Carbon, Carbon or both popup
menus. (If no selections are available, see the following note.)
Before you can declare a script or a shared library, you must first add it to the
installer (see “Adding External Code to an Installer” on page 9-2). Only files
that are listed in the Scripts/Shared Libs section of the Project window will be
available to declare.
6. Click OK.
Resources imported from external resource files whose ID is within 5000
and 9999 (inclusive) will be automatically set to preload and non-purgable.
Editing External Code
Information
To modify custom code information:
1. At the External Code List dialog box, select the code you wish to edit.
2. Click Edit. The Edit External Code dialog box will be displayed.
About External Code
9–7
3. Make changes to the information as needed.
4. When finished, click OK.
Deleting External Code
Information
To delete custom code that you no longer need:
1. At the External Code List dialog box, select the code you wish to delete.
2. Click Delete.
Specifying When to Call
External Code
Once you have added custom code to an installer and declared the code, the final step is
to specify when the installer should call the code.
There are three areas within an archive where custom code can be assigned for
execution during the install process:
1. Custom code can be assigned in the Installer Settings Advanced tab to be executed:
■
At Installer Initialization
■
Before Install
■
During the Event Loop
■
After Install
■
When the installer is quit
For more information about External Code and Advanced Installer Settings, see
“Assigning External Codes to an Installer” on page 14-28.
2. Custom code is assigned to files or folders through the Info dialog box and other
methods. The code may then be executed:
■
Before Install
■
After Install
For more information about file and folder options, see “Calling External Codes
Associated with an Item” on page 12-17.
3. Custom code is assigned to action items through the Info dialog box and other
methods. The options for custom code execution vary by action item. See “Assigning External Codes to Action Items” on page 8-44.
For complete information about the use of external codes, see Chapter 32-Creating
External Code.
9–8
About External Code
10–1
Chapter 10
Creating and Editing Gestalt Calls
About Gestalt Calls
Gestalt calls allow you to check for features available in the current operating system.
Gestalt calls can be assigned to an individual file or folder in the archive window detail or
in the item’s Get Info window (see Chapter 12-Setting File and Folder Options) or as
minimum requirement for the entire installation (see Chapter 14-Setting Installer
Options). To change the available gestalt calls for the minimum requirements, you must
use ResEdit (see Chapter 33-Gestalts for Minimum Install Requirements).
You can create and edit gestalt calls that will be assigned to files and folders from within
the application, without using ResEdit. Installer VISE contains 25 pre-defined gestalt call
options which you may edit or delete. You may have no more than 63 gestalt call options
in an installer. You can delete gestalt entries which you will not need so that you may create new ones.
The default setting is for gestalts to be checked only during an Easy Install. If you wish
gestalts to be checked during a custom install, select Check Gestalts on Custom Install in
Installer Settings/Interface tab.
Creating and
Modifying Gestalts
Gestalts are created and modified in the Edit Gestalt dialog box, displayed below:
Illustration 10-1: Edit Gestalt
10–2
Creating and Modifying Gestalts
■
Name contains the name you assign to the gestalt so that you can recognize it
easily when assigning it to an item in the archive. The name may be up to 31
characters long.
■
Selector is a four-character code that is passed to the Gestalt Manager. If you are
checking for an existing selector, you must enter its unique code. (Information
about gestalt selectors can be found in Inside Macintosh or obtained from the
company whose product you are checking for.)
■
Gestalt is a pop-up used to determine how the result of the gestalt check will be
evaluated. It contains the following items:
Gestalt
Meaning
Exists
This gestalt must exist. If it does, the
Condition and Value are evaluated.
Doesn’t Exist
This gestalt must not exist.
Doesn’t Exist or…
Either this gestalt must not exist, or
the Condition and Value checks
must be true.
Table 10-1: Gestalt popmenu
■
Condition checks the returned gestalt value against the value in the value field.
Values include:
Condition
Meaning
> (Greater than)
This gestalt must exist. If it does,
the Condition and Value are
evaluated.
< (Less than)
This gestalt must exist. If it does,
the Condition and Value are
evaluated.
= (Equal to)
This gestalt must exist, and the
Condition and Value checks must
be true.
<> (Not equal to)
The returned value must not be
equal to the one in the Value field.
Bit set
The bits set in the Value field must
be set in the returned value.
Bit clear
The bits returned must not include
any of the bits in the Value field.
Table 10-2: Condition popmenu
■
Value is the hexadecimal number against which the returned value from the
gestalt call is compared. This number may contain up to 32 bits.
To set specific bits for the value field, hold down the mouse over the triangle to the
right of the Value field and select the desired bit. The correct hexadecimal number
Chapter 10 Creating and Editing Gestalt Calls
Creating a Gestalt Call
10–3
for the bits that are set will be displayed in the field.
To deselect a value, select it again so that a check is no longer displayed.
Before creating a gestalt call, make sure that you’ve read “About the Edit Gestalts Window,” above.
To create a gestalt call:
1. In the Archive menu, select Gestalts...
Illustration 10-2: Gestalts… menu item
2. The Gestalt List window will be displayed.
Illustration 10-3: Gestalt List
10–4
3. Click New. The Edit Gestalt window will be displayed.
Illustration 10-4: Edit Gestalt window
4. Enter the information for each field as required by your gestalt.
5. When finished, click OK to close the Edit Gestalt window and OK to close the
Gestalt List.
6. The new gestalt check is now ready to be assigned to items in your archive.
Chapter 10 Creating and Editing Gestalt Calls
11–1
Chapter 11
Setting Up Disk Information
Installer VISE allows you to name the disk images or folders that contain the installation
sets (if using one of these build options).
You may name the first disk image/folder and segment in the series and have Installer
VISE append the correct number to the rest of the disk images/folders and segments. A
caret (^) is used to request auto-incrementing, For example, if you name your disk
image “Install Disk ^,” then the first disk image will be named Install Disk 1, the second
will be named Install Disk 2, and so on.
Setting Up Disk
Information
To set up disk information for disk image or folder format installers that will
require multiple segments:
1. From the Archive menu, select Disk Names... The Disk Name List window will be
displayed.
2. Select Disk ^.
3. Click Edit Disk. The Edit Disk Name window will be displayed:
Illustration 11-1: Edit Disk Name
4. In the Disk Name field, delete “Disk ^” and type the name you wish to assign to
the first disk image or folder. If you wish to use auto-incrementing, append a “^”
to the end of the name (for example, “Install Disk ^”).
11–2
Setting Up Disk Information
5. In the Segment Name field, delete “Segment.^” and type the name you wish to
assign to the first segment. If you wish to use auto-incrementing, append a “^” to
the end of the name (for example, “Segment ^”).
If the Segment Name field is left blank, the segments will automatically be named
“Segment.1” on the first disk image or folder, “Segment.2” on the second disk
image or folder, and so on.
6. Hold down the mouse over the pop-up menu for Disk Size and select the maximum size that your segments should be.
7. Hold down the mouse over the pop-up menu for Segment Size and select the size
you wish each segment to be. To create segments at the maximum disk size, you
may select Custom and enter the same size used for Disk Size, or you may select
Fill Disk, which writes the maximum amount of data for each segment.
8. Make sure that Name Disk is selected. This renames the disk image or folder with
the name you entered at the beginning of the procedure.
Chapter 11 Setting Up Disk Information
12–1
Chapter 12
Setting File and Folder Options
Changing File and
Folder Options
Setting File and Folder
Options
Installer VISE allows you to set several options for each file and folder included in an
archive. The characteristics that you may change for a file and folder are slightly different.
Available options include the following:
■
Assigning new file types and creators.
■
Evaluating the result of a Find action item and installing or not installing the file
or folder based on the result.
■
Choosing a location where the item should be installed.
■
Assigning replacement instructions in case of a pre-existing item.
■
Assigning gestalts to be evaluated.
■
Assigning custom code to be called before or after the file is installed.
■
Choosing whether a file should be uncompressed and if so, on which installer
disk the uncompressed file should be located.
■
Selecting whether 68K, Power PC or fat binary versions of fat binary files will be
installed.
■
Determining whether the item is opened or launched when the installer is finished.
■
Selecting whether the computer should be restarted after installing this item.
■
Selecting where the item's Finder icon should be placed after installing.
■
Assigning an application and its required support files to be installed as an
application package.
■
Assigning group and permissions to the item for use in Mac OS X installs.
■
Setting the owner of the installed item to the root user.
File and folder options can be changed directly in the Archive Window Detail, or in the
Installer VISE Get Info window for a particular file or folder.
12–2
Setting File and Folder Options
Using the Archive Window To change options for a file or folder at the Archive Window:
1. Select the file or folder in the Archive Window Item List whose options you wish
to change. The Archive Window Detail will update to reflect the current attribute
values for the item
2. In the Archive Window Detail area, hold down the mouse over the appropriate
popmenu and select the desired option, as described in the next sections.
Illustration 12-1: Changing Item Options in Archive Window Detail
Using the Get Info Window To change options for a file or folder at the Installer VISE Get Info window for
that file or folder:
1. At the archive window, select the file or folder whose options you wish to change.
2. Click Get Info, press Command-I, or double-click the item. Depending on
whether the item was a file or folder, a window similar to one of these displayed
will be visible.
Illustration 12-2: Get Info Window for a File and a Folder
Chapter 12 Setting File and Folder Options
Shadow Items
12–3
3. Select options as described in the next sections.
4. To return to the archive window, click the Close box in the upper left corner or
press Command-W. If you haven’t saved your changes, you’ll be prompted to do
so unless you have turned off this warning in Preferences.
Shadow Items
Shadow Items are duplicates of an original archive item. What makes shadow items powerful install components is the fact that shadow items can have different options than the
original yet they do not take up more size in the archive. Shadow items allow install
options without adding to installer size.
To create a shadow item:
1. Select the original item in the Archive Window Item List.
2. Click the Duplicate button at the top of the Archive window.
3. A duplicate, or shadow, item will be created directly below the original in the item
list. The Shadow item name will be in italic as a visual indicator.
4. Set options for the shadow which are independent of the original. A shadow file
can have different Install If, Install To, Gestalt, Package assignment, Replace
options, etc.
In the example below, a message action is used to display a dialog to the user at install
time. The user will be able to click one of two buttons.
Illustration 12-3: Message dialog
In the VCT, the MyApp 1.0 item is set to install to the Startup Items Folder if the user
selected Startup ƒ in the message dialog. A shadow of the MyApp 1.0 item is set to install
to the Shutdown Items Folder if the user selected Shutdown ƒ in the message dialog.
Illustration 12-4: Shadow Items with Options Different from Original
12–4
Notes on Shadow Items
Item Options
There are several factors to consider when using shadow items in an installer:
■
Items which have been shadowed cannot be installed to an NT volume unless
the user has Admin privileges.
■
Shadows should always be after (below) the original item in an archive.
■
In order to install a shadow item, the installer must also install the original.
Item Options
The item options described in this section can be changed at the Installer VISE Get Info
window and in the Archive Window Detail if the field has been included in the current
Archive Window Layout. Each item below contains information about whether the
option is available for files, for folders, or for both kinds of objects.
Changing an Item’s Long
Name
You may use the Long Name field to assign a display name (up to 32 characters) for the
item when it is displayed in List Packages. The original file or folder name on your source
disk is not changed. Long Name allows you to add a list package display name that may
be more meaningful to your users than the file or folder name. The item will be installed
with its original name, not the Long Name.
Alternately, the Long Name field will accept up to 63 characters for files and folders that
you install on Mac OS X. If you assign the item to a package that is not a List Package, the
item will be installed with its Long Name of up to 63 characters.
Changing a File’s Language If you wish the file or folder to be installed based on a language check, hold down the
mouse over the Language popmenu. During installation, if the user’s computer is not of
the language specified, the item will not be installed.
If you wish language and region checks to be in effect for files and folders in
custom packages be sure to select Check Item Gestalts On Custom Install in
Installer Settings Interface tab. For custom packages (non-Easy Install) language and region checks are not performed unless Check Item Gestalts On
Custom Install is on.
Changing a File’s Region
If you wish the file or folder to be installed based on a region check, hold down the
mouse over the Region popmenu. During installation, if the user’s computer is not of the
region specified, the item will not be installed.
When there are check marks on items in both the Language and the
Region popmenus it represents an AND condition. Multiple check marks
within one popmenu act as an OR condition.
Changing a File’s Type
You may use the Type field to assign a new type to a file in the archive. The original file
on your source disk is not changed, but the installed version from the archive will be of
the new file type.
The default setting in this field is the original file type. To modify the file type, enter the
four-character string for the new file type in the Type field.
Item Options
Changing a File’s Creator
12–5
You may use the Creator field to assign a new creator to a file in the archive. The original
on your source disk is not changed, but the installed version from the archive will belong
to the new file creator.
The default setting in this field is the original file creator. To modify the file creator, enter
the four-character string for the new file creator in the Creator field.
Installing the Item Based
on an Action Item
The Install If option lets you choose to install or not install the selected item based on the
result of a an action item.
To use the Install If options:
1. To the right of Install If click in the space labeled (Click to Assign). The Select
Action Item window will be displayed.
2. Click the name of the action item you wish to use and click Select. The name of
the selected action item will be displayed in the space next to Install If.
3. If you want the item to be installed if the action succeeds, make sure that Succeeds
is displayed in the popmenu at the right of the action item’s name.
If you want the item to be installed if the action fails, select Fails from the popmenu at the right of the action item’s name.
If the selected action is a message action the popmenu choices will be the button
titles for the message dialog.
Install To Location
The Install To popmenu lets you choose the location where the item will be installed. To
assign a location, hold down the mouse over the popmenu to the right of Install To and
select from the following options:
Illustration 12-5: Default Install To Locations
12–6
Item Options
For a discussion of extended install to locations, see Chapter 36-Extended Install Locations.
locations exist, or deselect the Stop Install if “<type of action>“ Fails
Options that are not described below install the item in the selected location for the System defined in the Installer Settings/Behavior tab.
Install To:
Location
Install Folder
Installs the item in the same folder as it was located in your
archive.
Other…
Allows you to select another location for the item to be
installed. If the item is a file and you choose a file as the target
location, the file’s resources and data fork will be merged with
the file you choose (to retain the intended install location, your
source and target files must have different names). If the
selected item is a file or a folder and you choose a folder as the
target location, the file or folder will be installed inside the
folder you choose.
Ask User
Prompts the customer to identify the location on the system
where the item should be installed. A Standard Put File dialog
box will be displayed; if the customer clicks Cancel at the dialog
box, they’ll be asked if they wish to cancel the entire
installation.
Find Action
Result
Installs the item in the location that was the result of a predefined Find action item.
Root of Startup
Drive
Installs the item in the root folder of the startup volume.
Table 12-1: Install To Locations
Domain Location
Due to significant changes introduced in Mac OS X, a file that installs to one location on
Mac OS 9 may install to a different location on the new OS. In addition, a user’s access to
an install location may vary by the domain in use (System, Local, Network, User).
To help you manage install locations for the various platforms, Installer VISE offers the
Domain feature. You can use domains in conjunction with Mac OS X install locations to
easily install items where they will have the desired accessibility.
Setting a domain for archive
items (Mac OS X only)
Your options for setting a domain are:
■
On System Disk
■
On Appropriate Disk
■
System Domain
■
Local Domain
Item Options
Archive items that support
the Domain setting
12–7
■
Network Domain
■
User Domain
■
Classic Domain (This domain enables installers launched on Mac OS X to
install files to the Classic environment. It is not required for non-Carbon
installers, which will ignore domain settings.)
You can set a domain for any of these archive items:
■
File or Folder Info (defaults to User Domain)
Illustration 12-6: File Info showing Domain setting
■
Folder Defaults (these settings apply to entire folder contents)
Illustration 12-7: Folder Defaults showing Domain setting
■
Action items that do searches (Find, Delete, Copy, Move, Rename, Alias, Sub-
12–8
Item Options
launch and Edit Text File). These also default to the User Domain setting.
Illustration 12-8: Delete Action showing Domain setting
By using domains in conjunction with install locations, you can install to folders that are
specific to a given domain. For example, you could select the User Domain, Components
folder, which would install the item to a different location than if you select Local
Domain, Components folder.
For important information regarding Mac OS X install locations under the
various domains, see the Mac OS X Install Locations document included
in the Installer VISE folder.
Merging A File's Resources
and Data Into Another File
If desired, you may merge the resources and data of a file in the archive into the resources
and data of another file in the archive using the Other... option in the Install To: popmenu. Complete information about this topic can be found in the section “Merging
Files” on page 12-11.
Item Options
Installing the Item to the
Location of a Find Action
Result
12–9
You may choose to install an item to the location that was the result of a pre-defined Find
action item. In this case, the selected item in the archive will be installed in the same
folder as the item located by the Find action item.
To install the file or folder in the archive to the same location on the target system as the item located by a Find action:
1. From the Install To popmenu, select Find Action Result... The Select Find Action
window will be displayed.
2. Click the name of the desired Find action item.
3. Click Select. You’ll return to the archive window or the Get Info window, with the
name of the selected Find action item displayed in the popmenu.
Default Locations of
Common File Types
Installer VISE assigns a default location to certain types of files that are added to an
archive. The default locations for certain types of files are listed in the following table:
File Type
INIT
RDEV
PRES
fext
dsam
csam
ldev
LTMC
tbnd
adev
mdev
etpp
atlk
scri
dic1
dict
pdvr
drpt
ndrv
expt
shlb
thng
AINI
PRER
detf
msam
dash
libr
cbnd
fbnd
ddev
appe
ttpp
help
dic0
dic2
vbnd
pext
uspt
comd
CLMP
sclr
Install Location
Extensions Folder
cdev
APPC
Control Panels Folder
APPD
dfil
DFIL
da
Apple Menu Folder
Table 12-2: Default Install Locations for Common File Types
12–10
Item Options
File Type
Install Location
ffil
tfil
FFIL
cfil
LWFN
fnt
sfnt
ttcf
Fonts Folder
mlts
Modem Scripts Folder
oded
Editors Folder
sdev
Control Strip Modules
Folder
utbl
ecpg
Text Encodings Folder
cmpi
Contextual Menu Items
Folder
osax
Scripting Additions
Folder
prof
ColorSync Profiles
Folder
pltn
thme
scen
Theme Files Folder
tsnd
Sound Sets Folder
issp
Internet Search Sites
Folder
dlct
Scripting Dialects Folder
pref
Preferences Folder
fbce
Find by Content Plugins Folder
almn
Location Manager
Modules Folder
lcfl
Language & Region
Support Folder
Table 12-2: Default Install Locations for Common File Types
Item Options
12–11
By default, if all the files in a folder are installed to a different location than
the folder itself, the folder will not be created. (For example, if you have a
folder that only contains system extensions, and the extensions are all
installed to the Extensions folder, then the folder that contained the extensions will not be created.) However, you may use the Install Empty Folders option in
Installer Settings/Behavior tab to force the installation of empty folders.
Merging Files
By using the Other... option in the Install To popmenu, you may merge the resources and
data of a file in the archive with another file in the archive, or you may merge a file in the
archive with a file that already exists on the customer’s system, located as the result of a
Find action item.
During the merge process, resources in the source file's resource fork are merged into the
destination file's resource fork. Data in the source file's data fork is appended onto the
end of the destination file's data fork.
Sample usage of this feature includes building an application on-the-fly based on the
configuration of the target system.
To merge the resources and data of a file with another file in the archive or to a file
located by a Find action item, follow these steps:
1. Make sure that the source file to be merged (the one that is currently selected)
appears in the archive window after the destination target file in the archive (the
one that will receive the resources and data) or the Find action item that locates
the target file on the customer’s system.
When merging the resources and data of one file with another, the two
files must use different names. Otherwise, the target file will not reside
at the intended install location following the merge.
2. In the Install To popmenu, select Other... The Select Destination window will be
displayed, listing the names of all the files, folders, and Find action items in the
archive.
3. Click the name of the target file with which you want to merge the current file’s
resources and data or the name of the Find action item whose result on the customer’s system is the target location for the file’s resources and data.
name of the target file or action item displayed in the Install To popmenu.
Installing a File or Folder
To Another Folder in the
Archive
If desired, you may install a file or folder in the archive within another folder in the
archive that you specify. Even though the item isn’t contained within the folder in the
archive, it will be installed to the folder when the installer is run. To install a file or folder
within another folder in the archive, follow these steps:
1. Make sure that the file or folder you wish to install within a folder (the one that’s
currently selected) appears in the archive window after the destination folder.
2. In the Install To popmenu, select Other... The Select Destination window will be
displayed, listing the names of all the files, folders and action items in the archive.
(If the item you selected is a folder, only the names of folders in the archive will be
displayed.)
12–12
Item Options
3. Click the name of the folder where you want the selected item to be installed.
name of the target folder displayed in the Install To: popmenu.
Replacing Existing Items
on the Target System
This option is available at the archive window or the Get Info window for both files and
folders.
Setting Replace options for a folder won’t affect the folder itself; instead,
the Replace settings selected for a folder will be applied to all the files that
are contained within the folder.
The Replace popmenu lets you determine the circumstance under which an existing file
will be replaced if a version of the file being installed is already on the target system. By
default, these settings use the modification date of the item.
To choose replacement options, hold down the mouse over the popmenu to the right of
Replace and select from the following list:
Illustration 12-9: Replace Popmenu
Replace Option
replaces an item if the item in the archive
is newer than the item on the target
system. This is the default setting.
If Newer
If Newer or Equal
If Older or Equal
If Older
Description
is newer or equal to the item on the target
system.
is older or equal to the item on the target
system.
is older than the item on the target system.
Table 12-3: Replace Options (Sheet 1 of 2)
Item Options
12–13
Replace Option
If Different
Description
replaces an item if the item on the archive
has a different creation date, modification
date, file size, file type, or file creator than
the item on the target system. (The
contents of the item are not evaluated.)
installs the item from the archive only if
the item exists on the target and the
modification date of the item in the
archive is newer than the one on the target
system.
If Exists
Compare Modification Dates
forces the comparison above to be based
upon modification dates of the files.
Compare Creation Dates
upon the creation dates of the files.
Compare Version
upon the version of the files.
Always
replaces the item on the target system with
the item in the archive.
never replaces an existing item on the
target system, installs the item only if the
item does not exist on the target system.
Never
installs the item if it does not already exist.
If the item does exist, a dialog box is
displayed allowing the customer to choose
whether to install the item in question.
Ask User
Ask if False
Rename Existing
is selected in addition to an item above the
separator line in the popmenu. If the item
above the separator line fails (e.g., “If
Newer” is selected but the item in the
archive is older), the customer is given the
option to install the file in the archive
anyway. This option applies to all Replace
flags except “Always” and “Ask User.”
when a conflict situation arises the
existing file will be renamed rather than
replaced.
Table 12-3: Replace Options (Sheet 2 of 2)
Assigning Build Directives Build Directives can be set for a file or folder either from the Get Info window or from
the Archive Window detail if the Build Directive field has been included in the current
to Files and Folders
layout. The Standard archive layout contains the Build Directive popmenu and you can
add it to any custom layout.
12–14
Item Options
To assign a build directive to a file or folder:
1. If you want to limit the inclusion of a file or folder to specific installer builds, with
the item selected in the archive window item list, hold down the mouse over the
Build Directives popmenu.
Build Directives serve as limiting agents for archive items. If no build directives are
checked, the inclusion of the file or folder in an installer build will not be limited.
Another way to say the same thing would be that if no items are checked in the
Build Directive popmenu, this item will always be included when an installer is
built.
Illustration 12-10: Setting Build Directives for a file
The Build Directives popmenu will display any build directive that has been set up
in the Build Directive window as well as the Any Match item.
If only one build directive item is checked, as in the example below, this item will
be included in the built installer only when that build directive is in effect.
Checking multiple items in the Build Directive popmenu will result in an AND
condition. In the example below, this item will be included in the installer when
the Debug Build AND the English Release build directives are in effect.
The Any Match item causes an OR condition to be in effect for any other checked
items.
In the example below, this item will be included in the installer when Debug Build
OR English Release is in effect.
If Any Match is the only item checked in the Build Directive popmenu, this file or
folder will never be included when an installer is built.
If no items are checked in the Build Directive popmenu, this file or folder will
Any item in the Archive Window item list including action items, files and
folders, which has no build directives specified will always be included in
the built installer.
Item Options
12–15
Storing the Item
Uncompressed in a Disk
Image or Folder
This option is available at the archive window or the Get Info window for both files and
folders.
For Disk Images or Folders
The Disk popmenu lets you specify which disk image or folder in the installer set will
contain the item. The default setting is In Archive, which places the compressed items in
the archive. If you specify a certain disk image or folder to contain the item, it will be
placed uncompressed on that disk image or folder when the installer is built. (There is no
way to place a compressed file on a specific disk image or folder.)
To assign an item to be stored uncompressed on a specific disk image or folder, hold
down the mouse over the popmenu to the right of Disk and select the name.
By default, an installation will fail if the uncompressed file is not found on
a disk image or folder. However, you can set the installer to succeed if
uncompressed files are missing by selecting Uncompressed Files are
Optional in Installer Settings/Behavior tab.
For CD Installations
By default, all the files in an archive for a CD installation will be uncompressed when you
build the installer. However, you may specify that you only want certain files to be
uncompressed. In this case, only the files that you specify to be uncompressed will be
uncompressed, and the rest of the files in the archive will be compressed, even though
you didn’t change any settings for them.
To specify that certain files be uncompressed for a CD installation:
1. Set up the archive for a CD installation as described in Chapter 19-Creating CD
Installers.
2. Select the item(s) that you want to store uncompressed on the CD.
3. In the archive window detail or in the item’s Get Info window, select the name of
the CD that you entered when you set up your disk names from the Disk: popmenu.
By assigning a specific item or items to be uncompressed, all the other items whose Disk:
options are still set to “In Archive” will be compressed in the built installer on the CD.
For more information on building CD installers, see Chapter 19-Creating CD Installers.
Installing the Item Based
On a Gestalt Check
This option is available at the archive window or the Get Info window for files, folders,
and action items.
12–16
Item Options
The Gestalt popmenu lets you select the gestalt calls that will be made to evaluate the target system.
Illustration 12-11: Gestalt popmenu contents
Gestalt evaluations assigned to a file can not be overridden by the customer. To assign a
gestalt, hold down the mouse over the popmenu to the right of Gestalt and select the
desired gestalt(s) from the list.
Gestalts and Any Match
The Any Match item causes an OR condition to be in effect for any other checked items.
Illustration 12-12: Gestalt menu with Any Match checked
If the requirements of the gestalt call(s) are not met for a file, the file will not be installed
during Easy Install. If a folder has a gestalt which fails, the entire folder will not be
installed. If an action item has a gestalt which fails, the action will not be executed.
By default, gestalts are only evaluated during an Easy Install. To evaluate gestalts during
Custom Install, select “Check Item Gestalts on Custom Install” in Installer Settings/Interface tab. For more information, see “Custom Install Options” on page 14-9.
Gestalt calls that are assigned here only determine whether that particular item will be
installed or executed. To evaluate minimum install requirements for an entire installation, use the Gestalts popmenu in the Installer Settings/Attributes tab. For information
about creating gestalt calls, see Chapter 10-Creating and Editing Gestalt Calls.
Setting Fat Binary Install
Options
The Install Fat Binary On popmenu is only active for application files that contain fat
binary code.
Item Options
12–17
By default, fat binary code will be installed on all platforms. This menu lets you override
the default and install fat binary code only on a single platform, or never at all. Available
options are listed below:
Option
Description
68K Architecture
installs fat binary code on 68K platforms.
PowerPC
Architecture
installs fat binary code on PowerPC platforms.
Ask User
lets the customer select whether fat binary code will be
installed. (You may use the Ask User Once on Fat Binary
Installs option in Archive Settings/Behavior tab so that the
customer is only asked once, regardless of how many fat binary
files are in the install set.)
Install “PPC
only” Alert
installs a 68K code resource in a PowerPC-only application that
warns the user of a 68K machine upon launch that they can not
run a PowerPC application on that kind of Macintosh. (This
replaces the System-generated message that an error of type
-192 has occurred.)
Table 12-4: Fat Binary Install Options
To change the fat binary install options, hold down the mouse over the popmenu to the
right of Install Fat Binary On and select or deselect the desired settings.
To ensure that fat binary code is never installed, make sure that 68K and
PPC are not selected. In this case, the installer will only install the version
of the application that applies to that machine.
Assigning an Item to
Packages
This option is available in the archive window detail, archive window columns, or the in
the Get Info window for files, folders and action items.
The Packages popmenu lets you assign the selected item to packages. To assign the item
to a package, hold down the mouse over the popmenu and select the name of the desired
package.
For complete information about working with packages, see Chapter 7-Creating Packages And Assigning Files.
Calling External Codes
Associated with an Item
Calling External Codes Before This option is available in the archive window detail, archive window columns, or the
Get Info window for files, folders, and action items.
Installing the Item
The Before Installing popmenu lets you assign custom codes to be called before installing
the file or folder. To select a custom code, hold down the mouse over the popmenu to the
right of Before Installing: and select the name of the code. You may assign as many codes
as you wish.
12–18
Item Options
For information about creating custom code, see Chapter 32-Creating External Code.
Action Items have additional options for executing external codes. See Chapter 8-Creating Action Items.
Calling External Code After
Installing the Item
This option is available in the archive window detail, archive window columns, or the
Get Info window for files, folders, and action items.
The After Installing popmenu lets you assign custom codes to be called after installing
the file or folder. To select a custom code, hold down the mouse over the popmenu to the
right of After Installing: and select the name of the code. You may assign as many codes as
you wish.
Calling External Code When
Uninstalling the Item
Installer VISE can call external code when it installs or uninstalls an item. This feature is
active for every item that calls external code. Whether your installer calls external code
before or after it installs an item, the uninstaller will follow that order when it removes
the item.
Open After Installing
This option is available for files (including applications) and folders.
To launch the application after the customer quits the installer, select Open After Installing. This item is not selected by default.
■
If the Finder was shut down during the installation, the installer will attempt to
relaunch the Finder so that it can launch the application. To ensure that the
Finder is not shut down during installation, select Don’t Quit Finder During
Install from Installer Settings/Behavior tab.
■
If you select this option for more than one item, only the first application that
was installed with this item selected will be launched.
To open the folder after the installation is complete, select Open After Installing. This
item is not selected by default.
Deleting the Item During
Uninstalls
If this file or folder should be deleted if the customer chooses to uninstall the software,
make sure Delete on Uninstalls is selected in the Get Info window. (By default, this is
selected for every item set to Install Folder.)
If the file or folder should not be deleted if the customer chooses to uninstall the software, deselect Delete on Uninstalls.
In order to delete an empty folder on Mac OS X, an uninstaller will
attempt to remove the .DS_Store file if present.
Installing an Update File as The Install as Normal File option is only available for Installer VISE and Updater
VISE 1.4 update files. If this option is selected, the installer will simply install the update
a Normal File
file as a normal file rather than performing an update which is the default.
For complete information on update files, see Chapter 24-Including Update Files in an
Installer.
Restarting After Installing
an Item
The Restart After Installing option lets you choose to restart the machine when the
installation is complete if the file is being installed to the boot drive.
Item Options
12–19
A Contextual Menu item will default to Restart After Installing. If this is the
only install item set to recommend a restart, the installer will automatically
load the Contextual Menu after installing it, and not require a restart. This
convenient feature can help your customers start using your software as soon
as it’s installed.
Turning on the package restart flag will always ask for a restart if that package is selected unless no files were installed.
Don't Install Folder
(Placeholder)
The Don't Install Folder (Placeholder) option lets you identify a folder in your archive
as an organizational container only. This setting will override the Install Empty Folders
checkbox of Installer Settings.
■
If the Don't Install Folder (Placeholder) option is unchecked for an empty
folder (whether empty because it contains no items or because all of its items
are installed elsewhere) that folder will be installed according to the Install
Empty Folders Advanced Setting. For more information on this advanced setting, see “Miscellaneous Behavior Settings” on page 14-18.
■
If the Don't Install Folder (Placeholder) option is checked for a folder (regardless of whether the folder contains any items), that folder will NOT be installed.
Don't Retain Icon Position
The Don't Retain Icon Position option allows you to determine that a particular item
should not retain it's icon position from when that item was added to the archive. The
Finder will then place the icon for that item where it sees fit during the install.
Synchronizing Dates
Installer VISE can synchronize the dates of specified install items at build time, according
to the target used.
To enable synchronization for a file or folder, select Synchronize Dates in its Get Info
window. For information on setting up build targets to synchronize dates, see “Dates
tab” on page 27-17.
Installing Application
Packages
Introduced in Mac OS 9.0, application packages keep an application and all its required
support files together. Because they appear in the Finder as a single file, application packages also simplify the user’s experience.
Installer VISE makes it easy to install application packages on Mac OS 9 or Mac OS X.
On Mac OS X, applications may be packaged as bundles. These bundles
are similar to application packages in that they appear in the Finder as a
single file and keep applications and their required support files together.
Two ways that bundles differ from application packages is that bundles do
not utilize an alias to launch the application, and their internal structure is much
more strict. For information on creating Mac OS X bundles, please refer to current
Apple documentation.
12–20
Item Options
To create an application package:
1. Place your application and all support files into one or more folders, using any
organization that you prefer.
2. Place the folder(s) into a single folder.
3. Make an alias of your application, and move it to the top level of the main folder,
as illustrated in the example below.
Illustration 12-13: Macintosh Folder Window
4. Drag the folder into an Installer VISE archive.
5. Double-click on the folder item to display its Info dialog.
Illustration 12-14: Archive Window
Item Options
12–21
6. Click the check box next to Application Package to turn it on.
Illustration 12-15: Info Dialog
7. Click the Gestalt popmenu and select MacOS 9 or Greater (optional).
8. Close the dialog.
9. Build the installer.
Should you decide to install your application and its support files into regular folders,
turn off the Application Package setting before building your installer.
Installer VISE does not validate application packages. You should check
your application packages for any problems before you create a final build
of your installer.
Installing Application
Bundles on Mac OS X
On Mac OS X, applications may be packaged as bundles. These bundles appear in the
Finder as a single file and keep applications and their required support files together. (For
information on creating Mac OS X bundles, please refer to current Apple documentation.)
To install application bundles with Installer VISE, make sure that the Application Package option is set for the bundle in its Get Info window. Installer VISE automatically sets
this option for application bundles that you add to an archive.
12–22
Including an Uninstall Function in the Installer
To define the filename extensions that Installer VISE should use to recognize bundles, you can add the desired extensions to the text file “Bundle
Extensions.txt” in the Installer VISE Extensions folder. Installer VISE will
then treat folder structures with these extensions as bundles when you add
them to the archive or use them to set search criteria.
Also see “How Installer VISE Checks For Bundle Version” on page 8-15.
Cancel If Update Fails
The Cancel If Update Fails option is only available if the selected item is an Installer
VISE or Updater VISE 1.4 update file which is not set to be installed as a normal file.
If this option is selected and the installer fails to perform the update successfully, the
entire installation process will be canceled.
For complete information on update files, see Chapter 24-Including Update Files in an
Installer.
Symbolic Link
Symbolic links are a way to reference files and folders in the Mac OS X file system.
Because they refer to items by path, symbolic links are useful when the file or folder
should always exist at a specific location.
Installer VISE can properly install symbolic links on Mac OS X. To enable this feature,
make sure that the Symbolic Link option is checked for every symbolic link you add to
the archive.
Including an Uninstall
Function in the
Installer
Installer VISE lets you include an uninstall function directly into your installer.
If you include an uninstall function in your installer, it is available as an option in the
Packages popmenu where the customer selects Easy Install or Custom Install.
The Uninstall function performs the following operations:
■
Locates the items from the archive for which you selected Delete on Uninstall
that are installed on the customer’s system.
■
Performs all the action items for which you selected Perform on Uninstall at
the action item’s window. If you selected Stop Install if <Action> fails, then
failure of the action item will cause the uninstall function to quit.
■
If the customer has placed new items in a folder that is marked to be deleted on
an uninstall, the folder will not be removed. A message will be displayed informing the customer that the item has not been deleted.
By default, the uninstall function will only look for items in the location
that the installer thinks they were installed. To remove an item that may
have been moved to another location, use a Delete action item to identify
and locate the target file. (If you think the customer may have changed the
name of the item, identify it by type, creator and version number in the action item.)
Setting Up Your
Archive For Uninstalls
To set up your archive to include the Uninstall function:
1. Make sure that any item that you wish to remove on uninstalls has Delete on
Uninstall selected at the item’s Get Info window, and that any item that you don’t
wish to delete does not have Delete on Uninstall selected.
Folder Default Settings
12–23
2. Make sure that any action items that you wish to perform on uninstalls have Perform on Uninstall selected at the action item’s window.
3. In Installer Settings/Interface tab, select Show Uninstall in Installer Popmenu.
4. Click the Edit Uninstall Text… button and enter any explanatory text to be displayed when the user selects Uninstall from the Easy Install popmenu at the upper
left of the install window.
Folders within an archive can be set up with default settings so that whenever a new file
or folder is added to this folder, the default attributes will be assigned to the newly added
item.
To set up Folder Default Settings:
1. Open the Get Info for a folder by selecting the folder and clicking the Info button
at the top of the Archive window (or type Command-I) or by double-clicking the
folder.
Illustration 12-16: Folder Get Info window
12–24
2. In the folder’s get Info window, click the Setup Defaults button.
Illustration 12-17: Folder Default Settings
3. Make all settings changes which you wish to be default settings for all items at the
first level within the folder.
4. Click OK when done setting defaults.
5. Close the folder’s Get Info window.
To remove Folder Default Settings:
1. Open the Get Info for a folder by selecting the folder and clicking the Info button
at the top of the Archive window (or type Command-I).
2. In the folder’s get Info window, click the Setup Defaults button.
3. Click the None button.
4. Close the folder’s Get Info window.
About Folder Default
Settings
Folder Default Settings can be used before items are added to a folder so that new items
added get assigned the default settings. Folder Default Settings can also be used after
folders and files are arranged in the archive so that items in the folder will all be assigned
the default settings.
Notes on Folder Default Settings functionality:
■
Assignment of default attributes functions when a file or folder is added by drag
and drop from the Finder, by using the Add button or by Bring Up To Date.
■
Folder Default Settings will not be used when dragging an existing file in the
VCT into the folder.
■
Folder Default Settings will be applied to all items one level deep (but not
deeper) within the folder when the folder’s Get Info window is closed.
■
Folder Default Settings do not apply to items nested within folders. In the
example below, Folder Default Settings for Folder 1 would apply to Item 1, Item
Setting Group and Permissions
12–25
2 and Folder 1A but not to Item 3 and Item 4.
Setting Group and
Permissions
■
The Folder Default Install To setting will override the Always Set Install To
Install Folder setting in the Installer Settings Advanced tab.
■
Folders for which Default Settings have been made are indicated by a D on their
folder icon in the Archive Window and in the Get Info window.
■
Double-clicking on a folder in the archive while holding down the ‘D’ or the ‘d’
key will bring up the default folder settings dialog for that folder.
With support for groups and permissions, Installer VISE lets you control user access to
items you install on Mac OS X. These options are available in the Get Info window of
files and folders, as illustrated below.
Illustration 12-18: Group and Permissions Options
A thorough description of groups and permissions is beyond the scope of
this documentation. Accordingly, the following information focuses only
on how to set these properties with Installer VISE.
Overview
Each file and folder on Mac OS X has an owner, a group and a set of permissions that
apply to the owner, members of the group and all others. With Installer VISE, you can
manipulate these properties to control who can read, write and execute the item.
12–26
Setting Group for an Install The Group popmenu allows you to designate a group of users for the file or folder. You
may choose from one of three standard Mac OS X groups, or you may accept the group
Item
setting of the folder in which you install the item. Your options are as follows:
Option
Description
Default
With this option, the install item will use the group setting of
the folder in which it is installed.
Wheel
The installer will assign the install item to the Wheel group.
Staff
The installer will assign the install item to the Staff group.
Admin
The installer will assign the install item to the Admin group.
Table 12-5: Group Options
Setting Permissions for an After you choose a group for the install item, the next step is to set permissions. For this,
you will need to note the following:
Install Item
■
The owner of the item will be the person (according to the account in use) who
installs it.
■
The group for the item is determined by the forenamed Group setting.
■
Other includes anyone with access to the computer who is not the item’s owner
or a member of its group.
You may use the Permissions popmenu to set the following options:
Option
Description
Owner - r
The owner may read the install item.
Owner - w
The owner may write to the install item.
Owner - x
The owner may execute the install item.
Group - r
Members of the group may read the install item.
Group - w
Members of the group may write to the install item.
Group - x
Members of the group may execute the install item.
Other - r
Others may read the install item.
Other - w
Others may write to the install item.
Other - x
Others may execute the install item.
Table 12-6: Permissions Options
If you do not set group or permissions for an install item, Installer VISE
will install it with the permissions rwxrwxr-x (full access for everyone,
except Others have no write access) and a group of Staff.
12–27
When running Mac OS 9.0 or later, files and folders that you add to the
archive will retain any preset permissions.
Setting the Owner of an
Install Item to Root
As noted above, the owner of the install item will be the person (according to the account
in use) who installs it. For instances in which the owner of the install item must be the
root user, Installer VISE includes a “Set Owner To Root” feature that can be set for any
install item.
To enable the feature, check Set Owner to Root. You will also need to enable Mac OS X
authentication, which is set from the Attributes tab of Installer Settings. See “Assigning
Minimum Requirements for Installation” on page 14-22 for more information.
12–28
13–1
Chapter 13
Setting Icon Locations
Standard Icon
Positioning
When files and folders are added to an Installer VISE archive, their Finder icon positions
are included with the files and folder in the archive. If the icon positions need to be
changed, the source files can be moved and Bring Up To Date will update the archive
with the new positions.
Installer VISE’s standard handling of icon positions is sufficient for most situations.
There are cases however, when the icon positions of the source files are not the desired
icon positions for the files and folders when installed. Cases where standard icon positioning is inadequate include:
■
Source files are maintained by a source control system and file arrangements do
not match installation file arrangements.
■
Folders are created within the archive and therefore have no Finder position.
■
Source files coming from many locations may not have proper icon positions in
relation to other items in the installation.
■
Installed folder window settings may need to differ from those of the source.
The Set Icon Locations and Capture Icon Locations features documented
in this chapter are supported for pre-Mac OS X systems only. For information on how to set icon positioning for Mac OS X installs, see the following
MindVision knowledge database article: http://www.mindvision.com/
knowledge/kdb_1263.html.
Set Icon Locations
Installer VISE includes a mechanism by which icon locations and folder window settings
can be made to items in the archive. Set Icon Locations works only for folders and their
contents within the Archive window.
To set icon locations:
1. From the File menu, select Save. Set Icon Location is only available for folders
which have been saved in the archive.
13–2
Set Icon Locations
2. Select the folder in the Archive window for which you wish to set icon locations.
Illustration 13-1: Folder selected in Archive window
3. From the Archive menu select Set Icon Locations…
Illustration 13-2: Set Icon Locations… menu item
A disabled Set Icon Locations menu item indicates one of the following conditions:
Chapter 13 Setting Icon Locations
■
The archive has not been saved since items were added.
■
A folder has not been selected in the Archive Window Item List.
■
There is no archive currently open.
Set Icon Locations
13–3
4. A dialog will be displayed indicating that Installer VISE is waiting for completion
of the icon placement operation.
Illustration 13-3: Icon Position waiting for completion
5. Click the Finder button. The folder you selected in the archive and its contents
will be displayed within a Finder window.
Illustration 13-4: Sample Archive Materials before icon location change
6. Move items wherever you wish within the window. Finder View settings for the
window can also be set and applied.
Illustration 13-5: Sample Archive Materials after icon location change
13–4
Capture Icon Position and Catalog Only
7. When everything is arranged, close the windows open at the Finder and switch
back to Installer VISE from the application menu at the far right of the menu bar.
Illustration 13-6: Application menu
8. Click the Apply button to apply the changed icon locations and window positions
back to the items in the archive.
Illustration 13-7: Applying Set Icon Location changes
9. From the File menu, select Save to save your changed icon positions.
Capture Icon Position
and Catalog Only
Catalog only archives do not contain compressed copies of the archive items, they contain only a catalog of the files to be installed and non-file archive items (i.e. Action Items,
Splash Screens, Billboards, etc.). Catalog only archives are usually used for building
CD ROM installs.
To capture icon positions for a catalog only archive:
13–5
1. Check Only Store Catalog of Files in the Installer Settings Advanced tab.
Illustration 13-8: Installer Settings Advanced tab
When checking this advanced setting a warning will be displayed indicating the
one way nature of this setting.
Illustration 13-9: Catalog Only warning
13–6
2. Open the Project Window and set up a build target for a CD Installer.
Illustration 13-10: Build Destination for CD Installer
For more information on setting up Build Targets see “Build Directives” on
page 27-1.
3. When the archive is ready for the installer to be built, an initial build must be performed so that files and folders are placed in their build location.
Illustration 13-11: Build Installer before Capture Icon Location
Building a CD Installer will place a non-compressed set of files at the same location as the installer. For more information, see Chapter 19-Creating CD Installers.
4. At the Finder, arrange the icons of the files and folders in their build location.
13–7
5. Return to Installer VISE and select Capture Icon Position from the Archive
menu. When an archive is set to catalog only, the Set Icon Locations menu item
changes to Capture Icon Locations.
Illustration 13-12: Capture Icon Location menu item
The changed menu item indicates the change in the way this feature works for
archives that are catalog only.
6. A message will be displayed indicating that the icon positions have been successfully captured.
Illustration 13-13: Capture Icon Position Success dialog
7. Build your installer once again so that it contains the newly assigned icon positions.
13–8
14–1
Chapter 14
Installer Options
Installer Settings
The last step before building your final installer is to set general options for the installer,
such as the following:
■
Attaching a Read Me or multiple Read Me text files based on language.
■
Modifying settings, like forcing restarts or including a PowerPC decompressor.
■
Assigning minimum requirements for installation, including CPU, system, and
gestalt information.
■
Activating user authentication for installs on Mac OS X.
■
Attaching external codes to the general installer, instead of to specific items in
packages.
■
Entering informational text to be displayed in the installer window when Easy
Install is selected.
■
Entering informational text to be displayed in the installer window when
Remove is selected.
■
Attaching a custom icon to the installer.
■
Assigning Splash Screens to the installer.
To set options for the installer in Installer Settings:
1. Make sure that your archive is set up exactly as you wish. If you have made
changes to any of the source files, update the archive before building the installer
to ensure that the new files are part of the install set. (For more information, see
“Bringing the Archive Up To Date” on 20-1.)
14–2
Designing the Interface Display
2. In the Archive menu, select Installer Settings. The Installer Settings window will
be displayed:
Illustration 14-1: Installer Settings
Designing the
Interface Display
You have many choices to choose from as you design the interface of your installer. Select
the appropriate settings. Some settings are conditional upon other selections.
Choosing the Default
Language
To choose which default language will be used for installer interface elements, hold down
the mouse over the popmenu for Language. This popmenu will display all installer language files from the Installer VISE Extensions folder.
For more information about creating installers in different languages, see Chapter
29-Localization.
Setting the Default
Installer
By default, the Easy Install option is displayed to the customer after launching the
installer. If you wish for the Custom Install option to be displayed instead, select Custom
Install from the Default To popmenu. (A Custom Install option is not available if you
have not defined packages.)
Choosing the Installer
Interface
There are three primary Installer interface options as described in the table below:.
Option
Installer
Description
The standard installer interface. The button in the install
window will be named “Install” and progress dialogs will use
installation terminology.
Table 14-1: Installer Settings Display Interface Options
Chapter 14 Setting Installer Options
14–3
Option
Description
Updater
The button in the install window will be named “Update” and
progress dialogs will use update terminology. There must be a
Default Install Location set and at least one update file in the
archive before the Updater Interface can be used.
Generic
The button in the install window will be named “Continue.”
For Generic installers there is no dialog presented when no
items were installed. The Generic interface option is designed
for installers composed of only action items or composed of
actions where Install terminology might be confusing and/or
inaccurate to the end user.
Table 14-1: Installer Settings Display Interface Options
Setting Options for User
Navigation
An installer can be designated as having one of five navigation options:.
Option
Option as Displayed in an Installer
Disk Popmenu
.
Select Folder Button
.
Switch Disk Button
Select Folder &
Switch Disk Buttons
None
.
Table 14-2: Installer Settings Installer Navigation Options
14–4
Custom Install
Display Options
.
Option
Description
Display Billboards in Separate
Window
When selected, displays billboards in a separate
window, instead of above the progress gauge.For
examples of billboards displayed with this option
turned on and off see “Adding Billboards to an
Installer” on 15-1.
Use White Background for
Billboard and Splash
When selected the background for the Splash and
Billboards will be white rather than the default
gray. NOTE: When Display Billboards in Separate
Window is NOT checked the Use White
Background for Billboard and Splash will affect
the background for the progress/billboard
combination dialog.
Show Installer Window During
Install
When selected, the installer window will not be
hidden during an actual installation. The
progress and billboard dialogs will appear on top
of the installer window.
Table 14-3: Installer Settings Other Display Options
Choosing Interface Items to
Suppress
14–5
Under certain situations it may be advantageous to suppress installer interface items.
Suppress
Interface Element to be Suppressed
Main Window
Progress Stop
NOTE: It is the Stop button on the Progress dialog which is
suppressed, not the dialog itself.
Success
Table 14-4: Installer Settings Interface Suppress Options
Choosing the Default
Install Location
You may set up Installer VISE so that it chooses a default installation location on the customer’s system. If you allow other navigation options for the Install window, the customer may still choose to install the items to a different location.
14–6
A Find action item created in the Installer Settings window is used to determine the
default location to install files. Click on the Interface tab and locate Install Location.
Click the Set Default Install Location... button.
Illustration 14-2: Setting the Default Install Location
At the Default Install Location window, you may select Quit Installer if Find Fails. If the
item identified in the Search Criteria isn’t found, and Quit Installer if Find Fails is
selected, the installer will quit.
If Quit Installer if Find Fails is not selected, and the item identified in the Search Criteria
isn’t found, then the installation will default to the root directory of the startup drive.
If Return Parent of Found Item is checked, the Default Install Location will be set to the
enclosing item of the file or folder identified by the Search Criteria.
When searching for bundles, installers search by the name of the executable inside the bundle (in case the end user has changed the bundle name).
When checking for bundle version, installers use the bundle version inside
the .plist file in addition to the older-style 'vers' resource.
After clicking OK in the Default Install Location dialog, your search criteria is summarized in the Text field below the Set Default Install Location button.
Installing to the Applications As an alternative to setting the Default Install Location as described above, you may set
up your installers to default to the Applications folder, which is a common Mac OS X
Folder by Default
install location. Whenever possible, the installer will default to the root level Applications
folder, which allows read access to virtually any user. Otherwise, the installer will default
14–7
to whichever Applications folder is appropriate to the user’s access privileges. (For information about the available install locations, see the Mac OS X Install Locations document included in the Installer VISE folder.)
To set up your installers to default to the Applications folder:
1. From the Installer Settings window, click the Interface tab (if necessary).
2. Check the box for Use the “Applications” folder by Default and click OK.
Illustration 14-3: Installer Settings Interface tab
For non-Carbon installs, the default install location for Installer VISE
installers (when not set under Archive>Installer Settings>Interface) is the
root of the boot drive. On Mac OS X only, the default install location for
Installer VISE installers is the User Domain, Applications folder.
Adding Text for Display
During Easy Install
You may enter informational text to replace the generic text that’s displayed when the
Easy Install option is selected. To add informational text:
1. Click Edit Easy Install Text button.
14–8
2. In the box, enter the text that you wish to display. The text will appear exactly as
you type it in the box. (You may type more characters than can be displayed in the
box, but they may not be visible to the customer.)
Illustration 14-4: Edit Easy Install Text
As in the example above, you can use runtime variables in Easy Install text. The
runtime variables, represented by %VariableName%, will be replaced at runtime
with the values you set with constants or had set through the use of the Set Variable Action item. For a complete discussion of runtime variables see Chapter
28-Using Runtime Variables.
Other Easy Install Options
Option
Description
Show Sizes in
Easy Install
When selected, the amount of free space on the currently
selected drive and the amount of space required to install the
contents of the Easy Install package will be displayed in the Easy
Install window.
Display Easy
Install Package In
Progress
When selected, and the user selects Easy Install only the name
“Easy Install” will be displayed in the progress dialog.
Normally, the names of the files being installed show up in the
progress dialog.
Table 14-5: Installer Settings Easy Install Options
Custom Install Options
14–9
There are several installer options which apply to custom packages only.
Option
Description
Check Item
Gestalts On
Custom Install
When selected, gestalt, language and region settings assigned to
files and folders will be evaluated if the customer uses the
Custom Install option. This option is selected by default.
Show Easy Install
Package in
Custom Install
When selected, the installer will show the Easy Install package
as the first package available from a Custom Install.
Allow Only Single
Selections In
Custom Install
When selected, allows the customer to have only one custom
package turned on at a time from the Custom Install section.
Show “Select All”
Button
When selected, a Select All button will be placed to the right of
the Easy/Custom Install popmenu when viewing custom
packages. When this button is selected, all packages are
checked.
Table 14-6: Installer Settings Custom Install Options
Adding an Uninstall
Feature to Installers
If Show Uninstall In Installer Popmenu is checked, the Uninstall function is enabled in
the installer. An Uninstall menu item is added to the Easy Install/Custom Install pop
menu, the Install button is changed to Uninstall and the Uninstall text (if any) from
Installer Settings is displayed.
Illustration 14-5: Installer displaying Uninstall option
Preventing Shutdown of
Running Applications on
Uninstall
By default, the installer will shut down applications that are running during an uninstall.
To prevent this, check Don’t Shutdown Running Apps on Uninstall.
14–10
Adding Text for Display
During an Uninstall
Adding Read Me and License Agreements to the Installer
You may enter informational text to replace the generic text that’s displayed when the
Uninstall option is selected.
To add informational uninstall text:
1. Click Edit Uninstall Text… button.
2. In the box, enter the text that you wish to display. The text will appear exactly as
you type it in the box. (You may type more characters than can be displayed in the
box, but they may not be visible to the customer.)
Adding Read Me and
License Agreements to
the Installer
Installer VISE allows you to create and attach separate Read Me files and License Agreements. Select Installer Settings from the Archive menu. Click on the Text Files tab.
Illustration 14-6: Installer Settings Text Files tab
Requirements For Read Me
and License Agreement Files
Using SimpleText
Read Me and License Agreement files must be of type TEXT. If the file contains a ‘styl’
resource, then style information will automatically be included.
Assigning a Read Me File
The Read Me file which you assign here will be the first item visible after the splash screen
when the installer is being used. (If you don’t use a splash screen, it will be the first item
visible.)
To add a picture to a SimpleText document, type Option-Space at the location where the
picture should be located. Pictures must then be added to the resource fork of the document as PICT resources starting with ID 1000.
If you don’t wish the Read Me file to be automatically displayed after the installer is
launched, select Don’t Display During Launch
If you do not assign a Read Me file, then the Read Me button will not be visible to the
customer during installation.
Assigning the File
To assign a Read Me file:
1. Click the Add button. A standard file dialog box will be displayed.
14–11
2. Navigate the dialog box until you select the ReadMe file you wish to use.
Illustration 14-7: Select Read Me Text File
3. Choose Relative to .vct or Absolute Path from the Path popmenu.
4. If you wish this Read Me to be the one used for a specific language, select the language from the Language: popmenu.
5. Click Select. The language and pathname of the file will be displayed in the Read
Me Files scroll list.
6. To view the Read Me file as it will be displayed to the customer, click View.... To
Remove the file, click Remove. To select a different Read Me or to edit the Path or
Language settings, click Edit…
Attaching a License
Agreement
If you attach a license agreement in Installer Settings Text Files tab, the user of the
installer you build will be presented with a window like the one that follows. The user
will need to click the Accept button before any installation can take place. If the user
declines the license agreement, the installer quits.
14–12
To assign a text file as a license agreement:
1. Click Add. A standard file dialog box will be displayed.
2. Navigate the dialog box until you select the license agreement file you wish to use.
3. Choose Relative to .vct or Absolute Path from the Path popmenu.
4. If you wish this License Agreement to be the one used for a specific language,
select the language from the Language popmenu.
5. Click Select. The language and pathname of the file will be displayed in the in the
License Agreement Files scroll list.
6. To view the License Agreement as it will be displayed to the customer, click View...
at the bottom of the window. To remove the file, click Remove. To select a different license agreement or to edit the Path or Language settings, click Edit….
Read Me and License
Agreement Display Options
Display options for both Read Me files and License Agreements can be found in the
Installer Settings Text Files tab.
Read Me Display Option
Don’t Display During Launch
Result
When checked, a Read Me screen will not be
displayed during installer launch even if there is a
Read Me file in the list. The Read Me can,
however, be accessed from the popmenu at the
upper left of the Install window.
Table 14-7: Read Me and License Agreement FilesDisplay Options
Extra Installer Options
14–13
Read Me Display Option
Result
Don’t Display Lang. Popmenu
When checked, the Language popmenu for the
respective items (Read Me files or License
Agreement files) is no longer available in the
built installer.
Force Scroll Before Accept
When checked, the customer will need to scroll
to the bottom of the License Agreement before
the Accept button will be enabled.
Table 14-7: Read Me and License Agreement FilesDisplay Options
The Installer Settings Extras tab has areas for setting a log file which your installer can
automatically produce during the install process, for setting up on-line registration and
for setting installer Splash Screens which appear when the installer is launched.
Illustration 14-8: Setting an Installer Splash Screen in Installer Settings
Installer Log File
If Create Log File During Install is checked, the installer will produce a text log at the
location designated by the Location popmenu with a name designated in the Log File
Name text field. The Options popmenu contains replace options for log file.
To set up your installer log file:
1. Check Create Log File During Install from the Installer Settings Extras tab.
14–14
2. Select a location to which the log file can be saved from the Location popmenu.
Illustration 14-9: Log File Location
You can choose to have the log file created in the Install folder, on the root of the
hard drive, in the Installer Logs folder, or in any folder installed by the installer.
3. Type in a log file name in the Log File Name text field.
4. Set the desired log file replace options from the Options popmenu. Log file
replace options are described in the table below.
Replace Option
Description
Always Replace
If the installer finds an identically named item at the location it
has set to save a log file, the pre-existing item will always be
replaced.
Append to
Existing
has set to save a log file, the new log file information will be
appended to the end of the pre-existing item.
Auto-suffix
has set to save a log file, the pre-existing item will be renamed
with a suffix.
Table 14-8: Log File Replace Options
A Carbon installer will set the creator of the Installer Log File to ‘text,’
which enables the file to launch natively on Mac OS X. (For non-Carbon
installs, the Installer Log File creator is ‘ttxt.’)
On-line Registration
The on-line registration module provides a means for your users to quickly and conveniently register your product during the installation process. The end result should be a
higher percentage of users registering your product and more complete information
from the user.
To enable the on-line registration module:
1. Select Include On-line Registration Module from the Installer Settings Extras
tab.
2. Select Add to File Menu if you wish a Registration menu item to be added to the
Installer’s File menu.
14–15
3. From the Display Registration popmenu select when in the install process you
wish the registration form to be displayed to the user.
4. From the Registration Form popmenu select which form to display for registration.
For complete information on setting up forms see Chapter 34-Installer VISE
Forms.
For complete information on setting up the on-line registration module see
Chapter 35-On-Line Registration.
You may add a custom splash screen to greet the customer when your installer is
launched. Both 1-bit and 8-bit splash screens may be added so that the screen appears
correctly regardless of the customer’s target system. You can use any illustration program
to create the 1-bit and the 8-bit images.
You may wish to restrict the size of your splash screen to 512 by 342 pixels, the size of a
standard 9" monitor screen. If you use a larger splash screen, it will appear centered if the
installer is run on a 9" monitor, and the Continue button will not be visible on the
screen.
To add a splash screen:
1. Select and copy the picture you wish to use to the Clipboard.
2. In Installer VISE, click on the Extras Tab in the Installer Settings dialog box.
3. In the Splash Screen panel, select B & W if the picture is
1-bit, or Color if the picture is 8-bit.
4. Press Command-V to paste the screen into the window.
Illustration 14-10: Edit Splash Screen
Although the image appears scaled within the dialog box, it will appear correctly
to the customer at the beginning of the installation.
5. After pasting, Select OK in the Edit Splash Screen dialog.
Although the image appears scaled within the Installer Settings Extras tab, it will
appear correctly to the customer at the beginning of the installation.
To remove a splash screen, select Clear from the Edit menu or paste a new screen
into the window.
14–16
Designing the Installer's Behavior
Adding the Screen Manually
If you wish to manually add the splash screens to the archive resource file, the black and
white screen must have resource ID 2000, and the color screen must have resource
ID 2001.
Designing the
Installer's Behavior
You can customize the installer's behavior including warning messages, installation destination options, and other installation choices. Select Installer Settings from the
Archive menu. Click on the Behavior tab.
Illustration 14-11: Installer Settings Behavior tab
Including or Excluding
Warnings
Option
Description
Ask User Only
Once on Fat
Binary Installs
If there are two or more Fat Binary files in the install set and
their Install Fat Binary ON options are set to Ask User, the
customer will only be asked once whether to install the Fat
Binary or the platform-specific application. All other Fat Binary
files in the install set will be set to the result of the question.
Shutdown
Applications
Before Installing
Causes all applications, to be shutdown before installation. The
Finder will also be shutdown unless Don’t Quit Finder During
Installs is checked on.
Don’t Quit
Finder During
Installs
There are three conditions under which an installer will try to
shut down running applications, 1) when installing files of type
DFIL or dfil into the Apple Menu Items folder, 2) when
anything is installed into the System file, and 3) when a package
is installed which has the restart flag turned on. Checking this
checkbox will keep the Finder from being shutdown even under
these three conditions.
Table 14-9: Installer Settings Warning Options
14–17
Option
Description
Force Restart
when
Appropriate
When appropriate, forces the customer's computer to restart
after installation. The customer will be warned at the beginning
of the installation that a Restart will be required, and given the
option to cancel installation at that time.
No Restart
Warnings
By default, the installer warns the customer if it needs to shut
down all running applications at the beginning of the install. If
you select this option, no warning message will be displayed to
the customer; the installer will automatically shut down the
running applications.
Table 14-9: Installer Settings Warning Options
Choosing Installation
Destinations
Option
Description
Install System
Folder Items In
Active System Folder, which places the items in the System
Folder of the boot volume. Destination Volume System Folder,
which places the items in the System Folder of the volume
where the customer chooses to place the rest of the items. Ask
User, which prompts the customer to choose in which System
Folder the items should be installed.
If Active System is
On A Locked
Volume, Ask User
Which System ƒ
to Use
This option is only enabled if Active System Folder is selected in
the Install System Folder Items In popmenu above. When
checked, if the active system folder is on a locked volume, the
user will be asked which system folder to install items into.
If No Fonts
Folder, Ask User
For Install
Location
This item applies only if fonts are part of the install set. If no
Fonts Folder is present on the customer's system, and items
were specifically assigned to the Fonts Folder, the customer is
asked whether to install the fonts in the System Folder or as a
Suitcase.
Create
Installation
Folder Named
When selected, the installer will create a folder with the given
name and install the items on the root level of the archive in it.
Allow Installation
To Mounted
Servers
When selected, allows the software to be installed over a
network to a remote volume. This option will not work for
installations that require file/folders to be installed into the
destination volumes System File or Folder.
Table 14-10: Installer Settings Destinations Options
14–18
Option
Description
Allow Installation
to UFS Volumes
When selected, allows the software to be installed to UNIX File
System (UFS) volumes. NOTE: The two major file systems on
Mac OS X are Mac OS Extended (HFS+), the traditional
Macintosh volume format, and UFS. Most users will have their
system installed on HFS+.
Allow User To
Choose Invisible
Folders (Carbon
only)
When selected, the installer will allow users to install items to
invisible folders on Mac OS X. By default, this option is
unchecked, in which case the installer will not display invisible
folders to the user during a Mac OS X install.
Table 14-10: Installer Settings Destinations Options
Miscellaneous Behavior
Settings
Option
Description
Don't Allow
Multiple Installs
If selected, the customer is not given the option to install
another package after a successful installation has occurred.
(However, they may quit the installer, then relaunch it and
install another package.)
Install Empty
Folders
If this setting is OFF the installer will not install an empty folder
if all of that folder’s items are installed elsewhere.
If this setting is ON the installer will install an empty folder if
all of that folder’s items are installed elsewhere.
If a folder has no items in it in the archive, this setting does not
apply. (The folder will be installed in this instance.)
NOTE: You can override this setting for individual folders in
your archive with the Don’t Install Folder (Placeholder)
option. The “placeholder” option lets you identify a folder in
your archive as an organizational container only, so that the
folder will never be installed (regardless of whether the folder
contains any items). For more information, see “Don't Install
Folder (Placeholder)” on page 12-19.
Uncompressed
Files Are
Optional
When selected and an uncompressed file is deleted from a
diskette, the installer will continue to function correctly. The
missing files will be skipped.
Modify File Date
When Merging
Resources
When resources are merged into another file, the file’s
modification date will be set to that of the merged file.
Table 14-11: Installer Settings Miscellaneous Behavior Options
14–19
Option
Description
Always Create
Moved Items
Folder
A Moved Items folder, called Developer VISE Moved Items, is
created in the System folder whenever the Installer needs to
move something during an install. This folder may then be used
from an external code. The System folder is determined by
selection in Installer Settings, Behavior tab, Destination panel,
Install System Items In. The Installer installs an extension when
the Moved Items folder is created. The installer will delete the
files it moved there, but will not delete the entire folder
contents or folder. The extension will delete the folder upon
restart and then delete itself.
Read Only Teach
Text Documents
When checked, TeachText documents (TEXT) will be installed
as read only documents (ttro).
Action Items
Ignore Hidden
Items
When checked, installers will ignore hidden Mac OS X items
during searches. A file or folder with the invisible bit enabled or
a name starting with “.” will be not be valid for search results.
Also, if any parents of an item are invisible as defined here, the
item will not be valid for search results.
Table 14-11: Installer Settings Miscellaneous Behavior Options
Sub Launch Locks
Sub-launch Locks allow you to control which interface items will always be displayed by
your installer when it is sub-launched from another Installer VISE 6 or greater installer.
Option
Description
Splash Screen
When checked in a sub-launched installer, the Splash Screen
will always be displayed regardless of the sub-launch options set
in the parent installer’s Sub-launch Action item.
License
Agreement
When checked in a sub-launched installer, the License
Agreement will always be displayed regardless of the sub-launch
options set in the parent installer’s Sub-launch Action item.
Read Me
When checked in a sub-launched installer, the Read Me will
always be displayed regardless of the sub-launch options set in
the parent installer’s Sub-launch Action item.
Billboards
When checked in a sub-launched installer, the Billboards will
always be displayed regardless of the sub-launch options set in
the parent installer’s Sub-launch Action item.
Table 14-12: Installer Settings Sub-launch Lock Options
Sub-launch Locks in a sub-launched installer will override any sub-launch
options set in the Parent Installer’s Sub-launch Action item. For more
information on the Sub-launch Action item see “Sub-launch Action
Options” on page 8-33.
14–20
Installer Attributes
You can customize your installer with your own installer icon, set your own size
Resource, allow more than one user to install at the same time, and define minimum
requirements for software installation. Select Installer Settings from the Archive menu.
Click on the Attributes tab.
Illustration 14-12: Installer Settings Attributes tab
Assigning a Custom Icon
You may assign a custom icon to the installer at the Installer Settings window. Icons that
you assign in this way will only be visible on computers using Mac System 7.0 or higher;
this method turns on the Finder bit for a custom icon and adds the icon resources to the
installer.
Installer VISE supports large (128x128 pixel) icons for crisp display on
Apple’s Aqua interface (Mac OS X). This size of icon will display properly
at all available views on computers using Mac System 7.0 or higher.
To assign a custom icon to the installer at the Installer Settings window:
1. Copy the icon to the Clipboard.
2. Click in the Installer Icon box so that it is selected.
3. Press Command-V to paste the icon from the Clipboard to the window. The icon
on the left displays in black and white; the icon on the right displays in color.
You can also drag and drop a file on the Install Icon dialog and it will use the icon
from that file’s bundle resource for the custom installer icon. Drag and drop is
supported for Mac OS X icon (.icns) files.
To remove a custom icon, click in the box and press Command-X.
Changing the
SIZE Resource
If your archive contains many files, or if you are using large billboards, you may need to
increase the memory partition of the installer. To find out, run your installer and look at
14–21
its memory usage in your favorite debugger or using “About this Macintosh” at the
Finder.
Option
Description
Minimum Size
Assign the minimum amount of RAM needed to launch the
installer.
Preferred Size
Assign the preferred amount of RAM needed to launch the
installer.
Table 14-13: Installer Settings Installer Memory Partition
For information on how including updaters in an installer automatically changes the
Minimum Size and Preferred Sizes for an installer see, “Installer Memory Requirements”
on page 24-2.
Setting Finder Flags
Option
Description
Set Installer
Shared Bit
When selected, the Finder's “Shared” bit is set for the installer.
This allows more than one person to run the installer at a time
from a shared volume.
Set Installer
Locked Bit
When selected, the Finder's “Locked” bit is set for the installer.
Table 14-14: Installer Settings Installer Finder Flags
14–22
Assigning Minimum
Requirements for
Installation
This area allows you to define the minimum system requirements for installing your
product. Minimum requirements can be assigned in the following ways:
Option
Description
Gestalt
Gestalt calls check if certain system requirements are met. You
may select as many gestalts from the following list as you wish.
Has Alias Manager
Has Apple Events
Has a 68K FPU
Has Help Manager
Has a MMU
Has Notification Manager
Has Power Manager
Has Color QuickDraw
Has 32-Bit QuickDraw
Has QuickTime
Has Script Manager
Has Time Manager
Has Virtual Memory
PowerPC Architecture
68K Architecture
No AUX Support
Has CarbonLib 1.1 or Greater
The gestalt calls for minimum requirements can not be
modified from within Installer VISE. If you need to change
these gestalt calls, see Chapter 33-Gestalts for Minimum Install
Requirements for instructions on modifying the GLST
resource.
CPU
Allows selection of the minimum CPU upon which your
software can be installed. The default setting is 68000.
System Version
Allows setting of the minimum version of the operating system
that your software requires. The earliest System that can be
defined is System 7.0.0 (the minimum System requirement for
Installer VISE). Use the Tab key to move between fields.
Physical RAM
Allows setting the minimum amount of installed RAM that
your software requires. You may enter up to 255 MB.
Quit Installer
if Not
Administrator
When checked on, the installer will display a message and
cancel the install if the user is not logged in as administrator.
Table 14-15: Installer Settings Minimum Requirements to Install
14–23
Option
Description
Require OS X
Authentication
When an install to Mac OS X requires special access privileges,
Installer VISE can prompt the user for user name and
password, and authenticate that information before
proceeding. If the user is already logged in as administrator, the
installer will simply relaunch itself to get authentication
privileges. Check this option on to enable such authentication.
Allow User to
Override
When checked on, the customer will be given the option to
install the software, even if one or more of the minimum
requirements for installation outlined above have not been met.
A dialog box will be displayed that states which requirement
was not met, and allowing the customer to choose whether the
installation should continue.
Table 14-15: Installer Settings Minimum Requirements to Install
Setting an Installer
Password
Installer VISE allows you to set up a password for an installer and to determine when the
password will be required.
Illustration 14-13: Installer Password Options
Setting a password will cause all data in your installer to be encrypted.
Auto-Validating Password
Auto-validating passwords provides a way to allow one installer to accept multiple passwords. Each customer can then be given a different password, which can be used for
tracking in software piracy cases. The algorithm used in authenticating the password is
by no means foolproof, but should provide a deterrent for the average user.
To set up an auto-validating password:
1. Enter a seed value in the Password field of the Installer Settings Attributes tab.
The seed value should be a number of 5 or 6 digits.
The seed value for your auto-validating password should not begin with
zero. You may use zero for any of the remaining digits, however.
2. Check the Auto-Validating Password checkbox.
3. Click the Generate button.
14–24
4. In the Generate Password dialog enter a starting value and how many passwords
to generate.
Illustration 14-14: Generate Password dialog
5. Pick a location to save the password list.
Illustration 14-15: Saving Password File
6. The text file generated will contain the initial password and the list of all self-validating passwords.
Illustration 14-16: Password file
Adding Advanced Features to Your Installer
Adding Advanced
Features to Your
Installer
14–25
Installer VISE allows you to select various compression settings, choose whether or not
to replace existing files in an archive and add external code. Select Installer Settings from
the Archive menu. Click on the Advanced tab.
Illustration 14-17: Installer Settings Advanced Tab
Compressing Files
Option
Description
Include PowerPC
Decompressor
When selected, adds a PowerPC version of the VISE
decompression engine to the installer for faster installations on
Power Macintoshes. This feature adds approximately 12K to the
size of the installer
Don’t
Recompress Data
When selected, data in the archive will not be recompressed
when you build the installer. This may result in larger installers.
Only Store
Catalog of Files
When this item is checked a Catalog Only installer will be
produced at build time.This item should only be used with CDROM installs where all the files to be installed will be
uncompressed. This feature creates an archive which only
contains a catalog of the files, saving the time required to
compress and decompress them. The installer is then created
using only the catalog, so the items in the archive must be
placed on the CD in the same hierarchy as they were placed in
the archive.
Don’t Copy Files
from Source at
Build Time
If this checkbox is turned on, when the installer is built, files
will not be copied from the build source to the build target. You
may want to turn this checkbox on if your build source and
build Target is the same location on your hard drive.
Table 14-16: Installer Settings Compression Options
14–26
Setting Only Store Catalog of Files for an archive is a one way street. Since an archive cannot be converted back to a standard archive of compressed files after this setting has been
saved, the warning below is displayed before the setting is saved.
Illustration 14-18: Catalog Only warning
Catalog Only archives cannot be used to build compressed installers.
When Only Store Catalog of Files is checked on, all Build Targets which
require compressed data will be automatically set to Ask at Build. For
more information on Build Targets see Chapter 27-Advanced Project
Management.
Adding Files to an Existing
Archive
Option
Description
Always Set Install
to Install Folder
When selected, new files added to the archive window are not
set to any other install location than the Install Folder. So Fonts,
Extensions, Control Panels, etc. will not be defaulted to the
appropriate folder. They will just be installed to the install
folder.
Update Archive
Files With Any
Difference
When selected and you update an archive, files that are different
in any way from the files already in the archive will replace the
ones in the archive.
Update Only Files
Already In The
Archive
When selected and you update an archive, only files that are
already in the archive will be evaluated during the update
process. Other files in the source folder will be ignored.
Don’t Update
Packages on
Imported VCT
Files
When selected, package assignments for embedded VCT items
will not be overridden (back to what they were in the VCT
before it was embedded) by a Bring Up To Date operation.
Ignore DS_Store
Files
When selected and you add a folder to an archive, DS_Store
files will not be imported. Also, when you update the archive
DS_Store files will never be marked to be added to the VCT as
new files.
Table 14-17: Installer Settings Builder Options
Option
14–27
Description
View Generic
Icons In
Windows
When selected, Installer VISE will not access the Desktop
database to show icons for items in the Archive window, Add
File Window, or Update window. Generic icons appear instead.
Perform
Intelligent
Filename Check
on Update
When checked, the similar filename check will be performed
when doing a Bring Up To Date. For more information on the
similar filename check see, “Replacing Similar Items During
Bring Up To Date” on page 20-3.
Show Size in
Your selection determines whether the size of the files in the
archive will be displayed as kilobytes or as bytes.
Table 14-17: Installer Settings Builder Options
Assigning a Resource File
The default resource file for the archive is the resource fork of the archive itself, so that
you don’t have to store icons and external code resources in a separate location.
External resource files can be attached to an archive from the Project Window (see Chapter 9-Assigning External Code). Assigning a resource file from Installer Settings has been
maintained in Installer VISE 5.0 and newer for compatibility purposes.
To assign a resource file to your archive from Installer Settings:
1. Click on the Installer Settings Advanced tab, locate the External Files section and
click Set Resource File... button. A standard file dialog box will be displayed.
2. Navigate the dialog box until you select the resource file you wish to use.
3. Click the Select button. The pathname of the file will be displayed in the field.
To remove a resource file assigned from Installer Settings, click the Remove button.
Assigning a Localization
File
Localization files can be attached to an archive from the Localization Window (see Chapter 29-Localization). The localization file set in the localization window will also appear
in Installer Settings. Assigning a localization file from Installer Settings has been maintained in Installer VISE 5.0 and newer for compatibility purposes.
To assign a localization file to your archive from Installer Settings:
1. In the Installer Settings Advanced tab, locate the External Files section and click
Set Localization File... button. A standard file dialog box will be displayed.
2. Navigate the dialog box until you select the item localization file you wish to use.
3. Click the Select button. The pathname of the file will be displayed in the field.
To remove a localization file, click the Remove button.
14–28
Assigning External Codes
to an Installer
Any custom external codes which you defined can be attached to the installer as well as to
individual files.
Illustration 14-19: Installer Settings Advanced tab, External Codes
Custom external codes may be called at the following times:
■
Initialization calls the code immediately when the installer is launched, before
anything is displayed to the customer.
■
Event Loop calls the code in the main event loop, before normal processing
occurs for that event. Sample usage: To override the regular call for help.
■
Installer Quit calls the code when the installer is quit. Sample usage: To free up
memory allocated in the System Heap from another call to external code.
■
Before Install calls the code after the install button is clicked and before any
files are installed. Sample usage: To check whether certain packages are selected
before beginning an installation.
■
After Install calls the code after the installation is complete but before a dialog
box is displayed to the customer. Sample usage: To bring up a dialog box so that
the customer can register your software package.
To attach a custom code to one of these items, hold down the mouse next to the name of
the item and select the code from the pop-up.
For information about creating custom codes, see Chapter 32-Creating External Code.
Option
Description
External Code Is
Optional
By default, any external code that needs to be called must be
present in the resource fork of the installer. When selected and
external code has been deleted from the installer, the installer
will function as if no external code was assigned to the files.
Allow Installer
Resources To Be
Replaced
When selected, you may include resources in the resource fork
of the archive file that replace the installer's own resources.
Disable Strict
Library Checking
When selected, this option prevents Installer VISE from
performing library checks before calling external code. This
checking is otherwise performed by default to prevent calling
an InterfaceLib-linked external code from a Carbon installer, or
a CarbonLib external code from a PowerPC installer.
Table 14-18: Installer Settings External Codes Options
Installer Settings for Web Installers
Installer Settings for
Web Installers
14–29
There are a number of Installer VISE options which apply specifically to web installers.
Those options can be found in Installer Settings Web tab. For more information on the
construction and deployment of web installers see Chapter 37-Active Web Installers.
Illustration 14-20: Installer Settings Web tab
Option
Description
Create Separate Catalog
When checked, a separate catalog file will be
created. This catalog enables the web installer
to self update when appropriate.
Store Installer Data in External
File
When turned on, the compressed data for the
installer will be put in a data file, instead of
the data fork of the installer application.
Data File Name
Name of the file to store the compressed data
in for the installation. This file is to be placed
in the same location as the installer.
Strict Installer Data Time Stamp
Checking
When turned on, the built installer will
require the time stamp of the installer and the
time stamp of the VISEICat.idx file on the
Web/FTP server to be the same. This will
require the VISEICat.idx file to be uploaded
to the Web/FTP site every time you build.
Table 14-19: Installer Settings Web tab Options
14–30
Saving Installer Settings
Option
Description
Upload Cab File(s) To Web Server
At Build Time (FTP Sites Only)
When turned on, Installer VISE will upload
CAB files to the FTP servers listed in the
Download Sites dialog. (Do not use this
feature if you have HTTP servers listed in the
Download Sites dialog.) This feature requires
the servers to have FTP “STOR” command
support.
Suppress Internet Dialup Dialog
Turning this checkbox on, prevents the
installer from displaying the “Please make
sure you have an active internet connection”
dialog to the user. You may want to turn this
on if you are assured the user will already have
an active connection.
Allow User To Choose Download
Site
When turned on, a popmenu will appear in
the “Please make sure you have an active
internet connection” dialog, allowing the user
to choose which site to download the data
from.
Suppress Internet Disconnect
Dialog
installer from displaying the “Disconnect
from the internet now” dialog to the user.
Byte Range Downloads
When turned on, Installer VISE will create a
single CAB file instead of using Group File
assignments. This feature allows for the
smallest and quickest downloads possible. It
also requires the web servers to be HTTP 1.1
compliant or FTP “REST” support.
Saving
Installer Settings
Installer VISE allows you to save your Installer Settings for use with another archive or so
that different Build Targets can have different Installer Settings.
You can save your final selections by selecting Save Setting As... from the Settings popup menu in the lower left corner of the Installer Settings window. Enter an unique name
for the setting file. Click the Create button.
Illustration 14-21: Saving new Installer Settings
14–31
Selecting Installer Settings From the Settings menu at the bottom left of the Installer Settings window you can
change the Installer Settings for the current archive to any other saved archive setting.
Illustration 14-22: Selecting a Different set of Installer Settings
Defaulting Installer
Settings
You may want to designate a saved Installer Settings file as the default settings for any
new archive.
To set a default archive setting:
1. Set up and save an archive setting file as described above.
2. Select Export Setting... from the Settings popmenu.
Illustration 14-23: Export Settings
14–32
3. Enter a name for the exported settings file.
Illustration 14-24: Exported Settings Name
4. The exported settings file will be saved in your Preferences, Installer VISE Settings
folder.
Illustration 14-25: Installer VISE Settings folder
5. Select Preferences… from the Edit menu.
Illustration 14-26: Preferences Menu Item
14–33
6. Click the Select File… button in the Preferences window.
Illustration 14-27: Installer VISE Preferences
7. Select the default Installer Settings file you wish to be used for new archives created with Installer VISE. Saved Installer Settings files are located at:
Illustration 14-28: Selecting the Installer Settings file for Default
Exported Installer Settings files are saved at the following path:
■
StartupDrive:System Folder:Preferences:Installer VISE Settings
Illustration 14-29: Installer VISE Settings
14–34
8. The name of the Installer Settings file will be displayed in the preferences window.
Any new VCTs will use this archive setting
Illustration 14-30: Preferences Displaying Default Installer Settings
Deleting Installer Settings
You can delete Installer Settings that you have created and saved.
1. Select Delete Setting... from the Settings pop-up menu in the Installer Settings
window.
Illustration 14-31: Deleting an Archive Setting
Installer Launches
14–35
2. A dialog appears. Select the appropriate archive and click Delete.
Illustration 14-32: Select Settings To Delete
3. Click OK to close the Installer Settings window.
Installer Launches
In addition to the ability to sub-launch other installers using the Sub-launch Action,
Installer VISE provides another mechanism for launching other installers before or after
the main installer.
To launch other installers before or after your main installer:
1. From the Archive menu, select Installer Launches.
Illustration 14-33: Installer Launches menu item
14–36
Installer Launches
2. In the Launch Installer List, click the New button.
Illustration 14-34: Launch Installer List
3. In the Edit Launch dialog enter a name for this launch item, a relative path to the
installer location on the CD (including actual installer name), and select whether
the installer will be launched before the main installer or after the main installer.
Illustration 14-35: Edit Launch dialog
4. Close the Edit Launch dialog and enter other Installer Launches or close the
Installer Launch List. When there are more than one installer to launch, a dialog
will be displayed in the top left of the users monitor showing which installer
launch is being executed.
Supporting Multiple Users Accounts
Supporting Multiple
Users Accounts
14–37
Introduced in Mac OS 9.0, Multiple Users Accounts can prevent users from installing
files where they shouldn’t. Installer VISE supports this security feature with every
installer that you build. On a system that uses Multiple Users Accounts, the Finder will
return an error if the user tries to install files without the proper privileges.
Illustration 14-36: Macintosh Privileges Error
14–38
Supporting Multiple Users Accounts
15–1
Chapter 15
Adding Billboards to an Installer
Billboards
Billboards are communication tools used during the install process for purposes ranging
from highlighting software features to encouraging user registration. Billboards are one
more avenue for installer personalization.
Illustration 15-1: Billboard as Displayed During Installation
15–2
Installer Settings
Billboard Display
Options
Installer Settings Billboard Display Options
During the install, billboards can be displayed together with the progress bar in the same
window (as in the example above), or displayed above the progress bar in a separate window (as in the example below).
Illustration 15-2: Billboard Displayed in Separate Window During Install
You also have the option of displaying splash screen and billboards against a white background or against the standard gray background. Both settings can be found in the
Installer Settings Interface tab.
Installer Settings Options
Explanation
Display Billboards in Separate
Window
When checked on, billboards will be displayed
in a separate window above the progress bar.
When unchecked, billboards will be displayed
together with the progress bar in one window.
Use white background for
Billboard and Splash
When checked, billboards and splash will use
white backgrounds rather than the standard
gray.
Table 15-1: Installer Settings Billboard Display Options
Billboard Display
Method
Billboards can be displayed sequentially, by disk or by package.
Display Method
Sequentially
Explanation
Billboards will be displayed in sequence during
the install. Billboard duration can be set per
billboard. If billboard durations exceed actual
install time, some billboards may not be
displayed.
Table 15-2: Billboard Display Methods
Chapter 15 Adding Billboards to an Installer
Assigning Billboards
15–3
Display Method
Explanation
By Disk
Billboards will be displayed by disk during the
install. If a disk is not used during an install, the
billboard assigned to that disk will not be
displayed.
By Package
Billboards will be displayed by package as the
package is installed.
Billboards can be set to be displayed sequentially, by package or by disk. The default setting is to display billboards sequentially.
It is recommended that all PICTs for billboards be the same size, as
Installer VISE will scale all billboards to the size of the first one displayed
by the installer.
To set up billboards:
1. Select and copy the picture you wish to use to the Clipboard.
2. At the Archive window, select Billboards… from the Archive menu. The Billboards dialog will be displayed.
Illustration 15-3: Billboards dialog
3. From the Display Billboards popmenu, select one of the following display
options: Sequentially, By Disk or Package.
15–4
4. If you’re setting up a sequential billboard, click the New button. Otherwise, skip
this step and continue with step 5.
5. In the appropriate Billboards section of the Billboards window (Sequential, Disk
or Package), click on the words “No Billboard.” (If more than one disk image is
listed, click the words above the leftmost one.)
6. Press Command-V to paste the graphic into the billboard. Although the image
appears scaled within the billboard box, it will appear correctly to the customer.
Illustration 15-4: Disk Billboards
7. Repeat this process to paste graphics into the placeholder for each billboard. Your
billboard entries should look like similar to the Disk Billboards example below.
Illustration 15-5: Disk Billboards with graphics
8. When you’re finished, click OK to close the Billboards window.
Selecting an option from the Display Billboards popmenu as described in
step 3 above will automatically set the same option for the active build
target. However, if you are using multiple build targets in your archive,
you must manually set the Display Billboards popmenu for each of the
additional targets. See “Display Billboards” on page 27-13 and “Active Build Target”
on page 27-21.
Using Billboard Files
Installer VISE supports the use of multiple billboard sets, called billboard files. Billboard
files allow you to create different sets of billboards for different languages or even to create different sets of billboards for the same language.
15–5
Billboard files are created and configured from the Billboard dialog, Billboard File popmenu.
Illustration 15-6: Billboard dialog Billboard File popmenu
The Billboard File popmenu contains:
■
Resource of Archive - The billboards assigned to Resource of Archive are the
default billboards. This set of billboards will be used by a built installer if these
are the only billboards in the installer or if the language specific billboards do
not match the language of the Mac OS under which the installer is being run.
■
The name of any billboard file added to the Project Window. Select the billboard file to edit the contents.
■
New Billboard File - selecting this item brings up a standard pick dialog where
an existing billboard file can be selected or a new billboard file can be created.
When a new billboard file is added from the New Billboard File item, the Project
Window is automatically opened and the newly added item is selected.
At the Project Window, Build Directives and Language can be set for billboard
Files. For more information on Billboard File settings accessed from the project
Window, see “Billboard Files” on page 27-27.
When the installer is built, all of the billboards which meet the build directive criteria are
merged into the installer. Resource IDs are renumbered to avoid conflicts. This allows a
multi-language installer to be built with language specific billboards. When the installer
is run, the billboards for the appropriate language will be displayed.
If the path to a particular billboard file cannot be resolved, then that item is grayed in the
Billboard File popmenu.
Illustration 15-7: Billboard File Item with Unresolved Path
Removing a Billboard
To remove a billboard:
1. Select Billboards… from the Archive menu. The Billboards dialog will be displayed.
15–6
2. Select the image you wish to remove and click the Edit button. The Edit Billboard
dialog is displayed. In the Edit Billboard window click the Clear button.
Illustration 15-8: Edit Billboard dialog
16–1
Chapter 16
Generating Archive Reports
Before creating a final installer, you can generate different kinds of reports to anticipate
problems that may arise.
Archive Reports
To generate an archive report for the current archive:
1. From the File menu select Page Setup.
Archive Reports (whether to Printer, Text File or Screen) will use the current Archive Window layout selection of columns.
For some Archive Window layouts, you may want to select a landscape orientation or adjust the scale percentage in order to show more of the
columnar data.
You may want to define an Archive Window layout specifically for archive reports.
After selecting your page setup options, select OK.
2. From the File menu select Print Archive Report.
Illustration 16-1: Print Archive Report
16–2
Archive Reports
3. In the Archive Report selection dialog you are presented with options for Report
to Print, Report Kind and Packages to include. From the Report to Print popmenu, select the desired report.
Illustration 16-2: Archive Report selection
4. From the Report Kind popmenu select the output option desired for the report.
Illustration 16-3: Archive Report output options
5. If the Packages popmenu is enabled you may limit the report to cover only chosen
packages.
6. Click the Print... button to generate the archive report.
Chapter 16 Generating Archive Reports
Generating Archive Reports
16–3
7. If To Text File was chosen, you are then asked for the saved report’s name and
location.
Illustration 16-4: Save Report As dialog
If To Printer is selected, the standard Print dialog follows.
Generating Archive
Reports
The following kinds of reports are available:
Report Type
Description
Packages
Provides a report of files to be installed organized by package.
You can select the packages for which you wish to view a report
from the Package popmenu. If you select a package or packages
from the popmenu, the report will only display information for
those packages; if you don’t specify any packages, the report will
contain information about all the packages in the archive.
Files
Provides a report of files to be installed organized by file.
Install Locations
Provides a report of install locations for each file in the archive,
including replace option, gestalt selector calls, information on
an Install If setting, information on an Execute If setting, and
(if uncompressed) disk assignment.
Diagnostic
Provides a report containing troubleshooting information,
such as files which are not associated with packages; packages
which contain no files; invalid resource IDs; missing external
codes; or external codes which are included in the archive but
have not been called.
Specific Packages
Lets you generate a report listing the files that are assigned to
the exact combination of packages that you select. For example,
if you only select Easy Install, the report will list any files that
are assigned to the Easy Install package but are not part of any
other package. If you select two packages, then the report will
list only the files that are assigned to both packages; items that
appear in one package but not the other will not be included in
the report.
Table 16-1: Archive Report Types
16–4
Report Output Options
Report Output Options
Installer VISE reports can be directed to a printer, to a text file or to the screen.
Report Type
Description
To Printer
Output is directed to the printer selected in the Chooser.
To Text File
Output is directed to a tab delimited text file created at the
location selected.
To Screen
Output is directed to an on-screen report.
Table 16-2: Archive Report Output Options
Chapter 16 Generating Archive Reports
17–1
Chapter 17
Finding Items in an Archive
Find Feature
To find an item within an archive:
1. From the Edit menu select Find…
Illustration 17-1: Find menu item
2. The Find dialog appears.
Illustration 17-2: Find dialog
17–2
Find Feature
3. Select the archive item category upon which to search or choose Any Item to
search without restricting the search by category.
Illustration 17-3: Find by Archive Item Category
4. Select the archive item property upon which to search.For this example we chose
Created Date.
Illustration 17-4: Find Files by Created Date
Chapter 17 Finding Items in an Archive
Find Feature
17–3
5. Select the operator to use for narrowing the search. For this example we chose to
limit our search to all files with a created date that is within 1 week of 10/8/2001.
Illustration 17-5: Selecting the Search Operator
6. The Find operation will start searching from the top of the archive and will search
down, including within folders, until it finds a file with properties which fall
within the search criteria. The found item will be selected and if it is within a
folder it will be revealed in the archive window item list. To find the next item with
properties which fall within the search criteria select Find Next from the Edit
menu or use the keyboard equivalent Command-G.
To Find Previous:
■
Hold down the Shift key while clicking the Find button; or
■
Use the keyboard equivalent Command-Shift-G; or
■
Hold down the Shift key and select Find Previous from the Edit menu.
7. If you check Select All Found in the Find window, all items within the archive
with properties which fall within the search criteria will be revealed and selected
in the archive window item list.
8. With all found items selected, changes can be made to the selected files at once by
holding down the option key and clicking the Get Info button. The resulting compound Get Info window allows you to apply settings changes to all selected items.
It is sometimes useful to see all items of a particular type in an archive. For
instance, find all alias action items. To do so, select the desired type, select
containing and make sure the field to search is blank.
17–4
Chapter 17 Finding Items in an Archive
Find Feature
18–1
Chapter 18
Building the Final Installer
Before the Final Build
Before building the final installer, make sure that everything in your archive is correct,
including:
■
Assignment of files to packages
■
Addition of external codes
■
Use of gestalt calls
■
General settings for the installer
It is recommended that you verify the archive and that you run a diagnostic archive
report to make sure that there are no problems in the setup of the installer.
Build Targets
All Installer VISE builds are controlled by Build Targets. Even if you choose not to use the
Project Window or to set up your own Build Targets, each time the Build command is
issued the build is performed according to the settings of the active build target.
A build can be initiated by:
■
Selecting Build Installer… from the File menu.
■
Typing Command-B from the keyboard; or
■
Running an AppleScript that tells Installer VISE to Build.
All new archives have one build target which is the active build target. The active build
target is indicated by a bullet next to the build target icon in the Project Window. While
the active target is the target currently being edited, any number of targets can be
18–2
Build Targets
checked in the project window. When a build command is issued, all checked targets will
be built.
Illustration 18-1: Active Default build target
For a new archive, the active build target is named Default Target and it has as its Format,
Ask at Build.
Illustration 18-2: Default Build Target
Chapter 18 Building the Final Installer
Build Targets
18–3
When a build is initiated and the active build target is set to Ask At Build the following
build dialog will be presented.
Illustration 18-3: Ask At Build Dialog
In the Ask At Build dialog you can choose:
■
Where the installer will be built
■
What the installer segment(s) will be named
■
What type of installer, or Target, to build
■
The platform for this installer, such as PowerPC or Carbon
■
Whether to built the installer as a debug installer
■
What the disk name should be, if the target type requires disk names and the
name has not been predefined in Disk Names
■
How big segment sizes should be
■
Whether to create a BinHex version of the built installer segment
■
Whether to create a MacBinary version of the built installer segment
Much of this information can be determined in advance so that the choices do not need
to be made at each build. By configuring Build Targets, the Ask At Build dialog can be
completely bypassed. Setting up multiple Build Targets can enable you to produce an
installer in multiple forms and/or multiple locations. By setting up and then checking
several build targets you can automate the entire process of building multiple installers to
multiple locations.
By setting up Build Targets you can preset:
■
Where the installer will be built
■
What type of installer, or Target, to build
■
The platform on which this installer will run
■
Whether to built the installer as a debug installer
18–4
Building a Debug Installer
■
Whether to create a BinHex version of the built installer segment
■
Whether to create a MacBinary version of the built installer segment
By setting up Disk Names you can preset:
■
What the installer segment(s) will be named
■
What the disk names should be
■
How big segment sizes should be
Below we will set up a build target for creating a debug installer.
Building a Debug
Installer
As in software development, the feedback available from a debug build can be valuable in
pinpointing faulty implementation. It is recommended that you build a debug installer
and run it through all options of Easy and Custom Install before building and releasing
your final installer.
A debug installer is identical to a non-debug installer in content and logic but contains
an additional window, the debug window. When using a debug installer, information is
written to the debug window as each archive item is processed. Some of the information
available in the debug window includes: gestalt checks, variable setting and testing,
action item results, and install if conditions.
Debug installers can be very helpful in tracking down install problems, verifying install if
conditions, and tracking the progress of Find actions or the Search Criteria within other
action items.
When a debug installer is run, a debug window is displayed to the left and behind the
Install window. As the install progresses, item execution information is written to the
Debug Window as shown below.
Illustration 18-4: Debug Installer with debug window
18–5
To build a debug installer:
1. From the Archive menu select Show Project Window.
Illustration 18-5: Show Project Window
2. Select the Targets heading in the Project window and click the Add button.
Illustration 18-6: Adding a build target to the Project Window
3. Name the build target, select a Format type and Platform type, and check the Create Debug checkbox. If you wish the build path to be other than where the VCT is
located you can edit the path by clicking on the Edit Path button. Click OK when
you are done setting up the build target.
Illustration 18-7: Creating a Debug build target
18–6
4. In the Project Window click just to the left of the Debug Target icon to make it the
active target. A bullet will appear next to the Debug Build build target indicating
that it is the active build target. Check the Debug Target and uncheck the Default
Target.
Illustration 18-8: Setting the Active Build Target
5. Select Build Installer… from the File menu.
Illustration 18-9: Build Installer menu item
Building the Release Installer
18–7
6. The installer build will proceed unattended unless you chose a build target which
requires input (i.e. Ask User). If the active build target is Ask at Build a debug
installer can be built by checking Debug in the build dialog.
Illustration 18-10: Create Debug Installer in the Build Dialog
Building the Release
Installer
To create the release installer:
1. Create a build target for your release installer:
■
Name the build target.
■
Choose a Format.
Target Format
Explanation
Ask At Build
At build, the standard build dialog will be displayed
where save location, segment name, debug status, and
postprocessing can be determined.
Floppies
This feature was disabled for Installer VISE version 8.0.
Older VCTs that have the Floppies option selected will
behave as if Ask at Build was selected.
Disk Images
At build, installer disk images will be created at the
location designated by the path field. This option
creates an installer that would be identical to one
produced by building to floppies and then creating
disk images of those floppies. Installer VISE calls on
Apple’s Disk Copy to build standard disk images.
These images can be 800K and larger.
Table 18-1: Build Format Options
18–8
Target Format
Explanation
Folders
At build, an installer based on data from the Disk
Names List is created at the location designated by the
path field. Disk Names are used for folder names and
Segments are saved within the appropriate disk folder.
CD Installer
At build, a CD installer is created at the location
designated by the path field and files are extracted
from the archive and copied to the same location as the
CD installer.
Sngle File
At build, a single file installer containing compressed
archive items is created at the location designated by
the path field.
Web Installer
At build, a web installer and designated group files are
created at the location designated by the path field. If
Upload Cab file(s) to Web Server at Build Time (FTP
Sites Only) is checked in the Web tab of Installer
Settings, the group file(s) are uploaded to the web
server designated in Download Sites from the Internet
menu.
Web Installer (Data In
Installer)
At build, a web installer (containing all data as if user
had just downloaded it) and designated group files are
created at the location designated by the path field. If
Upload Cab file(s) to Web Server at Build Time (FTP
Sites Only) is checked in the Web tab of Installer
Settings, the group file(s) are uploaded to the web
server designated in Download Sites from the Internet
menu.
USB Installer
At build, a single file USB installer is created at the
location designated by the path field. This installer will
deliver the driver (system extension file) required for a
specific USB device, and can also deliver other files.
For more information,see Chapter 38-USB Installers.
Single File w/External
Data
This format was created to work around a file mapping
conflict on Mac OS X, and is no longer needed. It is
retained for legacy purposes.
Table 18-1: Build Format Options
■
Choose a platform.
Target Platform
Explanation
Classic
This setting builds installers for 68K platforms.
PowerPC
The PowerPC setting builds installers for PowerPC
platforms.
Table 18-2: Build Target Platform Options
18–9
Target Platform
Carbon
Explanation
Installers built with the Carbon setting will run on
Mac OS X and Mac OS 8.1 through OS 9.x (on OS 8
and OS 9 systems, the CarbonLib 1.1 or newer system
extension must be installed).
If the format is Single File and the platform setting is
Carbon, a Create OS X Bundle checkbox will be active.
With this option selected, Installer VISE will build the
installer as a Mac OS X application bundle. This is the
preferred way to deliver a multi-language installer on
Mac OS X. It allows the proper display of single-byte
and double-byte character sets from within the same
installer.
Unified
The Unified setting builds installers that contain
executable code for both Carbon and non-Carbon
platforms. This allows a single executable installer to
run on anything from Mac System 7.1 to Mac OS X
systems.
PowerPC SharedLibData
Installer VISE can build a data file containing all
necessary files and install information. Applications
can then call MindVision's shared library to install files
as specified in the data file. This performs installations
without displaying a traditional installer interface. It is
useful in situations where you don't need to give the
user install options, such as for self-healing
applications, or first-run installers. The data file option
is available for PowerPC and Carbon formats. See also
“Calling the MindVision Shared Library” on
page 27-11.
Carbon SharedLibData
See the preceding explanation.
■
Make sure the Create Debug checkbox is NOT checked.
■
Set the path for the built installer. The default path for built installers is the
directory of the VCT.
■
Make post processing choices.
■
Complete eSeller tab information if you are creating an Installer eSeller.
■
Close the build target and make it the active build target.
2. From the File menu, select Build Installer....
18–10
3. If your copy of Installer VISE is not registered, you will be asked to register the
copy at this time.
Illustration 18-11: Installer VISE Registration
If you select Later and build an installer with an unregistered copy of Installer
VISE, the installer will:
■
Display the Installer VISE splash screen to the customer before your splash
screen, alerting them that you used unlicensed software; and
■
Expire three days from the date that the unlicensed installer was built.
If your copy of Installer VISE is registered, then the Installer VISE splash screen
will never be visible to the customer, and installer will not automatically expire.
When the installer is created, certain unused CODE resources will be
deleted. If there is no Read Me file, the readme resource will be removed; if
there are no additional help resources, the help code will be removed; and
if there are no files to be installed to the System file, Fonts folder, or Apple
Menu Items folder, the resource copier code will be removed.
19–1
Chapter 19
Creating CD Installers
Creating a CD Installer
The Catalog Only Question
To create a CD Installer:
1. Decide whether you want users to have direct access to the files on your CD.
By default the installer contains all of the files in a compressed format. Since the
files are stored inside of the installer they cannot be accessed directly. The customer must run the installer to install your files.
If you do not want users to have direct access to the files on your CD you do not
need to perform any of the following steps. This guarantees that your customers
must go through the installer to install your files.
If you do want users to have direct access to the files on your CD, the installer can
also be set up to install normal Finder-draggable files. This is common on many
software CDs. Your customers can copy individual files to their hard drive and
bypass the installer if they wish. This can be good or bad depending on how much
control you want to give your customers.
19–2
2. If you do want users to have direct access to the files on your CD select Installer
Settings from the Archive menu, go to the Advanced tab and check Only Store
Catalog Of Files.
Illustration 19-1: Installer Settings, Advanced Tab, Only Store Catalog Of Files
Only Store Catalog Of Files is an often-misunderstood Advanced Setting option
that allows you to store only a catalog of your files in an archive, not the actual
compressed file data. Many people believe that you need to turn this option on to
build CD installers that can install uncompressed files. Not so! This option only
affects only how your files are stored in your archive file, NOT the installers you
build with it. It was implemented for developers with very large archives building
only CD installers in order to eliminate the time needed to compress files when
the archive is saved and decompress files while building the installer.
There are limitations for Catalog Only archives.
1) Only CD installers can be built from the archive.
2) The file hierarchy in the archive MUST match the file hierarchy of the
actual files on CD.
3)This option cannot be turned off once it has been turned on.
Chapter 19 Creating CD Installers
19–3
When the Only Store Catalog Of Files option is turned on the following warning
will be displayed:
Illustration 19-2: Catalog Only Warning
Create a CD Installer
Build Destination
3. From the Archive menu select Show Project Window.
The Project Window is where Build Targets are created and activated. Build Targets enable easy creation of multiple types of installers.
4. Select Targets in the Project Window and click the Add button to create a new
Build Target.-
Illustration 19-4: Adding a new Build Target
19–4
5. Name the new Build Target and set the Format popmenu to CD Installer.
Illustration 19-5: Creating a CD Installer Build Target
See Chapter 27-Advanced Project Management, for information on other Build
Target formats.
6. The Path defaults to {Vct folder}: meaning that the installer will be built to the
same location as the archive (VCT). Set the path to the location of your CD master
volume. When the installer is built, the files and the installer will be placed at the
location specified in the Build Target Path.
7. Select the OK button in the Build Target window.
Check the CD Target and make it the active target (represented by a bullet) by
clicking to the left of the CD Target icon.
Illustration 19-6: Activating a Build Target
Whenever the Build command is issued the checked Build Targets will be built.
19–5
Set Installer Name
8. When built, the installer will be named based on the Installer Name field in its
Build Target. Select Disk ^ and click Edit Disk. In the Installer Name field, type
the name you wish to assign to the installer and Click OK.
Building the CD Installer
9. Build the Installer. There are a number of ways to initiate a build:
Capture Icon Locations
■
By selecting Build Installer from the File menu.
■
By typing Command-B; or
■
By telling Installer VISE to Build from an AppleScript (see “Building an
Install Set” on page 30-9).
10. When building a CD installer, files are extracted from the archive and copied to
the same location as the installer. The file icon positions are set either to their original folder and file positions, or to the location set when using the Set Icon Locations command. See “Capture Icon Position and Catalog Only” on page 13-4 in
Chapter 13-Setting Icon Locations.
Disk space is not checked when a CD-ROM installer is created, so make
sure that you don’t exceed the capacity of your storage media.
File Compression Options
for CD-ROM Installations
By default, all items in the archive will be placed uncompressed on the CD. However, by
changing file and folder options at the archive window or the Installer VISE Get Info
window, you may specify that you only want individual items to be uncompressed on the
CD.
Catalog Only On:
■
Files are copied from the source on the hard drive to the Build Target. All files
will be in a Finder draggable form.
Catalog Only Off:
■
If the Build Target is a CD installer, all files will be decompressed from the compressed data in the archive, to the Build Target.
■
If you have certain files/folders set to be on disk then those files/folders will be
decompressed to the Build Target while the remaining files will be compressed
in the installer.
For instructions on assigning specific items to be uncompressed on a CD, see “Storing
the Item Uncompressed in a Disk Image or Folder” on page 12-15.
19–6
20–1
Chapter 20
Maintaining Archives
Bringing the Archive
Up To Date
Bring Up To Date synchronizes your archive with the original source files allowing you to
add, delete or modify the files in the archive without redefining packages or file information for a file. During the Bring Up To Date process you will be given an opportunity to
verify differences and to decide if you would like new files to be added, obsolete files to be
deleted and similar files to be updated.
During VCT construction, if you have changed folder names in the VCT
or on the HD source without changing the folder name in the other
location (VCT or HD) it is necessary to perform a Validate Paths operation before doing a Bring up To Date. The Validate Paths operation is
more comprehensive in its efforts to determine paths for items. For
more information on validating paths see “Validating Paths” on page 20-5
To bring an archive up to date:
1. Make sure that the source folder for the archive contains the new or modified files,
and that it’s closed so that the Finder has updated any new icon locations.
20–2
Bringing the Archive Up To Date
2. From the Archive menu in Installer VISE, select Bring Up To Date...
Illustration 20-1: Bring Up To Date Menu Item
3. If a folder can no longer be found at its old location, you will be asked to locate the
folder.
Illustration 20-2: Locate Folder Not Found at Old Location
4. If the folder is no longer valid, click Cancel. The folder will be marked as
<missing> in the Bring Up To Date window and will be deleted unless you
uncheck it.
When you need to permanently rename an item, you should do so at the
Finder, then by Bring Up To Date. Updating in this way will synchronize
the archive items with the source items at the Finder.
If you rename an item within the archive only, Bring Up To Date will cause
the item to be renamed back to its old name.
Chapter 20 Maintaining Archives
20–3
5. If there are any files in the source folder that appear to match a file that’s already in
the archive but have a slightly different name (i.e. a version number appended to
the name), a dialog box will be displayed that lets you select the new version of the
file as a match for the version of the archive. (For example, if your archive contains
the application MyApp 1.1 and the source folder is updated so that it now contains the application MyApp 1.2, you will be asked if MyApp 1.2 should replace
MyApp 1.1 in the archive file.
Illustration 20-3: Replacing Similar Items During Bring Up To Date
The process of replacing items with similar names during Bring Up To
Date is controlled by the Perform Intelligent Filename Check on
Update archive setting. The checkbox can be found in the Installer Settings Advanced Tab. See “Perform Intelligent Filename Check on
Update” on page 14-27 for more information.
The Bring Up To Date window will then be displayed:
Illustration 20-4: Bring Up To Date window
20–4
6. Use the chart below to determine which items have been modified since the last
time you saved the archive.
Indicator
Meaning
The item has been selected for update.
At least one item within the folder has been selected for update.
<same>
The item has not changed
<different>
At least one item within the folder has changed
<new>
The item did not exist when the archive was created.
<newer>
The version of the item in the source folder is newer than the
item in the archive.
<invalid>
The update file is not valid or has not been built. Update files
may be invalid because the compare operation has not been
done, the items are not in the right slots in the update window,
or the source or target files have changed since the last compare.
<valid>
The update file is valid.
<FInfo changed>
Finder information for the item, such as Label or placement
within a folder, has been changed.
You do not need to select items whose Finder information has
changed. The information will be automatically updated when
you save the archive, though the file will not be recompressed
If you do select an item whose Finder info has changed, the
item will be recompressed as well as include the new Finder
information.
<missing>
The item in the archive was not found in the source folder. That
item will be deleted from the archive if the checkbox for that
item remains selected.
Table 20-1: Bring Up-To-Date Window Indicators
7. To compare the old and the new versions of an item, select the item and click the
Get Info button. A box comparing the old file (on the left) and the new file (on the
right) will be displayed. Click OK to dismiss the comparison box.
8. Select any items that should be updated to the archive by clicking the checkbox on
the left of the item’s name. Items that have changed will automatically be selected
for updating.
Verifying an Archive
20–5
9. Select the Bring up To Date Options you wish to use for the current update session.
Option
Meaning
Assign Parents
Package to New
Files
By default, files that are added to an archive as a result of an
update have the same package assignment as its parent folder
in the archive. To disable this feature, deselect Assign Parents
Package to New Files at the top of the Update Archive
window.
Update Icon
Locations
Finder Info for an item is always updated if it has <FInfo
changed> in its status column. If the Update Icon Locations
checkbox at the top of the Bring Up To Date window is
checked, the icon location will be updated along with the
other FInfo data.
Table 20-2: Bring Up To Date Window Options
10. Click Update... to update the archive. If any files had the status of <missing>, then
a warning message will ask if you’re sure that you want to delete those files from
the archive.
Bring Up To Date and Embedded VCTs - The Don’t Update Packages
on Imported VCT Files Archive Setting will affect what happens to
embedded VCT items during Bring Up To Date. For more information
on this setting, see “Don’t Update Packages on Imported VCT Files” on
page 14-26.
Verifying an Archive
To verify that the files in an archive are intact, select Verify Archive from the Extras
menu. If you receive an error message, you should update the archive.
If you verify an archive for a CD installation which only contains a catalog of files to
install, you’ll be asked to locate the specific folders that resemble the archive. This ensures
that the hierarchy of files in the archive matches the files that will be used to create the
CD.
Validating Paths
To make sure that the paths for files in an archive are intact, select Validate Paths from
the Extras menu. If the paths from source to archive have changed, you will be asked to
locate new locations for source items.
During VCT construction, if you have changed folder names in the VCT
or on the HD source without changing the folder name in the other
location (VCT or HD) it is necessary to perform a Validate Paths operation before doing a Bring up To Date. The Validate Paths operation is
more comprehensive in its efforts to determine paths for items.
20–6
Validating Paths
Section 3
Building Updaters
21–1
Chapter 21
About VISE Updaters
Why Use an Updater?
Why Use VISE Updaters?
Updaters are the best means to provide upgrades and quick fixes for your existing applications. Not only are they easy to create and distribute, they are an ideal way to let your
customers know that you are constantly working to improve the product. Updaters are
the most convenient, cost-effective way to help your customers stay current because...
■
Updaters are small. Updaters only store information about the changes between
versions of an application—they are not complete releases of the application
itself. So, updaters are almost always small files, easily distributed on diskette or
via FTP and Web sites, commercial online services and bulletin boards.
■
Updaters are safe. VISE updaters do not contain a new, complete version of your
software—they create a new application based on the differences between the
old and new versions. If a person does not have a copy of your original application, the updater will not create a new file. So, you can freely distribute updaters
without contributing to piracy of your products.
■
Updaters are fast. They are easy to create—just identify the source files (the files
you want to update) and the target files (the files you want to update to), customize your options, and click a button to build the updater application. And,
they are easy for customers to use—you can even build updaters that automatically locate the customer’s applications that are candidates for updating.
By combining an easy-to-use graphical interface with innovative development features,
Installer VISE is the ideal tool for creating updaters for any Macintosh application.
Installer VISE updaters have...
■
A simple, flexible interface. Although you can precisely configure your updater
to meet your custom requirements, almost all development takes place in a single “Drag and Drop”-aware window and a few easy-to-understand dialog boxes.
It’s simple to make changes and test them immediately to make sure that you’ve
designed the updater exactly the way you want.
■
Support for multiple application versions. VISE updaters do not limit you to
upgrading from only a single version number—you can build updaters that
identify and upgrade multiple previous versions. So, if your customers might
21–2
Why Use an Updater?
have versions 1.1, 1.2, and 1.3 of your application, you can upgrade all of them
to version 2.0 with a single updater.
Chapter 21 About VISE Updaters
■
Support for multiple application formats. In the old days, when everyone had a
680x0 Macintosh, application formats were not a problem—there was only one
kind. But with the advent of the PowerPC, keeping track of 68K, PowerPC and
Fat Binary applications on various platforms is a little more complicated. VISE
provides complete control of format handling within a single updater application; instead of creating a separate updater application for each format, you can
store all three formats in the same updater—easier for you to manage, and easier for your customers to use! And, you can decide exactly what kind of format
will be installed on specific machines, or let the customers choose whether to
install Fat Binary, PowerPC-specific or 68K-specific code on their own
machines.
■
“Double fail-safe” checksum security. VISE updaters use checksums twice to
ensure the accuracy of an update: at the beginning of the update to make sure
that the selected file is a valid candidate for updating, and at the end of the
update to ensure that the newly-updated application is 100% accurate and complete.
■
Powerful handling of resource exceptions. Your customer’s application is rarely
going to be exactly the same as when it shipped—resource information such as
registration, preferences, size and icons may have been changed. Installer VISE
lets you identify what resources are likely to have been modified by your customers and choose whether to use the old resource or new resource in the
updated application. For your convenience, VISE updaters already lists the most
commonly modified resources by default.
■
Security for the customer’s original file. VISE updaters do not modify your customer’s existing file—they generate an entirely new one. So, if an update is canceled or unexpectedly interrupted, the customer’s original file will not be
modified or corrupted in any way.
■
External code hooks for absolute flexibility. VISE updaters include support for
external code, letting you fully customize the updater to perform tasks beyond
its built-in functionality.
■
Comprehensive localization features. Installer VISE supports the development
of updaters in multiple languages from a single VISE updater file. All you need
to do is identify any new custom materials (such as a Read Me file or splash
screen for the new language), and build a new updater using the new language.
Installer VISE automatically generates dialog boxes and other application-generated messages in the language you select.
■
Full integration with Installer VISE. VISE updaters, whether stand-alone updaters, eSellerate Update files or update files for inclusion in an installer, can be
created from within Installer VISE. By using VISE updaters within MindVision’s
Installer VISE installers you can create installers that update existing files as well
as install new ones. VISE update files can be created, built and included in
Installer VISE installers, allowing you to update more than one file at a time;
create installers that update existing files; and install new files that aren’t part of
the application’s original install set but are associated with the upgrade (such as
tutorials or samples).
The Customer’s Perspective: A Sample Session
The Customer’s
Perspective: A Sample
Session
21–3
The following is an example of the kind of session a customer might encounter when
using a simple standalone updater application created with Installer VISE.
After launching the updater application, the customer is greeted with a customized
splash screen and an informative Read Me file, explaining what will happen as a result of
the update.
Illustration 21-1: Update application Read Me
After the customer dismisses the Read Me file, the updater searches the system for source
files that match the ones you identified when creating the updater, and displays them in
the updater application’s main window.
Illustration 21-2: Updater application main window
21–4
The Customer’s Perspective: A Sample Session
11. The customer selects the file to update, and clicks the Update button. When the
update is complete, the customer is informed that the operation was successful
and the application is ready to use.
Illustration 21-3: Successful update dialog
12. After clicking OK to dismiss the message, the customer clicks Quit at the updater
application’s main window.
Chapter 21 About VISE Updaters
22–1
Chapter 22
Designing an Updater
This chapter contains some general guidelines and examples of typical ways to set up an
updater, covering the most common variations for source and target files.
Basic Components of
an Updater
The basic items that you must identify when creating an updater are:
■
All old versions and formats of the file that may be on the customer’s system
(the source files)
■
For each source file, the corresponding new file you wish to update to (the
target files)
■
What resources may have been modified in the original file (resource exceptions)
In a simple case, you might only need to identify a single source file to be updated and a
single target file to update it to. However, the situation can be more complicated, as discussed below.
Handling Multiple Versions VISE updaters allow you to include multiple versions and formats of a source file within
a single updater.
and Formats
For example, if your product has a full release numbered 1.0 and an incremental release
numbered 1.1, and you’re creating the updater for a release numbered 1.2, you can identify both the 1.0 version and the 1.1 version as source files. Then, customers who have
either 1.0 or 1.1 can use your updater to upgrade their version to 1.2.
Since the introduction of PowerPC machines, your files may be in several possible formats, including 68K, PowerPC, or Fat Binary. VISE also lets you build a single updater
application to update multiple formats of a file. It can correctly identify whether the file
to be updated is a 68K file, a PowerPC file, or a Fat Binary file, and update it to the correct format for the new file.
Several examples of updaters for multiple versions and formats can be found in “Sample
Update Files” on page 22-4. It’s strongly recommended that you review these materials
before building your updater to ensure that the updater is set up correctly.
22–2
Handling User System or
Program Modifications to
Resources or the Data Fork
Designing Your Updater
VISE updaters identify source files on the customer’s system by comparing them to the
source files that you included when you built the updater. If the resources of the customer’s file have been changed so that they no longer match the resources of the source
file in your updater, the updater will refuse to update it. However, the customer, the system, or a program may have modified the source file’s resources by a common action
such as entering registration information, modifying the amount of allocated RAM, or
attaching a custom icon.
To handle these resource exceptions, Installer VISE lets you identify the resources that
may have been modified, so that source files can be correctly updated. Additionally, you
can choose whether to override the modifications or to apply them to the newly-installed
file. (For example, if the customer attached a custom icon to the application, you can
choose to use the custom icon on the updated version or to replace it with the icon of the
updated version.)
Because your application may store preferences or other information in the data fork,
Updater VISE also provides a means to copy or override information in the data fork of
the source file.
For complete information on handling resource or data fork modifications to your
source files, see Chapter 23-Identifying Resource and Data Fork Exceptions.
Designing Your
Updater
Depending on your particular combination of file formats and versions, there may be
dozens of different ways to set up an update file. Installer VISE was designed to be as flexible as possible to handle these many possible combinations. You can build a single
updater that update multiple versions and multiple formats of a file. Use the following
guidelines to help you develop an update scheme:
1. List all the possible variations of the source file that a customer may have installed
that you wish to update. The list should include all combinations of versions (1.0,
1.0.1, etc.) and formats (68K, PowerPC, or Fat Binary). An example source list
might be:
■
MyApp 1.0.0 (68K)
■
MyApp 1.0.0 (PPC)
■
MyApp 1.0.0 (FAT)
■
MyApp 1.0.1 (68K)
■
MyApp 1.0.1 (PPC)
■
MyApp 1.0.1 (FAT)
You’ll need to locate unmodified copies of each item to use as source files when
creating your updater.
2. List all the variations of the target file that comprise the new release that you wish
to update to. If you have multiple formats of your application, you may have multiple target files. An example target list might be:
■
MyApp 1.0.2 (68K)
■
MyApp 1.0.2 (PPC)
■
MyApp 1.0.2 (FAT)
You’ll need to locate unmodified copies of each item to use as target files when creating your updater.
Chapter 22 Designing an Updater
Designing Your Updater
22–3
3. Decide how to place the files in the update window. Use the examples in “Sample
Update Files” on page 22-4 to determine where each source and target file should
be placed in your updater.
In the simplest case, if you use the default settings, each source file that appears in
the update window will update to the corresponding target file that it points to on
the right.
4. If any of your target files are Fat Binary format, you must decide whether you
want to update the target file to the same format as the customer’s source file; if
you want to force the installation of Fat Binary code; or if you wish to let the customer decide to install Fat Binary or platform-specific code on the system.
Each example in “Sample Update Files” on page 22-4 contains information about
which options to choose in the PowerPC Options dialog to achieve the desired
result.
5. Determine if there are any resources in the customer’s source file that may have
been added, removed, or modified since the file was installed. Examples of these
types of resources are those that system modifies, such as SIZE and custom icon
resources, or resources that the program itself modifies such as registration or
preference resources. (Because SIZE and custom icon resources may be modified
by any customer, they are included in the Resource Exception lists by default.)
Any resources that may have been modified must be included in one of the
three Resource Exception lists in the updater; otherwise, the updater will
see that they have been modified and not perform the update. Information
about how to enter resource information into the Resource Exception lists
can be found in Chapter 23-Building Updaters.
6. Decide on other settings for the updater, such as the following:
■
Should a splash screen or a Read Me file be displayed when the Updater is
launched?
■
Should the updater automatically search for files on the customer’s system
that match the source files you identified?
■
What should the newly-created target file on the customer’s system be
called after the update?
■
Should the original source file on the customer’s system be removed?
■
What creation and modification dates should be used for the newly-created
target file on the customer’s system?
For complete information about available settings for an updater, see “Modifying Update
Settings” on 23-11.
Options for Updating
PowerPC and Fat Binary
Files
Normally, you will set up your updater so that the format of the selected source file determines the format of the target file. However, you may override this default behavior by
setting the PowerPC Options. These options allow you to control the format of the target
file based on machine-type or customer's choice.
If you include a target file that contains PowerPC or Fat Binary code in the PPC or FAT
rows, the PowerPC Options button in the Update Settings dialog will be enabled. The
settings in this dialog let you determine whether Fat Binary or platform-specific code will
22–4
Sample Update Files
be installed on 68K and PowerPC systems, or whether the customer will choose which
kind of code to install.
If the target file is in Fat Binary Format, you may choose to do one of the following:
■
Let the selected source file determine the target file and format to be created
during the update. In this case, the updated file will be the same format as the
original source file on the customer’s machine.
■
If the customer’s machine has 68K architecture, strip the PowerPC code from
the Fat Binary target file. In this case, the ‘cfrg’ resource and the data fork are
removed.
■
If the customer’s machine has PowerPC architecture, strip the 68K code from
the Fat Binary target file. In this case, the ‘CODE’ resources are removed.
■
Let the customer choose to install platform-specific code or to leave the Fat
Binary target file unmodified.
If the target file is in PowerPC-only format, you may choose to install a “PowerPC Only”
alert, which adds a code snippet to the application that displays a user-friendly message if
the application is launched on a 68K machine. (This message replaces the System Error 192 message that would normally appear.) If there’s any chance that a customer might
update to a PowerPC-only target file, consider installing this alert.
Adding the PowerPC Only alert to an application adds the following
resources:
■
CODE 0
■
CODE 1
■
ALRT 27309
■
DITL 27309
If you construct updaters for that application in the future, be sure to take this
into account and make resource exceptions for these resources .
These options are only valid for Fat Binary and PowerPC target files. If your target file
has only a 68K format, the button will not be enabled. If you include multiple formats of
your target file, the options you select will only apply to the PowerPC and Fat Binary formats.
VISE updaters support Fat Binary CFM files, where both 68K and PowerPC code fragments are stored in the data fork. If any of the above options are selected, the updater will
strip the unneeded code from the data fork and adjust the cfrg resource accordingly.
Information about how these settings affect different kinds of updaters appears below.
For instructions on using the PowerPC Options, see Chapter 23-Building Updaters.
Sample Update Files
This section contains examples of updaters for a variety of different source and target
files. Information about PowerPC Options are included for each where applicable.
Sample Update Files
22–5
Placing Files in the Update All source and target files are identified in the update window, pictured here:
Window
Source and target files must be placed in the appropriate rows and columns. Use the rules
and examples in the rest of this section to determine where you should place your source
and target files.
Correct placement of files in the update window is crucial for two reasons:
■
Using the default settings, each source file selected on the left will update to the
target file it points to on the right.
■
If a target file is a PowerPC or Fat Binary file, it must be placed in the appropriate PPC or FAT rows to enable the PowerPC Options in Update Settings. Where
applicable, the following examples will explain these options and their consequences.
Updates With A Single
Format Source and Target
If your application has only one possible format for the source file and only one possible
format for the target file, use the information in this section to determine how to set up
the update file.
For 68K Source and 68K
Target Files
If you are updating a 68K source file or files to a 68K target file, follow this rule to set up
the update file.
Put these source files...
68K-only file(s)
And this target file...
68K-only files
In this row:
68K
Table 22-1: 68k Source and 68k Target Files
22–6
Sample Update Files
Your update file will look something like this:
Illustration 22-2: Update for 68k Source and 68k Target files
In these cases, the updater can update the 68K source file(s) that you identify to the new
68K target file.
For PPC Source and PPC
Target Files
If you are updating a PowerPC source file or files to a PowerPC target file, follow this rule
to set up the update file.
PPC-only file(s)
PPC-only files
In this row:
PPC
Table 22-2: PPC Source and PPC Target Files
Illustration 22-3: Update for PPC Source and PPC Target files
In these cases, the updater can update the PowerPC source file(s) that you identify to the
new PowerPC target file.
PowerPC Options:
This setup will enable the PowerPC Options button in Update Settings. However, the
only option that applies to this setup is Install “PowerPC Only” Alert.
Sample Update Files
22–7
See “Options for Updating PowerPC and Fat Binary Files” on page 22-3 for more information.
For FAT Source and FAT
Target Files...
If you are updating a FAT source file or files to a FAT target file, follow this rule to set up
the update file.
FAT file(s)
FAT files
In this row:
FAT
Table 22-3: Update for FAT Source and FAT Target files
Illustration 22-4: Update for FAT Source and FAT Target files
In these cases, the updater can update the FAT source file or files that you identify to the
new FAT target file.
PowerPC Options
This setup will enable the PowerPC Options button in Update Settings. The default setting will leave the Fat Binary target files untouched. However, by setting the various
options, you can strip platform-specific code depending on the customer’s machine; or
let the customer decide whether to strip the platform-specific code.
Keep in mind that if you allow updating to platform-specific code, future
updaters will need to address the issue of multiple formats.
See “Options for Updating PowerPC and Fat Binary Files” on page 22-3 for more information. Further instructions about the PowerPC Options dialog appear in Chapter
23-Building Updaters.
22–8
For Other Single Format
Combinations
Sample Update Files
You are not restrained to only updating from one format source file to the same format
target file. For example, to update from 68K source files to a Fat Binary target file, follow
this rule.
68k file(s)
FAT files
In this row:
FAT
Table 22-4: Update 68k Source to Fat Binary Target files
Illustration 22-5: Update 68k Source and FAT Target files
In these cases, the updater can update the source file or files that you identify to the new
FAT target file.
PowerPC Options
This setup will enable the PowerPC Options button in Update Settings. The default setting will leave the Fat Binary target files untouched. However, by setting the various
options, you can strip platform-specific code depending on the customer’s machine; or
let the customer decide whether to strip the platform-specific code. Keep in mind that if
you allow updating to platform-specific code, future updaters will need to address the
issue of multiple formats.
See “Options for Updating PowerPC and Fat Binary Files” on page 22-3 earlier in this
chapter for more information. Further instructions about the PowerPC Options dialog
appear in Chapter 23-Building Updaters.
For Updates Where There If your application has more than one possible format (68K, PPC, or FAT) for either the
Are Multiple File Formats... source or the target file, use the information in this section to determine how to set up
the update file.
In this case, you must decide whether you want the target file to be created in the same
format as the customer’s source file under all circumstances.
Sample Update Files
22–9
If the Source File Format WILL This is the most common scenario. If the target file that is being created will always be
determined by the original source file that the customer selects, follow these rules to set
Determine the Target File
up the update file.
Format...
In this row:
68k only file(s)
68k-only files
68k
PPC-only file(s)
PPC-only file
PPC
FAT-only file(s)
FAT-only file
FAT
Table 22-5: Update Target determined by Source
Illustration 22-6: Update Target determined by Source
In this example, the updater can update the source file(s) that you identify to the new target file with the same format. In other words, 68K source files will always be updated to
the 68K target file; PowerPC source files will always be updated to the PowerPC target
file; and Fat Binary source files will always be updated to the Fat Binary target file.
PowerPC Options:
This setup will enable the PowerPC Options button in Update Settings. Since you
decided that the format of the target file will always be determined by the format of the
source file, there is no need to modify any of the settings related to the format of the file
to be installed. However, you may wish to install the PowerPC alert for a PowerPC-only
file.
If the Source File Format Will
NOT Determine the Target
File Format
If the target file that is being created will be determined by the type of machine or by the
customer’s choice, follow this rule to set up the update file.
22–10
Sample Update Files
.
68k only file(s)
and
PPC-only files
and
Fat Binary files
Fat Binary
In this row:
FAT
Table 22-6: Update Target not determined by Source
Illustration 22-7: Update Target not determined by Source
In these cases, the updater can update the source file(s) to the new target file with the format that you specify in the PowerPC Options dialog.
PowerPC Options
This setup will enable the PowerPC Options button in Update Settings. The default will
leave Fat Binary target files untouched. However, by setting the various options, you can
strip platform-specific code depending on the customer’s machine, or let the customer
decide whether to strip platform-specific code. Keep in mind that if you allow updating
to platform-specific code, future updaters will need to address the issue of multiple formats.
Single-format updaters for
more than 8 Source Files
For single-format updaters where you might need more than 8 source files, you can place
up to 24 total source files in the updater by using all three format areas. In the example
below, MyApp versions 1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, and 1.7 are placed in the 68K field
and will be updated to MyApp 3.5. My App versions 1.8, 1.9, 2.0, 2.1, 2.2, 2.3, 2.4, and 2.5
are placed in the PPC field and will be updated to MyApp 3.5. And My App versions 2.6,
Sample Update Files
22–11
2.7, 2.8, 2.9, 3.0, 3.1, 3.2, and 3.3 are placed in the PPC field and will be updated to
MyApp 3.5.
Illustration 22-8: Updating 24 Source Files
22–12
Sample Update Files
23–1
Chapter 23
Building Updaters
This chapter contains complete information about building updater applications with
Installer VISE. Before you begin building an updater to ensure that the updater you build
meets your requirements, see Chapter 22-Designing an Updater.
General Procedures
The following is the general procedure for creating update files and updater applications.
The rest of this section will explore each item in detail.
1. Identify the source and target files for the update file.
2. Modify the Resource Exception lists as needed.
3. Select the settings for application name, modification and creation dates, splash
screens, Read Me files, PowerPC and Fat Binary options, etc.
4. Build the update file.
5. Test the update file.
6. Do one of the following:
■
Build a stand-alone updater application.
■
Build an eSellerate Update file (for use with the eSellerate e-commerce system,
an optional service).
■
Include the update file in an archive.
This chapter covers building stand-alone updaters and eSellerate Update files.
23–2
Stand-alone vs.
Multi-file updaters
Before You Start
Stand-alone vs. Multi-file updaters
A stand-alone updater is an application that will update multiple versions
and formats of one file or one application to a new version. Stand-alone
updaters cannot install additional items and they cannot update multiple
items.
A multi-file updater is an installer that contains multiple update files, each of which
will update multiple versions and formats of one file or one application to a new version. Multi-file updaters can install additional items in addition to performing
updates and can be set up to update many different files or applications.For complete
information on including an updater in an installer, see Chapter 24-Including Update
Files in an Installer.
Before you start creating an update file, be sure that you have the following:
■
Unmodified copies of all the source files and target files for the updater application installed on your machine
■
If necessary, the resource types and ID numbers for resources that may have
been modified by the system, program, or customer
■
Any splash screens and Read Me files that you wish to associate with the updater
application
Creating a New Update File To begin creating an updater application, you must first build an update file.
To build an update file
1. At the Finder, launch the Installer VISE application.
2. If you have not registered your copy of Installer VISE, the registration window will
be displayed. If you fail to register your copy of Installer VISE, the updater applications you create will display a splash screen letting your customers know that
you used an unlicensed development tool. Your unregistered updaters will also
expire after three days.
3. From the File menu, select New Archive…. A standard file dialog box will be displayed.
4. Enter a name for the archive file.
5. Click Save. An Archive window will open, displaying the name that you entered
for the file.
6. From the Archive menu, select New Updater.
7. Enter a name for the new file and click Create.
8. Set up the update item. An explanation of that process begins with “About the
Updater VISE Window” on page 23-4.
9. Close the update window and save changes to the update item if necessary.
Chapter 23 Building Updaters
Modifying an Existing
Update File
23–3
To modify an existing update file:
1. Launch Installer VISE.
2. From the File menu, select Open Archive... A standard file dialog will be displayed.
3. Locate and select the VCT file containing your update file.
Illustration 23-1: Locating Archive Containing Updaters
4. In the Installer VISE archive window, select the update file and click the Get Info
button. The update item’s Get Info will be displayed.
Illustration 23-2: Update item Get Info window
23–4
5. Click the Show Files button in the upper right corner of the Get Info window. The
update window will be displayed.
6. Make any changes necessary to the updater.
7. Compare the Source and Target files if necessary.
8. Close the update window and save changes to the update item.
About the Updater VISE
Window
All actions for creating updaters will be performed in the Update window, which appears
below:
The following is a brief description of each item in the window:
■
The 68K, PPC and FAT rows contain the fields in which you’ll identify the
source (original) files eligible for updating and the target (new) files to update
them to. Each source file field may contain up to 8 different source files; the
source file fields will grow as needed to display the files they contain. In Illustration 24-4 above, MyApp 1.0 (PPC) is identified as the source file to be updated
and MyApp 1.1 (PPC) is the target file to update to.
■
The Resource Exceptions item displays the fields where you will identify which
resources may have been modified by the program, system, or customer; and
what action should be taken by the updater in that case.
Complete information about Resource Exception lists, including an explanation of the resource list fields, can be found at “Identifying Resource and
Data Fork Exceptions” on page 23-7.
■
The Trash Can allows you to remove files from the source and target file lists by
dragging them over the icon.
■
The Add File... button lets you add a file to the currently-selected field. You can
also add files by drag and drop directly from the Finder.
■
The Settings... button displays the Update Settings window, where you can
make several choices regarding the appearance and actions of the updater application.
■
The Show Info button displays an Update File Info window.
Adding Files
23–5
■
The Save As … button allows you to create a stand-alone updater application,
or an eSellerate Update file.
For a differentiation between stand-alone updater applications and multi-file
updaters, see “Stand-alone vs. Multi-file updaters” on page 23-2.
For information about eSellerate Update files, see Chapter 5-Integrated eSellers
and Chapter 7-eSellerate SDK Reference in the eSellerate User’s Guide.
■
The Test… button becomes active after you’ve built an updater. It allows you to
test the actions of the updater without quitting Updater VISE.
The delete and name options that you have set are overridden for the test to prevent you from accidentally modifying one of the files that the updater was built
with.
■
Adding Files
The Compare button becomes active after you have added at least one source
and one target file. It builds an update file for the files and options that you
identified.
Correctly adding source and target files to the update file is the most important step in
building an updater application.
For each file format that you need to update (68K, PowerPC, or Fat Binary), you must
identify at least one source file (the file to be updated) in the Source column and one target file (the file to update to) in the Target column.
The row for each format must either be blank or contain entries in both the source and
target file fields. If you identify a source file and fail to identify an associated target file, an
error message will be displayed when you attempt to build the update file.
Drag and Drop is the easiest way to add files to the updater source and target file fields, instead of using the Add File… dialog. You can also drag and
drop items between fields within the update window.
Adding Source Files to the
Updater
To add a source file, perform one of these two procedures:
■
Drag the icon for the file from the Finder into the appropriate field in the
Update window.
OR
1. Select the field where you wish to add files, and click Add File... or double-click the
field. A dialog box will be displayed.
2. Locate and select the desired file.
3. Click Add. The name of the added file will be displayed in the field at the bottom
of the window.
4. Repeat as needed until all source files for that format are identified. You may identify up to eight files. The source file field will grow as needed to display all the files
that you select.
5. When you have identified all the source files for that format, click Done. The files
you selected will be displayed in the current field of the update window.
23–6
Adding Target Files to the
Update File
Adding Files
A target file field can only contain one file. If you attempt to add an item to a target field
that isn’t empty, the first file will be replaced by the new one.
To add a target file, perform one of these two procedures:
■
Drag the icon for the file from the Finder into the appropriate field in the
Updater VISE window.
OR
1. Select the field where you wish to add files, and click Add File... or double-click the
field. A dialog box will be displayed.
2. Locate and select the desired file.
3. Click Select.
Removing Files from the
Update File
If you wish to remove a source or target file from the update file, select the file and drag it
over the Trash Can icon at the lower left of the window. When you release the mouse, the
file will automatically be removed.
The Update File
Information Window
The Update File Info window displays important information about the files included in
your update file such as format, size, version, and location. It can help you keep track of
files which have the same name or if you are unsure about their format and version.
Illustration 23-4: Update File Info
The File Information window always remembers it’s position on the screen, so you can
move it to a convenient location and it will always appear there.
To show the File Information window:
1. Select the Show Info button from the update window.
2. Click once on a file in your update window to update the information.
To hide the File Information window:
■
Select the Close command from the File menu.
OR
■
Click on the close box of the Update File Info window.
Identifying Resource and Data Fork Exceptions
Identifying Resource
and Data Fork
Exceptions
23–7
VISE updaters identify files on the customer’s system by comparing them to the source
files that you included in the updater. If a resource in the customer’s source file has been
modified by the system, program or customer, the updater will not update the file unless
that resource has been flagged as an acceptable modification.
You can identify the resources that may have been changed, added, or removed in the
customer’s source file. This allows an updater to update source files even if the identified
resources don’t match. You may also choose whether you want the updater to ignore the
modified resources or copy them into the new file.
The following is a picture of the Resource Exception lists, containing VISE’s default
resource exceptions. You should only add resources to these lists that may have been
modified, added, or deleted in the customer’s source file.
Illustration 23-5: Updater window showing default Resource Exceptions
Resources are identified by their four-character name and range of associated ID numbers. (For example, in the Keep Old If Exists field, both SIZE 0 and SIZE 1 are identified
for use because the range 0 to 1 is identified.) If only one ID number is appropriate for
the resource, the same number should be used in the starting and ending columns within
the field.(For example, in the Keep Old If Exists field, only icl4 -16455 is identified for
update, since the items in the starting and ending number columns are the same.)
23–8
The meaning of each field is described in the table below
Always Use New
Always Keep old
Keep Old if Exists
If resource in this
field is
encountered…
Always replace
with the resource
of the target file
Always use the
resource of the
customer’s own
source file
If the customer has
modified or added
this resource, use
their changes
Example
If you want the
newly-installed file
to have the same
SIZE -1 resource as
the target file you
placed in the
updater, instead of
the SIZE -1
resource in the
customer’s source
file
If you have a
registration
resource in your
application, you
can transfer the
registration
information to the
newly-updated file
If the customer has
added a custom
icon to their file or
modified the
minimum and
preferred memory
sizes in the Get
Info window, the
changes will be
carried over to the
newly-updated
file.
Table 23-1: Resource Exception categories
Installer VISE includes the following defaults for the common customer actions of modifying the memory requirements or adding a custom icon in the Finder’s Get Info window:
Resource
String ID
Ending ID
Resource Exception?
SIZE
-1
-1
Always Use New
SIZE
icl4
icl8
ICN#
ics#
ics4
ics8
0
-16455
-16455
-16455
-16455
-16455
-16455
-16455
1
-16455
-16455
-16455
-16455
-16455
-16455
-16455
Keep Old If Exists
Table 23-2: Default Resource Exceptions
You may modify or remove the default resources if necessary.
Example of Using Resource
Exception Lists
In the following example, there are several resources that may have been modified in the
customer’s original source file: the registration resource (regs 128), which we wish to
copy from the customer’s source file into the target file, and a preference resource (pref
128) that we wish to ignore so that the target file’s pref resource is always used. Additionally, we’ll leave the default resources for SIZE and custom icons in place.
23–9
The update file for this situation will look something like this:
Illustration 23-6: Update file Resource Exceptions
Data Fork Information
68K applications sometimes use the data fork to store preferences, registration, or other
information. If your application uses the data fork in this way, Installer VISE updaters
provide a mechanism to treat the data fork as a resource exception as described above. To
do so, use the resource type <df> to represent the data fork; read the sections below to
determine which starting and ending ID numbers to use.
The <df> resource with appropriate starting and ending ID numbers can be placed in
any column in the Resource Exceptions lists as described earlier in this section.
For 68K Files...
If your source and target files are both 68K applications, enter the <df> resource with a
starting and ending ID of 0 (<df> 0 0) in the appropriate column of the Resource Exception Lists. This represents the entire data fork of 68K applications.
For PowerPC and Fat Binary
Files...
Normally, the data fork of PowerPC and Fat Binary applications consists only of PowerPC code, so you will not have data fork exceptions. However, if you store other information in the data fork of your PowerPC or Fat Binary files, see “Data Fork Exceptions
for PowerPC and FAT Files” on 23-20.
Identifying Resources
To enter resource exception information:
1. If the Resource Exception List fields are not displayed, click the triangle to the left
of the words Resource Exception Lists, or press Command-R.
2. If blank lines are visible in the field where you wish to enter a resource, click the
mouse in the field. A new line will be added to the field.
If the field contains more than four entries (as the Keep Old If Exists field does by
default), click the mouse in the field where you wish to add a resource and press
Tab to move through the entries until a new line is added to the field.
No matter how you create the new line, the area for the four-character resource
type will be selected so that you may immediately enter the information, and 0
will be entered by default for both the starting and ending ID numbers.
23–10
3. Enter the four-character type of the resource you wish to identify.
4. Press Tab to move the mouse to the column for the starting ID number.
5. Enter the starting ID number of the resource.
6. Press Tab to move the mouse to the column for the ending ID number.
7. Enter the ending ID number of the resource.
8. To add another resource in the same column, press Tab to create a new line and
follow steps #3-7, above.
To add a resource to another column, follow steps #2-7, above.
9. Select Save from the File menu to save your changes.
Modifying Resource
Information
To modify resource information that’s already entered:
1. Select the item you wish to modify. You may select a resource name or a starting or
ending number.
2. Modify the information as desired.
Deleting a Resource
To remove an entry for a resource:
1. Select the name of the resource you wish to remove.
2. Press the Delete key.
You do not need to delete the resource ID numbers. Because the name of the
resource has been removed, updaters that you build will not contain that
resource’s information.
Modifying Update Settings
Modifying Update
Settings
23–11
Settings are modified in the Update Settings window, displayed here:
Illustration 23-7: Update Settings
The following items may be modified for all update files (whether included in an
installer, built as stand-alone updaters or built as eSellerate Update files):
■
Whether the customer’s original file is deleted after installing the updated version
■
What name is used for the newly-installed file
■
What creation and modification dates are used for the newly-installed file
The following items are valid only for update files built as stand-alone updaters (and are
ignored if the updater is included in an installer or built as an eSellerate Update file):
■
Whether a custom splash screen is displayed to the customer after launching the
stand-alone updaters
■
Whether a Read Me file is displayed to the customer after launching the standalone updaters
■
What text is displayed in the header of the updater window
■
Whether to search for matching source files when the customer runs the
updater
■
Whether to replace the updater interface with a Standard File Dialog
■
Whether to generate a log file when the customer runs the stand-alone updater
■
Whether the folder containing the updated application should be opened after
23–12
the updater is finished
■
Modifying File Options
PowerPC Options which affect a PowerPC or Fat Binary target file
To modify file options for update files (whether included in an installer, built as
stand-alone updaters or built as eSellerate Update files):
1. Click the Settings... button to display the Update Settings window.
2. Hold down the mouse over Delete Original and select one of the following items
from the pop-up menu:
■
If you do not want the original source file on the customer’s machine deleted,
select Do Not Delete Original After Update.
■
If you want the original source file on the customer’s machine to be deleted after
a successful update, select Delete Original After Update.
■
If you want the customer to decide whether or not the original source file on the
customer’s machine should be deleted, select Ask User For Delete Permission.
When the updater application is run, a dialog box will appear that asks the customer whether the original should be deleted.
■
If you want the original source file on the customer’s machine to be moved to
the Trash, select Move Original to Trash (7.x Only). This option is only functional if the customer has System 7.0 or later installed. (If this option is selected
and the customer does not have System 7 installed, the original file will be
deleted after a successful update.)
3. Hold down the mouse over New File Name and select one of the following
options from the list:
■
To display a dialog box that asks the customer to enter a name for the new file,
select Ask User For Name. If selected, the Default Name field will appear below
the pop-up menu. If you enter a name in the Default Name field, the default
name will appear to the customer in the dialog box.
■
To name the newly updated file with the same name as the original source file
on the customer’s machine, select Same As User’s File Name.
■
To name the newly-updated file with the same name as the target file that you
included in the updater application, select Same As Target File Name (the
default option).
■
To automatically name the newly-updated file with the name of your choice,
select Use Default Name. If selected, the Default Name field will appear below
the pop-up menu. Be sure to enter a name in the Default Name field.
4. If you selected Use Default Name, or if you selected Ask User For Name and wish
for a default name of your choice to appear in the dialog box, enter the desired
name in the Default Name field.
If the new file is named the same as the original, and the original file is not
deleted, and both the new and original files are stored in the same location, then the original will be renamed with “.old” appended to the file’s
name. For example, MyApp 1.0 would become MyApp 1.0.old.
Modifying Creation and
Modification Date Options
23–13
To choose the desired creation and modification dates for the newly-installed file, follow
these steps in the Date Options section of the Update Settings window:
1. To choose the creation date for the file that will be installed, hold down the mouse
next to Set Creation and select the desired setting:
■
If you want the creation date of the newly-installed file on the customer’s
machine to be the date that the customer runs the updater, select Date User
Runs Updater.
■
machine to be the date that you built the updater, select Date the Updater is
Built.
■
machine to be the same as the creation date of the original target file that you
included in the updater application, select Creation Date of New Version (the
default option).
■
machine to be the same as the creation date of the customer’s source file that
was replaced, select Creation Date of User’s File.
2. To choose the modification date for the file that will be installed, hold down the
mouse next to Set Modification and select the desired setting:
■
If you want the modification date of the newly-installed file on the customer’s
machine to be the date that the customer runs the updater, select Date User
Runs Updater (the default option).
■
machine to the be the date that you built the updater application, select Date
the Updater is Built.
■
machine to be the same as the modification date of the target file you included
in the updater application, select Modification Date of New Version.
■
machine to be the same as the modification date of the source file that was
updated on the customer’s system, select Modification Date of User’s File.
Update Settings for Stand- The update settings labeled Stand-alone Updater Options Only contain settings which
alone updater applications apply only when building a stand-alone updater application.
Illustration 23-8: Stand-alone updater applications update settings
23–14
Any changes made to settings in this area will be disregarded when the update file is used
within an installer, or as an eSellerate Update file.
You may add a custom splash screen to greet the customer when the stand-alone updater
application is launched. Both 1-bit and 8-bit splash screens may be added so that the
screen appears correctly regardless of the customer’s system. You can use any illustration
program to create the 1-bit and the 8-bit images.
You may wish to restrict the size of your splash screen to 512 by 342 pixels, the size of a
standard 9" monitor screen. If you use a larger splash screen, it will appear truncated
when installed on a platform with a 9" monitor.
To add a splash screen:
1. Select the picture you wish to use and copy it to the Clipboard.
2. At the Update Settings window, click Splash Screen… The Setup Splash Screens
window will be displayed.
3. In the Setup Splash Screens window, select Black and White if the picture is 1-bit,
or Color if the picture is 8-bit.
4. Press Command-V to paste the screen into the window. Although the image
appears scaled within the dialog box, it will appear correctly to the customer at the
beginning of the installation.
To remove a splash screen
■
Click Remove.
OR
■
Adding a Read Me File
Paste a new screen into the window.
After the splash screen is displayed, a Read Me file which you assign will be the next item
visible when the stand-alone updater application is used. (If you don’t use a splash
screen, it will be the first item visible.) The Read Me file must be of type TEXT and may
not be larger than 32K.
SimpleText 7.5d1 and later allows you to create text files containing style information
and graphics. If the file contains a styl resource, then style information will automatically
be included. To include a graphic in your Read Me file, type <Option>-<Space> at the
location where the graphic should be located and paste the picture. Graphics must be
stored as PICT resources starting with ID 1000.
To assign a Read Me file:
1. Click Read Me… A standard file dialog box will be displayed.
2. Locate and select the file you wish to include as a Read Me file.
3. Click Open. The pathname of the file will be displayed in the field.
To remove a Read Me file:
1. Hold down the Option key. The Select Read Me button will change to Remove
Read Me.
2. Click Remove Read Me.
Entering Header Text
23–15
After a stand-alone updater application is launched, a text area is displayed at the top of
the window beneath the banner. You can enter header text to display instructions or
other information about the updater application.
The header may contain up to five lines of text; the updater window displayed to the customer will resize accordingly. The text will be displayed with the same font and line
length as are used in the dialog box, shown below.
To enter or change text to be shown in the header:
1. Click Header Text... The following dialog box will be displayed.
Illustration 23-9: Header Text dialog
2. Type the desired text into the box.
Choosing Whether To
Search For Matching Files
If you want the stand-alone updater application to search for matching files on the customer’s machine immediately after launch, select Search for Matching Files. (By default,
this item is selected.) Source files that match the ones you identified in the updater will
automatically be displayed in the updater application’s window.
This feature uses PBCatSearch to identify matching files, and only works
on machines with System 7.x. If you wish to search on System 6
machines, you may select Support System 6 Search, which will include
extra glue code that simulates PBCatSearch. (The Support System 6
Search item is only active if Search for Matching Files is selected.)
If you don’t want the updater to automatically search for the files on the customer’s
machine that match the source files you identified in the updater, make sure that Search
for Matching Files is not selected. The customer may then locate and select files to
update by clicking the Select File button, which displays a Standard File Dialog box.
Using a Standard File
Dialog Box Instead of the
Updater Window
If you wish to display a Standard File Dialog box to the customer instead of the Updater
VISE window that displays all files that match the source regardless of their location on
the disk drive, select Use Standard File Dialog.
If you select this item and select Search For Matching Files (described above), then the
default directory in the Standard File Dialog will be set to the directory containing the
first item found that matches your source files.
23–16
A normal stand-alone updater application window displayed to the customer will look
something like this:
Illustration 23-10: VISE Updater window
An updater that uses the Standard File Dialog will look something like this:
Illustration 23-11: VISE Updater using Standard File Dialog
Generating A Log File
If you wish for a simple diagnostic log file to be generated when the customer runs the
stand-alone updater application, select Generate Log File. The file will be created in the
same location as the target file. It may be useful for testing purposes or technical support
questions.
Opening the Application’s
Folder After Updating
If desired, you may set the standalone updater application so that it automatically opens
the folder containing the updated application. To do so, select Open Folder After Updating. If this item is not selected, the folder will be open if it was open it before beginning
the update, and will be closed if it was closed before beginning the update.
Modifying PowerPC and
Fat Binary Options
The PowerPC Options button is only available if you placed a target file that contains
PowerPC or Fat Binary code in the PPC or FAT target fields. Thorough discussion of how
to create your stand-alone updater application to take full advantage of these settings can
be found in Chapter 22-Designing an Updater.
23–17
To modify the PowerPC and Fat Binary options, click the PowerPC Options button. The
PowerPC Options dialog will be displayed:
Illustration 23-12: Updater application PowerPC Options
If your target file is a PowerPC-only application, skip the section titled “Fat Binary
Update Options” and go directly to “PowerPC Alert.”
Fat Binary Update Options
If your target file is a Fat Binary application, you can choose to strip platform-specific
code from the Fat Binary file, depending on the customer’s machine. The following
options are available:
■
On 68K Architecture, Strip PowerPC Code. If selected, the PowerPC code will
be stripped out of a Fat Binary target file on a 68K machine. (This includes the
cfrg resource and the data fork.)
■
On PowerPC Architecture, Strip 68K Code. If selected, the 68K code (the CODE
resources) will be stripped out of a Fat Binary target file on a PowerPC machine.
■
Ask User. This lets the customer choose whether a Fat Binary target file will be
installed without modification or it will include only platform-specific code.
VISE updaters support Fat Binary CFM files, where both 68K and PowerPC code fragments are stored in the data fork. If any of the above
options are selected, the updater will strip the unneeded code from the
data fork and adjust the cfrg resource accordingly.
PowerPC Only alert
The PowerPC Options also let you install an alert within PowerPC applications that warn
the customer if the application is launched on a 68K machine. This message, which
23–18
Building the Update File
appears below, replaces the System-generated message that an error of type -192 has
occurred.
Illustration 23-13: PowerPC Only Alert
If any of your target files are PowerPC-only files or Fat Binary files that may have their
68K code removed, we strongly recommended that you select this option. Then, if a customer accidentally tries to run the PowerPC-only version of the application on a 68K system, the descriptive error message will be displayed.
Saving Default Settings
By clicking on the Save As Default Settings checkbox the current settings will be saved to
your Updater VISE Preferences file. This is a convenient way to have any new update files
you create use these defaults without having to set them each time.
The Splash Screens and Read Me file are NOT saved as defaults since these
will almost always change with each update file. All other settings are
saved.
Building the Update
File
When you have identified the source and target files, created your Resource Exception
lists, and chosen your update settings, the next step is to build the update file. When you
build the update file, Installer VISE compares the source files and target files that you
identified and analyzes the differences.
Building an update file is not the same as building a stand-alone updater
application for distribution; however, it is necessary to build the update
file before you can build a stand-alone updater application.
To build your update file:
1. Make sure that you’ve set up the update file as desired.
2. Click Compare. The Comparing Files... window will appear, displaying a progress
gauge. When the Comparing Files... window disappears, the build is complete.
Once you have built the update file, you may test its functions.
Testing the Update File
Installer VISE’s built-in Test feature lets you make sure that you have built the update file
as desired without having to build a separate updater application. This allows you to
identify desired changes quickly, without having to regenerate a new application each
time.
Saving the Update File
23–19
The Test Update feature does not display the same user interface features as a stand-alone
updater application. Instead, it simply lets you select a file to update; performs the
update; and creates a new version of the target file on your system, which you must
name.
The Test Update feature will update your files exactly as a stand-alone updater would,
with the following exception: to prevent you from accidentally modifying or deleting one
of the files used to build the updater, any naming and deletion options that you set in the
Update Settings section will be overridden. The updater will act as if the “Do Not Delete
Original” and “Ask User For Name” options have been selected—you will always be
asked how you wish to name the files, and the original will never be deleted.
Testing Your Update File
To test the update file:
1. Make sure that you have built the update file.
2. Click Test.
The application will guide you through the file selection and updating process.
If the update file behaves as desired, you can close the update window to include the
update file in an archive or you can proceed to the next section to save the update file as a
stand-alone updater application. If the update file does not behave as desired or
expected, modify it as needed per the instructions in the preceding parts of this chapter.
Saving the Update File
When the update file performs as desired, you can save it as a stand-alone updater application to be distributed to your customers. Alternately, you can save the file as an eSellerate Update file for use with the eSellerate e-commerce system.
To save the update file:
1. Make sure that the updater performs exactly as you wish.
2. In the Update window, click the Save As button. A Standard File dialog box will be
displayed.
Illustration 23-14: Save As dialog for eSellerate updaters
3. In the Language popmenu, select the language you wish the updater to use.
23–20
Data Fork Exceptions for PowerPC and FAT Files
4. In the File Type popmenu, select either Stand Alone Updater or eSellerate
Update File.
5. Name the application as desired and click Save. A progress bar will be displayed as
a new application or file is generated.
The stand-alone application will display the Updater VISE application icon, while the
eSellerate Update file will display no default icon:
Illustration 23-15: Stand-alone Updater Application and eSellerate Update file
If you wish to change this icon, paste your custom icon in the application’s Get Info window. Do not change the updater’s BNDL or icon
resources; this may cause other updaters on the customer’s drive to display your custom icon.
Data Fork Exceptions
for PowerPC and FAT
Files
What follows contains information about handling data fork exceptions for PowerPC
and Fat Binary files.
PowerPC Data Forks
Normally, the data fork of a PowerPC or Fat Binary application consists only of PowerPC
code, so the data fork will never be modified. In this case, you do not have to worry about
data fork exceptions and can skip the discussion below.
However, if your application stores other material in the data fork of PowerPC or Fat
Binary applications, such as registration information or preferences, or if you have multiple code fragments stored in the data fork, you may need a way to identify this data as a
resource exception. You may also need to identify exceptions if you are building updates
for Fat Binary code fragments. VISE provides limited support for handling data fork
exceptions in PowerPC and Fat Binary files.
The cfrg Resource
PowerPC and Fat Binary applications contain a code fragment resource (cfrg), which
indicates that the file contains code, and identifies the location and size of each code fragment. (See Inside Macintosh: PowerPC System Software for a description of the Code
Fragment Manager.)
The location and size of each code fragment in the data fork are identified by the values
in two fields of the cfrg resource: offset and length. (The resource contains other fields
that allow for code fragments that are not in the data fork; however, these are beyond the
scope of VISE’s data fork exceptions.)
Normally, there will only be a single code fragment whose offset is 0 (kZeroOffset) and
length is 0 (kWholeFork). This indicates that the code fragment occupies the entire data
fork.
23–21
If there is more than one code fragment, the offset field will identify the position in the
data fork where the code fragment begins. The length field identifies the length of the
code fragment, in bytes. For example, a code fragment with offset 32 and length 500
means that the code fragment begins at byte 32 of the data fork and continues for 500
bytes. VISE also knows that a code fragment will always begin on a 16-byte boundary so
it will perform any necessary padding.
If Your cfrg Resource Has
Multiple Code Fragments...
It’s possible that your cfrg resource will have more than one code fragment, signified by
two or more pairs of offset and length fields.
For example, you may have an optional code fragment that is only installed on certain
machines. In this case, the first offset and length of the cfrg resource will identify the
locations of the main code fragment, and the second offset and length of the cfrg
resource will identify where the optional code fragment is stored. Since this second code
fragment may or may not exist in the customer’s source file, you must identify it as a
resource exception. In this case, use <df> 2 to indicate the second code fragment, and
enter it in the Optional Copy Resource Exception list. The updater will then look at the
second code fragment’s offset and length, and if the data is present, either ignore it or
copy it over to the new target file (depending on which Resource Exception list you put it
in.)
To identify a code fragment as a resource exception, the first pair of offset and length
identifiers will comprise <df> 1; the second pair of offset and length identifiers will comprise <df> 2; and so on. (Remember <df> 0 indicates the data fork of 68K files) To enter
this information into the Resource Exception lists of the update file, enter <df> x x in the
appropriate column, where x signifies whether it’s the first, second or third (etc.) pair of
offset and length identifiers in the ‘cfrg’ resource.
Updater VISE only supports placing either the first or last code fragment in a Resource
Exception list. If you need to perform more complicated operations on multiple code
fragments, you will need to write external code to directly manipulate the data fork during the update. For a discussion of writing external code for VISE Updaters, see “Creating
External Code Resources for VISE Updaters” on 32-18.
If Your cfrg Resource Has
Only One Code Fragment...
If your file’s data fork has only one code fragment occupying the entire data fork, you
probably won’t have to worry about data fork exceptions. The only circumstance under
which data fork exceptions can become relevant is if the program manually appends
other information, such as registration data, to the end of the data fork. In this case, you
will need to write external code to directly manipulate the data fork during the update,
see “Creating External Code Resources for VISE Updaters” on 32-18.
23–22
24–1
Chapter 24
Including Update Files in an Installer
This chapter contains information about creating installers that update existing files on
the target system, instead of installing new versions. Creating this kind of installer
requires that you use VISE update files created with Installer VISE or Updater VISE 1.4 in
the Installer VISE archive.
About Updater VISE
and Installer VISE
Updaters are small applications that let your customers upgrade their current version of
your software to the most recent version. Companies benefit from using updaters to provide upgrades and quick fixes because updaters don’t install a complete version of your
software; instead, updaters modify the existing files on the customer’s system. So, you
can freely distribute updaters without fear of contributing to the piracy of your product.
MindVision’s Installer VISE is the premier installation development tool. With the integration of Updater VISE, Installer VISE has also become a premier updater development
tool. VISE updaters, whether created with Installer VISE or with Updater VISE 1.4, are
seamlessly integrated with Installer VISE to allow you to create installers that can update
existing files as well as install new ones. VISE updaters and Installer VISE work hand-inhand so that you can:
■
Create installers that update existing files.
■
Update more than one file at a time.
■
Install new files that aren’t part of the application’s original install set but are
associated with the upgrade (such as tutorials or samples).
Application Requirements The following requirements must be met to successfully include VISE update files in an
Installer VISE installer:
■
Installer VISE 6.0 (or greater) or Updater VISE 1.4 must be used to create the
update files.
24–2
Installer Memory
Requirements
When updaters are added to an installer, the memory requirements for the installer are
automatically changed according to the table below:
Installer
Installer with Updaters
Minimum Size
1024K
2024K
Preferred Size
1024K
2024K
Table 24-1: Installer Memory Requirements
Installer memory requirements can be set from the Installer Settings, Attributes tab.
How It Works
When you build an installer that contains update files, VISE updater code is included in
the installer. When an installer encounters an update file in the install set, it does not
simply install it as it would a normal file. Instead, it installs the update file in a temporary
folder, updates the target file, and finally deletes the update file. This process is invisible
to your customer.
Including Update Files
in an Installer
General steps for including update files in an installer:
1. Build your update files as described in Chapter 23-Building Updaters.
2. Make sure that each update file can locate the target file it will be updating. To do
this, you must either:
■
Assign the update file to a Find Action Item to locate the target file, or…
■
Name the update file with the same name as the file you are updating.
3. If you wish to use the Updater interface, select Updater from the Display Interface
popmenu in Installer Settings Interface tab.
4. Set the default update location for the user. In Installer Settings Interface tab, set
the Default Install Location criteria to find a file within your product's main
folder or the folder itself.
5. Build the installer as usual.
Additional information about these steps follows.
Ignored Updater Settings
Some updater settings are ignored when an update file is included in an Installer VISE
archive. This is mainly because the standalone updater interface is not used during a
multi-file update from Installer VISE.
Updater settings changes when an updater is incorporated into an Installer VISE
installer:
■
Updater Splash Screens are not displayed.
■
Updater Read Me text is not displayed.
■
Updater Header text is not displayed.
■
Search for matching files is ignored. Use Installer VISE Find Action Items
instead to locate the files to update.
■
Open Folder After Updating is ignored.
■
Use Standard File Dialog is ignored.
Chapter 24 Including Update Files in an Installer
24–3
■
Generate Log File is ignored. The Installer VISE log file will be used instead
(assuming you configured Installer VISE to create a log file.) Log files created by
the installer will reflect any updates that occur as part of the installation.
If an update file's delete option is left at its default, Move Original To
Trash, and the installation is canceled, the original file will be moved back
out of the trash to its previous location and the new file deleted. This
allows a user's volumes to be restored to their original state if a multi-file
update fails.
■
Creating Action Items to
Find Files to Update
Finally, you may select the “Install As Normal File” checkbox in the Get Info
window to install an update file as a normal file instead of performing an update
with it.
The next step in building an installer containing update files is to create action items that
will find the files on the target system that should be updated. There are two ways to do
this, depending on where the file to be updated is located and whether it may have been
renamed or not
1. If the target item to be updated may have been renamed, or is not in the current
install location...
If the file or application may have been renamed or the current install location is
not correctly set to the folder containing the file you are updating, you must create
a Find action item to locate the correct item. For example, this would be necessary
if a customer may have renamed your application, or if you need to update a file in
a folder other than the folder containing the main application.
■
Create a Find action item to locate the target file you wish to update. Make
sure you set the Find Action's Stop Install/Remove If Find Fails option if
you wish the installation to be canceled if the file to update cannot be
found.
■
Select the update file, and use the Install To: pop-up menu to set the installation location as the result of the Find action you created.
■
Make sure that the Find action item appears before the update file it’s
attached to in the archive window.
2. If the target item to be updated will not have been renamed, and the current
install location is correct...
Some items will not typically be renamed by the customer. For example, many
applications have tools or plug-in files that it looks for by name in a certain location. If you are certain that you are updating a file that will not have been renamed
and the install location is correctly set to the folder containing the file you are
updating, follow these steps:
■
In the archive, rename the update file to the same name as the item you
wish to update on the target system. For example, if you want to update a
file that’s definitely called MyApp Dictionary on the target system, and your
update file is called Update to <MyApp Dictionary>, rename the update
file in the archive to MyApp Dictionary.
■
Select the update file, and use the Install To: pop-up menu to identify the
location of the item to update on the target system.
24–4
Setting the Default Install
Location
Set a Default Install Location so that the updater will default to the folder containing the
files that the user needs to update.
To set the Default Install Location for an installer containing updaters:
1. From the Archive menu select Installer Settings…
2. In the Installer Settings Interface tab click the Set Default Install Location button.
3. Click Set Default Install Location... and create a Find action item to locate the file
on the target system you wish to update.
Illustration 24-1: Sample Default Install Location
When the customer runs the installer, the default installation location will execute
the Find Action and default the install to the correct location.
Interface Options
Installer VISE lets you choose to present a slightly different interface to the customer for
installers that contain update files. The basic differences between an Updater interface
and a regular installer interface are the following:
■
An Update button is displayed in the lower-right corner of the window.
■
The title of the panel on the lower-left of the window is “Update Location.”
■
Clicking the Select Folder button displays only a list of folders that meet the
Install Location criteria that you specify.
24–5
You must have a Default Install Location set before selecting the updater
interface.
To use the Updater interface feature:
1. From the Archive menu, select Installer Settings. The Installer Setting Interface
tab will be displayed.
2. From the Interface popmenu select Updater.
Illustration 24-2: Setting the Updater Interface
3. Click OK when you are finished.
4. To build the installer, select Build Installer… from the File manu.
You may want to enter Easy Install text requesting that the customer make
sure that the default selected Install Location is the folder containing the
main file that you wish to update.
24–6
Updater Interface
When you choose to display an “Updater” interface the built installer will be similar to
the following:
Illustration 24-3: Installer with Updater Interface
The differences between an installer with the updater interface and the regular installer
interface are as follows:
■
An Update button is displayed in the lower-right corner of the window, instead
of an Install button.
■
The title of the panel on the lower-left corner is “Update Location,” not “Install
Location.”
■
The Select Folder button is displayed in the Update Location panel. Clicking the
Select Folder button will display a list of folders that meet the Install Location
criteria that you specify. (In an installer where the Updater interface isn’t used, a
Standard File Dialog box that lets the customer select any location would be displayed.)
Illustration 24-4: Select Folder dialog
24–7
If you do not choose the Updater interface, the only visible difference to the customer
between an installer containing update files and a regular installer is in the progress
gauge. During installation, two bars will be visible (as illustrated below): one for the
progress of the general install, and one for the progress of the updates.
Illustration 24-5: Updater dual progress dialog
This type of progress will be displayed whether you choose the Updater interface option
or not.
24–8
25–1
Chapter 25
Auto-Create Updater Archive
Multi-file Updater
Archives
Creating a multi-file updater archive can be a tedious process if you are updating many
files. You must first create a separate update file for each of your files using Updater VISE
and then add them to your archive. Next, you create Find Actions for any files whose
name or location is not guaranteed. Finally, you must set the Default Install Location in
the Installer Settings/Interface tab and turn on the Use Updater Interface, so that the user
can select the correct folder to update.
Installer VISE Automates
the Process
Installer VISE can help do some of this work by automatically creating a multi-file
updater archive using the AutoCreate Updater Archive command in the File menu.
AutoCreate Updater Archive takes an existing installer archive and compares it to the
folder containing your newer files. Instead of updating your existing archive files, however, it creates a new archive and generates update files for any files that have changed. It
can also include any new files that have been added and delete old files
During the auto-creation process, Installer VISE will create the update files, create Find
Actions for update files to applications, add any new files, create delete actions for old
files, set the initial Install Loc to the first application in your archive, and set the Use
Updater Interface checkbox. This can greatly minimize the work that you need to do to
create a multi-file updater.
The AutoCreate
Updater Process
The AutoCreate Updater Archive process is similar to the Bring Up To Date process.
Bring Up To Date starts with an existing archive, compares it with the files at the location
25–2
Auto-Create Updater
of the original source files produces an updated original archive.Installer VISE can start
with an existing archive, compare it to a new set of files and build an updater archive.
Illustration 25-1: The AutoCreate Updater Process
Auto-Create Updater
To use the Auto-Create Updater Archive command:
1. Make sure that the source folder for the archive contains the new or modified files,
and that it’s closed so that the Finder has updated any new icon locations.
(Installer VISE will automatically update Finder information at the end of this
procedure without any additional steps on your part.)
2. From the Archive menu in Installer VISE, select Autocreate Updater Archive…
Illustration 25-2: AutoCreate Updater Archive menu item
Chapter 25 Auto-Create Updater Archive
Auto-Create Updater
25–3
3. The AutoCreate Updater Archive dialog box will be displayed prompting you to
locate three folders necessary to perform this operation.
Illustration 25-3: AutoCreate Updater Archive dialog
The Storage Folder and the Create As locations default to the location of the
archive (VCT). You may change these locations if you wish.
For the Storage Folder, it is recommended that you select an empty folder on a
volume with plenty of available disk space. AutoCreate Updater Archive will create
two folders inside the selected folder, an Updater Archive Files folder which will
contain your update files, and an Updater Extracted Files folder which will contain the source files which are extracted from your original archive. These source
files are necessary for Updater VISE to compare with your new files. Installer VISE
maintains the same folder hierarchy and icon positions when creating the new
update files. This allows you to later perform an Update Archive command on
your updater archive if you change any update or new files.
4. Click the Select… button for the Compare To folder.
Navigate through your file hierarchy until the name of the source folder for the
archive is displayed in the window. Select the source folder for the archive by clicking its name and click Select at the right of the dialog box.
Illustration 25-4: Selecting the Compare To folder
25–4
Auto-Create Updater
If the items in your archive are not stored in a folder, you’ll be prompted to locate
the first item in the archive. If any items in the archive are stored in a different
location than the first item, you’ll also be asked to locate those items on your system.
5. If items in your archive are similar to new files, you will be prompted with a dialog
like the one below:
Illustration 25-5: Similar files warning
6. A Create Updater window will then be displayed allowing you to override any
individual item. See the Modification Indicators table below for an explanation of
the status messages.
Illustration 25-6: Create Updater Button
Auto-Create Updater
25–5
The following table explains the different status descriptions.
Description
Meaning
<same>
This item has not changed. If you select an item that is the
same the entire file will be added to the new updater
archive. The default is to not select files that are the same
since they do not usually need to be updated.
<different>
Only appears for folder items. At least one item within the
folder has changed.
<missing>
This item in your archive no longer exists or has been
moved from your archive folders. The default is to not
select these missing items. Select this item if you wish to
create a Delete action for it.
<new>
This item did not exist when the archive was created. You
can add this item to your new updater archive. The new file
will be added in its entirety to the new updater archive. The
default is to select new files.
<newer>
The version of the item in the source folder is newer than
the item in the archive. An update file will be created and
added to your updater archive. The default is to select
newer files since these are the ones that you will most
commonly want to create update files for.
<FInfo changed>
Finder information for the item, such as Label or
placement within a folder, has been changed.
You do not normally need to select items whose Finder
information has changed. If you do select this item, the
entire item will be added to the new updater archive.
An “X” appears in
the box to the left of
an item
The item has been selected for adding to the new updater
archive
An “—” appears in
the box to the left of
an item
Some items within the folder have been selected to add to
the updater archive.
Table 25-1: Modification Indicators
7. After making any modifications, click the Create button.
25–6
Auto-Create Updater
8. After processing, a Results Message like the one below will be displayed.
Illustration 25-7: AutoCreate Updater Archive Results Message
9. After clicking OK in the Results Message window, the new updater archive window will be displayed. AutoCreate Updater Archive has created a Default Install
Location in Installer Settings, and an archive containing all new items, updaters to
update existing items, Find actions for the update items, and Delete actions for
removal of outdated items.
Illustration 25-8: Updater Archive.vct Created by AutoCreate Updater Archive
The Updater Archive.vct contains items, updaters and actions necessary to build a
Auto-Create Updater
25–7
multi-file updater which can locate a MyApp 1.0 folder and update it to a MyApp
1.1 folder — all at a fraction of the size of a new MyApp 1.1 installer.
IMPORTANT: The update files created during this process will all use
the default settings. You may need to open some update files if you need
to modify resource exceptions or settings.
25–8
Auto-Create Updater
Section 4
Advanced Features
26–1
Chapter 26
Customizing the Archive Window
Archive Window
Overview
Much of the work of building installers takes place in the Archive Window and in the Get
Info windows for individual items. Installer VISE combines the overall scope of the
Archive Window item list with the individualized detail of the Get Info window by allowing you to customize the archive window detail and column layout. Any field associated
with an archive item can now be included in the detail or the columns or both.
Illustration 26-1: Standard Archive Window layout
User-definable Archive
Window Layouts
With Installer VISE you can construct a layout with an arrangement of item detail fields
and list columns which fits the type of installers you need to build. If you do not use
Gestalts, Languages or Regions, set up a layout without those items. Maybe you need to
set Delete on Uninstall for a number of items in your archive but you’d like an easier way
than opening each individual item’s Get Info window. With a custom archive window
26–2
Archive Window Overview
layout you can set up a layout which has the Delete on Uninstall field as one of the fields
in the list columns.
Archive Window Layouts
Defined
In Installer VISE an Archive Window Layout contains the definition for the Item Detail
and the List Columns. Layouts belong to the Installer VISE application, not any one
archive so you will have identical archive layouts for any archives you open. You may create as many custom layouts as you wish in addition to the Installer VISE Standard Layout.
Should you want to have the same layouts on different computers, Archive Window Layouts are stored in the Installer VISE Layouts (7.x) file, which can be found in the Preferences folder of the active System folder.
Standard Archive Window
Layout
Installer VISE has a default archive window layout which cannot be removed or edited.
The archive window illustrated below uses this Standard Layout.
Illustration 26-2: Archive Window Areas
■
The Item Detail is at the top of the Archive window. The Item Detail contains
data associated with an individual item selected in the Item List. As the selection
in the Item List is changed, the data in the Item Detail changes. Many fields
which were previously only available by opening an item’s Get Info window can
now be placed in the Item Detail of a custom layout.
■
The Vertical Column Titles area contains titles for list columns. This area can
be expanded and collapsed by dragging it’s bottom separator. When the mouse
is placed over the separator the cursor changes as a visual indicator that the area
can be resized.
■
The Item List contains every file, folder, sub-archive and action item in the
archive. The order of items in the Item List from top to bottom is the order in
which they will be installed or executed in an installer.
■
The List Columns contain data associated with individual items in the Item
List. Many fields which were previously only available by opening an item’s Get
Chapter 26 Customizing the Archive Window
Defining an Archive Window Layout
26–3
Info window can now be placed in the List Columns of a custom layout. Like
packages, any item in the List Columns which represents a boolean value can be
toggled on or off by clicking in the appropriate cell.
Archive Window
Balloon Help
To get help for any field in the Archive window detail area:
1. Select Show Balloons from the Help menu,
Illustration 26-3: Show Balloons menu item
or click the Balloon Help icon in the upper right corner of the Archive window.
2. Park the cursor over the label for any field, checkbox or popmenu to see explanatory text in a popup balloon.
Illustration 26-4: Archive Window Balloon Help
Defining an Archive
Window Layout
To define an Archive Window layout:
1. Select Customize from the Layout menu.
Illustration 26-5: Customize Layout menu item
26–4
2. Click the New Layout button on the Layout List dialog.
Illustration 26-6: Layout List
The ordering of items in the Layout List determines the ordering of Layout names
in the Layout menu. The topmost layout is the default layout used for newly created archives. To make a custom layout the default layout, drag the custom layout
by its grab handle to the top of the Layout List.
3. In the Edit Layout dialog Name field, type a name for your new layout.
Illustration 26-7: Layout Name field
26–5
4. In the Edit Layout dialog select fields to be displayed in the Item Detail and the
List Columns.
Illustration 26-8: Edit Layout window
5. When you have the fields for the Item Detail and the List Columns set up as you
wish, click the OK button. Your layout will be saved and you will be returned to
the Layout List window.
Layout Setup
There are a number of tools at your disposal in the Edit Layout window:
■
Click the upper >> Copy >> button to place the field selected in the Available
Fields scroll list in the Item Detail. Double-clicking on a field in the Available
Fields scroll list will also place the field in the Item Detail.
■
Click the lower >> Copy >> button to place the field selected in the Available
Fields scroll list in the List Columns. Option Double-clicking on a field in the
Available Fields scroll list will also place the field in the List Columns.
■
When a field is selected in either the Item Detail or List Columns scroll list the
corresponding >> Copy >> button changes to Clear. Clicking the Clear button
removes the field from the corresponding scroll list.
■
To move a block of fields to the Item Detail or the List Columns scroll box,
select the first field of the block in the Available Fields scroll box then with the
Shift key held down, select the last field of the block. With the entire block
selected, click the upper or lower >> Copy >> button.
■
To move several discontinuous fields to the Item Detail or the List Columns
scroll box hold down the Command key to select discontinuous fields in the
Available Fields scroll box and click the upper or lower >> Copy >> button.
■
The Insert ¶ button will place a ¶ after the selected field in the Item Detail list.
The ¶ symbol indicates a line break. When the Archive window is made wider
more fields will fit on a single line in the Item Detail unless a field is followed by
a line break. A line break indicates that the field which follows will always be
placed on a new line in the Archive window Item Detail. The line break symbol
is especially helpful when you wish to give one field in the Item Detail an entire
line. This feature is especially helpful for fields which may have enough data to
26–6
Layout Samples
fill a line or more (i.e. Packages). See “Layout Samples” on page 26-6 for examples.
■
Fields can be moved up and down by dragging within the Item Detail and List
Columns scroll boxes to change their order in the Archive window.
In addition to determining the data which can be seen in the Archive Window, Layouts also determine the data arrangement for print routines.
Print Window and all Archive Reports except the Diagnostic Report use
the current layout’s column arrangement for printouts. You may want to
design layouts specifically for printing.
Customizing the Layout
Menu
The Layout menu is dynamically created based upon the custom layouts and the ordering of those layouts in the Layout List. Layouts are automatically numbered with command key equivalents in the Layout menu.
Layout Separators
To create a separator in the Layouts menu create a new layout and use a single dash (“-”)
as the layout name. then drag the separator layout in the Layout List to the desired location. Layouts designated as separators are not given command key equivalents in the Layout menu.
Default Layout
The default layout is the layout which is listed first in the Layout List. The default layout
will be used when an archive is first opened and when a new VCT is created. To set a layout as the default layout drag the layout name to the top line of the Layout List window.
The Standard Layout
The Standard Layout cannot be edited or deleted.
Layout Samples
Layouts make the Archive window extremely flexible and powerful.
Simple Layout
For the first sample, create a very simple layout containing an Item Detail where Packages
can display on multiple lines.
Illustration 26-9: Edit Layout Item Detail with line breaks
Layout Samples
26–7
The resulting Archive window lets you see and work with only the data that you need.
Illustration 26-10: Item Detail displaying effects of line breaks
Columns for Editing
In the sample below, the layout has been customized by adding fields to the List Columns
area.
Illustration 26-11: Archive Window with customized columns
Any column which represents a boolean value can be edited in the List Columns. As
shown in the table below, some settings are not appropriate for some items and are therefor disabled when an item of that type is selected.
Field Applies to:
Updater Items
Files
Folders
✓
Application Package
Cancel if Update Fails
✓
Delete on Uninstalls
✓
✓
✓
Table 26-1: Editable Archive Window Columns
26–8
Archive Window Shortcuts
Field Applies to:
Updater Items
Files
Folders
Don’t Retain Icon Position
✓
✓
✓
File is Invisible
✓
✓
File is Locked
✓
✓
✓
Gestalts
✓
✓
✓
Install as Normal File
✓
Open After Installing
✓
✓
✓
Packages
✓
✓
✓
✓
Placeholder Folder
Restart After Installing
✓
✓
✓
Use Custom Icon
Symbolic Link
✓
✓
Synchronize Dates
✓
✓
✓
Set Owner To Root
✓
✓
✓
Table 26-1: Editable Archive Window Columns
Expand and Collapse Column The Vertical Column Titles area can be expanded or collapsed by dragging the lower edge
of the title area up or down. When the mouse is in the proper position to expand or colTitle Area
lapse the title area the cursor changes to:
Illustration 26-12: Expand/Collapse Column Cursor
Archive Window
Shortcuts
Action
Shortcut
Click on a vertical column title
Selects all items assigned
Command-right arrow
Expands selected folder(s)
Command-left arrow
Collapses selected folder(s)
Option Command right arrow
Expands selected folder(s) and all its
sub-folders
Command-A
Selects all items in the item list
Table 26-2: Archive Window Shortcuts
26–9
Action
Shortcut
Option-Add Button
Use the alternate Add dialog from the
Preference setting
Up arrow
Select previous item above in item list
Down arrow
Select next item below in item list
Option Double-Click an Updater Item
Show Files window (Bypass Get Info)
Enter or Return
Make selected item’s name an editable
field (toggles)
Double-click on a folder while holding
down the ‘D’ key or the ‘d’ key.
Open the default folder settings dialog
for that folder.
Table 26-2: Archive Window Shortcuts
26–10
27–1
Chapter 27
Advanced Project Management
Installer VISE contains a number of features which enable new levels of installer project
management. Advanced Project Management features include:
■
Build Directives
■
Project Window
■
Build Directives
■
Build Source
■
Build Target
■
Archive Links
■
Read Me Files
■
License Agreements
■
Resource Files
■
Billboard Files
■
Shared Libraries
Using Installer VISE with Source Control
Build Directives allow you to conditionally include or exclude items (folders, files, action
items, and external resource files) from your installer at build time. They are very similar
in functionality to compiler directives in program code. Build Directives may be best
understood if contrasted to Packages.
■
Packages serve as limiting agents at installer runtime while Build Directives
serve as limiting agents at installer build time.
■
Packages determine whether the item in the installer will be executed or
installed while Build Directives determine whether the item will even be
included at all in the built installer.
■
Packages allow flexibility at installer runtime so that one installer can cover several install options. Build Directives allow flexibility at installer build time so
that one archive can be used to build multiple installers which share some con-
27–2
Build Directives
tent but each have some different content.
Build Directives serve as limiting agents for an item at installer build time. If no Build
Directives are checked for the item, the inclusion of the file, folder, action item or external resource file in an installer build will not be limited. Another way to say the same
thing would be – if no items are checked in the Build Directives popmenu, this item will
Up to 63 Build Directives can be defined per archive through the Build Directives window.
Illustration 27-1: Build Directives window
Once defined, Build Directives can be assigned to:
■
Action Items
See “Assigning Build Directives to Action Items” on page 8-4
■
Files and Folders
See “Assigning Build Directives to Files and Folders” on page 12-13
■
Packages
See “Package Build Directives” on page 7-18
■
External Resource files assigned through the Project Window
See “Resource Files” on page 27-27
Build Directive assignments are dependent on Build Targets, which allow
you to build multiple installers at once using pre-defined settings. At build
time, Installer VISE will include/exclude archive items based on the Build
Directive settings for each Build Target used. For more information on
Build Targets, see “Build Targets” on page 27-8.
Build Directives and the
Archive Window Item List
Archive items (files, folders and action items) which will not be included in a build performed with the current Build Directive settings are grayed in the Archive Window Item
Chapter 27 Advanced Project Management
Build Directives
27–3
List. If your Archive Window layout has been designed with Build Directives as one of the
columns, the active Build Directive(s) will be indicated by a bullet before the name.
Illustration 27-2: Item Dimmed in Archive Window due to Build Directives
Build Directives and the
Project Window
External resource files which will not be included in a build performed with the current
Build Directive settings are grayed in the Project Window.
Illustration 27-3: Item Dimmed in Project Window due to Build Directives
Build Directive Setup
To set up Build Directives for an archive:
1. Add to the archive all files, folders, action items and external resource files for all
installer builds. Your archive should contain a superset of all installer builds.
27–4
Build Directives
2. Select Build Directives… from the Archive menu.
Illustration 27-4: Build Directives… menu item
3. Enter Build Directive names for each Build Directive you will need.
Illustration 27-5: Enter Build Directive Names
Build Directives are not mutually exclusive. They may be used together. For example, in the illustration above, we may want to build an installer which will include
all items for Debug Build, Basic Install, Deluxe Install, and Deluxe + Fonts. All
Build Directives would be checked in that case. On the other hand, a Basic Debug
installer would be built if only the first two Build Directives were checked.
4. Close the Build Directives window by clicking the OK button.
5. From the Layouts menu, switch to an archive window layout which has Build
Directives in the columns. If you do not have an archive window layout which has
Build Directives in the columns see “Defining an Archive Window Layout” on
page 26-3.
6. Be sure that the active Build Target is the one you wish to associate with these
Build Directives (see “Active Build Target” on page 27-21).
Build Directives
27–5
7. Assign Build Directives to any item which will be limited.
Illustration 27-6: MyApp Archive with Sample Build Directive Setup
Items of note about the sample setup above:
■
The easiest way to understand the Build Directives assignments is to read
across the archive window from item name across to Build Directives
assignment.
No Build Directive Assigned
■
The Find SimpleText Action item is included in all installer build because it
does not have any Build Directive assignments. Items which will always be
included in any build have no Build Directive assignments (i.e. they are not
limited). The Find action item, the MyApp 2.0 folder, and the basic contents of the MyApp 2.0 folder do not have a Build Directive assignment.
They form the foundation of all builds of this product family.
Only One Build Target
■
The Debug Only folder will only be included in a build when the Debug
Build Directive is active (marked by a bullet in the column title area).
AND Conditions
■
The MyApp Deluxe Debug Issues item will only be added to the Debug
Only folder if both the Debug Build AND the Deluxe Install Build Directives are active.
27–6
Project Window
OR Conditions (Any Match)
■
Because the Any Match column is checked also, The MyApp Clip Art folder
will be included if either the Deluxe Install OR the Deluxe + Fonts Build
Directive is active.
NEVER Conditions
■
The “Last Mod” Message Action item has only the Any Match column
checked and will therefore never be included in an installer build. Using an
action item in this way facilitates creation of comment action items which
will never be included in built installers - this one is being used by the
developer to record who last modified the archive and when.
8. Open the Build Directives window and check the Build Directives which should
be active.
9. Close the Build Directives window.
10. Build the installer.
Using Build Directives, Build Targets and AppleScript you can easily create
an automated installer build system.
Project Window
The Project Window contains an overview of the current installer project.
To access the Project Window:
1. With an archive open, select Show Project Window from the Archive menu.
Build Sources
27–7
2. The Project window will be displayed.
Illustration 27-8: Project Window
The Project Window is always titled after the archive. If your archive name is
MyApp.vct the project window for that archive will be titled MyApp.vct Project.
When you have multiple archive windows and multiple project windows open it
can become important to be aware of which project window with which you are
working.
In the illustration above we can see that the Archive.vct project contains:
Build Sources
■
5 Build Targets
■
2 embedded VCTs
■
2 Read Me Files (one for the Default Language, one for French)
■
2 License Agreements (one for the Default Language, one for French)
■
2 External Resource files (in this case, external code resources)
■
2 Billboard Files (one for the Default Language, one for French)
■
2 Shared Library files
Each Installer VISE archive item stores a path to its source on a hard drive or server. In
the archive, folders can be created within the archive, files can be added to the folders and
the hierarchy within the archive can be changed without necessitating a change in the
source file’s location or hierarchy. Each item knows where its source is regardless of its
27–8
Build Targets
arrangement within the archive. The structure within the VCT no longer is forced to
match the Finder structure of the source files.
The Sources window displays source paths for each item that was dragged into the
archive. Paths will be displayed for all unique outermost enclosing folders and individual
files that have their own unique paths. By editing source paths, the archive items can be
directed to point to new source items.
Illustration 27-9: Sources Window
If the Option key is held down while opening the Sources dialog, all unique paths within
the archive will be displayed.
Bring Up To Date and Validate Paths use the path(s) displayed in Sources to perform
their operations.
Build Targets
Build Targets allow you to set up different kinds of installers and to easily switch between
them when building. Build Targets can be used to automate the process of building multiple installers with different settings at once.
Illustration 27-10: Target Window
Build Targets
27–9
Attributes tab
Format
Items selected from the Format popmenu control what happens when you select Build
Installer… from the File menu as well as the type of installer which will be built.
Target Format
Explanation
Ask At Build
At build, the standard build dialog will be displayed
where save location, segment name, debug status,
and postprocessing can be determined. Ask at Build
is the build behavior which most closely matches that
of Installer VISE versions prior to 5.0.
Floppies
This feature was disabled for Installer VISE version
8.0. Older VCTs that have the Floppies option
selected will behave as if Ask at Build was selected.
Disk Images
At build, installer disk images will be created at the
location designated by the path field. This option
creates an installer that would be identical to one
produced by building to floppies and then creating
disk images of those floppies. Installer VISE calls on
Apple’s Disk Copy to build standard disk images.
These images can be 800K and larger.
Folders
At build, an installer based on data from the Disk
Names List is created at the location designated by
the path field. Disk Names are used for folder names
and Segments are saved within the appropriate disk
folder.
CD Installer
At build, a CD installer is created at the location
designated by the path field and files are extracted
from the archive and copied to the same location as
the CD installer.
Single File
At build, a single file installer containing compressed
archive items is created at the location designated by
the path field.
Web Installer
At build, a web installer and designated group files
are created at the location designated by the path
field. If Upload Cab file(s) to Web Server at Build
Time (FTP Sites Only) is checked in the Web tab of
Installer Settings, the group file(s) are uploaded to
the web server designated in Download Sites from the
Internet menu.
Table 27-1: Build Target Format Options
27–10
Build Targets
Target Format
Explanation
Web Installer (Data In
Installer)
At build, a web installer (containing all data as if user
had just downloaded it) and designated group files
are created at the location designated by the path
field. If Upload Cab file(s) to Web Server at Build
Time (FTP Sites Only) is checked in the Web tab of
Installer Settings, the group file(s) are uploaded to
the web server designated in Download Sites from the
Internet menu.
USB Installer
At build, a single file USB installer is created at the
location designated by the path field. This installer
will deliver the driver (system extension file) required
for a specific USB device, and can also deliver other
files. For more information,see Chapter 38-USB
Installers.
Single File w/External
Data
This format was created to work around a file
mapping conflict on Mac OS X, and is no longer
needed. It is retained for legacy purposes.
Table 27-1: Build Target Format Options
Platform
The Platform popmenu determines the installer platform for the Build Target.
Target Platform
Explanation
Classic
This setting builds installers for 68K platforms.
PowerPC
The PowerPC setting builds installers for PowerPC
platforms.
Carbon
Installers built with the Carbon setting will run on
Mac OS X and Mac OS 8.1 through OS 9.x (on OS 8
and OS 9 systems, the CarbonLib 1.1 or newer system
extension must be installed).
If the format is Single File and the platform setting is
Carbon, a Create OS X Bundle checkbox will be active.
With this option selected, Installer VISE will build the
installer as a Mac OS X application bundle. This is the
preferred way to deliver a multi-language installer on
Mac OS X. It allows the proper display of single-byte
and double-byte character sets from within the same
installer.
Unified
The Unified setting builds installers that contain
executable code for both Carbon and non-Carbon
platforms. This allows a single executable installer to
run on anything from Mac System 7.1 to Mac OS X
systems.
Build Targets
27–11
Target Platform
Explanation
PowerPC SharedLibData
Installer VISE can build a data file containing all
necessary files and install information. Applications
can then call MindVision's shared library to install files
as specified in the data file. This performs installations
without displaying a traditional installer interface. It is
useful in situations where you don't need to give the
user install options, such as for self-healing
applications, or first-run installers. The data file option
is available for PowerPC and Carbon formats. See also
“Calling the MindVision Shared Library” on
page 27-11.
Carbon SharedLibData
See the preceding explanation.
A Carbon installer running on Mac OS X can install to a Mac OS X drive
or a Mac OS 9 drive.
Calling the MindVision
Shared Library
The files required to call MindVision’s shared library are located in the Shared Lib folder
of the Installer VISE folder. There you will find the Shared Library, the Stub Library and
a header file needed to call Installer VISE as a shared library from another application.
Your application project will link against the stub Library and include the header so that
the parameters passed to the shared library will be defined.
You will need to specify an address of:
1. FSSPec to the Shared Library
2. FSSpec to the Data File (Installer data file that was created with Installer VISE)
3. FSSpec to where you want the files installed (not yet implemented; pass nil)
4. Long variable to hold the Installer Result Flags (currently = 1 if the installer
requests a restart; else returns 0)
For example:
OSErr DoInstall(FSSpec *sharedlibFSSpec, FSSpec *dataFSSpec, FSSpec *destFSSpec,
long *ResultFlags);
27–12
Build Targets
If for some reason the installer fails (or the user cancels), an OSErr will be returned. The
error can be:
Error
Code
Meaning
-?
Any real OS or resource error (for example, a missing resource such as
'PsWd')
-11
User cancelled through the progress dialog, or there was an error during
the install process.
-1
Could not find the data file (FSSPec passed was not found)
1
Minimum install – OS is too old
2
Minimum install – insufficient machine RAM
3
Minimum install – CPU is too old
4
Minimum install – Open Transport version is too old
-5550
Minimum install – Gestalt not met
-927
Invalid password
-108
Insufficient memory
102
OS is too old – Gestalt() not supported
120
Default install location could not be found – installer will quit
5
User declined license agreement – installer will quit
Table 27-3: Error codes for MindVision shared library
Installer VISE includes a sample CodeWarrior project that demonstrates
how to call the VISE Shared Library to handle the installation of files. If
you need to install this project, run the Installer VISE installer and do a
custom install for “Tutorial and Sample Files.”
Create Debug
Create Debug - controls the inclusion of debug features in a built installer.
Build Targets
27–13
Settings
Illustration 27-11: Build Target, Attributes tab, Settings popmenu
Selecting an item from the Settings popmenu allows you to determine the Installer Settings set that will be used for the Build Target. Each Build Target can have its own
Installer Setting or Installer Settings can be shared by different Build Targets.
Display Billboards
Illustration 27-12: Build Target, Attributes tab, Display Billboards popmenu
27–14
Build Targets
Selections from the Display Billboards popmenu determine how the billboards will be
displayed.
Display Method
Explanation
Sequentially
Billboards will be displayed in sequence during
the install. Billboard duration can be set per
billboard. If billboard durations exceed actual
install time, some billboards may not be
displayed.
By Disk
Billboards will be displayed by disk during the
install. If a disk is not used during an install, the
billboard assigned to that disk will not be
displayed.
By Package
Billboards will be displayed by package as the
package is installed.
Installer Name
Language
The Installer Name field is used to designate the file name for the built installer. The
Installer Name field is only available for the following Build Target formats:
■
Ask at Build
■
CD Installer
■
Single File
■
Web Installer
■
Web Installer (Data In Installer)
■
USB Installer
Selections from the Language popmenu determine which languages this installer will
support. The Build Target Language popmenu contains all of the supported languages
plus the last item, Language In Archive.
At installer build, while copying the resources from the Localization File that have been
imported in the Localization window, Installer VISE will only copy the translated information for the language(s) checked in the Build Target language popmenu.
The last item, Language In Archive is used when there is only one language in the language file. If it is checked on, the installer will support the language in the VCT plus the
language that has been imported into the Localization file.
Path
The Path determines where the built installer will be saved along with any segments, file
group files, web catalog files and any Finder-draggable files.
Be sure to select a path for built installers that is different from the path
for source files. This becomes especially important for CD Installers.
Build Targets
Duplicating a build target
27–15
There may be times when you want to duplicate a build target. For example, you could
duplicate a complex build target and make just one change to the copy so that it creates a
debug installer.
To duplicate a build target:
1. Click on the target name to highlight it.
2. Hold down the Option key and click Add.
Directives tab
Illustration 27-13: Build Target, Directives tab
When a Build Target is built, Build Directives will be set on or off based upon the settings
in the Build Target Directives tab. This enables Build Targets to automatically include or
exclude files, folders and actions. Using Build Directives and Build Targets, one archive
can be used to build multiple installers with different file sets. For more information see
“Build Directives” on page 27-1.
27–16
Build Targets
Post processing tab
Illustration 27-14: Build Target, Post Processing tab
After an installer is built items set in the Post Processing tab enable the automatic creation and placement of BinHex and/or MacBinary files. The field allows you to predetermine the BinHex or MacBinary file name. The Edit Path button allows you to determine the BinHex and/or MacBinary files’ location.
Post processing is only available for the following Build Target formats:
■
Ask at Build
■
Single File
■
Web Installer
■
Web Installer (Data In Installer)
Post Processing file name and path are ignored for installers created with
the Ask at Build format. In this case, the BinHex and/or MacBinary files
will be saved at the same location as the installer, and use the installer file
name followed by ".hqx" or ".bin" as appropriate.
Build Targets
27–17
Scripts tab
Illustration 27-15: Build Target, Scripts tab
The Build Target Scripts tab allows you to designate one AppleScript applet to be executed before the target is built and one AppleScript applet to be executed after the target
is built.
Dates tab
Installer VISE lets you synchronize the dates of specified install items at build time,
according to the target used. You will need to mark the items to synchronize, and set the
dates in whatever target you use to build the installer.
To synchronize dates:
1. From the main archive window, double-click on an install item.
27–18
Build Targets
2. Check the check box next to Synchronize Dates to turn it on, and then close the
window.
Illustration 27-16: Document Get Info Window
3. Next, type Command+0 to display the Project Window. Then double-click on the
target that you want to use for this installer.
4. Click on the Dates tab.
Illustration 27-17: Build Target, Dates tab
Build Targets
27–19
5. Use the popmenu on the left to set the creation and modification dates. The
default options are Today, Yesterday and Tomorrow, or you can choose Custom to
set a different date.
6. Use the popmenu on the right to set the creation and modification times. The
default options are Current, 8:00 AM, Noon, 5:00 PM and Midnight. You could
also choose Custom to set a different time. When you’re finished, click OK.
7. Build an installer with this target.
Synchronize Dates occurs at build time and will only affect items as you
build them into the installer. The dates of the items in your archive will
remain unchanged.
eSeller tab
Installer VISE integrates seamlessly with eSellerate, the powerful e-commerce system
from MindVision. Sign up for our optional eSellerate service and sell software directly to
your customer from inside your installer. With eSellerate’s Installer eSeller, your customers can:
■
Purchase and install the retail version of your product.
■
Install the demo version of your product first and, later, purchase the retail version from inside the application using eSellerate’s Integrated eSeller technology.
eSellerate will guarantee that your installers always deliver the latest version of your software at the latest price. Your customers will never again install outdated software.
Integrating your installer
with the eSellerate system
Everything you need to integrate your installer with the eSellerate system is available in:
■
The Build Target eSeller tab.
■
The Edit Package window.
■
The Save As dialog for eSellerate updaters.
Illustration 27-18: Build Target, eSeller tab
27–20
Build Targets
The unique codes and IDs used in the eSeller tab are generated by the web-based eSellerate Sales Manager.
Illustration 27-19: Edit Package, Purchase popup menu
Build Targets
27–21
At install time, an Installer eSeller will show specific packages based on whether the user
chooses to purchase the product or try a demo.
Illustration 27-20: Save As dialog for eSellerate Updaters
eSellerate Update files provide all the functionality of other Installer VISE updaters.
When appropriate, Integrated eSellers can download these small update files and initiate
an update.
Learning About eSellerate Complete information about the forenamed eSellerate features is available in the eSellerate User’s Guide. You can find this documentation and the SDK at http://www.esellerate.net/downloads.
To learn more about eSellerate, visit http://www.esellerate.net. Here you can set up a free
evaluation account, read the FAQ, find pricing/licensing information and much more.
Active Build Target
Multiple Build Targets can be created. To set a Build Target as the active (current) Build
Target click your mouse to the left of the Build Target icon and name. The active Build
27–22
Archive Links
Target is indicated by a bullet symbol (•) Checked Build Targets (√) will all be built
whenever a build command is executed.
Illustration 27-21: Multiple Build Targets
To duplicate a Build Target, select the Target in the Project window, hold
down the option key and click the Add button.
Archive Links
Archive Links displays important information about any embedded VCTs in the archive.
Embedded VCTs are Installer VISE archives which have been linked to the archive. The
files, packages, gestalts, Build Targets, and external resource files of the embedded VCT
become part of the master archive. In this way, archives can be objects to be used within
other archives.
One department may be working on an archive of sample files, another department on
an archive of ancillary files and applications, and another department may be putting
together an archive containing 3rd party software necessary for successful operation (i.e.
QuickTime, Fonts, Acrobat Reader, etc.). All of those endeavors can be going on at once,
separately or together. The Master Installer Builder will be able to create the main archive
with Splash Screen, Billboards, Read Me and License Agreement files and embed the
other archives so that they are combined seamlessly into one archive for building an
installer.
Archive Links
27–23
VCTs that you embed in your main archive should be no more than one
level deep. In other words, an embedded VCT should not contain
another VCT. Embedding VCTs more than one level deep is not supported and will produce undesirable results.
To embed a VCT (with links) in your archive:
1. From the Edit menu select Preferences. The Preferences dialog will be displayed.
2. In the VCT Link Options panel, if it is not already selected, select Create Links
For.
Illustration 27-22: Preferences - VCT Link Options
3. If they are not already selected, make sure Packages, Gestalts, External Codes and
Build Directives are checked and click OK to close Preferences. When a VCT is
embedded, links will be created for each item checked.
If Don’t Create Links is on in Preferences, any VCT will be added and installed as
a normal file.
4. Add a VCT to your main archive by using the Add… button in the Archive window or by dragging a VCT into the archive window and dropping it in the desired
27–24
Archive Links
location within the item list. Embedded VCTs have the red inverted VISE icon.
Clicking the twist-down arrow next to an embedded VCT will reveal its contents.
Illustration 27-23: Archive window after embedding VCTs
When a VCT is linked, the embedded VCT’s packages, resource files, gestalts, and
external resource file assignments are added to the master archive.
With the exception of package assignments, an embedded VCT’s files, folders and
action items cannot be edited in the master archive.
5. The Project window will display embedded archives in the Archive Links section.
Archive Links
27–25
6. Click the embedded VCT’s twist-down arrow in the Project window to reveal the
package links and resource file links added to the master archive from the embedded VCT.
Illustration 27-24: Project window after embedding VCTs
27–26
Read Me Files
7. If you open the Get Info window for the embedded VCT there is an option entitled, Don’t Copy vct Resources. When checked, the resources for that embedded
VCT will not be copied into the built installer.
Illustration 27-25: Get Info window for Embedded VCT
Read Me Files
All Read Me files which are assigned to the installer in the Installer Settings Text Files tab
are listed in the Project Window Read Me Files section.
Viewing a Read Me File
To view a Read Me File:
1. Select the file name in the Project Window Read Me Files section.
2. Click the View button at the upper right of the Project Window.
License Agreements
All License Agreement files which are assigned to the installer in the Installer Settings
Text Files tab are listed in the Project Window License Agreements.
Viewing a License
Agreement
To view a License Agreement File:
1. Select the file name in the Project Window License Agreements section.
2. Click the View button at the upper right of the Project Window.
Resource Files
Resource Files
27–27
Installer VISE extensively supports the addition of custom code to perform additional
functions required by your installer. This custom code can be in the following forms:
■
Code resources
■
Shared libraries
■
UNIX shell scripts
You can add external code resources to your archive using the Resource Files heading of
the Project Window. Similarly, you would use the Scripts/Shared Libs heading to add
shared libraries.
To learn how to add custom code to an Installer VISE archive, see Chapter 9-Assigning
External Code.
Billboard Files
In Installer VISE, billboard files can be assigned to an installer by adding them to the Billboard Files section of the Project Window. Billboard files added through the project
Window can be assigned Build Targets and Languages.
To add a billboard file to the archive:
1. In the Project Window, select the Billboard Files heading and click the Add button.
Illustration 27-26: Adding a Billboard File
27–28
Shared Libraries
2. Locate the external billboard file to add and click the Select button.
Illustration 27-27: Selecting a Billboard file
By clicking the New File… button, you can create a new billboard file at the location shown.
3. The Billboard File dialog is displayed. If you are using Build Targets, make assignments by making selection(s) from the Build Target popmenu. If the billboard file
has no Build Targets assigned, it will be included in every build.
If the billboard is for a specific language, select the language from the Language
popmenu. This enables the creation of multiple billboard file sets for different languages or even different sets of billboards for the same language.
Illustration 27-28: Setting Build Targets for a Resource File
4. Click OK to close the Billboard File dialog
For information on Billboard setup see Chapter 15-Adding Billboards to an Installer.
Shared Libraries
Along with external code resources, shared libraries are another way to add custom code
to an Installer VISE archive. You add shared libraries using the Scripts/Shared Libs heading of the Project Window.
To learn how to add custom code to your archives, see Chapter 9-Assigning External
Code.
Scripts (Mac OS X only)
Scripts (Mac OS X only)
27–29
Carbon installers running on Mac OS X can execute UNIX shell scripts to perform various actions on the target computer. You add scripts using the Scripts/Shared Libs heading of the Project Window.
To learn how to add custom code to your archives, see Chapter 9-Assigning External
Code. Also see “Executing UNIX scripts from the installer” on page 32-22.
Installer VISE and
Source Control
To facilitate the use of Installer VISE in environments where Source Control is in place
features have been added to minimize the overhead when checking in an archive and to
recognize and honor a source control system’s file locking mechanisms.
Remove Compressed Data
To Remove Compressed Data from an Archive Before Source Control Check-in:
1. From the File menu select Remove Compressed Data…
Illustration 27-29: Remove Compressed Data menu item
2. When the installer is built, Installer VISE will go out and compress all of the data
from the source files before building the installer segments.
Honoring an Archive’s Locked Installer VISE will honor a locked state initiated by a source control system. When you
open an archive that has been checked into a source control system but that has not been
State
checked out for editing you will receive a warning.
Illustration 27-30: Source Control Warning
27–30
Installer VISE and Source Control
An archive which is part of a source control system but which has not been checked out
for editing is indicated by a lock icon in the status bar at the bottom left of the archive
window.
Illustration 27-31: Archive Window with lock
28–1
Chapter 28
Using Runtime Variables
Runtime Variables
Runtime variables are placeholders that are filled with values when the installer is run on
the customer’s computer. Runtime variables can be used for text substitution as well as
for program logic.
Runtime variables can be set by:
Using Variables for
Text Substitution
■
Assigning default values in the Variable list
■
Set Variable Action items which execute during installation
■
Form controls (buttons, checkboxes, and radio buttons) which are activated by
user choices in custom dialogs during installation
Runtime variables can be used as placeholders which will be substituted with variable
text when the installer is run. In the following example we will set up and use a variable
for runtime text substitution.
The basic steps for setting up variables for text substitution are:
Declaring a Variable and
Setting Initial Value
■
Declare variables and set initial values.
■
Enter variables in desired text areas.
■
If necessary, add Set Variable actions to reset variables to initial values for
installers which may be run multiple times without quitting between runs.
To declare a variable and set its initial value:
1. From the Archive menu select Variables…
2. The Variable List window will be displayed. Click the New button.
28–2
Using Variables for Text Substitution
3. In the Edit Variable window type in a variable Name. You may also enter a default
Value for the variable. If you wish to add an explanatory comment about the variable you can type that in the Comments field.
Illustration 28-1: Edit Variable
Variable names are case sensitive. %Product% is not the same as %product%. When testing the value of a variable, however, the test is not case
sensitive, so “Photoshop” is considered the same as “photoShop”.
4. Click OK to close the Edit Variable window.
5. Click OK to close the Variable List window.
Entering Variables in Text
Areas
Variables can be used in a number of locations within the installer. For a complete list of
areas where runtime variable substitutions are valid see Table 28-1, “Valid Archive Areas
for Runtime Variable Substitution,” on page 28-6. Also see “Special Variables” on
page 28-7 for information on variables with special uses.
In our example we will enable runtime variable substitution in Easy Install Text and in
Package Name and Description so that the archive we construct can be used to produce
installers for multiple versions of our product with a simple variable value change.
To enter variables in text areas:
1. From the Archive Menu, select Installer Settings.
2. In the Easy Install panel, click on the Edit Easy Install Text button.
3. Type in the text to be displayed for Easy Install. When entering a variable to be
substituted at runtime, type a percent sign, followed by the variable name, fol-
Chapter 28 Using Runtime Variables
28–3
lowed by a percent sign. %VariableName% is the indicator for a runtime variable.
Illustration 28-2: Entering a runtime variable in Easy Install text
In our example, when the Installer is run, %Vers% will be replaced with the text
“1.1”. Make sure you type the variable name exactly as it is declared in the Edit
Variable dialog.
4. Click OK to close the Edit Easy Install Text window and click OK to save Installer
Settings.
5. To enter variables in descriptive text for packages, from the Archive menu select
Packages to get the Package List.
6. In the Package List, select the New button to create a new package.
28–4
7. In the Edit Package window type in text as it appears in the illustration below.
Illustration 28-3: Edit Package window using variables
Note the use of runtime variables in the Package Description and in the Package
Version fields When this installer is built and run the text “1.1” will be substituted
for %Vers%.
8. Select OK to close the Edit Package window and OK to close the Package List window.
28–5
9. Add files to your archive, assign files to packages, and build the installer to test the
runtime variable substitution.
Illustration 28-4: Installer with Easy Install Text
Select Custom Install in the installer and click the package info button for the
Application Only package to test the variable substitution in the Package Description.
Illustration 28-5: Package Description displaying substituted variable text
28–6
Valid text areas for
variable substitution
Valid areas for variable substitution are listed in the table below:
Archive Area
Valid for Variable Substitution
Find Action Item
Search Criteria Name
Search Criteria Type
Search Criteria Creator
User Prompt
Delete Action Item
User Prompt
Copy Action Item
User Prompt
New Name
Move Action Item
User Prompt
Rename Action Item
User Prompt
New Name
Alias Action Item
User Prompt
Alias Name
Message Action Item
User Prompt
Button 1 Name
Button 2 Name
Set Variable Action Item
Set Variable To value
Test Variable Action Item
Test Variable Comparison value
Sub-launch Action Item
Edit Text File Action Item
User Prompt
Search For Text
Text to Add/Append
Table 28-1: Valid Archive Areas for Runtime Variable Substitution
Using Variables for Install Logic
28–7
Archive Area
Valid for Variable Substitution
UNIX Script Action Item
UNIX Script
Packages
Package Name
Package Description
Package Version
Package List Header
Package List Footer
Default Install Location
Installer Settings
Easy Install Text
Uninstall Text
Create Installation Folder Named
Log File Name
Forms
Static Text Item text
Edit Text Item text
Files
File Name
Table 28-1: Valid Archive Areas for Runtime Variable Substitution
If you need to include a percent symbol in a valid variable substitution
field, use %%. At installer runtime, %% will be replaced with %.
For instance, if my Package Description field needs to display, “MyApp
now features 50% faster start-ups,” the field should be set to “MyApp now
features 50%% faster start-ups.” When the installer is run and the variable is substituted, the resulting string will be “MyApp now features 50% faster start-ups.”
Special Variables
Using Variables for
Install Logic
Installer VISE recognizes the following variables for use in special install functions:
■
InstallVar. Installers can use the value of this variable to dynamically set install
locations at the time of install. See “Setting Install Locations With Variables” on
page 36-3.
■
ShellVar. Installers can send the value of this variable to a UNIX shell script. See
“Executing UNIX scripts from the installer” on page 32-22.
The best way to demonstrate the use of variables for install logic is to walk through the
use of variables in a real world install situation. For the purposes of this example we will
step through the setup of the archive used to create the Installer VISE 7.2 installer. Our
scenario is as follows:
The installer for Installer VISE 7.2 can optionally install a set of preconfigured
archive window layouts. All archive window layouts are stored in one file in the
user’s Preferences folder and since there can only be one file named Installer VISE
Layouts (7.x) in the Preferences folder, installing a sample set would replace any
existing layouts that had been created previously by the user. We wanted to allow
the user to choose not only if the sample layouts would be installed or not but also
whether the install would replace or rename an existing Installer VISE Layouts
(7.x) file.
28–8
Installer VISE versions 5.0 through 7.0 used a file named Installer VISE
Archive Layouts to store layouts. With the introduction of the Domain feature in Installer VISE 7.1, the layouts file name changed to Installer VISE
Layouts (7.x).
1. The archive window for our finished installer is shown in the illustration below.
Illustration 28-6: Var Logic VCT
If you use an archive window layout which displays Install If, Install To and
Replace options in the columns, the flow of the install can be traced. With a little
practice you should be able to read down through the archive items’ Install If,
Install To and Replace settings to get an overview of the archive’s logic flow. In the
following steps, we’ll walk through the archive one item at a time explaining the
details of the setup. We will start with variable declaration.
2. The Variable setup in the archive:
Variable Name
InstallLayouts
Value
No
Table 28-2: Var Logic VCT Variables
There is only one runtime variable declared which is necessary for example here.
The first item in the archive is a Set Variable action item. We start by initializing
our key variable InstallLayouts to “No” so that we can count on a consistent variable value even if the installer is run multiple times in the same session.
28–9
3. We needed to construct a dialog that would be displayed to the user during the
install which would clearly spell out the layout install options.
Illustration 28-7: Var Logic Form
Note that the Yes-rename radio button is the default selection and the OK button
is the default button so that the user can accept the choice of the dialog by hitting
the Return or Enter key. Each item in the form layout is listed below with the
properties that are important for our example.
Var Logic
Form Item
Properties
Picture
Res ID 998 (icon graphic)
Static Text
Text asking user for input.
Radio Group
Name: Layout Install Options
Title: Layout Install Options
Set Variable: InstallLayouts
Radio Button
Name: Rename
Title: Yes - rename existing layout file
Default On: Checked
Radio Button
Name: Replace
Title: Yes - replace existing layout file
Default On: Unchecked
Radio Button
Name: No
Title: No
Default On: Unchecked
Button
Title: OK
Default button: On
Behavior: Continue
Table 28-3: Var Logic Form Items
28–10
Note that the Radio Group item set the variable InstallLayouts. None of
the individual radio buttons are configured to set a variable. When the OK
button is clicked (since it has a behavior of Continue), the InstallLayouts
variable will be set to the Name of the highlighted radio button. It is
important to note that each of the radio button Names differ from their Titles. The
Test Variable actions which follow this form will test the InstallLayouts variable for the
values “Rename,” “Replace” or “No” rather than “Yes - rename existing layout file,”
“Yes - replace existing layout file” and “No.”
4. Each root level item in the archive is listed below with a description of the items
function and/or properties.
Archive Item
Item Type
Description
Initialize
InstallLayouts
Set Variable
Action
Set InstallLayouts variable to “No.” Provides
initial variable value and resets variable if they
do multiple installs without quitting.
Installer VISE
7.2
Folder
Install items
Find IVISE7
Archive Layouts
Find Action
Search the Preferences folder for a file named
“Installer VISE Layouts (7.x)” with a Type of
LAYO and a Creator of VIs5.
Install Archive
Layouts?
Form Action
If the Find IVISE7 Archive Layouts Find Action
succeeds then display the Install Archive Layouts
form.
Form execution will set the InstallLayouts
variable based upon user selection of options.
Rename Layout
Test Variable
Action
Test the InstallLayouts variable to determine if it
equals “Rename”.
Replace Layout
Test Variable
Action
Test the InstallLayouts variable to determine if it
equals “Replace”.
Installer VISE
Layouts (7.x)
File
If this hard drive does not have Installer VISE
Layouts (7.x)on it then automatically install the
sample layouts file.
Install If: Find IVISE7 Archive Layouts fails.
Install To: Preferences
Replace: Never
Table 28-4: Var Logic Archive Item Descriptions
28–11
Archive Item
Item Type
Description
Installer VISE
Layouts (7.x)
Shadow of
Installer
VISE Layouts
(7.x) file
If the InstallLayouts variable equals “Replace”
then install the original of this shadow item.
Install If: Replace Layout variable test is TRUE.
Replace: Always
Installer VISE
Layouts (7.x)
Shadow of
Installer
VISE Layouts
(7.x) file
If the InstallLayouts variable equals “Rename”
then install the original of this shadow item.
Install If: Rename Layout variable test is TRUE.
Replace: Always, Rename Existing
Table 28-4: Var Logic Archive Item Descriptions
The same scenario could be modified to give the user the option of backing
up the file to a specific location (i.e. Install Backups). To do so, the shadow
files with differing Install If and Replace Options would be removed and
Move Actions could be added and configured with execute If options. The
Move Action(s) would need to be located above the Installer VISE Layouts (7.x) file in
the archive window so that they would execute prior to the installation of the new
Installer VISE Layouts (7.x) file.
28–12
29–1
Chapter 29
Localization
Creating Installers in
Different Languages
Installer VISE’s localization features allow you to create installers for different languages
in which:
■
The localized archives contain file names, package names and descriptions, and
Easy Install text in the new language, while the files’ assignments to packages,
disk information, gestalts, replace options, etc., are the same as the original
archive. You do not have to recreate the entire archive in the new language.
■
The language of the windows, buttons and dialogs of the installer itself are in
the new language.
You can create installers that are localized for a single language (such as a French-only
installer) or installers that can handle more than one language (such as a French-English
or a French-English-German installer).
MindVision Installer and
Updater Language Files
All Installer language files, including language files you may construct yourself, must be
stored in the Installer VISE Extensions folder. All Updater language files, including language files you may construct yourself, must be stored in the Updater VISE Extensions
folder.
Language files in the Installer VISE Extensions folder can be selected from the Language
pop-up menu in the Installer Settings Interface tab. The Language file selected in the
Installer Settings Interface tab controls the language of the windows, buttons and dialogs
of the installer.
MindVision Installer and Updater language files are currently available for:
Chinese (Simplified)
Chinese (Traditional)
Danish
Dutch
English
Finnish
French
German
Italian
Japanese
Korean
Norwegian
Portuguese (European)
Spanish
Swedish
Since languages are constantly being added, you may wish to check with MindVision if
you do not see a language on this list that you need.
29–2
Supported Languages
About the Localization Process
Installer VISE contains an easy method for creating as many localized versions of your
software as you desire.
The following languages are supported:
Albanian
Arabic
Croatoan
Danish
Dutch
English
Estonian
Faeroese
Finnish
Flemish
French
About the Localization
Process
German
Greek
Hebrew
Hindi
Hungarian
Icelandic
Irish
Italian
Japanese
Korean
Lappish
Latvian
Lithuanian
Maltese
Norwegian
Persian
Polish
Portuguese
Russian
Spanish
Swedish
Thai
Turkish
Urdu
The localization process is directed through the Localization window and uses three
types of files. It is important to understand what these files are and how they are used for
localization.
File
Icon
Description
Localization file
Used to store localized resources.
Translator
application
Application created by Installer VISE used to
isolate and collect resources for files, package
names and other items added to the archive by the
developer.
Language file
Localized Installer VISE resources provided by
MindVision for installer interface elements.
Table 29-1: Localization file types
How you create a localized installer depends on whether your installer will be:
Single-language Installers
Overview
■
A single-language installer (e.g., a French-only installer); or
■
Aa multi-language installer (e.g., a French-English Installer or a FrenchEnglish-German installer).
Overview of the steps to create a single-language installer:
1. Set up and finalize archive files, packages, action items, etc.
2. Create Translator Application.
3. Send Translator Application out for translation or translate in-house.
4. Create Localization File.
Chapter 29 Localization
About the Localization Process
29–3
5. Import Translator Application data into Localization file.
6. Set Language in Installer Settings Interface tab.
7. For each Build Target to be used, set Languages in Target Attributes tab.
8. Build single-language installer.
Multi-language Installers
Overview
Overview of the steps to create a multi-language installer:
1. Set up and finalize archive files, packages, action items, etc.
2. Create a Translator Application for each language to be supported.
3. Send Translator Applications out for translation or translate in-house.
4. Create Localization File.
5. Import Translator Applications data for each one created in step one into the
Localization file.
6. Import Installer VISE language File data for languages to be supported.
7. Add any other necessary resource items to the Localization file.
8. Set Default Language in Installer Settings Interface tab.
9. For each Build Target to be used, set Languages in Target Attributes tab.
10. Build multi-language installer.
Single-Language vs.
Multi-Language Installers
The procedure to create an installer that only supports a specific language (such as a
French-only installer) is somewhat different than the procedure to create a multi-language installer (such as an English-French installer or an English-French-German
installer).
Use the following table to determine how to build your installer:
To create a…
Put these resources in the
localization file…
…and select this Language
file at the Installer Settings/
Interface tab
Single-language
installer
• Translator application for
the desired foreign language
• and any localized external
code resources
Installer file for desired language
Multi-language
installer
• Translator applications for
each language,
• and resources of the
Installer file for each foreign
language.
The Installer file for the desired
default language. For example,
to create a French-English
installer that defaults to English
if the language of the operating
system is not English or French,
select the English Installer file.
Table 29-2: Creating Single and Multi-Language Installers
29–4
Creating
Single-Language
Installers
Creating Single-Language Installers
To create a single-language installer:
1. Create and set up your archive with all packages, files and action items as they will
be in the final installer. The localization process assumes a complete installer with
which to begin.
2. Select Localization… from the Extras menu.
Illustration 29-1: Localization Menu Item
3. You must create a translator application for the language you wish to support. The
translator application lets you enter the names of the files, packages, Easy Install
text, and disks in the archive in the new language.
You may import the resources of the translator application into a localization file
for the archive, allowing you to keep the archive in your native language while creating an installer that supports another language.
In the Localization Window, select Create New Translator Application.
Illustration 29-2: Localization Window
Create a Translator
Application
29–5
4. In the Create Translator dialog make a selection from the Source Language popmenu and Target Language popmenu and click the Create button.
Illustration 29-3: Create Translator dialog
For example, if your archive is in English, select English from the Source Language popmenu. The translator application created will contain all items in the
source language which need to be localized into the target language.From the Target Language popmenu select the language to which you wish to translate your
installation.
If you would like to make notes in the text of the source language, select Allow
modifications to source language text. The changes or additions that you make
here will have no effect on the source archive or the translator application, but it
can help you keep track of information.
If you want to default the source names of the files in the destination or target column, select Use source language as default translation. The file names in the target column will appear in your source language, so that you can select and modify
the text for the new language. (If this option isn’t selected, then the target columns
will contain no text.)
5. Click Create. A standard Save File dialog will be displayed. Save the translator
application at your desired location. The default name will reflect the source and
target language selections made in the Create Translator dialog.
Illustration 29-4: Save Translator Application
29–6
Enter Localization
Information in the
Translator Application
To enter localization information for your installer:
6. Launch the translator application that you created. Windows will appear for each
type of item where localization is possible.
Illustration 29-5: Translator Application Windows
7. In each window, the information from the source language appears on the left and
fields for the information for the new language appear on the right.
Illustration 29-6: Find Action Source and Target Language Text
An exception is the Easy Install text window, where the source language informa-
29–7
tion appears on the top and the new language information appears on the bottom.
Illustration 29-7: Easy Install Source and Target Language Text
Enter information for the new language as required by your installation.
Changes to each window must be saved individually, as if they were different documents. If desired, press Command-S or select Save from the File menu to save
your changes to the window before you move to another one.
8. To display another window, click the grayed-out title for the window or select the
name from the Windows menu.
9. If desired, use the following options to open, import, or export text for the translator:
■
To create a text file containing the information as entered in the translator
application, select Save as Text... from the File menu. (This may be useful if
you wish to have the translated text corrected outside the translator application.)
■
To open an external text file to view or to copy and paste the contents into
the translator application, select Open Text... from the File menu. (This
may be useful if you wish to copy and paste text that’s been proofed and
corrected.)
■
To transport information from an existing translator application into the
new one, select Import Translator... from the File menu. The target column in the translator you’re creating will be filled with any information
from the old translator that matched the files. This translator application
must have been created from the same archive, as the internal file numbers
stored in the archive must match.
10. When you have entered all the information into the translator application, press
Command-Q or select Quit from the File menu. If you haven’t saved each window
that you changed, you will be asked to save them individually at this time.
29–8
Create a Localization File
To set up a localization file and import translator application information:
11. In the Localization Window, click the Localization Select button. Rather than
selecting an existing localization file, we will make a new one.
Illustration 29-8: Creating New Localization File
12. A standard Save File dialog will be displayed. Click the New File… button.
13. Name the new localization file and click the Create button.
Illustration 29-10: Naming New Localization File
29–9
14. The archive’s localization file name will be displayed in the Localization window
next to the Select button as well as in the Installer Settings’ Advanced tab.
Illustration 29-11: Localization File Created
This localization file will contain all translation items, Installer VISE Language
File items and any other resource file items you designate.
The archive’s localization file name will also be displayed in the Installer Settings’
Advanced tab.
Illustration 29-12: Localization File Displayed
Import Translator
Application Resources
To Import the translator application for the new language into the localization
file:
15. Click the Translator Application Import button.
Illustration 29-13: Selecting Translator Application
29–10
16. Navigate to the correct Translator Application and click the Select button.
Illustration 29-14: Selecting Translator Application for Import
17. The Localization window will display translated items by bullets.
Illustration 29-15: Localization Display
18. Click Done to close the Localization window.
Select Installer Language
19. Open Installer Settings.
29–11
20. In the Installer Settings Interface tab, use the Language popmenu to select the target language installer file.
Illustration 29-16: Setting Installer Interface Language
21. Click OK to close Installer Settings.
Select Language for Build
Target(s)
22. Select Show Project Window from the Archive menu. The Project window displays.
23. Click to select a Target that you will use for this installer build. Then click the Edit
button. The Target window displays.
24. In the Attributes tab, use the Languages popmenu to select the target language.
Illustration 29-17: Target window, Languages popmenu
25. Click OK to close the Target dialog.
29–12
Creating Multi-Language Installers
26. Repeat steps 23 through 25 for each Target that you will use.
27. Build your single-language installer.
When you complete step 24 on the preceding page, an alternative is to
select Language in Archive instead of the target language. For more information, see “Language” on page 27-14.
Creating
Multi-Language
Installers
To create a multi-language installer:
1. Create and set up your archive with all packages, files and action items as they will
be in the final installer. The localization process assumes a complete installer with
which to begin.
2. Select Localization… from the Extras menu.
Illustration 29-18: Localization Menu Item
3. Create a translator application for each language you wish to handle. Each translator application allows the entry of the names of the files, packages, Easy Install
text, and disks in the archive in one new language.
After translation, you will import the resources of each translator application into
a localization file for the archive.
In the Localization Window, select Create New Translator Application.
Illustration 29-19: Localization Window
Create a Translator
Application
29–13
4. In the Create Translator dialog make a selection from the Source Language popmenu and Target Language popmenu and click the Create button.
Illustration 29-20: Create Translator dialog
For example, if your archive is in English, select English from the Source Language popmenu. The translator application created will contain all items in the
source language which need to be localized into the target language. From the Target Language popmenu select the language to which you wish to translate your
installation.
If you would like to make notes in the text of the source language, select Allow
modifications to source language text. The changes or additions that you make
here will have no effect on the source archive or the translator application, but it
can help you keep track of information.
If you want to use the source names of the files in the destination or target column, select Use source language as default translation. The file names in the target column will appear in your source language, so that you can select and modify
the text for the new language. (If this option isn’t selected, then the target columns
will contain no text.)
5. Click Create. A standard Save File dialog will be displayed. Save the translator
application at your desired location. The default name will reflect the source and
target language selections made in the Create Translator dialog.
Illustration 29-21: Save Translator Application
6. Repeat steps 3 through 5 for each language the installer will support.
29–14
Enter Localization
Information in each
Translator Application
To enter one language’s localization information for your installer:
7. Launch the translator application that you created. Windows will appear for each
type of item where localization is possible.
Illustration 29-22: Translator Application Windows
8. In each window, the information from the source language appears on the left and
fields for the information for the new language appear on the right.
Illustration 29-23: Find Action Source and Target Language Text
An exception is the Easy Install text window, where the source language informa-
29–15
tion appears on the top and the new language information appears on the bottom.
Illustration 29-24: Easy Install Source and Target Language Text
Enter information for the new language as required by your installation.
Changes to each window must be saved individually, as if they were different documents. If desired, press Command-S or select Save from the File menu to save
your changes to the window before you move to another one.
9. To display another window, click the grayed-out title for the window or select the
name from the Windows menu.
10. If desired, use the following options to open, import, or export text for the translator:
■
To create a text file containing the information as entered in the translator
application, select Save as Text... from the File menu. (This may be useful if
you wish to have the translated text corrected outside the translator application.)
■
To open an external text file to view or to copy and paste the contents into
the translator application, select Open Text... from the File menu. (This
may be useful if you wish to copy and paste text that’s been proofed and
corrected.)
■
To transport information from an existing translator application into the
new one, select Import Translator... from the File menu. The target column in the translator you’re creating will be filled with any information
from the old translator that matched the files. This translator application
must have been created from the same archive, as the internal file numbers
stored in the archive must match.
11. When you have entered all the information into the translator application, press
Command-Q or select Quit from the File menu. If you haven’t saved each window
that you changed, you will be asked to save them individually at this time.
29–16
12. Repeat steps 7 through 12 for each translator application.
Create a Localization File
To set up a localization file and import translator application information:
13. In the Localization Window, click the Localization Select button. Rather than
selecting an existing localization file, we will make a new one.
14. A standard Save File dialog will be displayed. Click the New File… button.
15. Name the new localization file and click the Create button.
Illustration 29-27: Naming New Localization File
29–17
16. The archive’s localization file name will be displayed in the Localization window
next to the Select button as well as in the Installer Settings’ Advanced tab.
Illustration 29-28: Localization File Created
By completion, this localization file will contain all translation items, Installer
VISE Language File items and other resource file items for all languages supported
by this installer.
The archive’s localization file can also be set or removed in the Installer Settings’
Advanced tab.
Illustration 29-29: Localization File Displayed
Import Multiple Translator To Import translator application resources into the localization file:
Application Resources
17. Click the Translator Application Import button.
Illustration 29-30: Selecting Translator Application
29–18
18. Navigate to the first Translator Application and click the Select button.
Illustration 29-31: Selecting Translator Application for Import
19. Repeat the import process for each translator application.
20. The Localization window will display translated items by bullets.
Illustration 29-32: Localization Display
Import Multiple Installer
VISE Language Files
29–19
21. For each language this installer will support, import the appropriate Installer VISE
Installer file. Select the Installer VISE Language File Import button.
Illustration 29-33: Import Installer VISE Language Files
22. Navigate to the location of your language files and select the Installer language file
to import. If you received the language files from MindVision, they will be located
in the Installer VISE Extensions folder.
Illustration 29-34: Installer VISE Extensions folder
MindVision’s French language file is named “French Installer;” the Japanese language file is named “Japanese Installer;” etc.
29–20
23. Click the Select button to import the installer language file into the localization
file.
Illustration 29-35: Selecting an Installer VISE Installer Language File for Import
24. A bullet appears below the User column for the imported language.
Illustration 29-36: Localization Window After Language File Import
25. Repeat steps 21 through 23 for each language supported by the installer.
Select Installer
Default Language
26. Open Installer Settings.
29–21
27. In the Installer Settings Interface tab, use the Language popmenu to select the
default language installer file.
Illustration 29-37: Setting Installer Default Language
The installer default language is the language the installer will default to if the language of the operating system is not one of the languages supported by the
installer. In our example above, the installer will support French, German, and
Italian. When run on a French operating system, the installer’s interface items will
appear in French. When run on a German operating system, the installer’s interface items will appear in German. When run on an Italian operating system, the
installer’s interface items will appear in Italian. When run on an operating system
other than French, German, or Italian the installer’s interface items will appear in
English.
28. Click OK to close Installer Settings.
Select Languages for Build
Target(s)
29. Select Show Project Window from the Archive menu. The Project window displays.
30. Click to select a Target that you will use for this installer build. Then click the Edit
button. The Target window displays.
29–22
31. In the Attributes tab, use the Languages popmenu to select the target languages.
Illustration 29-38: Target window, Languages popmenu
Select Mac OS X Options
for Build Target(s)
32. If the Target will build a multi-language installer for Mac OS X, consider building
the installer as a Mac OS X application bundle to allow proper display of character
sets. (See “About Multi-Language Installers on Mac OS X” on page 29-22 .)To create the application bundle, make the following selections in the Attributes tab:
Single File format, Carbon platform and Create OS X Bundle.
33. Click OK to close the Target dialog.
34. Repeat steps 30 through 33 for each Target that you will use.
35. Build your multi-language installer.
About Multi-Language
Installers on Mac OS X
As noted in step 32 above, Installer VISE can build a single-file, Carbon installer as a Mac
OS X application bundle. This is the preferred way to deliver a multi-language installer
on Mac OS X. It allows the proper display of single-byte and double-byte character sets
from within the same installer.
About Localized External You may include localized external code in a single or multi-language installer. For examCode in Localized Installers ple, if your installer requires external code that displays a custom dialog box to the user,
you may create a localized version of that resource for each language you wish to support.
There are two ways to include localized external code resources in foreign language
installers. The method you use depends on the kind of installer you are creating.
If your installer only contains one language (such as a French-only installer), you may
import the resource into the localization file, or paste the resource into the language
installer file.
29–23
If your installer contains more than one language (such as an English-French installer),
you must paste the resource into the language installer file, as you can only specify one
kind of USER resource for each language and the inclusion of the installer language file
resources is crucial.
Exporting User Resources
If you wish to export the resources identified as USER:
1. In the Localization window, select the line containing the USER resources you
wish to export.
2. Click the Installer VISE Language File Export button. You’ll be asked to identify a
name and location for the resource file.
Updating User Resources
If the source file containing USER resources has been changed, you can easily update the
resources in the archive.
To do so, follow this step:
1. In the Localization window, select the line containing the USER resources you
wish to update.
1. Click the Installer VISE Language File Update button. If any files containing USER
resources have been changed, you’ll be asked if you want to update the resources
in the language file.
Checking the Consistency of
Translator Applications
The consistency check makes sure that a translator application that you imported contains information for all the files, packages, disk names and text in the current archive.
To check the consistency of a translator application:
1. In the Localization window, select the line for the language whose translator you
wish to verify.
2. Click the Check Consistency button.
If the information that was imported from the translator application matches all the
items in the archive, a message “There are no inconsistencies to report” will be displayed.
29–24
Localized-at-Install Applications
If the information that was imported from the translator application does not match all
the items in the archive, the Consistency Information window will be displayed:
Illustration 29-39: Consistency Information
This window contains information about inconsistencies between the archive and the
translator. If inconsistencies exist, you should export a new translator, as described
below; enter translation information for the new items in the archive; and import the
updated translator application for the language, replacing the current one for that language.
Exporting Translator
Applications
If the files or packages in the archive have changed and you wish to export a
translator application containing the new information:
1. At the Language File Setup window, select the line for the language whose translator you wish to export.
2. Click Export.
3. Choose a name and location for the newly-exported translator, and click Save.
A new translator application will be created, using the selected language as the destination language. Existing translations for items in the archive will be preserved in the new
translator, but new items in the archive will appear in the translator application as blank.
Importing Other Resources
The Import button in the Other Resources of the Localization window allows the merging of a selected file’s resources into the localization file for that language.
For example, start by importing the French Installer file by selecting Import in the
Installer VISE Language File area of the Localization window. Then click the Import
button in the Other Resources area of the Localization window and select a resource file
that has some localized external codes for French. The resources from the resource file
selected will be merged into the data of the previously imported French Installer file. The
original French Installer file is not modified, the copy of that file stored inside the Localization file is modified.
Localized-at-Install
Applications
If desired, you can use Installer VISE to install applications which are localized on-the-fly
during the installation process. Instead of including a localized version of the application
Overriding Dynamic Localization
29–25
for each language in the installer, you can set Installer VISE to evaluate the language of
the customer’s operating system and merge the appropriate language resources into the
application at the time of installation.
To create an installer with Localized-at-Install Applications:
1. Save your application as just the code and other non localizable resources, without
any localized information in it for any language, and add it to the archive.
2. Create separate resource files containing only the localizable resources for the languages you wish to support, such as Spanish Resources, French Resources, and
German Resources files.
3. Assign the language to the appropriate resource files
4. For each resource file:
■
Select the resource file in the archive.
■
From the Install to: pop-up menu, select Other...
■
Select the language-free application as the target of the merge.
When the installer is launched, the operating system in use will be determined by
the language check, and the application and the appropriate language-specified
resource file will be installed. Both files will be opened, and the resources from the
resource file will be copied to the application. Then, the resource file will be
deleted.
Overriding Dynamic
Localization
In some cases, you may wish to allow the customer to override the dynamic localization
option and choose a language other than the language of their operating system.
Override by User Entry at
Startup
To dynamically override operating system language/region:
1. Launch Installer
2. Immediately after launching hold down the Control and Option keys. Two beeps
will be heard.
3. Enter two digit code for language.
For language codes see Table 29-3, “Language Codes for Installer VISE,” on
page 29-26.
Only numbers 0-9 are accepted, typing letters will result in a beep.
4. Enter two digit code for region
For region codes see Table 29-4, “Region Codes for Installer VISE,” on page 29-27.
Only numbers 0-9 are accepted, typing letters will result in a beep.
5. Debug installers will display the Language and Region codes in the Debug window.
29–26
Language Codes for
Installer VISE
Language Codes for Installer VISE
Installer VISE Language codes correspond to Apple’s Language Codes as defined in
Inside Macintosh/Text/Chapter 6: Script Manager/Script Manager Reference/Constants/
Language Codes. In the table below languages are arranged alphabetically for ease of use.
Language
Code
Language
Code
Albanian
36
Lettish
28
Amharic
85
Lithuanian
24
Arabic
12
Macedonian
43
Armenian
51
Malagasy
93
Assamese
68
Malay
83
Azerbaijani
49
Malay
84
Azerbaijani
50
Malayalam
72
Bengali
67
Maltese
16
Bulgarian
44
Marathi
66
Burmese
77
Moldovan
53
Byelorussian
46
Mongolian
57
Chewa
92
Mongolian
58
Chinese (simplified)
33
Nepali
64
Chinese (traditional)
19
Norwegian
09
Croatian
18
Oriya
71
Czech
38
Pashto
59
Danish
07
Polish
25
Dutch
04
Portuguese
08
English
00
Punjabi
70
Esperanto
94
Romanian
37
Estonian
27
Ruanda
90
Faeroese
30
Rundi
91
Farsi
31
Russian
32
Finnish
13
Sanskrit
65
Flemish
34
Serbian
42
French
01
Sindhi
62
Galla
87
Sinhalese
76
Table 29-3: Language Codes for Installer VISE
Region Codes for Installer VISE
29–27
Language
Code
Language
Code
Georgian
52
Slovak
39
German
02
Slovenian
40
Greek
14
Somali
88
Gujarati
69
Spanish
06
Hebrew
10
Swahili
89
Hindi
21
Swedish
05
Hungarian
26
Tagalog
82
Icelandic
15
Tajiki
55
Indonesian
81
Tamil
74
Irish
35
Telugu
75
Italian
03
Thai
22
Japanese
11
Tibetan
63
Kannada
73
Tigrinya
86
Kashmiri
61
Turkish
17
Kazakh
48
Turkmen
56
Khmer
78
Ukrainian
45
Kirghiz
54
Urdu
20
Korean
23
Uzbek
47
Kurdish
60
Uzbek
47
Language of Lapps/Sami
29
Vietnamese
80
Lao
79
Yiddish
41
Table 29-3: Language Codes for Installer VISE
Region Codes for
Installer VISE
Installer VISE Region codes correspond to Apple’s Region Codes as defined in Inside
Macintosh/Text/Chapter 6: Script Manager/Script Manager Reference/Constants/Region
Codes. In the table below regions are arranged alphabetically for ease of use.
Region
Code
Region
Code
Australia
15
Israel
13
Croatian system for Yugoslavia
25
Italy
04
Cyprus
23
Japan
14
Denmark
09
Korea
51
Table 29-4: Region Codes for Installer VISE
29–28
Languages as Defined in Apple’s Script.h File
Region
Code
Region
Code
Estonia
44
Lapland
46
Faeroe Islands
47
Latvia
45
Finland
17
Lithuania
41
France
01
Malta
22
French Canada
11
Netherlands
05
French for Belgium and
Luxembourg
06
Pakistan
34
French for Switzerland
18
People's Republic of China
52
German for Switzerland
19
Poland
42
Germany
03
Portugal
10
Great Britain
02
Russia
49
Greece
20
Sweden
07
Hindi system for India
33
Taiwan
53
Hungary
43
Thailand
54
Iceland
21
The Arabic world
16
Iran
48
Turkey
24
Ireland
50
United States
00
Table 29-4: Region Codes for Installer VISE
Override by External Code
Installer VISE allows you to build an installer that lets the customer choose the install
language; however, you’ll need to write external code to handle the input.
The external code resource must be of type Xcod and it must have the resource ID number 9999. The installer will look for this resource as soon as the installer is launched, and
before the install window is created. If this resource is found, the code will be called.
The selector passed in the paramblock is 7. If you want to override the default language,
set the paramblock ->itemHit field to the number of the language you wish to use as
defined in Apple’s Script.h file. (The contents of the Script.h file are listed at the end of
this chapter.)No other fields in the paramblock are valid at this time.
Languages as Defined
in Apple’s Script.h File
The following is a list of the languages as defined in Apple’s Script.h file. The number in
the right-hand column is the one that you should use to identify the language for the
purposes described above.
To make it easier to find the desired language, this table is organized alphabetically by language, not numerically by the numbers in the file.
29–29
For This Language…
Use This Number:
Albanian
00000024
Arabic
0000000C
00000021
00000013
Croatian
00000012
Danish
00000007
Dutch
00000004
English
00000000
Estonian
0000001B
Faeroese
0000001E
Farsi
0000001F
Finnish
0000000D
Flemish
00000022
French
00000001
German
00000002
Greek
0000000E
Hebrew
0000000A
Hindi
00000015
Hungarian
0000001A
Icelandic
0000000F
Irish
00000023
Italian
00000003
Japanese
0000000B
Korean
00000017
Lappish
0000001D
Lapponian
0000001D
Latvian
0000001C
Lettish
0000001C
Lithuanian
00000018
Table 29-5: Languages as Defined in Apple’s Script.h File
29–30
For This Language…
Use This Number:
Maltese
00000010
Norwegian
00000009
Persian
0000001F
Polish
00000019
Portuguese
00000008
Russian
00000020
Spanish
00000006
Swedish
00000005
Thai
00000016
Turkish
00000011
Urdu
00000014
Table 29-5: Languages as Defined in Apple’s Script.h File
User Defined Languages
There may be times when the pre-defined languages do not offer enough specificity for a
given installer. For example, your installer may need to be differentiated for International
English, British, and Canadian content. For those cases, up to 10 languages can be
defined by the developer.
To create a user defined language for Installer VISE:
1. From the Installer VISE Extensions folder, duplicate the language installer file
which is closest in content to the new language you wish to define. For our example we would duplicate English Installer.
2. Rename the duplicate. In our case, we renamed the duplicate to “British English.”
3. Open the duplicate file with a resource editor.
4. Edit whatever strings are necessary to be changed.
5. Edit the Insk resource.
Change the second bytes to be some unique number. A number in the 200 range is
preferable. In this example we used F1.
Change the 3rd byte from 0 to any number between 1 and 10. This number is the
position in which it will be added at the end of the languages popmenu in Installer
VISE.
Illustration 29-40: InsK Resource from Duplicated Language File
When Installer VISE is run, and when reading in the Insk resource, it will look at
the 3rd byte to see if it is a number between 1 and 10. If it is, then the name of that
29–31
Language file will be appended to the end of the Language popmenu as in the
example below.
Illustration 29-41: Language popmenu displaying user defined languages
6. Assign items within the installer to the appropriate language.
7. When the installer is run, you can have an external code that will set the default
language to be one of the user defined languages. You will need to return a value
from the Xcod that is the item number of the language wanted in the popmenu.
29–32
30–1
Chapter 30
Scripting Installer VISE with AppleScript
Scripting Installer VISE
and Installers
There are three ways that AppleScript can be used in conjunction with Installer VISE:
1. As the creator of an installer, you may include AppleScript scripts within the
installer to perform various functions on the target system. Information about
this topic can be found below, in “Including AppleScript Scripts Within an
Installer” on page 30-1.
2. As the creator of an installer, you automate the process of building installers by
using AppleScript. Information about this topic can be found in this chapter, in
the section titled “Installer VISE and AppleScript” on page 30-3.
3. Customers who use your installer may use AppleScript scripts to control the
installation process. For example, if your product will be installed by a network
system administrator, the administrator can automate the process by sending
scripts controlling the process to the installer. For complete information about
using AppleScript to control an installer application, see Chapter 31-Controlling
an Installer with AppleScript.
Including AppleScript
Scripts Within an
Installer
To include any AppleScript script in the installer:
1. Save your AppleScript script as a compiled script.
2. Using a resource editor such as ResEdit, open the script and copy the ‘scpt’
resource.
3. Create a new file (with the resource editor) and paste the ‘scpt’ resource into it.
4. Give the resource an available ID between 5000 and 10000 and save the file.
(For more information about the following steps, see Chapter 9-Assigning External
Code.)
30–2
Including AppleScript Scripts Within an Installer
5. Add the resource file to the installer via the Project window.
Illustration 30-1: Project window
6. Declare the resource in the installer. Be sure to use type ‘scpt’ and the ID assigned
in Step 4.
Illustration 30-2: Edit External Code dialog
7. Specify when the installer should call the resource (to execute the script).
Chapter 30 Scripting Installer VISE with AppleScript
Installer VISE and AppleScript
Installer VISE and
AppleScript
30–3
This section contains information about the AppleScript commands that can be used
with Installer VISE.
The following actions within InstallerVISE can be performed via AppleScript:
■
“Opening an Archive” on page 30-4
■
“Saving an Archive” on page 30-4
■
“Closing an Archive” on page 30-4
■
“Bringing an Archive Up to Date” on page 30-4
■
“Setting the Validate Paths flag before Bringing an Archive Up To Date” on
page 30-5
■
“Setting the Intelligent Update Flag” on page 30-5
■
“Setting the Assign Parent Package to New Files Flag” on page 30-5
■
“Performing a Regular Archive Update” on page 30-6
■
“Performing a Full Update” on page 30-6
■
“Performing an Update on One Root Level Item Only” on page 30-6
■
“Performing an Update on One Item Only” on page 30-7
■
“Extracting an Archive Item” on page 30-7
■
“Setting Billboard Mode” on page 30-7
■
“Setting the Current Build Target” on page 30-7
■
“Turning Build Directives On” on page 30-8
■
“Turning Build Directives Off ” on page 30-8
■
“Turning Build Targets On” on page 30-8
■
“Turning Build Targets Off ” on page 30-9
■
“Building an Install Set” on page 30-9
■
“Setting the value of an existing Variable” on page 30-9
■
“Editing an existing Download Site” on page 30-10
■
“Setting the Localization File” on page 30-10
■
“Validating an Update File” on page 30-10
■
“Setting the Disk Sizes” on page 30-11
■
“Removing Compressed Data” on page 30-12
30–4
The script examples shown here use the activate command to bring
Installer VISE to the frontmost process. In general, it is good practice to
activate a process before sending it Apple events.
Opening an Archive
To open an archive, use this script:
-- open an archive
tell application "Installer VISE"
activate
open {"full path name"} as alias
end tell
Full Path Name should always be constructed as in the example below.
Installer VISE will not accept paths constructed like those recorded at the Finder as in
the example below.
Saving an Archive
The following script is used to save the archive.
-- Save the archive
activate
SaveArchive
end tell
This script expects the archive to already be open.
Closing an Archive
To close the frontmost archive window, use this script:
-- close an archive
activate
CloseWindow
end tell
Bringing an Archive Up to
Date
The following script is used to update the frontmost archive using file paths stored for
the current build source.
-- Bring archive up to date
activate
30–5
BringUpToDate
end tell
Setting the Validate Paths
flag before Bringing an
Archive Up To Date
The following script is used to set the validate paths flag prior to bringing an archive up
to date.
-- Bring archive up to date
activate
BUTDValidatePaths "true"
BringUpToDate
end tell
If set to false and an item’s path is invalid, the item will be deleted when doing a Bring Up
To Date.
Setting the Intelligent
Update Flag
The following script will check on the Perform Intelligent Filename Check on Update
checkbox on in the Installer Settings Advanced Tab and will then perform a Bring up To
Date.
You can either pass a “true” or “false” to this AppleScript command.
For more information on the function of the Perform Intelligent Filename Check on
Update checkbox, see “Replacing Similar Items During Bring Up To Date” on page 20-3
and “Perform Intelligent Filename Check on Update” on page 14-27.
Setting the Assign Parent
Package to New Files Flag
This SetAssignPackagesFlag sets a global variable in Installer VISE which determines how
to default the Assign Parent Packages to New Files checkbox in the Bring Up To Date
window.
You can either pass a “true” or “false” to this AppleScript command.
The following script will set the Assign Parent Packages to New Files flag in Installer
VISE to true and then will perform a Bring up To Date.
For more information on the function of the Assign Parent Packages to New Files
checkbox in the Bring Up To Date window, see “Assign Parents Package to New Files” on
page 20-5 .
30–6
Performing a Regular
Archive Update
In a regular update, only the files in the source folder that are newer than the files in the
archive are brought into the archive.
To perform a regular update on an archive, use the following script.
-- Update an archive
activate
Update {"full path name"}
end tell
“Full path name” is the full path name to the folder on your hard drive that contains an
exact copy of the folder structure of your archive. If you have multiple items at the root of
the archive, you must supply a full path name to each item at the root of the archive, separated by commas, such as the following: Update {"full path to item 1", "full path to item
2", "full path to item 3"}
Performing a Full Update
In a full update, all the files in the source folder that are different from the files in the
archive are brought into the archive. (If older files are in the source file, the older files will
replace the newer files in the archive.)
To perform a full update, use the following script:
-- Update archive
activate
UpdateAll {"full path name"}
end tell
“Full path name” is the full path name to the folder on your hard drive that contains an
exact copy of the folder structure of your archive. If you have multiple items at the root of
the archive, you must supply a full path name to each item at the root of the archive, separated by commas, such as the following: Update {"full path to item 1", "full path to item
2", "full path to item 3"}
Performing an Update on
One Root Level Item Only
The UpdateOne AppleScript command will allow you to update just one item at the root
level of your archive. The string that is passed is first, the path to the location on your
drive that is the folder to compare, then a "," then the name of the item in the archive
window that you want to update. This item to update must be an item at the root level of
the archive.
To perform an update on one root level folder or file, use the following script example:
-- Update root level item
activate
UpdateOne {"full path name,item name"}
UpdateOne {"full path name,item name"}
end tell
30–7
Performing an Update on
One Item Only
The UpdateOneFile AppleScript command will allow you to update just one item of the
frontmost archive. The string that is passed is first, the path to the location on your drive
that is the file to compare, then a "," then the full path to the the item in the archive window that you want to update.
To perform an update on one folder or file, use the following script example:
-- Update one item
activate
UpdateOneFile {"full path name source,full path name
archive"}
end tell
Extracting an Archive Item The ExtractItem AppleScript command will allow you to extract one item of the frontmost archive. The string that is passed is first, the full path name to the extract location
on the hard drive, then a "," then the full path name to item in the archive.
To perform an update on one root level folder or file, use the following script example:
-- Extract archive item
activate
ExtractItem {"full path to extract location,full path to ¬
archive item"}
end tell
Setting Billboard Mode
To set which billboard mode to use before building an installer use the SetBillboardMode
command. SetBillboardMode sets the current Billboard mode for the frontmost archive.
The billboard mode must be used with one of the following parameters:
■
Sequential
■
By Disk
■
By Package
-- setting billboard mode
activate
SetBillboardMode “Sequential”
end tell
Setting the Current Build
Target
The following script is used to set the current Build Target.
-- Set current Build Destination
activate
SetBuildTarget {"build target name"}
30–8
end tell
Turning Build Directives
On
The following script is used to turn on one Build Directive for the frontmost archive.
-- Turn a build directive on
activate
BuildDirectiveOn {"build directive name"}
end tell
When the BuildDirectiveOn command is used without a parameter, all Build Directives
in the frontmost archive will be turned on.
-- Turn all build directives on
activate
BuildDirectiveOn
end tell
These script expects the archive to already be open.
Turning Build Directives
Off
The following script is used to turn off one Build Directive for the frontmost archive.
-- Turn a build directive off
activate
BuildDirectiveOff {"build directive name"}
end tell
When the BuildDirectiveOff command is used without a parameter, all build directives
in the frontmost archive will be turned off.
-- Turn all build directives off
activate
BuildDirectiveOff
end tell
These scripts expect the archive to already be open.
Turning Build Targets On
The following script is used to turn on one build target for the frontmost archive.
-- Turn a build target on
activate
30–9
BuildTargetOn {"build target name"}
end tell
When the BuildTargetOn command is used without a parameter, all build targets in the
frontmost archive will be turned on.
-- Turn all build targets on
activate
BuildTargetOn
end tell
Turning Build Targets Off
The following script is used to turn off one build target for the frontmost archive.
-- Turn a build target off
activate
BuildTargetOff {"build target name"}
end tell
When the BuildTargetOff command is used without a parameter, all build targets in the
frontmost archive will be turned off.
-- Turn all build targets off
activate
BuildTargetOff
end tell
Building an Install Set
The following script is used to build an install set using the active build destination.
-- Build install set
activate
Build
end tell
Setting the value of an
existing Variable
The following script is used to set the value of an existing variable.
-- Set variable value
30–10
activate
SetVariable "VariableName,VariableValue"
end tell
Editing an existing
Download Site
The following script is used to edit an existing download site of an archive. For more
information on web installers and download sites, see “Designating Download Sites” on
page 37-10
-- Edit the archive’s first download site
activate
SetDownloadSite {"1,MyCompany West,ftp.westcoast.com, ¬
anonymous,[email protected],¬
FTP/webinstall/mac/IVISE,FTP"}
end tell
This script expects the archive to already be open and for the download site to already
exist.
Parameters:
Setting the
Localization File
■
Number of Download Site to edit
■
Site name
■
Server Address
■
User Name
■
Password
■
Initial Directory
■
Server Kind (FTP or HTTP)
The following script is used to set the localization file of the archive. For more information on localization, see Chapter 29-Localization.
-- Set the archive’s language file
activate
SetLocalizationFile {"full path name of the localization file ¬
including the file name"}
end tell
Validating an Update File
The following script is used to validate an update file within an archive.
-- Set the archive’s language file
30–11
activate
ValidateUpdateFile {"full path name of the update file ¬
including the file name"}
end tell
If no parameter is passed, all update files will be validated.
Setting the Disk Sizes
The following script is used to set information about the sizes and names of the disks and
segments created by the installer. The items that you set here are similar to those that you
choose at the Edit Disk window. An explanation of the parameters of the SetDisk call
appears after the code.
-- Set the Disk Sizes and other disk information
activate
SetDisk “WhichDisk,DiskName,SegmentName,SegmentSize,DiskSize”
end tell
For example, to set the disk information for the first disk, naming the disk and segment
sizes sequentially, with a segment size of 1410 and a disk size of 1.44MB, the code would
be:
activate
SetDisk "1,Disk ^,Segment ^,3,3"
end tell
Description of the SetDisk Parameters:
The following is a description of the parameters for the SetDisk call. These parameters
appear between double-quotation marks after the SetDisk statement, and are separated
by a comma, as shown in the sample script.
1. which disk - The first parameter is which disk to set. This corresponds to selecting
the disk to edit at the Installer Disk Names window. To enter information for the
first disk, type 1; for the second disk, type 2; etc. To set information for all disks,
type 0. To set the last disk in the set, type 255 (this ensures that the settings are
applied to the last disk in the set.)
■
disk number
■
0 = All Disks
■
255 = Last Disk
2. disk name - The second item is the name of the disk. This corresponds to the Disk
Name field in the Edit Disk window. If desired, you may leave this item blank;
however, you must include the correct number of commas. For example, to leave
the disk name blank, sample parameters would be "1,,Segment ^,1410,3".
3. segment name - The third item is the name of the segment. This corresponds to
the Segment Name field in the Edit Disk window. If desired, you may leave this
item blank; however, you must include the correct number of commas. For example, to leave the segment name blank, sample parameters would be "1,Disk
^,,1410,3".
30–12
4. segment size - The fourth item in this field is the segment size for the disk. Type
the desired size of the segment in Kilobytes.
■
1 = 400
■
2 = 800
■
3 = 1.4
■
4 = Fill Disk
■
value other than 1, 2, 3 or 4 indicates the custom segment size
5. disk size - The fifth item in this field corresponds to the items in the Disk Size
pop-up menu in the Edit Disk Window. Type the number of the item in the Disk
Size pop-up menu that signifies the desired size of the disk
■
1 = 400
■
2 = 800
■
3 = 1.4
■
value other than 1, 2 or 3 indicates the custom disk size
Illustration 30-3: SetDisk AppleScript example
Removing Compressed
Data
The following script is used to remove compressed data from VCTs, which is often done
to make the VCTs smaller for source control purposes.
-- Remove compressed data
activate
RemoveCompressedData
end tell
31–1
Chapter 31
Controlling an Installer with AppleScript
Installer applications created by Installer VISE can respond to a variety of AppleScript
calls, which are described in this section. For example, network system administrators
might wish to use AppleScript to control multiple installations of the software on all
computers on the network.
Although you might not use this information as a developer, you may wish to make the
following information available to your customers in case they wish to use AppleScript to
control the installation of your application.
The script examples shown here use the activate command to bring the
installer application to the frontmost process. In general, it is good practice
to activate a process before sending it Apple events.
Setting Easy Install
To set the installer to default to the Easy Install option, use this script:
-- Default to the Easy Install option
tell application "installer_name"
activate
SetInstall "Easy"
end tell
Setting Custom Install
To set the installer to default to the Custom Install option, use this script:
-- Default to the Custom Install option
activate
SetInstall "Custom"
end tell
31–2
Selecting a Package
Installing the Software
To select a specific package in the installer, use this script:
-- Select a specific package
activate
Select "package_name"
end tell
Package Dependencies are ignored when using the Select and Deselect
AppleScript commands to check and uncheck package checkboxes in a
built installer.
For more information on Package Dependencies, see “Package Dependencies” on page 7-3.
Deselecting a Package
To deselect a specific package in the installer, use this script:
-- Deselect a specific package
activate
Deselect "package_name"
end tell
To have the installer application install the software, use this script:
-- Run an installer
activate
DoInstall
end tell
With No User Intervention
To have the installer application install the software without quitting applications which
are running and without doing machine restarts, use this script:
-- Run an installer
activate
DoAutoInstall
end tell
Chapter 31 Controlling an Installer with AppleScript
Selecting the Install Location
31–3
This feature allows you to perform an install that bypasses shutting down of running
applications, ignores any restart settings and successful install dialogs that appear during
a normal installation.
Illustration 31-1: DoAutoInstall Example Script
Updating the Drive List
To force the installer to rescan mounted disks to update the internal drive list, use this
script:
-- Update the list of disk drives
activate
UpdateDriveList
end tell
Selecting the Install
Location
Selecting a Hard Drive
To select a specific hard drive as the installation location, use this script:
-- Select a specific hard drive as install location
activate
SelectDrive "hard_drive_name:"
end tell
The colon after the name of the drive is crucial. For example, to install the
items to the drive named “Macintosh HD,” use SelectDrive "Macintosh
HD:"
31–4
Selecting a Folder
Selecting the Install Location
To select a specific folder on a hard drive as the installation location, use this script:
-- Select a specific folder as install location
activate
SelectDrive "hard_drive_name:folder_name:"
end tell
The colon after the name of the drive is crucial. For example, to install the
items to the drive named “Macintosh HD” in the folder named “Applications,” use SelectDrive "Macintosh HD:Applications:"
Chapter 31 Controlling an Installer with AppleScript
32–1
Chapter 32
Creating External Code
General External Code
Information
This chapter contains general information about creating external codes to use with
Installer VISE. An explanation of programming and debugging techniques for creating
external code is beyond the scope of this documentation. The procedure for attaching
external code to an installer is described in Chapter 9-Assigning External Code.
The information below contains general facts about how external codes are identified
and called. For important tips on developing your external codes, see “Helpful Hints” on
page 32-17.
When Codes Can Be Called External codes can be called at the following times:
Resource IDs and
Reference Constants
■
When the installer checks the language of the operating system
■
When the installer is initialized
■
During event processing (main event loop)
■
When installation begins
■
After installation
■
Before a file is installed
■
After a file is installed
■
Before an Action Item is executed
■
Before an Action Item’s action is performed (after search criteria is executed)
■
After an Action item’s action is performed
■
When checking install sizes
■
When user selects a custom package
Resource ID numbers must be between 5000 and 9999, inclusive.
If desired, you may assign a unique 32-bit number, or RefCon (reference constant), to
each resource so that the location it was called from may be identified. This may be helpful if you are using one code resource to perform multiple tasks.
32–2
General External Code Information
Using More Than One Code If more than one external code is assigned to an item, the codes will be called in the order
in which they are listed in the External Code List dialog box. In this case, be sure to
declare your codes in the proper order.
Nonexistent or
Misidentified Code
You may not build an installer that includes a call to nonexistent or misidentified external code. If you attempt to build an installer under these circumstances, you will be
alerted about the problem, and creation of the installer will be aborted. Creating a diagnostic report before building an installer will identify misidentified or nonexistent code,
as well as other problems that may affect the installer.
External code file name strings passed to Installer VISE may be no
longer than 31 characters. If Installer VISE encounters an external code
file name string that is longer than 31 characters, the program will crash
without generating an error message.
External code for 68K,
PowerPC or Carbon
Because Installer VISE can build installers for 68K, PowerPC and Carbon platforms, you
will sometimes need to use different versions of your external code to match the OS.
Here are some guidelines for creating different versions of your code:
■
It can be compiled as 68K or PowerPC code.
■
It can be compiled as a code resource or shared library.
■
If you are building a Carbon installer, you will need to link your external code
against CarbonLib. Otherwise, you should link against InterfaceLib.
■
Any external code linked against CarbonLib will not be executed by the installer
under a non-Carbon launch.
■
Any external code linked against InterfaceLib will not be executed by the
installer under a Carbon launch.
■
Unified installers will require both the Carbon and non-Carbon external codes.
If you are building a Unified application, you will need to use two different
external codes (each linked against the correct library) and assign both to be
executed. At install time, the Unified installer will execute the appropriate
installer and external code for the OS in use. On Mac OS X or OS 8.1 - 9.x with
CarbonLib 1.1 or newer, the installer will execute Carbon code. Otherwise, the
installer will execute non-Carbon code. See also “About External Code” on
page 9-1.
Installer VISE includes several sample CodeWarrior projects that can build
each of the possible external codes. If you need to install these projects, run
the Installer VISE installer and do a custom install for “Tutorial and Sample
Files.” Then see a folder called “Installer External Code.”
Chapter 32 Creating External Code
Creating External Code for Installer VISE Installers
32–3
About the Samples folder
Illustration 32-1: Samples folder
The Samples folder contains numerous files that can help you create external code for use
with Installer VISE. This folder includes:
■
Header files for interfacing your external code with Installer VISE
■
Sample projects, external code and installer archives
■
Resource templates that enable ResEdit and Resorcerer to correctly display
Installer VISE file resources
Be sure to look at the header files and sample code, as well as the extensive comments.
This is the fastest way to learn about the functions you can perform with external code
and Installer VISE.
for Installer VISE
Installers
Your external code should have a main entry point as follows:
pascal void main(ExternParmBlock *eInfo);
External codes are based around a paramBlock type interface:
struct ExternParmBlock {
short
version;
short
selector;
long
refCon;
long
flags;
Handle
userStorage;
short
easyCustom;
short
IPackageArrayHdl
numberOfPackages;
packages;
// current version of this ParmBlock
// where in the installer your external
code is being called from (see “ExternParmBlock->selector” on page 32-5)
// user defined number (number assigned in
Installer VISE External Codes dialog)
// bit flags (see “ExternParmBlock->flags” on
page 32-6)
// user storage handle - initialized to nil
at start of Installer
// only set & changeable when called with
kSelectorLaunchTime
// number of packages
// package handle (see InstallerDefines.h)
32–4
Handle
easyInstallText;
// handle to easy install text (displayed
on the install window (easy install only))
// information about the file to be
installed
// event record - used during event loop
call
// Install Dialog
// itemHit - Event loop processing
// which fork(s) of file to install (see
“ExternParmBlock->installFork” on page 32-14).
Initialized to kInstallFile
// Handle to a list of files that are in the
archive
// number of files in the ArcListHdl
// vRefNum of the moved items folder 0 = not
created
// dirID of the moved items folder
// refnum of the Installer log file 0 = not
open
// Handle to text to display if you include
an Uninstall
ArcFileType
theFile;
EventRecord
theEvent;
DialogPtr
short
short
theDialog;
itemHit;
installFork;
ArcListHdl
fileList;
long
short
numberOfFiles;
movedItemsVRefNum;
long
short
movedItemsDirID;
logRefNum;
Handle
removeText;
// NEW in 5.0
Ptr
callBackProcs;
long
long
long
languageCode;
regionCode;
extraStorage1;
long
extraStorage2;
long
extraStorage3;
long
extraStorage4;
// NEW in 6.0
Str27
FSSpec
userPassword;
installerFSSpec;
// user entered password
// FSSpec of this Installer
// NEW in 7.0
SerialNumberList
serialList;
DownloadItemList
downloadList;
// Handle to array of serial numbers and
registration names (eSellerate use only)
// Handle to array of items downloaded from
a purchase (eSellerate use only)
// NEW in 8.1
Ptr
sublaunchData;
long
sublaunchDataSize;
// array of callback routines used for log
file, debug window, and variable manipulation
// current language code
// current region code
// For Developer use. Initialize to 0 at
// start of installer.
// Pointer to data to be passed to sublaunched installer
// Size of sub-launch data pointer
};
32–5
typedef struct ExternParmBlock ExternParmBlock, *ExternParmBlockPtr;
typedef pascal void (*XCodProcCallPtr)(ExternParmBlock *eInfo);
#if TARGET_CPU_PPC
enum {
uppXCODProcInfo = kPascalStackBased
| STACK_ROUTINE_PARAMETER(1, SIZE_CODE(sizeof(ExternParmBlock *)))
};
ProcInfoType __procinfo = uppXCODProcInfo;
#endif
ExternParmBlock->version
#define kExternPBVersion
// Version number of the paramblock
// passed to the external routine,
// currently:
16
ExternParmBlock->selector
From where in the Installer your external code is being called. This is useful if you have
one code with many different procedures; you'll need to know where this is being called:
#define kSelectorLaunchTime
0
#define kSelectorEvent
1
#define kSelectorBeforeInstall
2
#define kSelectorAfterInstall
3
#define kSelectorBeforeFile
4
#define kSelectorAfterFile
5
#define kSelectorCheckingSizes
6
#define kSelectorDynamicTime
7
#define kSelectorPackChanged
8
#define kSelectorPreAction
9
#define kSelectorInstallerQuit
10
#define kSelectorPostInitTime
11
// External Code being called at launch
time (install dialog is valid, but invisible)
// External Code being called during main
event loop, ExternParmBlock.itemHit will be
filled in from DialogSelect
// External Code being called at the beginning of the install routine
// External Code being called at the end of
install routine
// External Code being called Before a file
is to be installed
// External Code being called After a file
was installed
// External Code being called to calculate
sizes - see “ExternParmBlock->flags” on
page 32-6 for if on Custom or Easy Install
// External Code being called to set the
localization language
// External Code being called when package
checkbox changes state
// External Code being called after doing
the search but before the actual action is
taken - valid for Action Items that do finds
// External Code being called when the
installer quits - Allows for Cleanup
// External Code being called at the end of
initialization
ExternParmBlock->refCon
32–6
The RefCon is a 32-bit number identified in the Edit Codes window in Installer VISE that
identifies the location from which the code was called. This may be useful if you call one
external code from different locations for more than one task.
ExternParmBlock->flags
These are bit flags that are set for your information or can be set by your external routine
(marked as Changeable).
#define kCancelInstall
(1L << 0)
#define kWhichInstall
(1L << 1)
#define kCreateMovedFolder
(1L << 2)
#define kRemoveInstall
(1L << 4)
// Cancel Install bit
// if (gPBExtern.flags & kCancelInstall)
// then quit
// install •Changeable•
// Easy or Custom Install bit
// if ((gPBExtern.flags & kWhichInstall)
/ == 0) then doing Easy Install else
// it’s custom install
// Set this flag to tell the Installer
// to create the Moved Files Folder in
// the System Folder
// If this flag is set, the user has
// selected Uninstall
/
ExternParmBlock->userStorage
This handle is initialized to nil at the start of the installer. You can use this to create and
store anything that you want. It is passed to all external code unmodified until the
installer is quit.
ExternParmBlock->easyCustom
This number is only used at time of initialization. Its default is what was selected in the
Setup Installer dialog from Installer VISE. You can change the default install to one of the
following two constants.
#define kGotoEasyInstall
#define kGotoCustomInstall
1
2
// default to Easy Install
// default to Custom install
ExternParmBlock->numberOfPackages
This is the number of packages that are defined (including the Easy Install Package).
ExternParmBlock->packages
This is a handle to an array of package definitions
struct IPackageType {
Str63
Str255
Str9
short
unsigned short
long
Handle
unsigned char
ipk_Name;
ipk_Description;
ipk_Version;
ipk_IconID;
ipk_UniqueID;
ipk_Size;
ipk_BillBoard;
ipk_NeedRestart;
// Internal Structure for packages
// Package Name
// Package Description
// Package Version
// Package Icon ID#
// Unique ID Assigned to each package
// Package Size
// PicHandle for the billboard
// Need Restart Flag 0 = No Restart, 1 =
Need Restart
unsigned char
unsigned char
unsigned char
Boolean
Boolean
ipk_Index;
ipk_UserFlag;
ipk_Checked;
ipk_UseFilesSetting;
ipk_68K;
32–7
// internal index
// Package Checkbox is on=true or off=false
// FAT Package - Use the Files Setting
// FAT Package - install 68K Version of Fat
Apps
ipk_PPC;
// FAT Package - install PPC Version of Fat
Apps
// if both ipk_68K and ipk_PPC then install
Fat Version of App
ipk_MEP;
// Mutual Exclusive Package
ipk_SubPackage;
// Package is a Sub-Archive Install Package
ipk_ListPackage;
// If this package is a List Package
ipk_ShowInPM;
// Show in popmenu with "Easy Install",
"Custom Install", etc.
ipk_DefaultPkgOn;
// If this package checkbox defaults to on
ipk_MustSelectOne;
// List Package Option
ipk_CanSelectMultiple;
// List Package Option
ipk_ExpandStatus;
// Whether or Not the Parent Package is
expanded
ipk_ListHelp;
// Handle to a PICT resource for the List
Package Help
ipk_ListHeader;
// A Pascal String for the List Package
Header Message
ipk_ListFooter;
// A Pascal String for the List Package
Footer Message
ipk_Gestalts[2];
// Bits for which Gestalts To Check
ipk_Indent;
// Indentation level of the package
ipk_OnOnDep[kMaxPackFlags];
// Internal Use
ipk_OnOffDep[kMaxPackFlags];
//Internal Use
ipk_OffOnDep[kMaxPackFlags];
//Internal Use
ipk_OffOffDep[kMaxPackFlags];
//Internal Use
ipk_SKU;
// Internal Use
Boolean
Boolean
Boolean
Boolean
Boolean
Boolean
Boolean
Boolean
unsigned char
Handle
Str255
Str255
long
unsigned char
long
long
long
long
Str32
};
typedef struct IPackageType IPackageType;
typedef IPackageType *IPackageTypePtr;
IPackageType.ipk_Name
Name of the package
IPackageType.ipk_Description
Description of the package (seen in information dialog from the custom install)
IPackageType.ipk_Version
Version # of the package (seen in the information dialog from the custom install)
IPackageType.ipk_IconID
Package Icon (seen in the information dialog from the custom install)
IPackageType.ipk_UniqueID
32–8
Unique ID assigned to this package
IPackageType.ipk_Size
Package Size in bytes (sum of bytes of all files assigned to the package, seen in custom
install when user selects the info icon for a package)
IPackageType.ipk_Billboard
PicHandle for the billboard.
IPackageType.ipk_NeedRestart
0 = no restart, 1 - restart needed. If the package is installed, this defines whether or not to
restart the machine when the user quits the installer. If 1, then it also requires that all
other applications be quit before the installation can occur.
IPackageType.ipk_Index
Internal index.
IPackageType.ipk_UserFlag
Character entered by the developer in the Edit Package dialog of Installer VISE. This can
be used to identify the package through external code.
IPackageType.ipk_Checked
True or false. Determines whether or not this package checked in the Custom Install.
IPackageType.ipk_UseFilesSetting;
For FAT applications, this package will use the files’ settings on how to install this FAT
app.
IPackageType.ipk_68K;
For FAT applications, this package will install the 68K part of this FAT app.
IPackageType.ipk_PPC;
For FAT applications, this package will install the PPC part of this FAT app.
If both ipk_68K and ipk_PPC are checked, the installer will install the app
as a FAT app.
IPackageType.ipk_MEP;
If this package is a Mutually Exclusive Package
IPackageType.ipk_SubPackage;
If this package is a sub install package (Sub Archive Package)
IPackageType.ipk_ListPackage;
32–9
If this package is a list package
IPackageType.ipk_ShowInPM;
If this package will be displayed in the Easy Install popmenu
IPackageType.ipk_DefaultPkgOn;
If this package will be defaulted to checked
IPackageType.ipk_MustSelectOne;
List package option
IPackageType.ipk_CanSelectMultiple;
List package option
IPackageType.ipk_ExpandStatus;
Whether or not this parent package is expaned
IPackageType.ipk_ListHelp;
Handle to a PICT for the help for this List Package
IPackageType.ipk_ListHeader;
List Package header text (pascal string)
IPackageType.ipk_ListFooter;
List Package footer text (pascal string)
IPackageType.ipk_Gestalts;
Gestalts to check before this package is displayed in the custom install list, and shown in
the easy install text.
IPackageType.ipk_Indent;
Indentation level of the package. Maximum is 4.
IPackageType.ipk_OnOnDep[kMaxPackFlags]
Internal use only
IPackageType.ipk_OnOffDep[kMaxPackFlags]
Internal use only
IPackageType.ipk_OffOnDep[kMaxPackFlags]
Internal use only
IPackageType.ipk_ipk_OffOffDep[kMaxPackFlags]
Internal use only
32–10
IPackageType.ipk_SKU
Internal use only
ExternParmBlock->easyInstallText
Handle to the text for the Easy Install window. (For example, "This installs the version of
the product and its associated data files.) The best time to change this handle is at launch
time, before the install dialog appears.
ExternParmBlock->theFile
This structure contains information about the last file manipulated (found, installed,
etc.). You can change fields in the file structure if you want (unless otherwise noted).
struct ArcFileType {
Str32
Str32
unsigned long
unsigned long
long
long
long
short
short
long
long
long
long
long
long
long
long
unsigned long
FInfo
long
long
long
Handle
unsigned long
unsigned long
unsigned long
short
unsigned short
unsigned short
unsigned short
af_Name;
af_Internal1;
af_CreateDate;
af_ModDate;
af_DirID;
af_Internal2;
af_Internal3;
af_Internal4;
af_vRefNum;
af_CompDataFork;
af_CompResFork;
af_unCompDataFork;
af_unCompResFork;
af_SegNumber;
af_Internal5;
af_Internal6;
af_Internal7;
af_CRC;
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
//
File Name
Internal Use Only
Modificaton Date of File
Modificaton Date of File
Directory ID
Internal Use Only
Internal Use Only
Internal Use Only
Volume Reference Number
Size of compressed data fork
Size of compressed resource fork
Size of uncompressed data fork
Size of un compressed resource fork
Segment Number file is in
Internal Use Only
Internal Use Only
Internal Use Only
Checksum
af_FInfo;
af_Flags;
af_ExtractFlags[2];
// FileInfo
// special location flags and replace flags
// gestalt calls bit flags (Gestalts to
call before installing this file)
af_Internal8;
// Internal Use Only
af_ActionName;
// Handle to name Action Item name
af_CodePreActionFlags;
// external code to call doing the
action of an Action Item - after the search
af_CodeBeforeFlags; // external code to call before installing
flags
af_CodeAfterFlags;
// external code to call after installing
flags
af_FatBinaryFlags;
// when to install fat binary (see FAT
BINARY FLAGS above)
af_UniqueID;
// a unique number used by the installer
af_MergeIntoID;
// UniqueID of file to merge into
af_InstallIfID;
// Install this file if Install Action
item/fails succeeds
unsigned long
unsigned
unsigned
unsigned
unsigned
unsigned
32–11
af_Version;
// 4 bytes 1st part, 2nd & 3rd parts, development stage, prerelease version
af_InstallWhen;
// Install if Succeeds or Fails
af_Directory;
// File is a directory (if nonZero)
af_Internal9;
af_Internal10;
af_InstallDisk;
// disk the uncomp. file is supposed to be
on 0 = compressed
af_Locked;
// file - locked - from ioFlAttrib
af_LanguageBits[2]; // PopMenu Value for "Language" Country
Code (1...37)
af_RegionBits[2];
// PopMenu Value for "Region" Country Code
(1...62)
af_Internal11;
af_PackageFlags[kMaxPackFlags];
// package flags
af_DirectiveFlags[kNumDirectiveLongs];
// Build directive
flags
af_PathID;
// Which folder is it in
af_FileGroup;
// File Group for Web Installer purposes
af_LongNameIndex;
af_InstallToDomain; // FindFolder() Domain constant used for
OSX
af_UnixPrivBits;
// Internal UNIX flags; rwx rwx rwx &
symbolic link
af_UnixUserBits;
// Internal UNIX flags; set user to
wheel, root, etc.
char
char
char
char
char
unsigned char
unsigned long
unsigned long
unsigned char
long
long
unsigned long
unsigned char
long
unsigned char
long
long
};
typedef struct ArcFileType ArcFileType;
typedef ArcFileType *ArcFilePtr;
Fields can be changed unless otherwise noted.
ArcFileType af_Name
Name of file to be installed
ArcFileType.af_CreateDate
Creation date of file
ArcFileType.af_ModDate
Modification date of file
ArcFileType.af_DirID
Directory ID of the location where the file is going to be installed or was installed
ArcFileType.af_vRefNum
32–12
Volume reference number where the file is going to be installed or was installed
ArcFileType.af_CompDataFork
Compressed size of the data fork of the file •do not change•
ArcFileType.af_CompResFork
Compressed size of the resource fork of the file •do not change•
ArcFileType.af_unCompDataFork
Size of the uncompressed data fork of the file •do not change•
ArcFileType.af_unCompResFork
Size of the uncompressed resource fork of the file •do not change•
ArcFileType.af_SegNumber
Which segment the start of the file is in •do not change•
ArcFileType.af_CRC
Checksum of the file •do not change•
ArcFileType.af_FInfo
Finder info on the file
ArcFileType.af_Flags
Private
ArcFileType.af_ExtractFlags
Which gestalt calls get called before installing this file. Each bit in this field is associated
with the Gestalt menu in the Info window in Installer VISE. •do not change•
ArcFileType.af_ActionName
Handle to the name of the Action Item being called in the installer
ArcFileType.af_PackageFlags1,2,3
To which packages this file is assigned. Each bit in this field is associated with the Package
menu in the Info window in Installer VISE. •do not change•
ArcFileType.af_CodeBeforeFlags
Which external codes get called before installing this file. Each bit in this field is associated with the Before Installing code menu in the Info window in Installer VISE. •do not
change•
ArcFileType.af_CodeAfterFlags
Which external codes get called after installing this file. Each bit in this field is associated
with the After Installing code menu in the Info window in Installer VISE. •do not change•
32–13
ArcFileType.af_FatBinaryFlags
Bits here shows if the file is a fat binary application and what part of the app to install if it
is. See FAT BINARY FLAGS in ListStructs.h for more detail. •do not change•
ArcFileType.af_UniqueID;
This is a unique # assigned to this file from within Installer VISE when the file is added to
the archive. •do not change•
ArcFileType.af_MergeIntoID;
This is a unique ID # of another file to merge this file into
ArcFileType.af_InstallIfID;
This is a unique ID of a Find Action which says whether or not to install this file based on
the result of that Find action
ArcFileType.af_Version;
This is the 4 bytes of from the vers resource of the file when it was added to the archive.
(1st part, 2nd & 3rd parts, development stage, prerelease version)
ArcFileType.af_InstallWhen;
This is when to install a file based on a Find Action. 0 = install when find was successful.
1 = install when find failed.
ArcFileType.af_Directory
This is a non zero value if this a directory •do not change•
ArcFileType.af_InstallDisk
Which disk contains this uncompressed file. A value of 0 means it is compressed in the
segment •do not change•
ArcFileType.af_Locked
If this file is to be locked or not after installing. A non-zero value means to lock the file
after installing.
ArcFileType.af_LanguageBits
Bit field that corresponds to which languages are selected for the file. Each bit in this field
is associated with the Languages menu in the Info window in Installer VISE. Legal values
are 1-37.
ArcFileType.af_RegionBits
Bit field that corresponds to which regions are selected for the file. Each bit in this field is
associated with the Regions menu in the Info window in Installer VISE. Legal values are
1-62.
ArcFileType.af_PackageFlags
32–14
Bit field that corresponds to which packages are selected for the file. Each bit in this field
is associated with the Packages menu in the Info window in Installer VISE.
ArcFileType.af_DirectiveFlags
Bit field that corresponds to which build directives are selected for the file. Each bit in
this field is associated with the Build Directives menu in the Info window in Installer
VISE.
ArcFileType.af_PathID
This is the unique ID of the parent folder of the file
ArcFileType.af_FileGroup
This is the File Group for the file. File Group is used for Web Installer purposes only.
ArcFileType.af_InstallToDomain
This is the Mac OS X domain to which the file will be installed.
ArcFileType.af_UnixPrivBits
Bit field that corresponds to which permissions (such as Owner-r and Other-w) are
selected for the file. Each bit in this field is associated with the Permissions menu in the
Info window in Installer VISE.
ArcFileType.af_UnixUserBits
Bit field that corresponds to which groups (such as Wheel and Root) are selected for the
file. Each bit in this field is associated with the Group menu in the Info window in
Installer VISE.
ExternParmBlock->theEvent
The current event from WaitNextEvent/GetNextEvent
ExternParmBlock->theDialog
The Installer Dialog
ExternParmBlock->itemHit
The itemHit returned from DialogSelect
ExternParmBlock->installFork
Which forks of the file to install. This field is defaulted to kInstallFile, and your external
routine would need to change it to one of the following if needed.
kDontInstallFile
kInstallDataFork
kInstallResFork
kInstallFile
ExternParmBlock->fileList
0
1
2
3
//
//
//
//
Don't install the file
Install Data Fork Only
Install Resource Fork Only
Install Both
This is a handle to a list of files to be installed. It is a handle of ArcFileTypes
32–15
ExternParmBlock->numberOfFiles
This is the number of files that are in the ExternParmBlock->fileList
ExternParmBlock->movedItemsVRefNum
This is the volume reference number of the volume containing the Moved Items folder.
When the Macintosh restarts, files placed in this folder will be deleted by the Installer
Cleanup Extension, and then the folder itself will be deleted. If movedItemsVRefNum ==
0 then folder has not been created.
ExternParmBlock->movedItemsDirID
This is the directory ID of the moved items folder. Make sure movedItemsVRefNum != 0
before trying to access this folder. Otherwise, the folder has not been created.
ExternParmBlock->logRefNum
This is the file reference number of the log file, so you can annotate the log file in any way
you want. If this logRefNum == 0 the file has not been opened/created yet.
ExternParmBlock->removeText
Handle to the text for the Install window when the user has chosen "Uninstall" from the
Easy Install/Custom Install/Uninstall popmenu. (For example, “This removes MyApp 2.0
and its associated data files.”) The best time to change this handle is at launch time,
before the install/uninstall dialog appears.
Using the following callback routines, external code can instruct the installer to perform
various tasks.
// CallBack Constants
#define kAddStrToLogFileCallBackId
0
#define kGetVariableCallBackId
1
#define kSetVariableCallBackId
2
#define kAddStrToDebugWindowCallBackId 3
#define kSetInternalsCallBackId
4
#define kCheckGestaltCallBackId
5
#define kCheck4WebUpdateCallBackId
6
#define kMyFindFolderCallBackId
7
//————————————————————————————————————————————————————————————————————————————————————————
typedef void (*LogFileProcPtr)(Str255 theString, Boolean spaceAfter, Boolean addCR);
This routine writes a string to the log file.
typedef void (*GetVariableProcPtr)(Str255 variableName, Handle *theHandle);
This gets the value of a user-defined variable and returns a handle to that data. You will
need to use the handle size to set the string’s length.
typedef OSErr (*SetVariableProcPtr)(Str255 variableName, Str255 newValue);
This sets the value of a variable.
typedef void (*DebugWindowProcPtr)(Str255 theString, Boolean addCR);
32–16
This adds a string to the debug window.
typedef void (*SetInternalsProcPtr)(long mask, long values);
This routine sets internal installer variables to control whether any one of the following
actions occur: display Read Me, automatically start the installation process, allow multiple installs or set the installer’s quit flag. For details, see “Setting Installer VISE Internal
Variables” below.
typedef void (*CheckGestaltProcPtr)(long whichFile, Boolean *gestaltPassed);
This checks whether a given install file passes the gestalt checks assigned to it. The whichFile parameter for this routine is an index into the list of files to install (eInfo->fileList).
typedef void (*Check4WebUpdateProcPtr)(Boolean *updateAvailable);
For use with Active Web Installers only, this routine checks whether an update to the
installer is available.
typedef OSErr (*MyFindFolderProcPtr)(short vRefNum, OSType folderType,
Boolean createFolder, short *foundVRefNum, long *foundDirID);
This is Installer VISE’s internal FindFolder routine. You can use it to perform some
checks that are unavailable through Apple’s FindFolder routine.
For examples of how to call these routines, see the ExternCodeDefines.h file.
Setting Installer VISE
Internal Variables
The SetInternals callback routine allows external code to set various internal installer
variables. For this, the external code must pass the following information to the routine:
■
A mask to specify which variable to set
■
A value to set for the variable
These are the actions that SetInternals can control:
Display Read Me
Setting Bit 0 on the mask tells the installer whether to display Read Me at startup.
mask = 0;
value = 0;
BitSet(&mask,0);
BitSet(&value,0);
BitClr(&value,0);
Start the installation process
// Force the installer to not show Read Me at startup
// Allow installer to show Read Me at startup
Setting Bit 1 on the mask tells the installer whether to automatically start the installation
process.
mask = 1;
value = 1;
BitSet(&mask,1);
BitSet(&value,1);
BitClr(&value,1);
Allow multiple installs
// Force the installer to automatically start executing
// Force the installer to not automatically start executing
Setting Bit 2 on the mask tells the installer whether to allow multiple installs.
mask = 2;
value = 2;
BitSet(&mask,2);
BitSet(&value,2);
BitClr(&value,2);
Set installer’s quit flag
32–17
// Force the installer to not allow multiple installs
// Force the installer to allow multiple installs
Setting Bit 3 on the mask sets the installer’s quit flag. (The installer won’t see this routine
until the main event loop.)
mask = 3;
value = 3;
BitSet(&mask,3);
BitSet(&value,3);
BitClr(&value,3);
// Set the done flag
// Clear the done flag
Helpful Hints
Checking
kSelectorCheckingSizes
When writing external codes that will be attached to a file and called Before Installing,
make sure that you test the selector against kSelectorCheckingSizes.This is necessary
because external codes attached to files and called Before Installing will also get called
when the installer needs to recalculate the space needed to install files.
Most of the time, however, you'd only want to do something when the external code is
called when the file is actually being installed. So, you want to get out of your external
code if selector is equal to kSelectorCheckingSizes.
Here's a code snippet you can use:
pascal void main(ExternParmBlock *eInfo)
{
// Make sure this External Code was compiled with the current Headers
if (eInfo->version != kExternPBVersion) {
SysBeep(1);
goto exit;
}
// Make sure we are not called for checking sizes
if (eInfo->selector == kSelectorCheckingSizes) {
goto exit;
}
// ... YOUR CODE GOES HERE ...
exit:
return;
}
Marking Codes
Be sure to mark external code resources (and any additional resources that your code
may require, such as STR#, DLOG, and DITL) as preload and non-purgeable to prevent
disk swapping when loading and calling the code.
32–18
Code Resource IDs for
Specialized Functions
Creating External Code Resources for VISE Updaters
If you include a code resource of type ‘Xcod’ and ID 9998, any time a package is checked
or unchecked by the user, this external code will get called allowing you to perform some
custom function. If you return a non-zero value in eInfo->itemHit, the list will be
redrawn and the size requirements will be recalculated.
If you include a code resource of type ‘Xcod’ and ID 9999, this external code will be
called when the installer is first launched. (For Carbon external code that you wish to call
when the installer is first launched, use resource type ‘Xshb’ and ID 9999.) The value in
eInfo->itemHit will equal what System language the user has installed (English, French,
etc.). The value in eInfo->region will contain what region the user has installed. The
external code can change the values of these two fields in the eInfo paramblock. You may
want to do this to display a list of languages the installer supports and let the user choose
which language of the product to install. The external code could then fill in the proper
language code and region code that applies to what the user chose.
An external code resource of type ‘Xcod’ and ID 9997 will be called at the end of initialization, just before the installer hits the main event loop.
Checking for Cancellations
and Errors
To check whether the customer canceled the installation or if there was an error during
the install process, check (externParamBlock->flags & kCancelInstall). If the value is
zero, then the install was successful; if the value is non-zero, then the install was not successful.
Resources for VISE
Updaters
What follows is general information about using external code resources with VISE
updater applications. An explanation of programming and debugging techniques for
creating external code resources is beyond the scope of this documentation. Consult the
documentation for your development environment for information on this topic.
About External Code
Resources
Installer VISE includes a THINK C and Metrowerks external code framework project
which you can use to build your own external code. The main entry point is a simple
switch statement which handles the various times that the external code may be called.
When External Code Can Be
Called
External code can be called at several different times:
■
When the updater application is launched by the customer
■
When the Update button is pressed but before the source file is analyzed
■
When the actual update of a source file begins
■
When the new file has been built on the target system
■
After the update is complete
■
After the update is canceled
A specific selector is sent to the external code’s main switch statement at each of these
times.
Error Codes
If desired, you may return error codes from your external code which halts the update
process and displays an error message. (Display of an error message is optional.)
Requirements for External Resource IDs for External Code Resources:
Code Resources
Your external code resource must have a resource type of CODE and a resource ID of
500. The updater application will always look for this resource and call it if available.
32–19
ID numbers for other resources used by your external code must be in the range
500-999, inclusive. This will ensure that they do not conflict with other resources used by
the updater.
Location of External Code Resources:
You will need to create a stand-alone updater application, as described in Chapter
23-Building Updaters. Then use ResEdit or another resource editor to manually paste
your external code resource and any other necessary resources into your stand-alone
updater application.
Using External Code
Entry Points for External Code
Your external code should have a main entry point as follows:
pascal OSErr main(ExternParmBlockPtr vExtBlkPtr);
The paramBlock Interface
External code is based around a paramBlock type interface:
struct ExternParmBlock {
short
version;
QDGlobals
short
FSSpec
*qd;
selector;
*uptSpec;
FSSpec
*tgtSpec;
optPtr;
refCon;
deletedSrc;
startProc;
stopProc;
FSSpec
OptRecPtr
long
Boolean
CursProcPtr
CursProcPtr
// makes sure you're using current
// external code
// use this for QuickDraw global access
// where it's being called from
// updater's FSSpec;
*srcSpec;// original file FSSpec
// new file FSSpec
// resource option lists
// user-defined storage
// did we delete the original file?
// start cursor proc - don't touch this!
// stop cursor proc - don't touch this!
};
typedef struct ExternParmBlock ExternParmBlock, *ExternParmBlockPtr;
The following is an explanation of each paramBlock field:
vExtBlkPtr->version
This is a way to make sure that you are using the latest external code framework.
vExtBlkPtr->qd
In external code resources, you do not have access to QuickDraw globals. (i.e., qd.arrow)
This pointer allows you to access these globals.
vExtBlkPtr->selector
Determines the point during an update that external code is called. Selectors are:
kLaunchExtCall
kInitSrcPatchCall
kStartPatchCall
kEndPatchCall
kFinishUpCall
kCancelCall
//
//
//
//
//
//
//
Called after launch/splash/readme
Update starting, before anything else happens
Update starting, target file has just been created
New file has been built but we have not deleted source or
moved new file from temporary folder and renamed yet
successful update completion, last chance to do something
update was canceled, last chance to clean up
vExtBlkPtr->uptSpec
32–20
Pointer to the updater's FSSpec.
vExtBlkPtr->srcSpec
Pointer to the user's original file's FSSpec.
vExtBlkPtr->tgtSpec
Pointer to the new file's FSSpec.
vExtBlkPtr->optPtr
OptRecPtr to the Resource Exception lists. See the description of the Resource Exception
list below for the exact structure of these lists.
vExtBlkPtr->refCon
Can be used for your own storage purposes.
vExtBlkPtr->deletedSrc
Was the source file deleted/moved to trash? This is only valid for the last external code
call, kFinishUpCall.
vExtBlkPtr->startProc
vExtBlkPtr->stopProc
Pointers to cursor spin routines. Do not modify these items directly. Instead, use the following routines included in the external code framework project:
void StopSpin(ExternParmBlockPtr vExtBlkPtr);
void StartSpin(ExternParmBlockPtr vExtBlkPtr);
The Resource Exception Lists
The structure of the resource exception lists is:
typedef struct OptRec {
OptItemListHdl
OptItemListHdl
OptItemListHdl
} OptRec;
typedef OptRec
replaceHdl;
copyHdl;
carryHdl;
*OptRecPtr;
typedef struct OptItem {
ResType
resType;
short
startID;
short
stopID;
} OptItem;
typedef OptItem
typedef OptItemPtr
typedef struct OptItem
typedef OptItemList
typedef OptItemListPtr
Helpful Hints
// always replace with new target rsrcs
// always copy from original file
// copy from original file if they exist
*OptItemPtr;
*OptItemHdl;
OptItemList[1];
*OptItemListPtr;
*OptItemListHdl;
An easy way to get started is to build the external code framework project with the
DebugStrs uncommented and paste the code resource into your stand-alone updater
application. Then, run the updater to see exactly when the external code resource is
called with each selector.
If you have any modal dialogs in your external code and create custom filter procs for
them, be aware that you are not guaranteed that the current A4 will be correct. In other
words, if you define global variables in your code resource and access them from within
Keeping a Debugger from Quitting
32–21
the filter proc, you must make sure that A4 is correct. One way to do this is to save off the
correct A4 in your dialog’s refcon.
Resources imported from external resource files whose ID is within 5000
and 10000 (inclusive) will be automatically set to preload and non-purgable.
Keeping a Debugger
from Quitting
When the archive setting Shutdown Applications Before Installing is on, any running
application, including a debugger, will be shutdown before the installation. During
debugging of external code it may be necessary to override this archive setting.
To prevent certain applications from shutting down when using “Shutdown Applications
Before Installing”, a SdEx resource can be added to the Installer.
To add a SdEx reource to your installer using Resorcerer:
1. Place the MV Templates file in your Resorcerer Private Templates folder (it contains a template so that you can edit the SdEx resource).
2. Open your archive with Resorcerer.
3. In the archive, create a new Resource of Type SdEx with an id of 1000.
Illustration 32-2: Creating a SdEx Resource
4. In the new SdEx resource window click New.
Illustration 32-3: Adding a New SdEx Resource
32–22
Executing UNIX scripts from the installer
5. Double-click on the word Type, enter the type code of the application you wish to
remain running, and click OK.
Illustration 32-4: Entering the Application Type
6. Double-click on the word Creator, enter the creator code of the application you
wish to remain running, and click OK.
Illustration 32-5: Entering the Application Creator
7. Close and save the VCT. When you build and run the Installer, the identified
application will not quit.
You can add more applications to the exception list as long as they are all kept in the 1000
resource.
Executing UNIX scripts
from the installer
With its UNIX foundation, Mac OS X opens the door for many existing UNIX applications to transfer to the Macintosh platform. To capitalize on this opportunity, Installer
VISE can execute UNIX scripts from the installer.
You may only execute shell scripts from a Carbon installer running on
Mac OS X.
There are two different ways to include a UNIX shell script in the installer:
■
Save the shell script in a plain text file and add the text file to the installer via the
Project window. See “Including shell scripts as plain text files” on page 32-23.
■
Save the shell script in a resource of type ‘shsc’ and add the resource file to the
installer via the Project window. See “Including shell scripts as resource files” on
page 32-24.
32–23
Also consider the UNIX Script action, which offers offers a simple way to
execute UNIX shell scripts from the installer. This action is a good choice
for when you don't need to perform actions on installed items. For access
to standard UNIX parameters such as $1, you'll need to use the more
advanced methods described here. See “UNIX Script Options” on page 8-40.
Including shell scripts as
plain text files
To allow for shell script creation without a resource editor, Installer VISE supports adding shell scripts to the Project window as plain text files.
To include a UNIX shell script in the installer:
1. Use a text editor to write the shell script.
2. Save the script as a plain text file.
Code.)
3. Add the script file to the installer via the Scripts/Shared Libs area of the Project
window.
4. Declare the script in the installer.
5. Specify when the installer should call the script file (to execute the shell script).
When calling the script file, an Installer VISE installer will:
Information passed from
installers to shell scripts
■
Create a temporary file for this script on the target computer.
■
Execute the UNIX “system” command and pass the path to the temp file, which
will execute the shell script.
■
Pass install path and other information to the shell script, as noted below.
■
Delete the temp file.
An installer that calls the script file before or after installing a file will pass the following
information to the script:
■
Install path. This path (which contains file name, such as “/Library/Internet
Plug-Ins/MyFile”) may be accessed through the UNIX $1 parameter. If the path
to the file includes spaces (such as “/Library/Application Support”), you must
enclose the $1 parameter in quotes (“$1”).
■
File name. This value may be accessed through the UNIX $2 parameter.
■
Special Installer VISE variable. Before calling the ‘shsc’ resource, the installer
will need to declare a runtime variable called “ShellVar” (case must match) and
set its value. This value may be accessed through the UNIX $3 parameter. For
information on declaring a variable, see Chapter 28-Using Runtime Variables.
To learn how to dynamically set the value of a runtime variable at install time,
see “Set Variable Options” on page 8-28.
■
RefCon value. This is the value entered in the RefCon field of the Edit External
Code dialog. It may be accessed through the UNIX $4 parameter. See “Declaring External Code in an Installer” on page 9-4 and “Resource IDs and Reference
Constants” on page 32-1 for more information.
32–24
When an installer calls a script file before installing a nested folder, the
value accessible through the UNIX $1 parameter will be the install path to
the parent folder, rather than the nested folder. (This is not an issue when
the installer calls the script file after installing a nested folder.) If you need
to perform some action on a nested folder before installing it, you can create a path to
the folder by combining the results of the $1 parameter (install path) and $2 parameter (folder name).
shell scripts to installers
The shell script can also return success or failure to the installer.
To set up the installer to cancel the installation if the shell script returns an error, use
“exit 1” at the end of the script. This has the same effect as external code setting the
kCancelInstall bit.
Scripts return a value of 0 for success and a non-zero value for failure.
Including shell scripts as
resource files
With this approach, the process for setting up your installer to execute UNIX scripts is
similar to the one used for including AppleScript scripts in an installer. In both cases, you
need to paste the script into a specific resource file type and set up the installer to recognize and call that resource.
To include a UNIX shell script in the installer:
1. Use a text editor to write the shell script.
2. Copy the script text.
3. Use a resource editor such as ResEdit to paste the text into a resource of type ‘shsc.’
4. Give the resource an available ID between 5000 and 10000 and save the file.
Code.)
5. Add the resource file to the installer via the Resource Files area of the Project window.
6. Declare the resource in the installer. Be sure to use type ‘shsc’ and the ID assigned
in Step 4.
7. Specify when the installer should call the resource (to execute the shell script).
When calling the ‘shsc’ resource type, an Installer VISE installer will:
installers to shell scripts
■
Create a temporary file for this resource on the target computer.
■
Execute the UNIX “system” command and pass the path to the temp file, which
will execute the shell script.
■
Pass install path and other information to the shell script, as noted below.
■
Delete the temp file.
An installer that calls the ‘shsc’ resource before or after installing a file will pass the following information to the shell script:
■
Install path. This path (which contains file name, such as “/Library/Internet
Plug-Ins/MyFile”) may be accessed through the UNIX $1 parameter. If the path
to the file includes spaces (such as “/Library/Application Support”), you must
enclose the $1 parameter in quotes (“$1”).
Sending information to sub-launched installers
32–25
■
File name. This value may be accessed through the UNIX $2 parameter.
■
Special Installer VISE variable. Before calling the ‘shsc’ resource, the installer
will need to declare a runtime variable called “ShellVar” (case must match) and
set its value. This value may be accessed through the UNIX $3 parameter. For
information on declaring a variable, see Chapter 28-Using Runtime Variables.
To learn how to dynamically set the value of a runtime variable at install time,
see “Set Variable Options” on page 8-28.
■
RefCon value. This is the value entered in the RefCon field of the Edit External
Code dialog. It may be accessed through the UNIX $4 parameter. See “Declaring External Code in an Installer” on page 9-4 and “Resource IDs and Reference
Constants” on page 32-1 for more information.
When an installer calls a script file before installing a nested folder, the
value accessible through the UNIX $1 parameter will be the install path to
the parent folder, rather than the nested folder. (This is not an issue when
the installer calls the script file after installing a nested folder.) If you need
to perform some action on a nested folder before installing it, you can create a path to
the folder by combining the results of the $1 parameter (install path) and $2 parameter (folder name).
shell scripts to installers
The shell script can also return success or failure to the installer.
To set up the installer to cancel the installation if the shell script returns an error, use
“exit 1” at the end of the script. This has the same effect as external code setting the
kCancelInstall bit.
Scripts return a value of 0 for success and a non-zero value for failure.
Sending information
to sub-launched
installers
You can use external code to gather information such as user preferences and send the
information from a parent installer to a sub-launched installer.
(Information on how to create external code for Installer VISE installers appears earlier
in this chapter. For further reference, see “Sub-launch Action Options” on page 8-33 and
Chapter 9-Assigning External Code.)
To send information from a parent installer to a sub-launched installer:
1. From the parent installer, use external code to do the following:
■
Collect the desired data.
■
Assign sublaunchData to point to the data to send.
■
Use sublaunchDataSize to specify the size of the data being sent.
(See “Creating External Code for Installer VISE Installers” on page 32-3 for specifics on the required fields.)
2. Use a Sub-launch action item within the parent installer to sub-launch an
installer.
3. From the sub-launched installer, use external code to read the data sent by the
parent installer.
32–26
Installing Text Encoding Converters
The Samples folder includes a sample project called “Sub-launchf ” that
demonstrates using external code to collect information and send the
information to a sub-launched installer. If you need to install the samples,
run the Installer VISE installer and select the “Tutorial and Sample Files”
Custom Install option.
Installing Text
Encoding Converters
Text encoding conversion allows a computer to correctly interpret text that it might not
otherwise understand. For example, a Mac OS application might be unable to read a text
file created on a Windows system, because it expects to find Mac OS character sets. Text
encoding conversion prevents such compatibility problems.
The procedure for writing text encoding converters is beyond the scope of this document. However, Installer VISE can make the installation of text encoding converters as
straightforward as possible.
With Installer VISE 6.5 and newer, you can install text encoding converters without having to write external code. Installer VISE will ensure that it correctly installs your text
encoding converters by keeping the converter file (located in the Extensions Folder) in
compliance with required converter documents (located at the root of the System
Folder). This feature is automatically enabled for text encoding converters in your
archive.
33–1
Chapter 33
Gestalts for Minimum Install Requirements
Modifying Gestalts for
Minimum Install
Requirements
This chapter contains information about modifying the gestalts that can be called to
determine minimum install requirements. These gestalts are selected in the Installer Settings/Attributes tab, and may only apply to an entire installation. If you wish to check
gestalts for individual files or folders, see “Creating and Modifying Gestalts” on
page 10-1.
The use of gestalts is exhaustively documented in Inside Macintosh. This section only
contains information about modifying the GLST resource in Installer VISE to change the
Minimum Install Requirements.
How the GLST
Resource is Handled
GLST resources are copied from the Installer VISE application to the archive when the
archive is first saved. If you need to add a new gestalt selector to an archive after it’s been
saved, you must edit the GLST resource in the archive file. If you wish to use this gestalt
selector for other archives, you should also copy it to the Installer VISE application.
Warnings
Please note the following critical information regarding modifying
gestalt selectors for minimum install requirements:
■
You may not have more than 63 gestalt selectors.
■
All new gestalt selectors should be added to the end of the gestalt
selector list within an archive.
■
If you delete a gestalt selector from an archive file, all subsequent gestalt
selectors in the list will be in the wrong location. For example, if bit one is
turned on, then the Has Alias Manager gestalt selector must be present for
that file to be installed. If you delete the gestalt selector for Has Alias Manager, then the first bit will apply to the Has Communications Toolbox
gestalt selector.
■
If you modify a gestalt call in an archive file, then all bits corresponding to
the original gestalt selector will now apply to the modified gestalt selector.
For example, if you change the Has Alias Manager gestalt selector to
Machine Type gestalt selector in an archive and Has Alias Manager was
selected, Machine Type will now be selected.
33–2
Adding a Gestalt
Selector
Adding a Gestalt Selector
To add a new gestalt selector to check minimum install requirements:
1. Open the Installer VISE application with ResEdit.
If you are modifying a gestalt selector for an archive, open Installer VISE and the
archive with ResEdit. (Installer VISE must be open for the GLST Picker TMPL to
be available.)
2. Select the GLST resource.
3. From the resource menu, select Open GLST Picker.
Illustration 33-1: ResEdit GLST Picker
4. Double-click resource ID 1001. (Resource ID 1000 is for gestalts to be called while
installing individual items, and it is much easier to modify this from within
Installer VISE.)
5. Scroll to the bottom of the GLST list. Five asterisks will be displayed at the bottom
of the window.
6. Select the five asterisks. A rectangle will be displayed around them.
Illustration 33-2: Preparing to Add a New Item
Chapter 33 Gestalts for Minimum Install Requirements
Modifying a Gestalt Selector
33–3
7. In the Resource menu, select Insert New Fields. A new gestalt entry will be added
beneath the asterisks.
8. Enter information as follows:
Item
Action
Selector
Enter the four-character name for the selector
Operator
Select desired operator, bit set, or bit clear
Result
Enter the result to compare
Name
Enter the name that should appear in the Gestalt selector popup in the Set Installer window
Table 33-1: Adding a Gestalt Selector
9. Dismiss the window
10. For every Gestalt you add, you must add a corresponding entry to STR# 1012
resource, which informs the user of the minimal install requirement. If you add a
18th Gestalt to the list of Gestalts, you must add the 18th string message in this
STR# 1012 resource. This STR# 1012 resource is in the English Installer file as well
as French Installer, German Installer, etc.
Illustration 33-3: Adding a STR# 1012 Resource for Gestalt
11. Save your changes.
Modifying a Gestalt
Selector
To modify a gestalt selector, follow steps 1-4, above. Then, locate the selector you wish to
modify and change the information as described in step 8, above. You should also modify
the message that corresponds to the Gestalt selector in the STR# 1012 resource in the
localized installer files (i.e., English Installer, German Installer, etc.).
33–4
Sample Gestalt
Selector
Sample Gestalt Selector
The following is an illustration of a correctly-defined gestalt selector to check Mac OS
Version. The “greater than” operator is selected, and the result for comparison is 0x07FF.
If the returned result is 0x0800 or greater, then you know that the user is running Mac
OS 8 or greater.
4 character Gestalt selector
Operator to use in comparing
the Result field against the
value returned by the
Gestalt call.
If on, check the bit number
indicated in the Result field
against the 32 bit value
returned by the
Gestalt call.
Validgestalt = (returned value & Result) == Result
Whether or not this Gestalt must
exist, must not exist, or if both
are on means doesn't exist or…
Compare this value with the
value returned by the Gestalt call
Title that appears in the Archive Settings
Minimum Gestalt popmenu
Illustration 33-4: Mac OS 8 or Greater Minimum Install Gestalt Setup
Chapter 33 Gestalts for Minimum Install Requirements
34–1
Chapter 34
Installer VISE Forms
Installer VISE Forms
Forms in Installer VISE are developer-defined dialogs which can be used for:
■
Displaying simple dialogs to convey information during the install
Illustration 34-1: Simple form
■
Displaying dialogs which query for information and set appropriate variables
Illustration 34-2: Form Used to Query for Information
34–2
Sample Layout
Sample Layout
The illustration below contains a sample layout with at least one of each type item
Installer VISE forms can contain.
Illustration 34-3: Sample Form Layout
Creating a New Form
To create a new form:
1. Select Forms… from the Archive menu. The Form List is displayed.
Illustration 34-4: Form Menu Item
Chapter 34 Installer VISE Forms
Sample Layout
34–3
2. Select New from the Form List window.
Illustration 34-5: Form List Window
3. Enter a name for the Form in the Name field.
Illustration 34-6: Edit Form
4. Set the Language and/or Region(s) for the Form Layout.
A single form can be made up of multiple form layouts. Form layouts allow the
form to be localized. Before a form is displayed by a built installer, the language
and region of the user’s operating system are compared with the Language and
Region settings of a form’s layouts and the form layout with the best match will be
displayed.
34–4
Sample Layout
When creating forms, it is important to finalize a base layout before working on
layouts for other languages and/or regions. Finalize the base layout, duplicate the
layout, localize the new layout, set the Language and/or Region settings for the
localized layout.
5. Select the Edit Layout button to edit the layout contents. A blank layout will be
displayed in the Form Layout Editor window and a new menu, Editor, will be
enabled.
Illustration 34-7: Form Layout Editor
The Editor menu contains all commands necessary to create, edit and test layout
content.
Illustration 34-8: Editor Menu
6. Set up the form layout contents using the Form Editor commands described
below (see “Form Editor Commands” on page 34-6).
Configuring a Form Action to Display a Form
Configuring a Form
Action to Display a
Form
34–5
Form Action items are used within an archive to determine form display. The display of a
form during an installation can be customized by:
■
The form action’s location in the Archive Window item list determines when
the form will be displayed during the install.
■
The form action’s Display Form If settings will determine if the form will be displayed during the install.
■
The form action’s package settings will determine which packages will display
the form during install.
To set up a form for display during an installation:
1. From the Archive Menu select New Action -> Form.
2. A Form Action will be added to the Archive Window Item List and the Form
Action window will open.
Illustration 34-9: Form Action
3. Name the Form Action.
4. Set up any Display Form If conditions. The Form Action, and therefore the form,
can be set to display conditionally according to:
■
Build Directives - determine whether the form action will be included in
the current installer build.
■
Gestalt - determines whether the form action will be executed by the
installer based on a gestalt setting from the end user’s computer.
■
Language - determines whether the form action will be executed by the
installer based upon the language of the operating system upon which the
installer is run.
■
Region - determines whether the form action will be executed by the
installer based upon the region of the operating system upon which the
installer is run.
34–6
Form Editor Commands
If your form is designed with localized layouts and appropriate Language
and/or Region settings, the Form Action’s Language and Region settings
need not be used. The form will display the correct layout based on the
language and/or region of the operating system upon which the installer is
run.
Use the Form Action’s Language and Region settings when a completely different form
needs to be displayed based upon the language and/or region of the operating system
upon which the installer is run.
■
Action Result - determines whether the form action will be executed by the
installer based upon another action item’s success or failure (including Test
Variable actions) or upon the button selected in a Message action.
5. From the Display Form Options Form popmenu, select the form to be displayed.
6. Close and save the Form Action.
7. Make package assignments for the Form Action. The form will only be displayed
for packages which include the Form Action.
8. Determine when during the installation you wish the form to be displayed and
drag the Form Action up or down in the Archive Window to the desired location.
Form Editor
Commands
Using the Form Layout Editor is similar to setting up a dialog in ResEdit or Resorcerer.
Undo
When there has been a change, the Undo menu item will be enabled and will undo whatever was last changed. It does not undo any “new” items and does not undo a form layout
move or resize.
Select All
Select All will select all the items in your customized form layout.
Duplicate
When at least one item is selected, the Duplicate item will be enabled and will duplicate
the item(s). When an editable text, checkbox, radio group or radio button item is duplicated, it will ask for a new name for the new item. For the editable text item it will create
a new static text item with the new title. For the checkbox, radio button, or radio group
items it will change the title of the checkbox to the new name that you enter.
New Button
Selecting the New Button command will cause the cursor to change to a button indicator. Click in the Form Layout Editor window to create a new button item with a default
title of “Button”. Rather than simply clicking, if you click and drag a new button will be
Below is a description for each of the Form Editor commands:
34–7
created with bounds set by your click and drag. Upon button creation a Button Item
window will open allowing you to set button properties.
Illustration 34-10: Button Item Properties
Button Property
Description
Title
Name which will be displayed on the button.
Default Button
Determines whether the button is drawn with dark outline to
indicate that it is a default button. At runtime, default buttons
can be selected from the keyboard by Return of Enter.
Top
The number of pixels between the top of the layout and the
top of the button.
Left
The number of pixels between the left side of the layout and
the left side of the button.
Height
The number of pixels from the top of the button to the
bottom. Default height is 18 pixels.
Width
The number of pixels from the left side of the button to the
right side of the button. Default width is 100 pixels.
Set
Allow selection of a variable to be set by the button. Clicking
the Set button opens the Variable List window from which an
existing variable can be selected or new variable can be
created and selected.
Table 34-1: Button Properties
34–8
Button Property
Description
To
When this button is clicked by the user at installer runtime
the variable indicated in the Set field will be Set to the value
indicated in the To field.
Behavior
A button will have one of several behaviors based upon your
selection in this popmenu. For a description of each button
behavior see Table 34-2, “Button Behaviors,” on page 34-8.
Buttons can be resized by changing Height and Width properties or by dragging a resize
handle on one of the button’s corners.
Button Behavior
Description
Register
A button with behavior of Register will cause a dialog to be
displayed presenting the user with registration options. The
fields found on the form layout will be used for the
registration data. For more information on registration see
Chapter 35-On-Line Registration.
At runtime, if the user clicks a button which has its behavior
set to Register, other items in the form which are configured
to set variables will set their variables.
Continue
A button with behavior of Continue will cause the installation
to proceed.
set to Continue, other items in the form which are configured
to set variables will set their variables.
Cancel
A button with behavior of Cancel, when used in a Form
Action with a setting of Stop Install If User Cancels, will cause
the installation to be canceled.
set to Cancel, other items in the form which are configured to
set variables will not set variables.
Print Mailer
A button with behavior of Print Mailer will initiate the
printing of a registration mailer. The fields found on the form
layout will be used for the registration data. For more
information on registration see Chapter 35-On-Line
Registration.
set to Print Mailer, other items in the form which are
configured to set variables will set their variables.
Table 34-2: Button Behaviors
34–9
Button Behavior
Description
Print For Fax
A button with behavior of Print For Fax will initiate the
printing of a registration fax form. The fields found on the
form layout will be used for the registration data. For more
information on registration see Chapter 35-On-Line
Registration.
set to Print For Fax, other items in the form which are
E-Mail
A button with behavior of E-Mail will initiate the sending of
an email registration. The fields found on the form layout will
be used for the registration data. For more information on
registration see Chapter 35-On-Line Registration.
set to E-Mail, other items in the form which are configured to
set variables will set their variables.
Go To Form
A button with behavior of Go To Form will cause the display
of the form indicated by the behavior. Buttons with behaviors
of Go To Form allow the creation of wizard-like interfaces for
your installer.
set to Go To Form, other items in the form which are
Table 34-2: Button Behaviors
When constructing forms, be sure to check the behavior of all buttons.
The default behavior for a newly created button is Cancel. At runtime, if
the user clicks a button which has its behavior set to Cancel, other items in
the form which are configured to set variables will not set variables. If you
do not set the button’s behavior to the proper setting for your purposes you may end
up with a form that does not produce the desired results.
New Static Text
Selecting the New Static Text command will cause the cursor to change to a static text
indicator. Click in the Form Layout Editor window to create a new static text item. The
default text is set to “Static Text”.
For Static Text items the initial default font is Geneva 9 Bold. Any changes
made to the Font, Size or Style popmenus become the defaults for new
Static Text items created during the current Installer VISE session.
Custom colors for text and backgrounds in forms are not supported on
Mac OS X. In this case, text will always display in black, and custom background color settings will be ignored. No such limitations exist on Mac OS
9, or in the Classic environment.
34–10
Rather than simply clicking, if you click and drag a static text item will be created with
bounds set by your click and drag. Upon static text item creation a Static Text Item window will open allowing you to set static text properties.
Illustration 34-11: Static Text Item Properties
Besides setting the text, you can also set the text to be framed and set the font, font size,
font style, color, and background color of the static text item. (For installers run on Mac
OS X, text color will always be black and any background color setting will be ignored.)
New Edit Text…
Selecting the New Edit Text… command will cause the cursor to change to an edit text
indicator. Click in the Form Layout Editor window to create a new edit text item.Before
the item is actually created, you must give the item a “Field Name”.
Illustration 34-12: Naming a New Edit Text Item
For Edit Text items the initial default font is Geneva 9. Any changes made
to the Font, Size or Style popmenus become the defaults for new Edit Text
items created during the current Installer VISE session.
Once the name has been entered a static text item will be created as a field label with the
text being the “Field Name” and a “:” appended to the end. To change the properties of
34–11
the Edit Text item, double-click on the edit text item or select the edit text item and hit
the Enter or Return key.
Illustration 34-13: Edit Text Item Properties
Edit Text Item
Property
Description
Name
Edit Text Item name. For internal purposes only. Can be
accessed and changed by selecting the edit text field and
choosing Edit “Field Name”… from the Editor menu or by
Option double-clicking the edit text field.
Text
Default text to be displayed in the field when the form is
displayed at runtime. Variables can also be entered as default
text. Be sure to use the % symbol before and after the variable
name. For example, if the variable name was “vProductName”
enter “%vProductName%” in the text field.
Required Input
Text must be entered into this field before continuing.
Required fields are indicated with a dark outline.
Font
Select the display font for edit text. You can select any specific
font or you can select System font or Application font which
may change based upon the end user’s machine.
Size
Select the font size for edit text.
Style
Select the font style for edit text
Top
top of the text edit field.
Left
the left side of the text edit field.
Table 34-3: Edit Text Item Properties
34–12
Edit Text Item
Property
Description
Height
The number of pixels from the top of the text edit field to the
bottom.
Width
The number of pixels from the left side of the text edit field to
the right side of the edit text field.
Text Color
Click inside the Text box to get a standard color picker. Select
the color for edit text. Default for text edit fields is black.
Background
Color
Click inside the Background box to get a standard color
picker. Select the color for edit text background.Default for
text edit fields is white.
Use
Determines whether the background color is used. If the Use
checkbox is not checked, the text edit field background is
transparent and will therefore have the background color of
the dialog.
Set
Allow selection of a variable to be set to the text entered into
the edit text field at installer runtime. Clicking the Set button
opens the Variable List window from which an existing
variable can be selected or new variable can be created and
selected.
Invisible
When checked on, the edit text field will be invisible during
form tests and at installer runtime. Invisible text edit fields
cannot be accessed by a user at installer runtime but can
contain text set via runtime variables or set data that you
enter. Invisible fields are included on Print For Fax and Email
registrations.
Table 34-3: Edit Text Item Properties
New Checkbox…
Selecting the New Checkbox command will cause the cursor to change to a checkbox
indicator. Click in the Form Layout Editor window to create a new checkbox. A new
34–13
checkbox item needs to be named before it can be created. Once the name has been
entered the checkbox is created.
Illustration 34-14: Checkbox Item Properties
At creation, the checkbox Name and the checkbox Title are the same. To change the title
of the checkbox independent of the name of the field, select the checkbox and choose Get
Info… from the Editor menu. You can also Option double-click the checkbox field to
change the Field Name.
Checkbox
Property
Description
Name
Checkbox Item name. Can be accessed and changed by
selecting the checkbox item and choosing Edit “Field
Name”… from the Editor or by Option double-clicking the
checkbox item.
Title
The text to be displayed to the right of the checkbox at
installer runtime.
Default On
Determines whether the checkbox is checked on when the
form is initially displayed at installer runtime.
Top
top of the checkbox.
Left
the left side of the checkbox.
Height
The number of pixels from the top of the checkbox to the
bottom.
Table 34-4: Checkbox Properties
34–14
Checkbox
Property
Description
Width
The number of pixels from the left side of the checkbox to the
right side of the checkbox.
Set
Allow selection of a variable to be set by the checkbox.
Clicking the Set button opens the Variable List window from
which an existing variable can be selected or new variable can
be created and selected.
NOTE: When using checkboxes to set variables it is important
to know that when checked, the designated variable will be set
to 1 or 0.
Table 34-4: Checkbox Properties
New Radio Button
Selecting the New Radio Button command will cause the cursor to change to a radio
button indicator. Click in the Form Layout Editor window to create a new radio button.
You will be asked to name the radio button before its creation. Rather than simply clicking, if you click and drag, a new radio button will be created with bounds set by your
click and drag.
To edit radio button properties double-click the radio button.
Illustration 34-15: Radio Button Item Properties
Radio Button
Property
Description
Title
The text to be displayed to the right of the radio button at
installer runtime.
Default On
Determines whether the radio button is on when the form is
initially displayed at installer runtime.
Top
top of the radio button.
34–15
Radio Button
Property
Description
Left
the left side of the radio button.
Height
The number of pixels from the top of the radio button to the
bottom.
Width
The number of pixels from the left side of the radio button to
the right side of the radio button.
Set
Allow selection of a variable to be set by the radio button.
NOTE: When using a radio button not in a radio group to set
a variable it is important to know that the designated variable
will be set to 1 or 0.
Radio buttons can be resized by changing Height and Width properties or by dragging a
resize handle on one of the button’s corners.
New Radio Group
Selecting the New Radio Group command will cause the cursor to change to a radio
group indicator. Click in the Form Layout Editor window to create a new radio group.
You will be asked to name the radio group before its creation. Rather than simply clicking, if you click and drag, a new radio group will be created with bounds set by your click
and drag.
A Radio Group (whether visible or invisible) causes all enclosed radio buttons to act as a
group - when one radio is selected the other radios are automatically deselected.
To edit radio group properties double-click the radio group item.
Illustration 34-16: Radio Group Item Properties
34–16
Radio Group
Property
Description
Name
Radio Group Item name. Can be accessed and changed by
selecting the edit text field and choosing Edit “Field Name”…
from the Editor or by Option double-clicking the edit text
field.
Is Visible
Determines whether the radio group is visible on the layout at
installer runtime.
Top
top of the radio group.
Left
the left side of the radio group.
Height
The number of pixels from the top of the radio group to the
bottom. Default height is 100.
Width
The number of pixels from the left side of the radio group to
the right side of the radio group. Default width is 100.
Set
Allow selection of a variable to be set by the radio group.
NOTE: When using radio group to set variables it is
important to know that the designated variable will be set to
the name of the radio button which is on.
Table 34-6: Radio Group Properties
Radio Groups can be resized by changing Height and Width properties or be dragging a
resize handle on one of the group’s corners.
New Picture
Selecting the New Picture command will cause the cursor to change to a PICT indicator.
Click in the Form Layout Editor window to create a new picture. If there is a picture in
the clipboard, a new picture item will be created containing the picture that is in the clip-
34–17
board. Rather than simply clicking, if you click and drag a new picture item will be created with bounds set by your click and drag.
Illustration 34-17: Picture Item Properties
Picture Property
Description
ResID
The PICT resource ID of the picture.
Top
top of the picture.
Left
the left side of the picture.
Height
The number of pixels from the top of the picture to the
bottom. Defaults to the actual height of the picture.
Width
The number of pixels from the left side of the picture to the
right side of the picture. Defaults to the actual width of the
picture.
Table 34-7: Picture Properties
Expand Right
When at least one item is selected, the Expand Right menu item will be enabled and will
increase the right boundary of the item(s) by 1 pixel. This will affect all selected items.
Reduce Right
When at least one item is selected, the Reduce Right menu item will be enabled and will
reduce the right boundary of the item(s) by 1 pixel.This will affect all selected items.
Get Info…
When at least one item is selected, the Get Info… menu item will be enabled and will
display the items’ properties dialog.
Edit “Field Name”…
When at least one editable text, checkbox, radio button, or radio group item is selected
the Edit “Field Name”… menu item will be enabled and will display a dialog that allows
you to name the field.
34–18
Item Order in Dialog
The field name will be used for:
■
Setting variable values in the case of radio buttons in a radio group
■
Submission via E-Mail
■
Output during Print for Fax
The name must be unique to the form that you are editing and is limited to 31 characters. You can also edit the “Field Name” of any text, checkbox, radio button, or radio
group by holding down the option key while double clicking on it or typing Enter or
Return. The “Field Name” is also visible in the title bar of the dialog when doing a Get
Info on an editable text of checkbox item, radio button or radio group.
Set Background Color
Set Background Color allows you to set the background color of the form layout. Selecting the Set Background Color menu item will display a standard color picker.
Set Tab Order
The Set Tab Order command will enable you to set the tab order of the editable text
fields by clicking on the items in the new order. All fields must be set before the renumbering is done. You can get out of the tab ordering mode without reordering anything by
using either the escape key or command period. While in the tab ordering mode the
cursor will change and no clicks will register unless they are within editable text items.
Once all editable text items have been selected, the reordering is set. You will still need to
save your changes in order to keep the order.
Save
The Save command is enabled when there has been a change to the form. Selecting this
item will save your changes without having to close the Form Editor.
Test…
The Test… command will display the customized dialog as your users will see it when
they install your software. You will be asked to save any changes before the dialog is displayed.
Be aware of the following issues when testing forms:
Close
Item Order in Dialog
■
If you have included buttons with any of the registration behaviors, you can test
the registration process.
■
The test operation does not do any manipulation of runtime variables.
■
The test operation uses the first registration destination in the list.
This will close the form layout dialog that you are editing. If you have made any changes
it will ask if you want to save them. You can also dismiss the form editor with the escape
key to bypass any of the saving process.
1. Buttons (Default button first)
2. Static Text
3. Edit Text (in tab order)
4. Checkboxes
Keyboard Commands
34–19
5. Radio buttons
6. Pictures
7. Radio Groups
Keyboard Commands
Key
Behavior
Return or Enter
Performs Get Info on the selected item(s) which
causes the items properties dialog to be displayed.
Arrow keys
Move the selected items appropriately by 1 pixel.
Command-arrow keys
Move the selection 10 pixels.
Option-arrow keys
Move the selection 50 pixels.
Escape
Dismisses the dialog without saving your latest
changes. Exits the new item. Exits tab order mode.
Delete key
Deletes the selected item(s)
Table 34-8: Form Editor Keyboard Shortcuts
34–20
Keyboard Commands
35–1
Chapter 35
On-Line Registration
Using Online
Registration
You may need information from end users in order to identify and keep in contact with
them. With Online Registration you can provide your users with a convenient way of
sending that information. Users will be presented with a dialog that you customize using
Forms.
Illustration 35-1: Example On-line Registration Dialog
35–2
Using Online Registration
Once they have entered the requested data they will be able to submit the information to
you by either e-mail, printing a mailer, or printing a list of the data to be either faxed or
mailed.
Illustration 35-2: Register by E-mail, Mailer or Fax
On-line Registration Setup Overview:
1. Create Registration Destination - Set up data identifying where you want the user
to send their information.
2. Create Form - Set up the layout of the desired user interaction dialog.
3. Enable Online Registration - Indicate that you wish to include Online Registration in the Installer by settings in Installer Settings or by using a Form Action.
Create Registration
Destination
Before you can use Online Registration you need to identify the addresses of where to
send the user's information.
To create a Registration Destination:
1. Select Registration Destinations… from the Archive menu. The Registration
Destination List will be displayed
2. Click the New button to create a new registration destination.
Illustration 35-3: Creating a New Registration Destination
Chapter 35 On-Line Registration
Using Online Registration
35–3
3. Enter your destination information into the appropriate fields. The example
below shows the MindVision Corporate Headquarters registration destination.
Illustration 35-4: Edit Registration Destination Window
Field
Description
Name
The name of the destination. For example you might name one
destination “US Dest” and another “Non-US Dest”. This field is
for internal use only and will not be displayed in the built
installer.
Region(s)
The region setting determines when this particular destination
will be used based upon a comparison with the region setting of
the operating system upon which the built installer is run.When
the installer is run, it first looks for an exact region match. If
there is not a region match then the first destination set to Any
Match will be used.
Mail To
The address to which registration mailers will be mailed from
the region(s) checked. Enter all address components (i.e. name,
street, and city state zip). This information will be printed in
uppercase on the mailer.
BRM Permit No,
City & State
The Business Reply Mail Permit number followed by the city and
state which issued the BRM number. If the BRM field is left
blank then a Courtesy Reply Mail (CRM) mailer is created
instead.
Table 35-1: Registration Destination Field Description
35–4
Creating a Registration Form
Field
Description
Zip Code For
Bar Code
A Zip Code is only needed in this field if a BRM is being used. A
zip code entered here must be in Zip+4 format.
Email Address
Enter the To address for the e-mail messages that the installer
will send to submit the registration data.
Reply Address
The value of the Reply Address field is used as the From address
of registration e-mail messages, and any undeliverable mail will
be bounced to this address.
Subject
The contents of the subject field will be used as the subject for
registration e-mail messages, enabling different e-mail subjects
for different products or e-mail destinations.
Table 35-1: Registration Destination Field Description
You may include more than one destination for the user's information. Which destination to be used is determined by the region that is obtained from the user's computer. For
example if you had offices in the United States and France, you could set up a Registration Destination that would send all information to the France location if the user is
located in any of the European regions. Then you would set up another destination so
that information being sent from any other region would go to the U.S. location.
The mailers that can be printed are either a Courtesy Reply Mail or a Business Reply Mail
picture that is built into Installer VISE. In order to have the user able to print out a Business Reply Mail mailer using our picture you must enter the BRM Permit Number, City
and State in the field provided. You must also include the 9-digit ZIP code that matches
the ZIP code included in the Mail To field.
When the user that is registering has chosen to Email their information, the installer will
send the data to the address in the Email Address field. The value of the Reply Address
field is used as the From address, and any undeliverable mail will be bounced to this
address. We recommend using a reply address that will also be returned to you but may
go through a different domain. For example, we use [email protected] for our reply
address.
Creating a
Registration Form
A Form specifies the dialog box presented to the user to obtain registration input. A
Form is made up of a collection of Form Layouts which can be used to localize the form.
For example, you may create one “Registration” form that is made up of three layouts:
English, French, and Japanese. You can also specify a layout that is to be used regardless
of the user's language and region (this is the default).
Create Form
To create a form for on-line registration:
1. Select Forms… from the Archive menu. The Form List will be displayed.
2. Click the New button to create a new form.
35–5
3. The Edit Form dialog will be displayed.
Illustration 35-5: Edit Form dialog
4. Type a name for the form in the name field.
5. Set the Language and Region(s) for the selected layout.
Each form layout can have only one language setting but may have multiple region
settings.
6. Edit the first layout of the form by clicking the Edit Layout button. A blank form
layout is displayed in the Form Layout Editor window.
Illustration 35-6: New Form Layout
7. Add user interface elements such as Static Text, Editable Text, Checkboxes, and
Radio Buttons to your registration form. You can also use variable substitution,
and set variables from Forms. For complete information on constructing forms
see Chapter 34-Installer VISE Forms.
35–6
8. In order for the form to function as a registration form it must contain a button
with a behavior of Register, Print Mailer, Print For Fax or E-Mail.
Illustration 35-7: Button with Register Behavior
The behaviors Print Mailer, Print For Fax and E-Mail perform only one function.
The Register behavior allows a choice to be made from Print Mailer, Print For Fax
and E-Mail when the button is clicked during installation. When a button with
behavior set to Register is clicked during installation, the following dialog will be
displayed allowing the user to pick the registration method.
Illustration 35-8: Registration Method Dialog
For samples of each of the registration methods see:
■
Illustration 35-14: E-mail Registration Sample
■
Illustration 35-15: Print Mailer Registration Sample
■
Illustration 35-16: Print For Fax Registration Sample
9. Define any invisible fields you may want. Invisible fields are displayed on Print For
Fax and in e-mail registrations. Invisible fields may be useful for items like Product Name and Destination fax number.
35–7
10. Set the tab order for user input by selecting Set Tab Order from the Editor menu.
Illustration 35-9: Setting Form Tab Order
Click on the fields in the order of desired entry. When the form enters tab ordering mode, each field will display a number indicating its current tab order. As you
click on a field, it will display the original tab order number followed by the new
tab order number. For example, 2 -> 1 indicates that the field was originally set to
be number two in the tab order but will now be set to be number one in the tab
order. When you have clicked on all fields the form will return to field edit mode.
Tab order is important for smoothing the flow of data entry Tab order can also be
important for invisible fields as tab order determines the order in which fields are
displayed in e-mail registrations and print for fax registrations.
To stop the process of setting tab order without saving any tab order changes, type
Command-period at any point before setting the tab order for the last field.
11. Test your form by selecting Test… from the Editor menu.
12. During test mode you will be able to test button behaviors and to see how items
will be displayed. Note that runtime variable substitution does not occur during a
form test
13. When your form test is complete, type Command-W to close the form layout test.
Below is an example of a finished registration form. Required fields are displayed with a
dark border. Note the use of a variable to default field values. Print for Fax and Email registrations will print all fields on a form, even invisible forms. This form uses an invisible
field which is filled in by variables (%Product% %version%) so that the product name
and version number will print on the mailer but will not be displayed in the form during
35–8
Include Online Registration
installation. The form also has two fields (Company and Serial #) which contain variables set by Xcod.
Illustration 35-10: Finished Registration Form
14. When you have finished your form layout type Command-W to close the Form
Layout Editor and return to the Edit Form dialog
To add localized layouts to the form:
15. If you need your registration form to display differently based upon Language
and/or Region you will need to set up localized layouts for your form. Start by setting the Language and Region for your base layout. This should be the layout that
has been completely designed and tested.
16. Duplicate the completed layout and change the Language and/or Region settings
for the layout.
17. Edit the new layout for the language/region chosen.
Include Online
Registration
There are two ways to include online registration in your built installer. The first involves
settings in Installer Settings. The second involves use of a From Action.
Including Registration by
Installer Settings
To include online registration in your built installer through Installer Settings:
1. From the Archive Menu select Installer Settings….
2. In Installer Settings select the Extras tab.
35–9
3. Check Include Online Registration Module.
Illustration 35-11: Include Online Registration via Installer Settings
4. Choose whether or not to add “Register Now…” to the File menu of your Installer
by selecting Add To File Menu.
5. From the Display Registration popmenu choose when you want the registration
form to be displayed.
Display Registration Option
Description
At Launch Time
The registration form will be displayed when the
installer is first launched.
Before Installing
The registration form will be displayed after the
user clicks install but before files are installed
After Installing
The registration form will be displayed when the
install has been completed
Table 35-2: Display Registration Options
6. From the Registration Form choose which form to use as the registration form.
Including Registration by
Form Action
You can choose to display your registration form by using a Form Action Item rather
than by using the options in Installer Settings.
Registering via Form Actions:
■
Allows the registration form to be displayed during the install process rather
than before or after
■
Allows the registration process to be conditional based upon execute if options
in the Form Action or by package assignment
To set up registration using a Form Action:
1. From the Archive Menu select New Action -> Form.
35–10
2. A Form Action will be added to the Archive Window Item List and the Form
Action window will open.
Illustration 35-12: Form Action
3. Name the Form Action.
4. Set up any Display Form If conditions. The Form Action, and therefore the registration form, can be set to display conditionally according to:
■
Build Directives - determine whether the form action will be included in
the current installer build.
■
Gestalt - determines whether the form action will be executed by the
installer based on a gestalt setting from the end user’s computer.
■
Language - determines whether the form action will be executed by the
installer based upon a the language of the operating system upon which the
installer is run.
■
Region - determines whether the form action will be executed by the
installer based upon a the region of the operating system upon which the
installer is run.
If the registration form is designed with localized layouts and appropriate
Language and/or Region settings, the Form Action’s Language and Region
settings should not be used. The form will display the correct layout based
upon the language and/or region of the operating system upon which the
installer is run.
Use the Form Action’s Language and Region settings when a completely different form
needs to be displayed based upon the language and/or region of the operating system
upon which the installer is run.
■
Action Result - determines whether the form action will be executed by the
installer based upon another action item’s success or failure (including Test
Variable actions) or upon the button selected in a Message action.
35–11
5. From the Display Form Options Form popmenu select the form to be used for
registration.
6. Close and save the Form Action.
7. Make package assignments for the Form Action. The registration form will only
be displayed for packages which include the Form Action.
8. Determine when during the installation you wish the registration form to be displayed and drag the Form Action up or down in the Archive Window to the
desired location.
Illustration 35-13: Registration Form Arrangement
In the example above, the registration form is set to display immediately before
the application is installed. The packages settings indicate that the registration
form will only be displayed for packages which install the application.
35–12
Registration Output
Samples
Registration Output Samples
Online registration can be set to send the user’s registrations by:
■
E-mail
■
Mailer
■
Print For Fax
■
The user’s choice of the above options
E-mail Registration Sample
Illustration 35-14: E-mail Registration Sample
Print Mailer Registration Sample
• If you have purchased Installer VISE or Updater VISE, filling out this form ensures you are
notified of any updates, bug fixes, and news about our products.
• If you have not purchased our products, go ahead and fill out the registration form. We will
use it to notify you by email of new versions of our software. We will not use the information
to call, or otherwise hassle you about our products. If you later decide to purchase our
products, we will already have your information in our database.
N a m e : Paul Welsh
Job
Title: Product Communications
Company: MindVision Software
A d d r e s s 1 : 5901 N. 58th Street
Address2:
C i t y : Lincoln
S t a t e : NE
Zip: 68507-3249
C o u n t r y : USA
Phone: (402) 323-6600
F a x : (402) 323-6611
E M a i l : [email protected]
Serial
#: XXXX000000000
(Leave blank if you have not purchased).
please fold here
PLACE
STAMP
HERE
PRODUCT REGISTRATION
MINDVISION SOFTWARE
5901 NORTH 58TH
LINCOLN NE 68507-3249
please fold here
Tape on bottom edge
Illustration 35-15: Print Mailer Registration Sample
The top portion of the mailer will contain an image of your completed registration form. The mailer address in the center portion is dynamically written based
upon the Registration Destination region(s) setting.
Custom Mailers
35–13
Print for Fax Registration Sample
Please fax to MindVision at: (402) 323-6600
Registration information for: IVISE 7.2
Name: Paul Welsh
Title: Product Communications
Company: MindVision Software
Address1: 5901 N. 58th Street
Address2:
City: Lincoln
State: NE
Zip: 68507-3249
Country: USA
Phone: (402) 323-6600
Fax: (402) 323-6611
EMail: [email protected]
Serial #: XXXX00000000000
Illustration 35-16: Print For Fax Registration Sample
Custom Mailers
You can create your own mailer graphic by first starting with a copy of the standard mailers to ensure alignment and then modifying whatever is necessary. You can find the standard mailers in the Base Installer file in the Installer VISE Extensions folder.
Your pictures will need to include the Mail To information and any other Permit Number
information. After completing the picture, paste it into the VCT file using a resource editor and assign it an ID within the range of 5000-10000. Within the destination dialog
leave the Mail To field blank and put the ID of your picture in the ZIP Code For Bar Code
field.
35–14
Custom Mailers
36–1
Chapter 36
Extended Install Locations
Extended Install
Locations
Several prebuilt locations and Mac OS 8, OS 9 and OS X install locations have been
added to the Install To and Search Location popmenus by adding the following files to
the Install Locations folder: Extra Locations, OS 8.5 Locations, OS 8.6 Locations, OS 9
Locations and OS X Locations.
When Installer VISE is launched, the contents of the Install To and Search Location popmenus are dynamically built from location definition files found in VISE’s Install Locations folder. The Install Locations folder can be found at the same level as Installer VISE
inside the Installer VISE folder. Extending the Install Locations is as simple as adding one
or more extended location definition files to the Install Locations folder.
Illustration 36-1: Default, Extra, OS 8.5, OS 8.6, OS 9 and OS X Install Locations Files
36–2
Extended Install Locations
Installer VISE ships with six location definition files: Default Locations, Extra Locations,
OS 8.5 Locations, OS 8.6 Locations, OS 9 Locations and OS X Locations, all of which can
be found in the Install Locations folder.
Default Locations
■
In the illustration below, the first column from the left shows the locations
made available by the Default Locations file.
Extra Locations
■
When the Extra Locations file is also in the Install Locations folder prior to
Installer VISE startup, the Install To and Search Location popmenus will contain the additional locations shown in the second column. (By default, the forenamed popmenus will display these locations in two different groupings, as
illustrated here.)
OS 8.5, OS 8.6 and OS 9 Locations
■
In the third column, the top illustration shows the additional locations made
available by the OS 8.5 Locations file. The middle illustration shows the two
additional locations made available by the OS 8.6 Locations file, while the bottom illustration shows the locations made available by the OS 9 Locations file.
OS X Locations
■
The fourth column shows the additional locations made available by the OS X
Locations file.
Default Locations
Chapter 36 Extended Install Locations
Extra Locations
OS 8.5/OS 8.6/ OS 9 OS X Locations
Setting Install Locations With Variables
36–3
locations exist, or deselect the Stop Install if “<type of action>” Fails
Setting Install
Locations With
Variables
You can use a special Installer VISE runtime variable to dynamically set install locations
at the time of install. (For this option to be available, the OS X Locations file must be
located in the Install Locations folder.)
Installer VISE makes the variable “InstallVar” available as an install location that can be
selected directly from the “Install To” and “Search Location” popmenus. At install time,
installers will substitute the current value of InstallVar whenever an item uses the variable install location.
To set install locations with variables:
1. Open an existing archive or create a new one.
2. Define the variable InstallVar (use matching case) and set an initial value if
desired. For more information, see Chapter 28-Using Runtime Variables.
3. Add the required files, folders, bundles and action items to the archive.
4. For each action item that should use the value of InstallVar as a search location,
select Variable “InstallVar” from the “Search Location” popmenu. See Chapter
8-Creating Action Items for details.
5. For each install item that should use the value of InstallVar as an install location,
select Variable “InstallVar” from the “Install To” popmenu. See Chapter 12-Setting File and Folder Options for details.
6. In your install logic, set a value for InstallVar before executing an archive item that
will use the variable. You may set the value as many times as needed. Options for
setting the value of InstallVar include a Find action (see “Find Options” on
page 8-18) and a Set Variable action (see “Set Variable Options” on page 8-28).
To function as an install location, the InstallVar variable must contain a
colon-separated full path (which is what a Find action will return). Do not
use a POSIX-based (slash-separated) path to set the value of InstallVar.
Creating Custom
Install Locations
You can create your own custom install locations that can then be selected directly from
the “Install To” and “Search Location” popmenus.
The following are instructions for adding and accessing custom Install Locations. It
involves writing a simple external code and saving the output into a file that Installer
VISE loads on startup. The item(s) that you add will be appended to the “Install To” and
“Search Location” menus in Installer VISE.
The Scripting Additions sample that has been provided is an example of an Install Location External Code (ILXC) code resource project. It looks for a file with a specific type
and creator and then reads a resource from that file. From that resource it gets the name
of a folder and the code gets the vRefNum and DirID of that folder which then becomes
the install location. External code can do almost anything, including bringing up dialogs,
as long as it returns the vRefNum and DirID of the folder that you want the file(s)
36–4
Creating Custom Install Locations
installed into. All external code is processed before any of the installation begins so that
any questions can be asked up front instead of in the middle of an installation.
Creating custom install locations for Carbon installers requires the use
of ILCC code resources, while non-Carbon installers require ILXC
resources. Therefore, when following these instructions for a Carbon
installer, use resource type ILCC instead of type ILXC.
Getting Started
1. Resorcerer users - Copy the MV Templates file into your Resorcerer:Private Templates folder.
2. ResEdit users - Copy the TMPL resources from the ResEdit MV Templates and
paste them in your new file or in your ResEdit application or open the ResEdit MV
Templates along with your new file.
3. Create a resource file in the Install Locations folder of type ILOC and creator VIs5.
Adding a Separator to the
“Install To” Popmenu
To add a separator to the popmenu:
1. Open your file with the resource editor of your choice.
2. Create a resource of type INL# (or add another item to an INL# list resource).
3. Edit the INL# resource item and set the Find Code to a 4 character code such as
'sepA', 'sepB', etc.
4. Set the Flags field to “Internal Location” (4).
5. Set the Menu Item Name to “-”.
6. Save the changes.
Creating an Install
Location External Code
To create an install location external code:
1. Build the code resource into your output file.
2. Copy all resources from your output file into the file you created in the Install
Locations folder.
3. Create a 16 x 16 cicn resource to represent your location (optional).
5. Edit the INL# resource item and set the Find Code to a 4 character code that will
be unique when combined with all INL# resources in all files in the Install Locations folder.
6. Set the “Create If Not Found” field to 1 if you want to create the folder if it isn't
found.
7. Set the Flags field to “Call External Code” (2).
8. Assign a Menu Item Name.
9. Set the ILXC ID field to the same ID as your ILXC resource.
10. Set the Icon ID field to the ID of the cicn you created (optional).
11. List any supporting resources with a TYPE and ID.
12. Save the changes and close the file.
Important Notes
36–5
13. Launch Installer VISE and open your VCT file.
14. Your new item should be available from the “Install To” pop menu.
Adding Install Location
Items with 4 Character
Codes
To add an install location that uses a four character code to call FindFolder:
2. Create a 16 x 16 cicn resource to represent the location (Optional).
4. Edit the INL# resource item and set the Find Code to a 4 character code that
“FindFolder” will accept.
5. Set the “Create If Not Found” field to 1 if you want to create the folder if it isn't
found.
6. Set the Flags field to “Real Find Folder” (1).
7. Assign a Menu Item Name.
8. Set the Icon ID field to the ID of the cicn you created (optional).
11. Your new item should be available from the “Install To” pop menu.
Editing an Existing Install To edit an existing install location:
Location Item from an INL#
Resource
2. Edit the INL# resource item and increment the Version field.
3. Modify either the cicn resource, the ILXC resource, the supporting resources, and/
or the INL# item.
6. The resource changes will be saved in the VCT file when the VCT file is saved.
Important Notes
All the resources in the Install Location files will end up being in each VCT file that you
edit with Installer VISE.
The method that is used when opening a VCT file is:
1. Check to see if an INL# resource exists in the VCT file.
2. If it does NOT exist it uses the data that it retrieved from the Install Location files.
3. If it does exist then it goes through each item in the INL# resource and compares
the Find Code with the Find Codes of the items in the INL# resources in the
Install Location files looking for matches. If it finds a matching code that has a
higher version number, then that new item replaces an existing one. The new item
will be in the same location in the menu as the previous one. If it finds a new item
that isn't already in the VCT file's INL# resource, the item is appended to the INL#
resource.
36–6
Important Notes
Do not modify or rearrange the items in the INL# resource within any
VCT file or within the Default Locations file. Installer VISE assumes the
first 71 items are in a particular location in the menu. Each file within a
VCT file points to their Install To location by an index into the list/
menu.
Once a VCT file has been saved with the Install To locations in a particular order, those
items will be in that VCT file in the same order even if you remove or add any Install
Location files.
The 4 character FindFolder codes that are currently reserved are:
Code
Location
IFld
Install Folder
sep1
(separator)
SFil
System File
Othr
Other
sep2
(separator)
AskU
Ask User
FAct
Find Action Result
BtRt
sep3
(separator)
macs
System Folder
extn
Extensions
ctrl
Control Panels
pref
Preferences
amnu
Apple Menu Items
desk
Desktop
strt
Startup Items
temp
Temporary Items
prnt
Print Monitor
font
Fonts Folder
shdf
ShutDown Items
sdev
Control Strip Modules Folder
extD
Extensions (Disabled)
ctrD
Control Panels (Disabled)
Table 36-1: Four-Character FindFolder Reserved Codes
Important Notes
36–7
AskU
Ask User
FAct
Find Action Result
BtRt
sep3
(separator)
macs
System Folder
extn
Extensions
ctrl
Control Panels
pref
Preferences
amnu
Apple Menu Items
desk
Desktop
strt
Startup Items
temp
Temporary Items
prnt
Print Monitor
font
Fonts Folder
shdf
ShutDown Items
sdev
Control Strip Modules Folder
extD
Extensions (Disabled)
ctrD
Control Panels (Disabled)
36–8
Important Notes
Code
Location
odod
OpenDoc
odsp
OpenDoc Shell Plug-Ins
odlb
OpenDoc Libraries
odst
Stationery
ƒmod
Modem Scripts
ppdf
Printer Descriptions
asup
Application Support
strD
Startup Items (Disabled)
shdD
Shutdown Items (Disabled)
cmnu
Contextual Menu Items
sep5
(separator)
appr
Appearance
aexƒ
Apple Extras
apps
Applications
astƒ
Assistants
flnt
Cleanup At Startup
prof
ColorSync Profiles
dtpƒ
Desktop Pictures
docs
Documents
favs
Favorites
fnds
Find
fasf
Folder Action Scripts
ilgf
Installer Logs
intƒ
Internet
issf
Internet Search Sites
laun
Launcher Items
morƒ
Mac OS Read Me Files
rapp
Recent Applications
rdoc
Recent Documents
rsvr
Recent Servers
Important Notes
36–9
Code
Location
scrƒ
Scripts
snds
Sound Sets
spki
Speakable Items
fbcf
TheFindByContentFolder
thme
Theme Files
utiƒ
Utilities
walk
Location Manager Modules
trip
Location Manager Prefs
fall
Locations
qtex
QuickTime Extensions
fbcp
Find by Content Plug-ins
ƒloc
Language & Region Support
sep6
(separator)
dspl
Display Extensions
kchn
Keychains
mpxf
Multiprocessing
sdat
Shared Documents
sctl
System Control Panels
sdsk
System Desktop Folder
sprf
System Preferences
strs
System Trash
vsfd
The Volume Settings Folder
usrs
Users
sep7
(separator)
cach
Caches
carb
Carbon
sync
ColorSync
ccmm
ColorSync CMMs
cscr
ColorSync Scripting
cmpd
Components
36–10
Important Notes
Code
Location
csrv
Core Services
devf
Developer
ddoc
Developer Docs
devh
Developer Help
info
Documentation
issd
Downloads
fram
Frameworks
dlib
Library
impr
Printers
pfrm
Private Frameworks
wcmp
QuickTime Components
rotf
Root Folder
ssnd
Sounds
spch
Speech
dtop
Top Level Folder
utmp
User Temporary Folder
InPV
Variable "InstallVar"
37–1
Chapter 37
Active Web Installers
Your users will greatly benefit from technical breakthroughs that seamlessly address data
transfer rate, interrupted connections, and various hardware configurations for a convenient, trouble-free download and installation over the Web. End users frequently do not
need all the files contained in an installer. Previously, on-line users faced an often-daunting task of either downloading complete installers or choosing just the right installer for
their system. MindVision’s Active Web Installer technology simplifies the user experience
by first downloading a small installer which can retrieve just the pieces needed for the
user’s specific requirements.
Users will benefit from reduced download times, reduced risk of download glitches, and
the most up-to-date software available. Developers will benefit from reduced server
loads, as well as an increase in customer satisfaction with the downloading and installation experience. In addition, MindVision’s technology provides developers with unprecedented flexibility in choosing when to offer updates and enhancements to on-line users.
The Active Web Install technology automatically handles interrupted connections and
corrupted files. When a connection is interrupted, previously downloaded files will
remain intact on the end user’s system and the remains of the active file being downloaded at the time of the interruption will automatically be removed. When the end user
reconnects, the download will continue with the interrupted file and finish downloading
the remaining files.
MindVision’s Active Web Install features include:
Active Web Installer
Setup
■
Grouping and packaging of files to create the smallest-possible data sets for
downloading
■
Storing the downloaded data into the installer application for future installs
■
Various settings to easily handle the creation of an Internet-ready installer for
the Web
An Active Web Installer differs from any other installer you might create in only a few
ways. In addition to the normal setup items such as package setup and assignment,
action item creation, splash screen and billboard creation, an Active Web installer needs
37–2
Active Web Installer Setup
information about the way that files will be stored, called File Groups, and where on the
web the installer can obtain file groups, called Download Sites.
Active web installers require a web server which supports HTTP 1.0 or
greater.
Overview
Overview of steps necessary to create an Active Web Installer:
■
Set Web Installer specific Installer Settings.
■
Create a Web Install Build Target.
■
Set up File Groups and assign files to file groups.
■
Set up Download Sites.
■
Build the installer.
■
Place the File Group files at the designated web sites.
In the following pages we will go into more detail on each step needed to create an Active
Web Installer.
Creating a Web Install build
target
Build Targets are a part of Installer VISE’s advanced project management features. Build
Targets allow the developer to set up one archive which will be used to produce multiple
installers. It is not uncommon to need a Web Installer, a CD installer and a Single File
installer produced from the same archive. Build Targets make setting up and building
multiple installers easy. For a full description of Build Targets, see Chapter 27-Advanced
Project Management. Installer Settings has a number of special options specifically for
Web Installers.
To create an Installer Setting for a Web Installer:
1. From the Archive menu select Installer Settings…
Illustration 37-1: Archive menu, Installer Settings…
Chapter 37 Active Web Installers
37–3
2. Go to the Installer Settings Web tab. and check the options you would like for your
web installer.
Illustration 37-2: Installer Settings Web tab
See the table below for a description of each option.
Option
Description
Create Separate Catalog
When checked, a separate catalog file will be
created. This catalog enables the web installer
to self update when appropriate.
Store Installer Data in External
File
When turned on, the compressed data for the
installer will be put in a data file, instead of
the data fork of the installer application.
Data File Name
Name of the file to store the compressed data
in for the installation. This file is to be placed
in the same location as the installer.
Strict Installer Data Time Stamp
Checking
When turned on, the built installer will
require the time stamp of the installer and the
time stamp of the VISEICat.idx file on the
Web/FTP server to be the same. This will
require the VISEICat.idx file to be uploaded
to the Web/FTP site every time you build.
37–4
Option
Description
Upload Cab File(s) To Web Server
At Build Time (FTP Sites Only)
When turned on, Installer VISE will upload
CAB files to the FTP servers listed in the
Download Sites dialog. (Do not use this
feature if you have HTTP servers listed in the
Download Sites dialog.) This feature requires
the servers to have FTP “STOR” command
support.
Suppress Internet Dialup Dialog
installer from displaying the “Please make
sure you have an active Internet connection”
dialog to the user. You may want to turn this
on if you are assured the user will already have
an active connection.
Allow User To Choose Download
Site
When turned on, a popmenu will appear in
the “Please make sure you have an active
Internet connection” dialog, allowing the user
to choose which site to download the data
from.
Suppress Internet Disconnect
Dialog
installer from displaying the “Disconnect
from the Internet now” dialog to the user.
Byte Range Downloads
When turned on, Installer VISE will create a
single CAB file instead of using Group File
assignments. This feature allows for the
smallest and quickest downloads possible. It
also requires the web servers to be HTTP 1.1
compliant or have FTP “REST” support.
37–5
3. From the popmenu at the bottom left of the Installer Settings window, select Save
Settings As…
Illustration 37-3: Save Installer Settings
4. Enter a name for the saved Installer Setting and click the Create button.
Illustration 37-4: Installer Setting Name
5. Close Installer Settings.
To create a Build Target for a Web Installer:
1. With an archive open, select Show Project Window from the Archive menu.
37–6
2. In the Project Window, click on the Targets heading.
Illustration 37-5: Project Window
3. Click the Add button at the top of the Project window to create a new build target.
The Build Target window is where you determine the type of installer you will be
building along with where that installer will be saved to and what, if any, post processing should occur.
4. In the Build Target window, type in a Name for the build target and select Web
Installer from the Format popmenu.
Illustration 37-6: Build Target set to Web Install
5. Clicking Create Debug Installer will add the Debug Window to the Web Installer
you build. The Debug Window can be helpful when testing installers. You may
want to set up a build target for creating a debug web installer and another build
target for creating a non-debug or release installer.
37–7
6. From the Settings popmenu, select the Installer Settings set you created specifically for your web installer. Whenever this target is built, it will use that Installer
Settings set.
Illustration 37-7: Selecting an Installer Settings for the Build Target
7. Click Edit Path if you would like the Web Installer to be built to a location other
than the default.
8. Click OK to save your changes to the build target.
9. Click just left of the folder icon for the newly created build target to make it the
active build target. A bullet appears next to the My App Web Installer build target.
Uncheck the Default Target built target. Only checked build targets will be built
when the build command is executed.
Illustration 37-8: Project Window with new Web Installer Build Target
37–8
Duplicating a build target
There may be times when you want to duplicate a build target. For example, you could
duplicate a complex build target and make just one change to the copy so that it creates a
debug installer.
To duplicate a build target:
1. Click on the target name to highlight it.
2. Hold down the Option key and click Add.
Creating File Groups
After creating a web installer Build Target, you will need to create and assign files to File
Groups.
If you have checked Byte Range Downloads in the Installer Settings web
tab File Group settings are ignored and only one CAB file is built by the
web installer. During the download portion of the install, the installer
pulls only the necessary items from the single CAB file. Byte Range Downloads requires a web server which is HTTP 1.1 compliant or which supports FTP
“REST”.
To create a File Group:
1. From the Internet menu, select File Groups.
2. In the File Group List window click New.
3. In the Edit Group Name window, type in a group name and a file name for the
group file.
Illustration 37-9: Edit File Group Name
When the installer is built, file group files will also be created for placing on a web
server. Group names should be descriptive to both the developer and the end user
as the group name is used when assigning files to a group and is visible when file
groups are being downloaded at install time.
It is important to segment installers into file groups so that end users will be able
to download only the files necessary to complete the install options they have chosen.
When naming your file groups be aware of limitations of the web server
where these file group files will reside. Some systems do not allow filenames containing spaces or slashes.
37–9
4. After creating all file groups you will be using, click OK to dismiss the File Group
List.
Illustration 37-10: File Group List
Assigning files to File Groups Files and folders are assigned to file groups in the same way that any other installer properties are assigned.
To assign files and folders to file groups:
1. Add the File Group item to an Archive Window layout.
For more information on adding fields to the Archive Window detail see Chapter
26-Customizing the Archive Window.
2. Select the item in the item list and select the desired File Group from the Group
popmenu in the Archive Window detail.
Illustration 37-11: Assigning files to file groups
If a folder is selected, then all items within that folder will be assigned to the file
group.
37–10
If a folder is selected in the Archive Window and it is set to Individual File. all files
within that folder will be set to Individual File. When the web installer is built the
folder will be created with individual group files for every file in the folder. When
the installer is run by an end user, it will look for that folder on the web server’s
Initial Directory. The installer will then try downloading the file from that directory.
If In Installer is checked for a file, that item’s compressed data will be included in
the installer file itself and will not be downloaded as part of a file group.
3. File Groups can also be assigned from an item’s Get Info window.
Illustration 37-12: Setting File Group in an item’s Get Info window
The Group item in the Get Info window changes to Disk when the current
build target is not set to Web Installer.
Designating Download
Sites
Within Installer VISE, download sites are predetermined web addresses where the built
web installer can retrieve file groups. You may set up multiple download sites. When an
end user runs an installer, a download site will be selected at random unless Allow User
to Choose Download Site is checked in Installer Settings.
To set up Internet download sites:
1. From the Internet menu select Download Sites.
2. In the Internet Site List click the New button.
37–11
3. In the Edit Internet Site window enter a Name, a Server Address, and Initial Directory.
Illustration 37-13: Edit Download Site
In the example above, the server at address http://www.server.westcoast.com contains a directory named WestcoastSoftware that contains a sub-directory named
MyApp which contains the File Group files created when the installer was built.
HTTP and FTP Server Notes
4. Set the Server Kind.
■
When choosing FTP, a user name and password must be entered even if
“anonymous” is used for the user name and an email address is used for the
password.
■
HTTP 1.1 servers and FTP servers can benefit by using byte range downloads (enabled from Installer Settings Web tab). Byte range downloads
enable Installer VISE to disregard the file group settings and produce one
large cab file for placement on the server. During the installation, the web
installer gets just the part it needs from within the cab file without needing
to download an entire file group file. This feature requires the web servers
to be HTTP 1.1 compliant or have FTP “REST” command support. For
more information, see “Byte Range Downloads” on page 14-30.
When entering Server Address, do not preceed with “http://”. The http
protocol declaration will be added by the web installer prior to searching
for the server at the address specified in the Server Address field.
5. After creating all download sites you will be using, click OK to dismiss the Internet Sites List
Creating a Separate Catalog
A catalog for a web installer contains a list of items to process during the install, including files, action items, packages, etc. Every web installer has an internal catalog. You can
also create an external catalog to put on the web site with the file groups. When the
installer is run by the end user, the date/time stamp within the installer is compared to
that stored in the VISEICat.idx file on the server. If the date/time of the catalog on the
server is newer than the installer’s internal catalog, a new installer will be downloaded.
This allows you to update your installer code, and subsequently, update your product so
the latest version of your software is available for download.
37–12
This feature is automatically enabled for active web installers that use a separate catalog
to store install information on the web server. When appropriate, Installer VISE will use
this catalog to create a new installer for downloading.
For an initial release installer, a separate web catalog is not necessary. If files have been
updated or modified, a separate catalog will be necessary for installers to access the new
data.
To create a separate catalog for a web installer:
1. Open Installer Settings from the Archive menu.
2. Select the Web tab in the Installer Settings window.
3. Check the Create Separate Catalog checkbox.
4. Build the installer. The following items will be created:
■
The installer application
■
File group files for every file group with files assigned to it
■
A VISEICat catalog containing the installer catalog
■
A VISEICat.idx containing the installer date/time stamp
5. Copy the catalog files and the file group files to the web server in the directory
indicated in the download site.
Illustration 37-14: File Group and Catalog files placed on web server
6. If there are multiple download sites, repeat step 5 for each site unless Upload Cab
File(s) To Web Server At Build Time (FTP Sites Only) is checked in Installer Settings web tab in which case cab files will be automatically uploaded to the server at
installer built time.
Verify Files on Server
After you have built your web installer and have the cab file(s) in place on the server you
can have Installer VISE verify the files on the server.
The User’s Initial Experience
37–13
To verify files on the server:
1. From the Internet menu select Verify Files on Server.
Illustration 37-15: Verify Files on Server
The User’s Initial
Experience
When your users use the web installer you’ve just delivered, they should have an install
experience very similar to that of a single-file installer. The installer file application can
be delivered on CD or downloaded from the web. When the end user double-clicks the
installer, they are presented with the usual installer items. Splash screen, packages, interface type, and Install Location options are the same as those presented from a single-file
installer with the exception of a Continue button rather than an Install button. Clicking
the Continue button takes the user to a download preparation window.
Illustration 37-16: Active Installer Install Window
37–14
Before downloading files the user is instructed to initiate a connection to the Internet. By
checking the Use Proxy checkbox, the user can enter proxy server and port information.
Illustration 37-17: Preparation to Download Files
The installer first tries to locate the server and check for the existence of a catalog newer
than that within the installer.
Illustration 37-18: Catalog check during Install
37–15
Following the catalog check, the installer immediately begins downloading the file
groups necessary to install the items indicated by the user’s package selection. Only the
necessary file groups are downloaded and incorporated into the installer.
Illustration 37-19: Downloading file groups within the Installer
When all necessary file groups have been downloaded, the user is told that they may disconnect from their Internet connection.
Illustration 37-20: Download complete message
If the user clicks Cancel, the active installer will quit. All items that were downloaded are
now incorporated into the active installer for future install sessions.
37–16
The User’s Subsequent Experiences
If the user clicks Continue, the installation will proceed as if it were a single-file installer.
Illustration 37-21: Installation progress
The User’s Subsequent
Experiences
After a web installer downloads the necessary file groups, they are incorporated into the
installer and do not need to be downloaded again unless they have changed.
When the user to runs the web installer again with the same package selection, the following message will be displayed.
Illustration 37-22: Message-Installer has all necessary files
If the Install button is clicked the initial installation will be repeated. If the Update button is clicked, the user is asked to initiate an Internet connection.
The installer then checks the data on the web server. If the data in the user’s installer is
the same as that on the server the following message is displayed.
Illustration 37-23: No download necessary
If the catalog on the server indicates that the data in the user’s installer is older than that
on the server, a new installer is downloaded, and the user can continue with the updated
install.
38–1
Chapter 38
USB Installers
USB Installers
One advantage of Universal Serial Bus (USB) devices is true plug-and-play performance.
When a user plugs in a USB device, the Macintosh USB system software will dynamically
load the appropriate USB device drivers (system extensions). If the required device driver
is not present on the system, the Mac USB system software will display a dialog that lets
the user choose to download a driver. When the user chooses to get the driver, the system
software will:
■
Download the appropriate USB installer from a URL specified by the developer.
■
Launch the installer, which performs a “faceless” install.
Beginning with version 7.1, Installer VISE can build USB installers.
Creating USB drivers
Before the Mac USB system software will recognize and download your device driver,
you must follow certain procedures set by Apple. These procedures are explained in the
USB developer kit and other documentation available through the Apple web site.
Building USB installers
At the most basic level, the USB archive would simply include the USB driver, set to
install to the Extensions folder. For more advanced install needs, USB installers can also
deliver other accessory files.
To build a USB installer:
1. Create a new installer archive.
2. Add the USB driver to your archive.
3. Click on the driver to select it.
38–2
USB Installers
4. From the archive window, click on Install To and select Extensions Folder.
Illustration 38-1: Install To popup menu
5. Add any secondary files to the archive, and select their install locations.
6. From the Archive menu, select Show Project Window.
7. In the Target window, click on a target to select it.
8. Click the Edit button.
Illustration 38-2: Project window, Edit Target button
9. In the Attributes tab of the Target window, click on the Platform popmenu.
Chapter 38 USB Installers
USB Installers
38–3
10. Select USB Installer.
Illustration 38-3: Build Target set to USB Installer
11. Click OK.
12. Be sure to select the USB target as your active Build Target, as illustrated below.
Illustration 38-4: Project window with one Build Target checked
13. From the File menu, select Build Installer...
When building the USB installer, Installer VISE will check the archive for a valid USB
driver. If the driver is missing, the build will not continue.
During a build, Installer VISE will bypass the following installer functions:
■
Password settings
■
Extra languages for multi-language support
■
Forms
■
Read Me files
■
License agreements
38–4
USB Installers
■
Splash screens
■
eSellerate functionality
■
Sub-archive packages
■
Progress dialogs
■
Billboards
The end result will be a single-segment installer.
Chapter 38 USB Installers
Section 5
Special Topics
39–1
Chapter 39
Frequently Asked Questions
Creating Uncompressed
Files
Can the installer store a file uncompressed in a disk image or folder without
checksumming it while installing it?
Yes. To store an uncompressed file in the installer set:
1. In the archive window, select the item you wish to store uncompressed.
2. Hold down the mouse over the Disk pop-up menu and select the disk image or
folder where you want the uncompressed file to be stored.
For more information, see Chapter 12-Setting File and Folder Options.
Adding Help to an Installer How can I include help text for the end user in an installer?
Adding a PICT with resource ID 5000 to the resource fork of the archive makes the Help
button visible in any installer created from the archive. When the user clicks the Help
button, the PICT whose resource ID is 5000 will be displayed, followed by the PICT
whose resource ID is 5001, and so on. The IDs of the consecutive help PICTs must
increase by an increment of one.
To add help materials to an installer:
1. Create a series of PICTs containing the information that you wish to display when
the user clicks the Help button.
Make sure that all PICTs are the same size. The size of the window in which the
help PICTs will be displayed is based on the size of the first PICT, so if the other
PICTs are larger, portions will be cut off.
2. Add the PICTs to the resource fork of the archive, making sure that the first help
PICT has a resource ID of 5000, the second has a resource ID of 5001, and so on.
Installation to System
Why can’t the installer install files to the System Folder of a remote volume?
Folders of Remote Volumes Because we use FindFolder to find the System Folder on a volume, and FindFolder
returns an error on a remote volume.
39–2
Bring Up To Date
I did a Bring Up To Date, and all my files are reported as missing! What happened?
The archive has become out of sync with the original files/folders. This may be because
you have moved them at the Finder, renamed some items (either at the Finder or within
the archive), or changed file/folder heirarchy (either at the Finder or within the archive).
The cure is quite simple. Choose Validate Paths from the Archive menu. You will be
asked for the location of the "missing" archive items. Thankfully, it is smart enough to
infer subsequent items, so you won't have to locate every single item within your archive.
After validating paths, do Bring Up To Date again.
Installer Disk Space
Requirements
Why is the amount of disk space required in the installer bigger than what is
actually in the archive?
Because we calculate the disk space required based on the allocation block size of the destination (or currently selected) volume. This is done for both the data and resource forks
of each file to be installed.
Package Sizes
Why is the package size information displayed in the Custom Install window
smaller than what is displayed in the installer window if you select the same
package?
Because the package size is just an accumulation of bytes for that package, and the
installer window takes into account the allocation block size of the currently selected volume.
Canceling an Install
What happens when the customer cancels the install, or when an error occurs?
If the installer was set to replace existing files on the customer’s system, the files are
moved to a temporary folder while the new items are installed. If the user chooses to cancel the installation or an error occurs, the original files are moved back from the temporary folder into their original location. If the installer was not set to replace existing files,
then the files that were installed are simply removed.
However, certain actions performed by an installer can not be reversed; for example, if
the customer cancels the installation after a Delete action item is performed, then the
item can’t be retrieved. For this reason, you may wish to consider the use and placement
of such items in your archive.
Forcing a Restart
If an INIT doesn’t get installed but the supporting files for the INIT are new, how
can I force the Installer to bring up the restart message so the INIT can look at
the new files?
There are two ways to do this:
Handling Fat Files
■
Assign the supporting files to a package that has the Restart after Installing flag
turned on.
■
Select the Restart After Installing checkbox for that support file in the file’s Get
Info window or in the Archive Window detail area.
How does the Package Type pop-up menu work in the Edit Package Dialog?
This only applies to Custom Installs and Fat binary files.
If the pop-up menu is set to Use Files’ Setting, the install will look at the Install Fat
Binary On pop-up menu in the Files’ Get Info Window.
Chapter 39 Frequently Asked Questions
39–3
When a package is checked by the end user, the installer goes through all files to see what
files belong to that package. When it finds one, it looks at what type of package it is, and
sets a flag for that file accordingly. For example, if it’s a 68K Package, it will set the flag to
install only the 68K portion of the file. If it’s a PPC Package, it will set the flag to install
only the PPC portion of the file. If it’s a Fat Package, it will set both of the above flags.
Version Checking
Does the installer do version checking?
Yes, Installer VISE provides numerous ways to perform version checking, which include:
■
The installer can compare versions when it determines whether to replace a file
or folder with a different version.
■
Action items that do searches (Find, Delete, Copy, Move, Rename, Alias, Sublaunch and Edit Text File) can check version as part of their Search Criteria.
Checking for Cancellations Is there a way for the After Install to know if the user canceled or if there was an
error?
and Errors
You can check the canceled bit in the eInfo->flags (i.e.. eInfo->flags & kCancelInstall)
Creating an "Installation
Folder”
The items in my archive are from several different locations on my own computer and on our local network, so there isn’t a single folder at the root of my
archive containing all the files. Can Installer VISE create an “installation folder”
that will be created on the customer’s system and store all the materials that get
installed?
Yes. To create an “installation folder,” see the section Creating an Installation Folder in
Chapter 14-Choosing Installation Destinations.
When the installer is run, all the items that are installed will be placed in a folder with the
same name that you entered in the Edit Installation Folder… dialog.
Installer VISE makes it easy to track item locations because each archive item stores a
path to its source. In the archive, folders can be created within the archive, files can be
added to the folders and the hierarchy within the archive can be changed without necessitating a change in the source file’s location or hierarchy. Each item knows where its
source is regardless of its arrangement within the archive. The structure within the VCT
does not need to match the Finder structure of the source files.
Install To Location
Can the install locations be specified more precisely? I have a folder inside the
Preferences folder called 'MyPrefs'. Can I install files in that folder? Can I delete
a specific file in that folder?
This can be done fairly easily. Include a MyPrefs folder in your archive and have this
folder set to be installed to the Preferences folder. If the folder already exists, it will not be
replaced. You can place your files in this folder and have them set to be installed to the
Install Folder. You can also put a delete action item in this folder and have its search location set to Current Folder.
39–4
Skipping File Replacement I frequently build CD-ROM installation sets and decompress the files to my hard
drive. If I've already decompressed the files once, I'm asked whether I want to
in CD-ROM Install Sets
replace items individually; replace all the items; or skip the individual item.
What I really want to do is just skip decompressing all items that already exist in
the location. Is there a way to do this?
Yes, there is. When the dialog box asking about replacement options is displayed, hold
down the Option key. The Skip button will change to Skip All. If you click the Skip All
button, each item to be decompressed that already exists in the location will be skipped,
and you won't be asked again.
Replacing the VISE
Installer Icon
How can I replace the VISE installer icon with my own installer icon?
Within Installer VISE, you can use the Installer Icon section of the Installer Settings/
Attributes tab to attach a custom icon to the installer.
Chapter 39 Frequently Asked Questions
40–1
Chapter 40
Shortcuts and Keyboard Commands
Archive Window
Keyboard Shortcuts
The following table lists keyboard shortcuts for navigating and selecting files within the
Archive Window.
Desired Action
Keyboard Shortcut
Select first item in archive window
item list
Command-up arrow
Select first item in archive window
item list
Command-down arrow
Collapse folder
Command-left arrow
Expand folder
Command right arrow
Expand all items in a folder
Option-click the triangle next to name
of folder or Option Command right
arrow
Select multiple items that are not next
to each other in the archive
(discontinuous selection)
Command-click
Select multiple items in a group
(contiguous selection)
Shift-click
Arrange multiple items in the archive
window at once
Shift-click on multiple items and drag
them to a new location
Select next item
Down arrow
Select previous item
Up arrow
Scroll up one page
Page up
Table 40-1: Archive Window Keyboard Shortcuts (Sheet 1 of 2)
40–2
Extended Add Dialog Keyboard Shortcuts
Desired Action
Keyboard Shortcut
Scroll down one page
Page down
Scroll to top
Home key
Scroll to bottom
End key
Open the default folder settings
dialog for that folder.
Double-click on a folder while holding
down the ’D’ key or the ’d’ key.
Table 40-1: Archive Window Keyboard Shortcuts (Sheet 2 of 2)
Extended Add Dialog
Keyboard Shortcuts
The following table lists keyboard shortcuts for navigating and selecting files within the
Archive Window
Desired Action
Keyboard Shortcut
Expand directory
Command-right arrow
Collapse directory
Command-left arrow
Select file by name
Type first characters of name until it
appears selected
Select next item alphabetically
Tab
Select previous item alphabetically
Shift-Tab
Select next drive
Command-shift-right arrow
Select previous drive
Command-shift-left arrow
Expand/collapse directory
Return
Toggle checkbox on/off
Command-down arrow
Add files to archive (same as Add
button)
Enter
Close Add dialog box (same as Done
button)
Escape, or Command-W, or
Command-.
Table 40-2: Extended Add Dialog Keyboard Shortcuts
Drag and Drop
Shortcuts
The following Drag and Drop shortcuts can be used in Installer VISE:
■
When you drag a file from the Finder into a folder in the archive (other than the
root folder), the item will inherit the package settings of its parent folder in the
archive. For example, if you have an Applications folder in the archive that’s
assigned to the Applications package, dragging a new application into the
Applications folder will automatically cause the application to be assigned to
the Applications package.
■
Dragging an item from the Finder into an Action Item Search Criteria will
assign that file's attributes.
■
Dragging an item from the archive window onto an Action Item window
Chapter 40 Shortcuts and Keyboard Commands
Changing Multiple File Attributes Shortcuts
40–3
(except message action) will assign the attributes of the file.
■
Changing Multiple File
Attributes Shortcuts
Dragging a file onto the Installer Settings/Attributes tab, Installer icon area will
copy the icons from that file and use them for the custom icon for the installer.
To change the attributes of several files in the archive at the same time:
1. Select all the files you wish to change.
2. Hold down the Option key while you click Get Info. A blank Get Info window will
be displayed. Any information that you change in this window will be applied to
all the selected files.
40–4
Chapter 40 Shortcuts and Keyboard Commands
Changing Multiple File Attributes Shortcuts
Index–1
A
B
C
D
E
F
G
H
I
J
K
L
M
N
O
P
Q
R
S T
U V W
X Y
Z
Index
Symbols
$1 UNIX parameter 32-23 to 32-24
$2 UNIX parameter 32-23, 32-25
%%
See Variables, percent symbol in 28-7
%InstallVar%
install location variable 28-7, 36-3
%ShellVar%
shell script variable 28-7, 32-23, 32-25
%VariableName%
registration example 35-7
See Variables, declaration of 28-3
.icns files 14-20
^0 in Alias Name Field
See Alias Name 8-24
A
Action items
about 8-1
and runtime variables 28-6
build directives 8-4
replace options 8-43
search criteria 8-11
search locations 8-9
Action Items Ignore Hidden Items 14-19
Activate (AppleScript) 30-4, 31-1
Active Build Target 27-21
Active System Folder 14-17
See Web Installers 37-1
Add 12-24
Add Dialog
changing preference 6-2
extended 6-3
standard 6-2
Add File... button 23-4
Add to File Menu 14-14
Add to OS X Dock 8-24
Advanced Project Management
action item build directives 8-4
After Install 14-28
After Main Installer 14-36
Alias Location 8-24
Alias Name 8-24
Alias Options 8-23
Alias Parent of Found Item 8-24
All Disks
search location 8-9
Allow Installation To Mounted Servers 14-17
Allow Installation to UFS Volumes 14-18
Allow Installer Resources To Be Replaced 14-28
Allow Only Single Selections In Custom Install 14-9
Allow User To Choose Download Site 14-30, 37-4
Allow User To Choose Invisible Folders (Carbon only) 1418
Always
replace options 8-43
Always Create Moved Items Folder 14-19
Always Replace
log file options 14-14
Always Set Install To Install Folder 12-25
Any Match
for action item build directives 7-22, 8-5, 12-14
Index–2
A
B
C
D
E
F
G
H
I
J
K
Appearance 36-8
Append to Existing
Apple Extras 36-8
Apple Menu Items 36-6 to 36-7
AppleScript
controlling an installer 31-1
in installers 30-4
AppleScript Commands
Activate 30-4, 31-1
BringUpToDate 30-4
Build 30-9
BuildDirectiveOff 30-8
BuildDirectiveOn 30-8
BuildTargetOff 30-9
BuildTargetOn 30-8
BUTDValidatePaths 30-5
CloseWindow 30-4
Deselect 31-2
DoAutoInstall 31-2
DoInstall 31-2
Extract Item 30-7
Open 30-4
RemoveCompressedData 30-12
SaveArchive 30-4
Select 31-2
SelectDrive 31-3 to 31-4
SetAssignPackagesFlag 30-5
SetBillboardMode 30-7
SetBuildTarget 30-7
SetDisk 30-11
SetDownloadSite 30-10
SetInstall 31-1
SetIntelligentUpdateFlag 30-5
SetLocalizationFile 30-10
SetVariable 30-10
Update 30-6
UpdateAll 30-6
UpdateDriveList 31-3
UpdateOne 30-6
UpdateOneFile 30-7
ValidateUpdateFile 30-10
Application Bundle
defining bundle filename extensions 12-22
Application Package 8-16, 12-21, 26-7
Application Packages
how to create 12-20
Application Support 36-8
Applications 36-8
fat binary install options 12-16
localizing on-the-fly 29-24
shutting down before installing 14-16
L
M
N
O
P
Q
R
S T
U V W
X Y
Z
Applications folder
as default install location 14-7
Archive Links 27-22
Archive Reports 16-1, 16-3
output options 16-4
to printer 16-4
to screen 16-4
to text file 16-4
Archive Window
and file/folder options 12-2
editable columns 26-7
item detail 26-2
item list 26-2
keyboard shortcuts 40-1
layout 26-1
list columns 26-2
shortcuts 26-8
vertical column titles 26-2, 26-8
Archives
about 6-1
adding files 6-4
assigning new resource file 14-27
changing names of files 6-4
opening with AppleScript 30-4
saving 6-4
saving with AppleScript 30-4
setting up remove function 12-22
updating 6-6
validating paths 20-5
verifying 6-6, 20-5
Ask At Build 27-9
Ask User 8-43, 36-6 to 36-7
install to location 12-6
search location 8-9
Ask User Only Once on Fat Binary Installs 14-16
Assign Parents Package to New Files 20-5
Assistants 36-8
Attributes tab 27-9
Auto-suffix
B
Before Install 14-28
Before Main Installer 14-36
Billboard Files 15-4
in project window 27-27
Billboards
and diskettes 15-3
by disk 15-2
by package 15-2
default 15-5
removing 15-4, 15-6
sequential 15-2
Index–3
A
B
C
D
E
F
G
H
I
J
K
L
setting mode via AppleScript 30-7
BinHex 27-16
BNDL resource 23-20
Bring Up To Date 12-24, 14-27, 20-2, 27-8, 30-5, 39-2
and embedded VCTs 14-26, 20-5
setting with AppleScript 30-4
Bring Up To Date Options
assign parents package to new files 20-5
Update Icon Locations 20-5
BringUpToDate (AppleScript) 30-4
BRM Permit No, City & State
for registration destination 35-3
Build (AppleScript) 30-9
Build Directives
AND condition 7-22, 8-5, 12-14, 27-5
and packages compared 27-1
any match 7-22, 8-5, 12-14
defined 27-1
for billboard files 27-28
for packages 7-10, 7-18
NEVER condition 27-6
OR condition 7-22, 8-5, 12-14, 27-6
setting for files and folders 12-13
Build Sources 27-7
Build Target
active 27-21
Display Billboards 27-13
duplicating 27-15, 27-22, 37-8
Installer Name 27-14
Language 27-14
Settings 27-13
Build Target Format
ask at build 27-9
CD installer 27-9
disk images 27-9
floppies 27-9
folders 27-9
single file 27-9
Single File w/External Data 27-10
USB Installer 27-10
web installer (data in installer) 27-10
web installers 27-9
Build Target Platform
Carbon 27-10
Carbon SharedLibData 27-11
Classic 27-10
PowerPC 27-10
PowerPC SharedLibData 27-11
Unified 27-10
Build Targets 27-8
and billboards 27-14
and localization 27-14
M
N
O
P
Q
R
S T
U V W
X Y
Build Directives 27-15
Dates tab 27-17
duplicating 27-15
eSeller tab 27-19
for web installers 37-2
Post processing tab 27-16
Scripts tab 27-17
Build Updater 23-19
BuildDirectiveOff (AppleScript) 30-8
BuildDirectiveOn (AppleScript) 30-8
BuildTargetOff (AppleScript) 30-9
BuildTargetOn (AppleScript) 30-8
Bundle
action item search criteria 8-10 to 8-11
defining bundle filename extensions 12-22
drag and drop behavior 8-12
search behavior 8-12, 14-6
version checking behavior 8-15, 14-6
Bundle Extensions.txt 12-22
BUTDValidatePaths (AppleScript) 30-5
Button
behaviors 34-8
properties 34-7
Button Behavior
cancel 34-8
continue 34-8
e-mail 34-9
go to form 34-9
print for fax 34-9
print mailer 34-8
register 34-8
Byte Range Downloads 14-30, 37-4
C
Caches 36-9
Cancel if Update Fails 26-7
Canceling installs 39-2
Carbon 27-10, 36-9
Carbon SharedLibData 27-11
Case Sensitivity
and variables 28-2
Catalog
for web installers 37-11
Catalog Only
and capture icon position 13-4
Catalog Only Installers 14-25
CD Installer
Build Target Format 27-9
CD installers
and uncompressed files 12-15
archive settings for 6-4
skipping file replacement 39-4
validating paths for 20-5
Z
Index–4
A
B
C
D
E
F
G
H
I
J
verifying archive for 20-5
cfrg resource 22-4, 23-17
and data fork exceptions 23-21
Check Consistency 29-23
Check for Duplicate 6-6
Check Item Gestalts On Custom Install 14-9
and Language/Region settings 12-4
Checkbox
properties 34-13
cicn
ids in message actions 8-26
in external resource file 8-26
Classic 27-10
Cleanup At Startup 36-8
CloseWindow (AppleScript) 30-4
CODE resource 22-4, 23-17
for custom external code 32-18
ColorSync 36-9
ColorSync CMMs 36-9
ColorSync Profiles 36-8
ColorSync Scripting 36-9
Comment Options 8-40
Compare button 23-5
Compare Creation Dates 8-43
Compare Modification Dates 8-43
Compare Version 8-43
Components 36-9
Compress Installer 14-25
Confirm Before Deleting Files 6-6
Confirm Before Saving 6-6
Confirm Creating Alias 8-24
Confirm Delete 8-19
Confirm Move 8-20 to 8-22
Consistency Information window 29-24
Contextual Menu Items 12-19, 36-8
Control Panels 36-6 to 36-7
Control Panels (Disabled) 36-6 to 36-7
Control Strip Modules 36-6 to 36-7
Copy Options 8-20
Copy Parent of Found Item 8-20
Copy To Location 8-20
Core Services 36-10
Create Installation Folder Named 14-17, 28-7
Create Log File During Install 14-13
Create Separate Catalog 14-29, 37-3
Creation date 23-13
Current Folder
search location 8-9
Custom Install
and Fat binary applications 39-2
package sizes in 39-2
setting as default 14-2
K
L
M
N
O
P
Q
R
S T
U V W
X Y
Z
Custom Mailers
for registration 35-13
Customize Layout 26-3
D
Data File Name 14-29, 37-3
Data fork
and Fat Binary files 22-4
handling modifications to 23-9
Debug Installer
building 18-5
Default Billboards 15-5
Default Install Location 14-6, 28-7
Default Installer Settings 14-31
Default Layout 26-4, 26-6
Default Locations 36-2
Default Package On 7-9
Delete Folder Only If Empty 8-19
Delete on Uninstalls 26-7
Delete Options 8-19
Delete Parent of Found Item 8-19
Deselect (AppleScript) 31-2
Desktop 36-6 to 36-7
Desktop Pictures 36-8
Destination Volume System Folder 14-17
Developer 36-10
Developer Docs 36-10
Developer Help 36-10
Diagnostic
archive report 16-3
Disable Strict Library Checking 14-28
Disk Images 27-9
Disk Information
Disk Size 11-2
Segment Size 11-2
Disk Popmenu 14-3
Disk Size
setting 11-2
Display Billboards in Separate Window 14-4
Display Easy Install Package In Progress 14-8
Display Extensions 36-9
Display Form Options 8-27
Display Found Items 8-19 to 8-21, 8-23 to 8-24
Display Invisible Files 6-6
Display Registration 14-15
DoAutoInstall (AppleScript) 31-2
Documentation 36-10
Documents 36-8
DoInstall (AppleScript) 31-2
Domain
selecting for search location 8-10
Index–5
A
B
C
D
E
F
G
H
I
J
K
L
M
setting for install location 12-6
Don't Allow Multiple Installs 14-18
Don't Install Folder (Placeholder) 12-19
Don’t Copy Files from Source at Build Time 14-25
Don’t Copy vct Resources 27-26
Don’t Display During Launch 14-10, 14-12
Don’t Display Lang. Popmenu 14-13
Don’t Quit Finder During Installs 14-16
Don’t Retain Icon Position 26-8
Don’t Shutdown Running Apps on Uninstall 14-9
Don’t Update Packages on Imported VCT Files 14-26, 20-5
Download Sites 37-10
Downloads 36-10
Drag and Drop 6-6
in Action Items 8-12
shortcuts 40-2
DS_Store file 12-18, 14-26
E
Easy Install 7-1
and gestalt calls 12-16
text for 14-7
Easy Install Package 7-1
Easy Install Text 28-7
Edit Disk 11-1
Edit Disk window 30-11
Edit Easy Install Text 14-7
Edit External Code 9-5 to 9-6
Edit Gestalt 10-3
Edit Layout 26-5
Edit Package 7-8
Edit Package Options
choose icon 7-10
description 7-8
gestalt 7-9
Icon ID 7-9
list footer 7-9
list header 7-9
list package 7-9
mutual exclusive group 7-9
name 7-8
package type 7-10
purchase 7-10
restart after installing 7-9
separator 7-8
sub-archive package 7-9
version 7-9
Edit Text File Options 8-37
Edit Text Item
properties 34-11
N
O
P
Q
R
S T
U V W
X Y
Edit Uninstall Text 14-10
Email Address
Email Registration 35-12
Embedded VCTs 27-22
and Bring Up To Date 20-5
don’t copy vct resources 27-26
updating 14-26
Empty Folders
installing 14-18
eSellerate 27-19, 27-21
Event Loop 14-28
exit 1
UNIX shell script command 32-24 to 32-25
Exporting
translator applications 29-24
user resources 29-23
Extended Add Dialog 6-2
keyboard shortcuts 40-2
Extended Add Dialog Box 6-3
Extended install locations 36-1
Extensions 36-6 to 36-7
Extensions (Disabled) 36-6 to 36-7
External Code 32-21
localized 29-22
External code
adding to an installer 9-2
External Code Is Optional 14-28
External code resources
adding to resource fork 9-4
ID number range 32-1
in foreign-language installers 29-22
marking 32-17
External codes
assigning to the installer 14-28
checking for cancellation 32-18
declaring in an installer 9-4
hints for using 32-17
nonexistent or misidentified 32-2
options by installer platform 9-1
Specifying when to call 9-7
using multiple 32-2
when they can be called 32-1
Extra Locations 36-2
Extract Item (AppleScript) 30-7
F
Fat Applications
package install options 7-23
Fat binary applications
and package type 7-18, 7-23
install options for 12-16
options for 22-4, 23-17
Z
Index–6
A
B
C
D
E
F
G
H
I
J
K
L
Fat Binary CFM files 23-17
Favorites 36-8
File
File creator
changing 12-5
File formats 22-1
fat binary options 22-4, 23-17
PowerPC options 22-4, 23-18
File is invisible 26-8
File is Locked 26-8
File type
changing 12-4
File versions 22-1
Files
archive report 16-3
changing attributes of multiple 40-3
default install locations for 12-11
deleting during uninstalls 12-18
installing based on gestalts 12-15
invisible 6-6
replacing during installation 12-12
storing uncompressed 39-1
Find 17-3, 36-8
items within an archive 17-1
Find Action items
for default install location 14-6
installing items based on 12-5
installing items to result location 12-9
Find Action Result 36-6 to 36-7
search location 8-9
Find by Content Plug-ins 36-9
Find Multiple Occurrences 8-11, 8-19 to 8-22, 8-24
Find Options 8-18
Find Previous 17-3
Finder
quitting during installs 14-16
FindFolder 39-1
Floppies 27-9
Folder
Folder Action Scripts 36-8
Folder Default Settings 12-23
notes on functionality 12-24
removing 12-24
setup 12-23
Folders 27-9
M
N
O
P
Q
R
S T
U V W
X Y
Z
installing based on gestalts 12-15
installing to archive folders 12-11
replacing during installation 12-12
storing uncompressed 12-15
Fonts Folder 36-6 to 36-7
Force Restart when Appropriate 14-17
Force Scroll Before Accept 14-13
Form
localization 34-3
Form Name 8-28
Frameworks 36-10
Full Path Name 30-4
G
Generate Log File 23-16
Generic Interface 14-3
Gestalt
OR condition 12-16
Gestalt selectors
adding 33-3
example 33-4
modifying 33-3
Gestalts 10-4, 26-8
and Easy Install 12-16
creating 10-3
installing items based on 12-15
Get Info window 7-22, 12-1, 12-14
GLST Picker TMPL 33-2
GLST resource 33-1
Group and Permissions 12-25
H
Header Text 23-15
Help 39-1
Hide Progress Bar 8-35
HTTP 1.0
and active web installers 37-2
I
Icon
for message action dialogs 8-25
Icon ID 8-25
Icon Locations 13-1
Icon resource 23-20
Icons
for packages 7-23
If Active System is On A Locked Volume, Ask User Which
Index–7
A
B
C
D
E
F
G
H
I
J
System ƒ to Use 14-17
If Different 8-43
If Exists 8-43
If Newer 8-43
If Newer or Equal 8-43
If No Fonts Folder, Ask User 14-17
If Older 8-43
If Older or Equal 8-43
Ignore DS_Store Files 14-26
Import
other resources 29-24
Importing Other Resources 29-24
In Installer 37-10
Include On-line Registration Module 14-14
Include PowerPC Decompressor 14-25
Individual File 37-10
Initial install location
setting 14-6
Initialization 14-28
Insk Resource 29-30
Install as Normal File 12-18, 26-8
Install Empty Folders 12-11, 12-19, 14-18
Install Folder 36-6
search location 8-9
Install Locations
archive report 16-3
Install locations
extended 36-1
extra 36-1
OS 8.5 36-1
OS 8.6 36-1
OS 9.0 36-1
OS X 36-1
Install System Folder Items In 14-17
Installer file
available languages 29-1
Installer Interface 14-2
Installer Launches 14-35
Installer Logs 36-8
Installer Memory Requirements
and updaters 24-2
Installer Password 14-23
Installer Quit 14-28
Installer Settings 14-1
defaulting 14-31
deleting 14-34
saving 14-30
selecting 14-31
Installer VISE
about 1-1
new features in 8.4 1-2
K
L
M
N
O
P
Q
R
S T
U V W
X Y
Z
Installer VISE Extensions Folder 2-3
Installers
adding Help 39-1
adding splash screens 14-15
and AppleScript 30-4
building with AppleScript 30-9, 30-12
canceling 39-2
creating remove functions 12-23
default install location 14-6
disk space requirements 39-2
on CD 19-5
supported languages 29-2
InstallVar 28-7, 36-3
Interface Options
generic 14-2
installer 14-2
updater 14-2
Internet 36-8
Internet Search Sites 36-8
Invalid
updaters 20-4
Invisible files 6-6
Item Detail 26-2
Item List 26-2
J
Jump Action 8-31
K
Keyboard equivalents
find 17-3
find next 17-3
find previous 17-3
Keyboard shortcuts 40-1 to 40-2
Keychains 36-9
kSelectorCheckingSizes 32-17
L
Language
action option 8-5
and Build Targets 27-14
and Check Item Gestalts On Custom Install 12-4
file and folder option 12-4
for billboard files 27-28
user defined 29-30
Language & Region Support 36-9
Language and Region
AND condition for actions 8-5
AND condition for files 12-4
OR condition for actions 8-5
OR condition for files 12-4
Index–8
A
B
C
D
E
F
G
H
Language Codes
for Installer VISE 29-26
Language file 29-2
Language In Archive 27-14
Launch URL Options 8-35
Launcher Items 36-8
Layout 26-1
default layout 26-6
reordering 26-4
samples 26-6
separators 26-6
seperators 26-6
setup 26-5
standard layout 26-6
Layout List 26-4
Library 36-10
License Agreements
viewing 27-26
List Columns 26-2
List packages
about 7-7
and long name 12-4
headers and footers 7-14
Help PICTs for 7-15
Localization
and build targets 27-14
features 29-1
of applications 29-24
of registration forms 35-8
Localization file 29-2
Localized External Code
in multi-language installers 29-23
in single-language installers 29-22
Location Manager Modules 36-9
Location Manager Prefs 36-9
Locations 36-9
Log File 14-13
Log File Name 14-14, 28-7
Log File Options
always replace 14-14
append to existing 14-14
auto-suffix 14-14
Long Name 12-4
I
J
K
L
M
N
O
P
Q
R
S T
U V W
X Y
Z
Mailer Registration 35-12
Main Window
supress options 14-5
Match Can be Alias 8-10
Memory Requirements
for installers with updaters 24-2
Message Options 8-25
Minimum install requirements 33-1
Minimum Requirements to Install
Allow User to Override 14-23
CPU 14-22
Gestalt 14-22
Physical RAM 14-22
Quit Installer if Not Administrator 14-22
Require OS X Authentication 14-23
System Version 14-22
Minimum Size 14-21, 24-2
Modem Scripts 36-8
Modify File Date When Merging Resources 14-18
Move Options 8-21
Move Parent of Found Item 8-21
Move To Location 8-21
Moved Items Folder 14-19
Moving Across Volumes 8-22
Multi-language Installers
and billboards 15-5
steps to create 29-3
Multiple file attributes, changing 40-3
Multiple Users Accounts
support for 14-37
Multiprocessing 36-9
Mutual exclusive group 7-10, 39-3
N
Name
for alias actions 8-24
Nested Folders
and folder default settings 12-24
Never 8-43
New Billboard File 15-5
New Name 8-20, 8-23
No Restart Warnings 14-17
None (interface option) 14-3
NT
and shadow items 12-4
M
Mac OS Read Me Files 36-8
MacBinary 27-16
Mail To
Index–9
A
B
C
D
E
F
G
H
I
O
Only Store Catalog of Files 6-4, 19-2
Open (AppleScript) 30-4
Open After Installing 12-18, 26-8
Open Folder After Updating 23-16
Open/Launch Found Items 8-18
OpenDoc 36-8
OpenDoc Libraries 36-8
OpenDoc Shell Plug-Ins 36-8
OS 8.5 Locations 36-2
OS 8.6 Locations 36-2
OS 9 Locations 36-2
OS X Locations 36-2
Other 36-6
Other Resources
import 29-24
Override Language 29-25
P
Package Build Directives 7-10, 7-18, 7-22
and sub-packages 7-22
Package Dependencies 7-3, 7-5
and AppleScript 31-2
Packages 8-35, 26-8
about 7-2
adding icons 7-24
and build directives compared 27-1
and runtime variables 28-7
archive report 16-3
assigning gestalts 7-15
build directives 7-18
creating on-the-fly 7-26
deleting 7-25
edit package options
choose icon 7-10
description 7-8
gestalt 7-9
Icon ID 7-9
list footer 7-9
list header 7-9
list package 7-9
mutual exclusive group 7-9
Name 7-8
package type 7-10
purchase 7-10
restart after installing 7-9
separator 7-8
sub-archive package 7-9
version 7-9
package sizes 39-2
removing items from 7-26
J
K
L
M
N
O
P
Q
R
S T
U V W
X Y
Z
setting package type 7-23
Packages pop-up menu 7-26
Password
for installer 14-23
Path
build targets 27-14
Paths
in Installer VISE 39-2
validating 20-5
PBCatSearch 23-15
Perform Intelligent Filename Check on Update 14-27, 20-3,
30-5
Perform Numeric Comparison 8-30
Permissions and Group 12-25
Picture
properties 34-17
Placeholder Folders 12-19, 26-8
Post Processing 27-16
PowerPC 27-10
PowerPC Only alert 22-4, 23-17
PowerPC Options 23-18
PowerPC SharedLibData 27-11
PPC applications
as source and target files 22-7
Preferences 36-6 to 36-7
default archive settings 14-33
setting options 6-6
Preferred Size 14-21, 24-2
Preventing application shutdown 32-21
Print For Fax Registration 35-12
Print Monitor 36-6 to 36-7
Printer Descriptions 36-8
Printers 36-10
Private Frameworks 36-10
Progress Stop
Q
QuickTime Components 36-10
QuickTime Extensions 36-9
Quit Installer if Find Fails 14-6
R
Radio Button
properties 34-14
Radio Group
properties 34-16
Read Me Files 23-14
viewing 27-26
Index–10
A
B
C
D
E
F
G
H
I
J
K
L
Read Only Teach Text Documents 14-19
Recent Applications 36-8
Recent Documents 36-8
Recent Servers 36-8
RefCon 32-1
Region
action option 8-5
and Check Item Gestalts On Custom Install 12-4
file and folder option 12-4
Region Codes
for Installer VISE 29-27
Region(s)
Registration Destination 35-3
BRM Permit No, City & State 35-3
email address 35-4
mail to 35-3
region(s) 35-3
reply address 35-4
subject 35-4
zip code for bar code 35-4
Remote Volumes
System Folders on 39-1
Remove function 12-22 to 12-23
text for 14-10
RemoveCompressedData (AppleScript) 30-12
Rename Options 8-22
Rename Parent of Found Item 8-22
Replace 8-20 to 8-21, 8-23 to 8-24
Replace Options
always 8-43
ask user 8-43
Replace options 8-20 to 8-21, 8-23 to 8-24, 8-43
Compare Creation Dates 8-43
compare modification dates 8-43
compare version 8-43
if different 8-43
if exists 8-43
if newer 8-43
if newer or equal 8-43
if older 8-43
if older or equal 8-43
never 8-43
Reply Address
M
N
O
P
Q
R
S T
U V W
X Y
Z
Report Output Options 16-4
Resource
and multiple code fragments 23-21
Resource exceptions 23-4
about 22-2, 23-9
default 23-8
entering information 23-10
for updaters 23-9
Resource Files
Resource files
assigning to archive 14-27
Resource of Archive 15-5
Resources
identification of 23-7
merging for localization 29-24
Restart 14-17
forcing 39-2
Restart After Installing 12-18, 26-8
Return Parent 8-18
Return Parent of Found Item 14-6
Root Folder 36-10
Root of Startup Disk 36-6 to 36-7
Root of Startup Drive
search location 8-9
Runtime Variables 28-2
S
Save as POSIX Path 8-18
SaveArchive (AppleScript) 30-4
scpt 30-1
Script.h 29-28
Scripts 36-9
SdEx resource 32-21
Search Criteria
action item 8-11
Search location pop-up menu 8-9
Search Locations
all disks 8-9
ask user 8-9
current folder 8-9
find action result 8-9
install folder 8-9
root of startup drive 8-9
Index–11
A
B
C
D
E
F
G
H
I
J
Search Locked Volumes 8-10
Search Subfolders 8-11
Select (AppleScript) 31-2
Select All Found 17-3
Select Folder & Switch Disk Buttons 14-3
Select Folder Button 14-3
SelectDrive (AppleScript) 31-3 to 31-4
Selected Disk 8-9
Send Install Location 8-35
Separators 7-10
Set Installer Locked Bit 14-21
Set Installer Shared Bit 14-21
Set Localization File 14-27
Set Owner To Root 26-8
Set Resource File 14-27
Set Variable 8-18
Set Variable Options 8-28
SetAssignPackagesFlag (AppleScript) 30-5
SetBillboardMode (AppleScript) 30-7
SetBuildTarget (AppleScript) 30-7
SetDisk
parameters 30-11
SetDisk (AppleScript) 30-11
SetDownloadSite (AppleScript) 30-10
SetInstall (AppleScript) 31-1
SetIntelligentUpdateFlag (AppleScript) 30-5
SetLocalizationFile (AppleScript) 30-10
Settings
for Build Targets 27-13
Settings... button 23-4
Setup Defaults 12-24
SetVariable (AppleScript) 30-10
Shadow Items 12-3
and NT 12-4
Shared Documents 36-9
Shared Libraries
K
L
M
N
O
P
Q
R
S T
U V W
X Y
Z
Shell scripts 27-29
ShellVar 28-7
Show “Select All” Button 14-9
Show Billboards 8-34
Show Easy Install Package in Custom Install 14-9
Show in Install Menu 7-9
Show Installer Window During Install 14-4
Show License Agreement 8-34
Show Read Me 8-34
Show Size in 14-27
Show Sizes in Easy Install 14-8
Show Splash Screen 8-34
shsc 32-24
Shutdown Applications Before Installing 14-16
ShutDown Items 36-6 to 36-7
Shutdown Items (Disabled) 36-8
Single File 27-9
Single-language Installers
steps to create 29-2
Single-language installers 29-4, 29-12
68K
68K applications 22-6
Skipping file replacement
for CD installers 39-4
Sound Sets 36-9
Sounds 36-10
Source files
customer modifications to 23-7
defined 22-1
maximum allowed 23-4
renaming customer’s 23-12
Speakable Items 36-9
Specific Packages
archive reports 16-3
Speech 36-10
Splash screens 14-15, 23-14
Stand-alone Updater Options
modification date 23-13
Standard File Dialog in updater 23-16
Standard Icon Positioning 13-1
Standard Layout 26-6
Startup Disk 8-9
Startup Items 36-6 to 36-7
Startup Items (Disabled) 36-8
Stationery 36-8
Stop Install With Error 8-32
Stop Installation Action Options 8-32
Store Installer Data in External File 14-29, 37-3
Strict Installer Data Time Stamp Checking 14-29, 37-3
Sub-archive packages
about 7-2
Index–12
A
B
C
D
E
F
G
H
I
J
K
Subject
Sub-launch locks 8-34
Sub-launched item is a VISE Installer 8-34
Sub-packages
about 7-2
and package build directives 7-22
creating 7-12
Success
Suppress 8-35
Suppress Internet Dialup Dialog 37-4
Suppress Internet Disconnect Dialog 14-30, 37-4
Supress Internet Dialup Dialog 14-30
Switch Disk Button 14-3
Symbolic Link 26-8
Synchronize Dates 26-8
System 6 23-15
System Control Panels 36-9
System Desktop Folder 36-9
System error -192 22-4, 23-18
System Extensions
and uninstalls 12-18
System File 36-6
System Folder 14-17, 36-6 to 36-7
remote volumes 39-1
System Preferences 36-9
System Trash 36-9
T
Target
active 27-21
Target files
adding 23-6
creation date 23-13
defined 22-1
modification date 23-13
options for naming 23-12
removing 23-6
TeachText Documents 14-19
Temporary Items 36-6 to 36-7
Test Update... button 23-5
Test Variable Options 8-29
Text Encoding Converters
installing 32-26
The Volume Settings Folder 36-9
TheFindByContentFolder 36-9
Theme Files 36-9
To Printer
archive report option 16-4
To Screen
L
M
N
O
P
Q
R
S T
U V W
X Y
Z
To Text File
Top Level Folder 36-10
Translator applications 29-2
consistency check 29-23
exporting 29-24
importing 29-7, 29-15
localizing 29-7, 29-15
Trash Can 23-4
Tutorial 4-21
U
Uncompressed files 36-1, 39-1
Uncompressed Files Are Optional 14-18
Unified 27-10
Uninstall Text 28-7
Uninstalls 12-22
on Mac OS X 12-18
text for 14-10
UNIX $1 parameter 32-23 to 32-24
UNIX $2 parameter 32-23, 32-25
UNIX Script Options 8-40
UNIX scripts
executing from the installer 32-22
UNIX shell scripts 27-29
Update (AppleScript) 30-6
Update Archive See Bring Up To Date
Update button 24-6
Update files
building 23-18
presentation options for installers with 24-6
removing files from 23-6
testing 23-19
validating with AppleScript 30-10
Update Icon Locations 20-5
Update Settings 23-11
for all update files 23-11
for stand-alone updaters only 23-11
Update Settings window 23-12
Update window
importance of 22-5
UpdateAll (AppleScript) 30-6
UpdateDriveList (AppleScript) 31-3
UpdateOne (AppleScript) 30-6
UpdateOneFile (AppleScript) 30-7
Updater Interface 14-3
using 24-4
Updater VISE 24-1
ignored settings 24-2
Index–13
A
B
C
D
E
F
G
H
I
J
K
L
M
Updater VISE Extensions folder 2-3
Updaters 24-1
about 21-1
adding files 23-5
adding files to 23-6
benefits and features 21-2
components of 22-1
customer’s perspective 21-3
default icon 23-20
designing 22-1, 22-3
Fat Binary options 22-3
general procedures for 23-1
integration with Installer VISE 21-2
invalid 20-4
localization features 21-2
PowerPC options 22-3
samples 22-4
saving as application 23-20
Why use updaters? 21-1
Why use VISE? 21-1
Updating
user resources 29-23
Updating an Archive 6-6
Upload Cab File(s) To Web Server At Build Time (FTP Sites
Only) 14-30, 37-4
USB Installers 27-10
creating 38-1
Use Custom Icon 26-8
Use Extended Add File Dialog Box 6-6
Use Standard File Dialog 23-15
Use the “Applications” folder by Default 14-7
Use Updater Interface 24-2
Use White Background for Billboard and Splash 14-4
User Defined Languages 29-30
User Flag 7-9
User Prompt 8-18 to 8-21, 8-23 to 8-24
USER resources
in foreign-language installers 29-23
User Temporary Folder 36-10
Users 36-9
Utilities 36-9
V
Validate Paths 20-5, 27-8, 39-2
ValidateUpdateFile (AppleScript) 30-10
Variable "InstallVar" 36-10
Variables 28-2
and case sensitivity 28-2
N
O
P
Q
R
S T
U V W
X Y
declaration of 28-3
InstallVar 28-7, 36-3
percent symbol in 28-7
ShellVar 28-7
VCT Link Options 27-23
Verify Archive 20-5
Verifying an Archive 6-6
Version checking 39-3
Vertical Column Titles 26-2, 26-8
View Generic Icons In Windows 14-27
VISEICat 37-12
VISEICat.idx 37-12
W
Wait for sub-launched item to complete 8-34
Web Installer (Data In Installer) 27-10
Web Installers 27-9, 37-1
assigning files to file groups 37-9
benefits 37-1
build target 37-2
catalog 37-11
download sites 37-10
In Installer 37-10
Individual File 37-10
self updating 37-3, 37-11, 37-16
setup overview 37-2
user’s initial experience 37-13
user’s subsequent experiences 37-16
What to <Action>
using a find action item 8-7
using archive item 8-7
with items found using search criteria 8-7
X
Xcod 29-28, 32-18, 35-8
Z
Zip Code For Bar Code
Z
Index–14
A
B
C
D
E
F
G
H
I
J
K
L
M
N
O
P
Q
R
S T
U V W
X Y
Z

Installer VISE User Guide

Transcription

Similar documents

important notice - Mille

Todd Relaford

PC Power Tool Data Sheet

Getting Started and Creative Applications

Rogue riggers - Wright`s Aerials

IBG Co Commercial Brochure - The Insurance Backed Guarantee

To the Consumer Brochure

How to Sell your Game