Feature Request: Support for Symbolic-Linked Folders on macOS

[vpoguru]

Congratulations on creating this impressive software. I’m very impressed by what you have achieved in just four days. This project looks very promising.

I would like to report an issue and suggest a potential improvement: Masterpiece currently does not appear to support symbolically linked folders on macOS.

Since Hauptwerk provides limited options for relocating individual folders, I use symbolic links to organize several folders and share them between multiple installations. I would appreciate if Masterpiece could find a way to address the issue.

Thank you for your work and for considering this request.

[bonninr]

Thank you for the report and the kind words. This is fixed in v0.5.0.

The organ root is now resolved first from the path as given and then, if that has no OrganInstallationPackages beside it, from the path with symbolic links resolved. That covers a relocated OrganDefinitions folder, a relocated OrganInstallationPackages folder, and a single package folder linked in from elsewhere. The change is covered by tests that build each of those layouts with real directory symlinks, and they run on the macOS and Linux CI machines.

It has not yet been tried on your own layout, so if a set still fails to load through your links, please reopen this issue with the folder structure and I will look at it straight away.

[vpoguru]

Many thanks for looking into this issue so quickly.

Unfortunately, the issue persists when OrganDefinitions is symlinked. I tested all four combinations:

OrganDefinitions	OrganInstallationPackages	Result
Not symlinked	Not symlinked	Works
Not symlinked	Symlinked	Works
Symlinked	Not symlinked	Does not work
Symlinked	Symlinked	Does not work

These results suggest that the remaining issue is specifically related to symlinking the OrganDefinitions folder. Symlinking OrganInstallationPackages works as long as OrganDefinitions is not symlinked.

On a related note, the error message displayed when the sample set cannot be loaded—“Console artwork could not be loaded (n images). Check OrganInstallationPackages.”—is so small on my Mac that it is almost impossible to read.

Thank you again for your help!

[bonninr]

Two changes in v0.5.3.

Wider search. When the folder beside the definition holds no OrganInstallationPackages, Masterpiece now walks up from both the path as given and the path with its symbolic links resolved, rather than one level up from each.

The folder can be named. One layout cannot be derived from a path: packages beside the link, definition opened through the resolved path. Settings, Engine tab, Organ folder — point it at the folder containing OrganInstallationPackages and it is saved with that organ. --organ-root <folder> does the same from the command line.

If it still fails, that setting will load it. Knowing which of the two paths your Mac hands over would tell me whether the search can find it unaided.

The unreadable load message is noted; worth its own issue if you want it tracked.

[vpoguru]

Thank you very much for looking into this again and for adding the new configuration option. I really appreciate the time and effort you are putting into supporting this somewhat unusual Hauptwerk setup.

I have done some more testing and would like to provide a few additional details. I hope they may help to narrow down what is happening.

My directory layout

These are the standard Hauptwerk locations on my system:

/Users/vpoguru/Hauptwerk/HauptwerkSampleSetsAndComponents/OrganDefinitions
/Users/vpoguru/Hauptwerk/HauptwerkSampleSetsAndComponents/OrganInstallationPackages

Both directories have been moved.

Their actual physical locations are:

/Users/vpoguru/Dropbox (Privat)/Hauptwerk/HauptwerkDataDev/OrganDefinitions
/Volumes/SanDisk/OrganInstallationPackages

At the original locations below HauptwerkSampleSetsAndComponents, symbolic links point to these moved directories.

So, logically, Hauptwerk still sees:

/Users/vpoguru/Hauptwerk/HauptwerkSampleSetsAndComponents/
├── OrganDefinitions
└── OrganInstallationPackages

but physically the two directories are located in completely different places:

OrganDefinitions
    -> /Users/vpoguru/Dropbox (Privat)/Hauptwerk/HauptwerkDataDev/OrganDefinitions

OrganInstallationPackages
    -> /Volumes/SanDisk/OrganInstallationPackages

There is therefore no meaningful common physical parent directory between the relocated OrganDefinitions and OrganInstallationPackages directories.

What I observe

The interesting part is that relocating OrganInstallationPackages works correctly.

Masterpiece can open the organ definition from the normal logical location and subsequently finds all required samples and images, even though OrganInstallationPackages itself is actually located on /Volumes/SanDisk.

The problem only appears when OrganDefinitions is also relocated.

The organ definition XML itself can still be selected and opened without any problem. However, Masterpiece then fails to locate the files in OrganInstallationPackages.

This is the part that initially seemed strange to me: the XML file itself is available, and the symbolic link to OrganInstallationPackages is also valid, but the combination does not work once OrganDefinitions has been relocated.

Difference from the current test case

I also wonder whether my setup may differ slightly from the layout covered by the existing test.

If I understand the test correctly, the relocated OrganDefinitions directory and OrganInstallationPackages directory still have a common physical parent. In that situation, resolving the symlink and walking back up the directory hierarchy can eventually find OrganInstallationPackages.

