Migrating from Hauptwerk v4 to v5+ on a Mac, 10.15 compat.

Latest updates to Hauptwerk.
Post Reply
User avatar
mdyde
Moderator
Posts: 15788
Joined: Fri Mar 14, 2003 1:19 pm

Migrating from Hauptwerk v4 to v5+ on a Mac, 10.15 compat.

Post by mdyde »


VERY IMPORTANT: please read this before upgrading any existing Hauptwerk Mac installation to v5, OR to macOS 10.15+ ('Catalina')


Dear all,

First some technical background: the default file system in macOS 10.15+ 'Catalina' is Apple's recently-introduced 'APFS'. With it, under macOS 10.15+, most of a Mac's internal SSD/hard-drive (boot drive) is now read-only, and applications are now only allowed to install their folders/files (or write to files) on that drive in a few specific locations designated by Apple.

The default installation locations for Hauptwerk v4's (and earlier versions) main data files were within a folder named 'Hauptwerk' at the very top-level of the Mac's internal drive. In macOS 10.15+, Apple no longer allows files to be written/installed there, and if you already have Hauptwerk v4 installed there, and you upgrade macOS from an earlier macOS version to macOS 10.15+, then the macOS 10.15+ installer will decide it needs to move the folder, but won't know what to do with it, so will move it into a new folder named '/Users/Shared/Relocated Items'.

This will cause your existing Hauptwerk installation to break (since Hauptwerk's files and folders will no longer be where Hauptwerk expects to find them). Here is one article from a third-party website that explains the 'Relocated Items' folder: https://usanewsgroup.com/2019/10/15/rel ... explained/

To avoid this issue, the default installation locations for Hauptwerk v5+'s main data files are now within a folder named 'Hauptwerk' within your macOS accounts home folder (i.e. '/Users/<your macOS username>/Hauptwerk'). That (10.15-safe) location will be used by default for any new/clean installation of Hauptwerk v5+.

Hauptwerk v2-v4's installer also ran with operating system administrator rights, which was fine on older OS X versions, but prevented them being fully compatible with recent macOS versions (including the v5-supported Mac platforms, i.e. 10.13, 10.14 and 10.15). In order to be able to work properly with those recent macOS versions, Hauptwerk v5's installer instead needs to run as the logged-in computer user account. That change prevents Hauptwerk v5's installer being able to update files that were installed by v2-v4 (because the existing file permissions would prevent it).

VERY IMPORTANT: In order to ensure that those situations don't result in a broken Hauptwerk v5+ installation:

If you currently have Hauptwerk v4 (or earlier) installed on a Mac, then please:

BEFORE running the Hauptwerk v5+ installer:
  • 1. If you're able to launch your currently-installed version of Hauptwerk (e.g. v4.2.1), then use 'File | Backup ...' within Hauptwerk to save a backup of all your Hauptwerk settings/combinations/voicing somewhere that you can easily find it (such as your desktop).

    2. If you're able to launch your currently-installed version of Hauptwerk's uninstaller (which can be found in the '/Applications/Hauptwerk Virtual Pipe Organ/Uninstaller' folder), then use that uninstaller to uninstall Hauptwerk completely, selecting the option in the uninstaller to remove all files and settings.

    3. Use Finder to make sure that all of the following folders are completely deleted (if they exist). You may be prompted for your password:
    • '/Applications/Hauptwerk Virtual Pipe Organ'
      '/Users/Shared/Relocated Items/Hauptwerk'
      '/Hauptwerk'
    [The latter folder is at the very top-level of your computer's SSD/hard-drive. In order to be able to find it, make sure that the 'Sidebar | Devices | Hard disks' option is ticked in Finder's preferences.]
Finally:
  • 4. Run the Hauptwerk v5+ installer to perform a clean installation of Hauptwerk, using its current (10.15-safe) default locations (or choose custom locations that are not on the Mac's internal drive). (If you're using macOS 10.15, in order to launch the Hauptwerk v5 installer you need to right-click on it, then select 'Open'.)

    5. You can then use 'File | Restore ...' in Hauptwerk v5+ to get your previous Hauptwerk settings/combinations/voicing back. (If you weren't able to launch Hauptwerk to make a backup in step 1, then, provided that you hadn't previously disabled automatic periodic backups in Hauptwerk, you should instead be able to restore the most recent backup found in the '/Users/<your macOS username>/Hauptwerk/AutomaticBackups' folder.)

    6. Use 'File | Install ...' in Hauptwerk v5+ to install the current versions of any sample sets that you might have (making sure that you install v5-compatible versions if applicable).
QUICK SUMMARY: If you have Hauptwerk v2/v3/v4 installed, then it's very important that you uninstall Hauptwerk completely (and delete all files/folders) BEFORE you install Hauptwerk v5+, then finally install v5+ using its (10.15-safe) default installation locations (or choose custom locations that are not on the Mac's internal drive).

[Edit 2019-12-11: I've edited this post to make it clear that the instructions above also need to be followed on any Mac platform if upgrading to v5, irrespective of whether upgrading to 10.15 specifically or planning to do so.]

[Edit 2020-03-04: The relevant instructions (above) have also been included in the installation instructions in the main Hauptwerk user guide for v5.0.1.]
Best regards, Martin.
Hauptwerk software designer/developer, Milan Digital Audio.
User avatar
mdyde
Moderator
Posts: 15788
Joined: Fri Mar 14, 2003 1:19 pm

Re: Migrating from Hauptwerk v4 to v5+ on a Mac, 10.15

Post by mdyde »

P.S. As always when upgrading between any major operating system versions (e.g. 10.14.x to 10.15.x), and especially so in this case (given the fundamental nature of the changes to macOS's file system, and that compatibility with most existing pre-10.15 software and drivers is broken by 10.15+), when installing macOS 10.15+ I would highly recommend performing a completely clean installation of macOS 10.15+, instead of allowing the macOS installer to upgrade your existing installation.

To do that, when the macOS (10.15+) installer runs, select its function to run Disk Utility when presented with the option, then use Disk Utility to reformat ('erase') you computer's main SSD/hard-drive, choosing APFS as the new file system to use, then exit Disk Utility, then allow the installer to continue. It will then perform a clean installation of macOS on the drive. (Of course, make sure that you have backed up any important documents, etc. somewhere safely on a different drive, or USB stick, before running the macOS installer.)
Best regards, Martin.
Hauptwerk software designer/developer, Milan Digital Audio.
User avatar
mdyde
Moderator
Posts: 15788
Joined: Fri Mar 14, 2003 1:19 pm

Re: Migrating from Hauptwerk v4 to v5+ on a Mac, 10.15

Post by mdyde »

I've edited my above post to make it clear that the instructions there (uninstall Hauptwerk v4 completely and delete files/folder, before installing v5) also need to be followed on any Mac platform if upgrading to v5, irrespective of whether upgrading to 10.15 specifically or planning to do so.
Best regards, Martin.
Hauptwerk software designer/developer, Milan Digital Audio.
Post Reply