Magic Folders and InstallAnywhere Variables
Magic Folders represent a specific location, such as the user selected installation directory, the desktop, or the location for library files. At install time, the installer determines which operating system it is running on and sets the Magic Folders to the correct absolute paths. Many Magic Folders are platform-specific, and many are predefined by InstallAnywhere to standard locations across InstallAnywhere-supported platforms.
Every Magic Folder has an associated InstallAnywhere variable. These variables are first initialized when the installer begins. Changing the value of a Magic Folder variable will change the destination to which the Magic Folder installs. Changing the value of the $USER_INSTALL_DIR$ through InstallAnywhere will change where the files will install.
With the three following exceptions, these variables are initialized at install time and will not change, except through using custom code or the Set InstallAnywhere Variable action:
USER_INSTALL_DIR$: This is initialized to the default value determined in the Platforms task in the Advanced Designer. Its value can change at the Choose Install Folder step if the end-user selects a different folder.
USER_SHORTCUTS$: This is initialized to the default value determined by the Platforms task in the Advanced Designer. Its value can change at the Create Alias, Link, Shortcut Folder install step if the end-user selects a different location.
JAVA_HOME$:
Installer without VM: Defaults to the value of the Java property java.home. Its value can change at the Choose Java Virtual Machine step if the end-user selects a VM.
Installer with VM: Defaults to the value specified in the Project | Java task. It can change when the $USER_INSTALL_DIR$ changes, or at the Choose Java Virtual Machine step if the end-user selects a VM already on his or her machine.
NOTE
Variables cannot be set to themselves. For example to append/test to USER_MAGIC_FOLDER_1, the developer cannot set USER_MAGIC_FOLDER_1 = $USER_MAGIC_FOLDER_1$$/$test. InstallAnywhere does not allow either direct or indirect recursion with InstallAnywhere variables. This condition will cause an error.
InstallAnywhere defines a number of Magic Folders as defaults, mostly those representing common installation locations. One of the keys to understanding Magic Folders is to understand that they resolve to different locations based on the configuration of the target system.
For example:
The Magic Folder system drive root ($SYSTEM_DRIVE_ROOT$) resolves, on UNIX, Linux, and Mac OS X, to C: (or the root of the drive containing the WINNT or Windows directory).
Other Magic Folders are reserved, but are defined by actions in the installer, or actions taken by the end-user. These Magic Folders are important to the operation of the installer.
One such Magic Folder is the User Install Dir ($USER_INSTALL_DIR$), the directory that represents the root of the installation as specified by the developer or as chosen by the user. This directory structure is not defined by the installer, but is defined on a project-by-project basis.
Another such Magic Folder type is the User Magic Folder. While InstallAnywhere defines many installation paths via predefined Magic Folders, Zero G cannot have accounted for all possible installation needs when implementing the technology. As such, the User Magic Folder is introduced. These variable-based installation paths are designed to allow you to define a path manually or using any of InstallAnywhere's dynamic installation tools. You can create your own User Magic Folders by setting the associated variables and then simply adding your resources to that Magic Folder in the install step.