1. OpenVerse system directory. ~ Library files, standard plugins, configuration defaults, basic avatars, documentation, languages files, and other files shared between users of the machine are installed to a global OpenVerse directory by a system administrator. Any customizations or additions to these files likewise are shared. In this manner site-wide defaults can be made. 1.1. Base installation directory. ~ Each platform has a default OpenVerse installation directory, but at the option of the system administrator an alternate directory may be used. On UNIX systems, including Mac OS X, the system installation directory is typically /usr/lib/OpenVerse. Other possibilities include /opt/OpenVerse or /packages/net/OpenVerse. On MS-Windows 9x/Me/NT/2000/XP, the OpenVerse installer places all shared files by default in C:\Program Files\OpenVerse. Note that OpenVerse cannot be used on MS-Windows prior to 95 or MS-DOS because of filename length restrictions. There are no suggested install locations for Mac OS prior to Mac OS X, simply that its name be OpenVerse. 1.2. Single-user installation. ~ Single-user installation is also possible: The user may install OpenVerse to his or her home directory or any other location on the filesystem that he or she has read-write access to. For UNIX this may be ~/OpenVerse or ~/local/OpenVerse or anything else the user wants. In MS-Windows NT, C:\Documents and Settings\username\OpenVerse is a likely candidate for single-user installation. Due to lack of multiuser support and file permissions, on MS-Windows 9x/Me and Mac OS 9 and earlier, there is no distinction between a system installation and a single-user installation. 1.3. Upgrading. ~ Upgrading OpenVerse typically consists of replacing the OpenVerse installation directory with that of a new version. The currently-installed copy of OpenVerse is deleted or saved as a backup, and the new copy is extracted from the distribution archive in its place. If any site-local customizations were made, such as adjustments to the default configuration files or the global installation of additional avatars or plugins, caution must be exercised to ensure they are not lost in the upgrade. Prior to the upgrade, the OpenVerse installation directory should be moved out of the way to avoid being overwritten. The new version is then installed. Next, all files added or modified to the old OpenVerse installation must be identified and copied from the old installation directory to the new. Take care when merging configuration files. If there is any problem with the new version OpenVerse, the old version may be reverted to if desired. 1.4. Installation utility. ~ The OpenVerse installation utility copies the OpenVerse system files into place and allows the system administrator to adjust site-wide settings. First it asks where to install OpenVerse, then creates the directory and populates it with the appropriate files. Next it generates MD5 checksums for all files in the OpenVerse system directory and writes them to disk. Finally it executes the OpenVerse setup system, allowing the adjustment of site-wide settings, including the location of user directories. If a prior installation of OpenVerse is detected and the user wishes to upgrade, the installation utility moves the old OpenVerse to a different directory of the administrator's choosing before performing the normal install procedure outlined above. After the setup step, the checksums in the old copy of OpenVerse are checked against those stored in the file generated during its installation. A list of new, modified, and deleted files and directories is produced and displayed. Each row in the list includes a checkbox indicating whether or not to copy the new or modified file to the new installation or to delete the corresponding file. In this manner the administrator can select which changes he or she wishes to preserve and which to discard. The following items are checked by default: - New plugin directories and the files they contain. - Deleted plugin directories. - Configuration files for new plugins. - New language definition files. - Modified icon files. Deleted files that do not correspond to files in the new version are disabled and cannot be checked. All other new/modified/deleted files are unchecked by default. The list interface includes "check all", "uncheck all", and "check recommended" buttons. Unfortunately, due to the lack of tristate checkboxes and tree views in Tk, the interface for directories may be a bit clumsy. After the selections have been made, the selected files and directories are copied from the old OpenVerse directory to the new or are deleted from the new, whichever is appropriate. 1.5. Structure. ~ TODO: Explain. Demonstrate panels. Demonstrate themes. /usr/lib/OpenVerse/ /usr/lib/OpenVerse/config/client/ /usr/lib/OpenVerse/config/personal/ /usr/lib/OpenVerse/plugins/client/Query/ /usr/lib/OpenVerse/plugins/client/Fun/ /usr/lib/OpenVerse/plugins/client/Fun/help/ /usr/lib/OpenVerse/plugins/client/Fun/icons/ /usr/lib/OpenVerse/plugins/client/Fun/lang/ /usr/lib/OpenVerse/plugins/server/Exit/ /usr/lib/OpenVerse/plugins/server/Exit/lang/ /usr/lib/OpenVerse/lib/client/ /usr/lib/OpenVerse/lib/client/help/ /usr/lib/OpenVerse/lib/client/icons/ /usr/lib/OpenVerse/lib/client/lang/ /usr/lib/OpenVerse/lib/server/ /usr/lib/OpenVerse/lib/server/lang/ /usr/lib/OpenVerse/avatars/ 2. OpenVerse user directory. ~ When a user runs OpenVerse for the first time, a personal OpenVerse user directory is created in which his or her configuration, avatars, cached files, downloads, logs, and plugins are stored. To this directory the user may also install additional languages or panels, or even override system-wide default avatars, language definitions, icons, etc. 2.1. Default user directory location. ~ Each platform has a different default user directory location, as enumerated below. The default OpenVerse user directory on UNIX systems is ~/.OpenVerse. On MS-Windows 9x/Me, it is C:\OpenVerse_User. For MS-Windows NT/2000/XP, the user directory defaults to C:\Documents and Settings\username\OpenVerse_User. On Mac OS 9 and earlier, any directory named OpenVerse_User will do. 2.2. Adjusting the defaults. ~ The path to the user directory is stored in the system-wide client configuration file. If the system administrator wishes to change the OpenVerse user directory name, he or she can edit the client server configuration files to specify new locations. An individual user can select an alternate location for his or her OpenVerse user directory by setting the OV_USER environment variable to reflect its path. Mac OS 9 and earlier do not support environment variables, but that's irrelevant because they also allow ordinary users to directly adjust the "system" configuration files. 2.3. Separation of user and system directories. ~ Normally the OpenVerse system directory is installed in such a way as to be unmodifiable by ordinary users. However, when OpenVerse itself is installed by an ordinary user, it becomes possible for this user to store his or her personal files in the same directory as the OpenVerse installation. This also happens on MS-Windows 9x/Me and Mac OS 9 and earlier because there are no users and access limitations. In prior versions of OpenVerse, this was in fact the default install for MS-Windows 9x/Me and Mac OS 9 and earlier. However, several problems arose indicating the need for separating the user and system directories even when it is possible to merge them. One, many MS-Windows 98/Me users were unable to find their OpenVerse avatars, downloads, room images, and so on because MS-Windows discouraged them from directly accessing C:\Program Files, in which OpenVerse was located. Two, because MS-Windows and old Mac OS users tend to be less computer-literate than UNIX users, they have a difficult time discerning between their files and the system files, because they were stored in the same directory, C:\Program Files\OpenVerse. As a result, there were problems with people damaging their installation by, say, deleting the wrong file. Three, reinstalling and upgrading OpenVerse was quite perilous since it was difficult to separate the files and directories that needed to be preserved from the files and directories that were to be erased or overwritten by the new version. This is related to problem two, above. It was not uncommon for users to damage their OpenVerse installation and proceed to lose all their personal files while reinstalling. Therefore the once-common configuration of user and system files in the same directory is now discouraged. However, it is still possible to have the old behavior by setting the user directory equal to the system directory in the configuration files. The user files and the system files are guaranteed to never collide because they either reside in separate subdirectories or because the user files were supposed to override the system anyhow. 2.4. Upgrading. ~ Each time OpenVerse starts, it checks the version list in the user directory. If the user directory corresponds to an old version of OpenVerse or a plugin, the user upgrade utility is invoked. The upgrade utility generates a list of changes it will need to make to the user directory to render it directly useful to the currently-installed version of OpenVerse. This list is presented to the user, who can then decide whether to go ahead or to cancel. Before actually doing anything, the upgrade utility offers the user the chance to make a backup of his or her user directory. This backup directory can be used to retry the upgrade or to make downgrading possible. Next, the list is written to disk to log the upgrade, to aid in locating any "missing" files, that is, files moved to new locations. Finally, the actions in the list are carried out. The version list is updated. 2.5. Downgrading. ~ Currently there is no automated method for downgrading OpenVerse or a plugin. The user must either restore from a backup or manually move his or her files into the expected locations and fix the configuration files to use the recognized options. If the version list in the user's home directory indicates a newer version than is currently installed, a warning is displayed including instructions for manually downgrading. The instructions include a recommendation to first make a backup. The web sites for the OpenVerse components in question are listed, so the user can visit them for more information. 2.6. Structure. ~ TODO: Explain. Demonstrate panels. Demonstrate themes. ~/.OpenVerse/ ~/.OpenVerse/config/client/ ~/.OpenVerse/config/personal/ ~/.OpenVerse/config/the_hippo_room/ ~/.OpenVerse/plugins/client/DuckControl/ ~/.OpenVerse/plugins/client/DuckControl/help/ ~/.OpenVerse/plugins/client/DuckControl/icons/ ~/.OpenVerse/plugins/client/DuckControl/lang/ ~/.OpenVerse/plugins/server/Topic/ ~/.OpenVerse/plugins/server/Topic/icons/ ~/.OpenVerse/plugins/server/Topic/lang/ ~/.OpenVerse/log/client/ ~/.OpenVerse/log/personal/ ~/.OpenVerse/log/the_hippo_room/ ~/.OpenVerse/cache/client/avatars/ ~/.OpenVerse/cache/client/objects/ ~/.OpenVerse/cache/client/rooms/ ~/.OpenVerse/cache/server/avatars/ ~/.OpenVerse/download/ ~/.OpenVerse/tmp/ ~/.OpenVerse/avatars/ vim:ft=help:et