In my actual Hauptwerk installation, that is not possible because the two physical locations are completely independent:

/Users/vpoguru/Dropbox (Privat)/Hauptwerk/HauptwerkDataDev/OrganDefinitions

and:

/Volumes/SanDisk/OrganInstallationPackages

Perhaps an additional regression test with two completely unrelated physical locations would reproduce the behaviour I am seeing.

Conceptually, something like:

HauptwerkSampleSetsAndComponents/
├── OrganDefinitions ---------> location_A/OrganDefinitions
└── OrganInstallationPackages -> location_B/OrganInstallationPackages

where location_A and location_B do not share a useful common parent.

The new "Organ folder" setting

I also tried the new Organ folder option.

The label itself is somewhat ambiguous, but the folder selection dialog is much more specific and asks:

Which folder holds the OrganInstallationPackages

This is interesting because OrganInstallationPackages is actually the directory that could already be relocated successfully in my setup.

In other words, when only this directory is moved:

OrganInstallationPackages
    -> /Volumes/SanDisk/OrganInstallationPackages

Masterpiece already follows the symbolic link correctly and the organ loads.

The problem appears only when OrganDefinitions is moved as well.

For that reason, I wonder whether this new setting may be addressing the part of the directory layout that was already working, rather than the part that is causing the remaining problem.

I have nevertheless tried changing the setting, but so far it does not appear to change the behaviour when OrganDefinitions is relocated.

If I am misunderstanding the purpose of this option, please let me know and I will gladly test the intended configuration.

Possible approaches

Ideally, I think the most transparent solution would be for Masterpiece to behave like Hauptwerk and let the filesystem handle the symbolic links without requiring any additional configuration.

For example, if the organ definition is selected through:

/Users/vpoguru/Hauptwerk/HauptwerkSampleSetsAndComponents/OrganDefinitions/MyOrgan.xml

it would be ideal if Masterpiece could preserve that logical relationship and use:

/Users/vpoguru/Hauptwerk/HauptwerkSampleSetsAndComponents/OrganInstallationPackages

for the package files. macOS would then transparently follow both symbolic links to their actual physical locations.

That would also have the advantage that a Hauptwerk installation which already works correctly would not require any additional configuration in Masterpiece.

If preserving the logical paths turns out to be difficult or unreliable, perhaps another possibility would be to provide two explicit directory settings as a fallback:

OrganDefinitions folder
OrganInstallationPackages folder

These could point directly to the real, non-symlinked physical locations, for example:

OrganDefinitions:
/Users/vpoguru/Dropbox (Privat)/Hauptwerk/HauptwerkDataDev/OrganDefinitions

OrganInstallationPackages:
/Volumes/SanDisk/OrganInstallationPackages

That would avoid having to derive the location of one directory from the location of the other.

It might also make the intended configuration less ambiguous than a single setting called Organ folder, since in a Hauptwerk installation there are really two independent locations involved.

My preference would still be for the symbolic links to work transparently without requiring additional settings, since that matches the way Hauptwerk itself sees the directory structure. But two explicit physical directory settings could perhaps provide a reliable fallback for installations where that is not possible.

These are only suggestions based on the behaviour I am seeing; I do not want to presume which implementation approach would fit the Masterpiece architecture best.

I hope the concrete paths above are useful in reproducing the issue. If it would help, I am also happy to test another build or provide additional logging from my setup.

Thank you again for continuing to investigate this.

[bonninr]

Addressed in v0.5.4, with your layout as the test case.

Masterpiece now keeps a list of sample libraries: folders holding OrganInstallationPackages. It starts with the standard Hauptwerk location, and every successful load adds its folder. When a definition's path leads to no packages, the library holding the packages that definition names is used. With OrganDefinitions and OrganInstallationPackages linked to unrelated drives, the standard location resolves the packages, so no setting should be needed.

A regression test covers two unrelated physical locations, as you suggested. The Organ folder setting remains as an override.

[vpoguru]

I was able to reproduce and isolate the issue on macOS.

The native macOS file chooser resolves the path when OrganDefinitions is a symlink. As a result, Masterpiece loses the logical relationship between OrganDefinitions and the sibling OrganInstallationPackages directory.

Loading the same ODF with --odf works because the symlink-containing path is preserved.

I implemented a fix that reconstructs the logical ODF path from the known Hauptwerk library root. This keeps the native macOS file chooser and also fixes reopening via lastorgan.

I tested it with:

• normal ODFs with audio
• an artwork-only ODF without samples
• switching repeatedly between ODFs
• reopening the last organ after restart
• a symlink whose target directory has a different name

A regression test has also been added.

I submitted PR #31 with the fix.

[bonninr]

The fix from #31 is in 0.5.5: an OrganDefinitions folder reached through a symbolic link now loads on macOS. Thank you for tracking it down. https://github.com/bonninr/masterpiece/releases/tag/v0.5.5