Clarify the language in entry.h about CLAP_PATH

[baconpaul]

I suggest two clarifications to the language in entry.h following the conversation here.

https://www.kvraudio.com/forum/viewtopic.php?t=583188&sid=2b626a18c4f414326a0a845c078b0091

The current 1.0.2 language is

// Additionally, extra path may be specified in CLAP_PATH environment variable.
// CLAP_PATH is formated in the same way as the OS' binary search path (PATH on UNIX, Path on Windows).

this language could be improved in several ways

1: The concept of 'extra path as os path' is clear to people who know how an OS path works, but not clear to others.
2: It is unclear, and therefore ambiguous, whether a host should search a directory recursively or whether it should simply look in a member of the CLAP_PATH. I am proposing that we imply a recursive search down each member of the PATH, but we can adjust the language
3: It is unclear what responsibility a plugin installer has if it chooses to install in a non-standard location. I suggest that we encourage such installers to update CLAP_PATH if the install location is not already in CLAP_PATH.

Therefore I suggest this language become

In addition to the OS-specific default locations above, a CLAP_HOST must query the environment
for a CLAP_PATH variable, which is a list of directories formatted in the same manner as the host OS
binary search path (PATH on Unix, separated by `:` and Path on Windows, separated by ';', as of this writing).

Each directory in the CLAP_PATH should be recursively searched for files and/or bundles as appropriate in your OS
ending with the extension `.clap`.

Moreover, we strongly suggest that a plugin installer install in a location which is either in the standard locations
or is in the CLAP_PATH, and if it offers alternate locations to users, guarantee that at the end of the install,
the location chosen is either a standard location or modifies the CLAP_PATH to indicate the install location to hosts.

[tim-janik]

As described in my latest KVR Post, recursive scanning is necessary (though the spec currently fails to outline this), because some plugins install into subdirectories:

~$ ls .clap/*
.clap/u-he:
ACE.64.clap
Diva.64.clap
Hive.64.clap
MFM2.64.clap

Useful clarification would include whether "hidden" subdirectories can be omitted from scanning, e.g. .samples/ or .icons/ so plugins may ship and install resources in subdirectories without causing useless subtree scans by the hosts.

[tim-janik]

The host would only scan the files matching *.clap. What's the benefit in preventing to scan hidden directories?

For instance the u-he/Hive plugin consists of over 6000 files in 236 subdirectories. Of this, only Hive.64.so is worth scanning by the host. Now the u-he installation is fairly clever in putting it all into ~/.u-he/Hive/ and then installing a single symlink from ~/.clap/u-he/Hive.64.clap into ~/.u-he/Hive/. If it was putting the entire Hive/ directory under ~/.clap/ that would slow down the scanning for *.clap files by orders of magnitudes.

So unless the spec demands that clap plugins should only be installed under clap/ as a symlink to binaries (which might not work as well under Windows or with some hosts that tend to ignore symlinks alltogether), it'd be wise to recommend a combination similar to e.g.:

1. Hidden directories should be omitted during recursive scans (under Unix, hidden directories start with a dot);
2. Plugin installations should move extra resource files into hidden subdirectories, which are omitted during recursive scans by CLAP hosts.

[abique]

22-06-17 09:43:36 abique@knot:~/d/c/b/ninja-system git:main> time find /home/abique/.u-he/ | wc -l
37949

real	0m0.030s
user	0m0.015s
sys	0m0.019s
22-06-17 09:43:39 abique@knot:~/d/c/b/ninja-system git:main> 

[abique]

Really I don't see the need to make the spec more complicated for that.

[abique]

I tried something even bigger:

22-06-17 09:45:49 abique@knot:~/d/c/b/ninja-system git:main> time find /usr/ 2>/dev/null | wc -l
506538

real	0m1.318s
user	0m0.221s
sys	0m0.500s
22-06-17 09:46:39 abique@knot:~/d/c/b/ninja-system git:main> 

So it took 1.3s to list my entire /usr consisting of 500K files on my 7 years old computer (which can't even install windows 11).

[baconpaul]

OK!

[abique]

Moreover, we strongly suggest that a plugin installer install in a location which is either in the standard locations
or is in the CLAP_PATH, and if it offers alternate locations to users, guarantee that at the end of the install,
the location chosen is either a standard location or modifies the CLAP_PATH to indicate the install location to hosts.

I'm against modifying CLAP_PATH for the user. I'd be horrified if a plugin or anything changes my environment variable. I don't trust and I would never let anyone touch my bashrc or my configuration files.

I think the right approach is:

• offer to install in default location, system wide or in the user's home
• otherwise let the user specify its directory and be responsible for setting up his DAW correctly, may that be using CLAP_PATH or just the DAW settings.

What do you think?

[Bremmers]

also would love feedback from @Bremmers on this

Frankly, I think CLAP_PATH is a bad idea that will cause problems. Let's remove it while we can.

In any case, plugins shouldn't set it themselves. Perhaps hosts shouldn't set it either, so only tech-geek users can use this. Plugin installers should just use the default location if CLAP_PATH isn't set.

[abique]

CLAP_PATH is still useful.
But I agree that a basic user should not be concerned at all with it, ideally he should not even know its existence.
It is so easy to add an extra location in your DAW, while adding an extra environment variable is difficult.

[abique]

@baconpaul I've used your two first paragraphs, but I think we don't need to say anything regarding installers. #106

[robbert-vdh]

Yes CLAP_PATH should definitely not be modified automatically, It's a feature that exists for power users, and it should not be too visible for 'normal' users. But for those power users it still needs to exist, and if it's not defined by the spec then everyone will just come up with its own solution. Similar things have already happened with other plugin specifications, so having it be standardized like this is a good idea IMO.

[baconpaul]

I agree.

[jpcima]

If I may ask regarding bundles:

a fair bit ago, I asked on KVR about whether CLAP can support bundles in VST3's fashion;
this was answered with yes, but there seems no explicit info about this anywhere.

Could one install a file structure like this in a CLAP folder and expect it to work on windows and linux OS?

my.clap/Contents/Binary/my.clap
my.clap/Contents/Resources/sample.wav

[robbert-vdh]

Then the scanning logic in those hosts are broken. And then we'd be seeing the same issue with VST3 on Windows. When walking a directory to scan for plugins you'd recurse through all directories and symlinks to directories, and then find all non-directory files in those directories with a .clap extension. I don't think anyone would specifically add a filter to stop recursing after a directory that ends in .clap.

[baconpaul]

Or in other words, when scanning for .clap files a correct host does this

            for (auto const &dir_entry : std::filesystem::recursive_directory_iterator(p))
            {
#if MAC
                if (dir_entry.path().extension().u8string() == ".clap" &&
                    std::filesystem::is_directory(dir_entry.path()))
                {
                    claps.emplace_back(dir_entry.path());
                }
#else
                if (dir_entry.path().extension().u8string() == ".clap" &&
                    std::filesystem::is_regular_file(dir_entry.path()))
                {
                    claps.emplace_back(dir_entry.path());
                }
#endif
      }

[robbert-vdh]

The std::filesystem::is_regular_file line should be (std::filesystem::is_regular_file(dir_entry.path())) || std::filesystem::is_symlink(dir_entry.path()))). Or for most practical purposes, a !std::filesystem::is_directory is probably also good enough.

[jpcima]

Can it also be clarified what is the plugin_path provided by init?
does the point to the executable or bundle, on the Mac platform?

[baconpaul]

Good point JP. The path points to the renamed dll on lin win and the bundle on mac indeed