File::Find: fix "follow => 1" on Windows

[xenu]

File::Find's code expects unix-style paths and it manipulates them using
basic string operations. That code is very fragile, and ideally we
should make it use File::Spec, but that would involve rewriting almost
the whole module.

Instead, we made it convert backslashes to slashes and handle drive
letters.

Note from xenu: this commit was adapted from the PR linked in this
blogpost[1]. I have squashed it, written the commit message and slightly
modified the code.

[1] - https://www.nu42.com/2021/09/canonical-paths-file-find-way-forward.html

Fixes #19995

[xenu]

Note for reviewers: one of the commits converts tabs to spaces, make sure to hide whitespace changes.

[sisyphus]

This PR fixes the issue with Module::Pluggable. Thanks @xenu, for digging through all of that.
However, it turns out that the issue with Module::Find is a different one - and not addressed by this PR..

The failing test script in Module::Find is t/07-symlinks.t.
That file tests to see whether symlinks are available or not by running:

SKIP: {
    eval { symlink($dirName, $linkName) };
    skip "Symlinks not supported on this system", 13 if $@;
.....

On my Windows systems, with perl-5.32 (File-Find-1.37), $@ is set and all 13 tests are skipped - as is the correct thing to do, IIUC.
But with perl-5.34, 5.36, and this PR, $@ is unset and it is therefore assumed (incorrectly) that symlinking is available.
Of course, that symlink() call has returned 0, but it seems that a return of 0 merely signifies that the call failed - not that symlinking is unavailable.
The symlink documentation says:

>perldoc -f symlink
    symlink OLDFILE,NEWFILE
            Creates a new filename symbolically linked to the old filename.
            Returns 1 for success, 0 otherwise. On systems that don't
            support symbolic links, raises an exception. To check for that,
            use eval:

                my $symlink_exists = eval { symlink("",""); 1 };

            Portability issues: "symlink" in perlport.

which is the behaviour that t/07-symlinks.t is checking for.
Unfortunately that documentation is, as of File-Find-1.39, no longer correct on Windows systems that don't support symlinks.

Cheers,
Rob

[Leont]

That check in Module::Find isn't quite what the docs say it should be, and should be changed IMO.

[sisyphus]

That check in Module::Find isn't quite what the docs say it should be, and should be changed IMO

But even if it strictly adheres to the docs, I still get different results between 5.32 and this PR.

With perl-5.32:

C:\>perl -e "$x = symlink('',''); print $x;"
The symlink function is unimplemented at -e line 1.

C:\>

With this PR:

C:\>perl -e "$x = symlink('',''); print $x;"
0
C:\>

IIU the symlink() docs correctly, we should be getting an exception in both cases - given that symlinks are unsupported on this system of mine.

Cheers,
Rob

[Leont]

IIU the symlink() docs correctly, we should be getting an exception in both cases - given that symlinks are unsupported on this system of mine.

The OS supports it, they're just not enabled. Hence symlink returns 0.

[xenu]

The best ways to check if you have the required permissions to create a symlink on Windows are:

• Attempt to create a symlink and check if $! gives you "operation not permitted" code
• Win32::IsSymlinkCreationAllowed

[blues1875]

I have never used symlinks on Windows before, but I find I can create them on my Windows 10 machine (as Administrator). I did a basic test of File::Find using my Strawberrry Perl 5.32 and 5.36 installations, with File::Find 1.37 and 1.40 respectively. This is what I found:

• File::Find 1.37

  • follow unset: find follows the symlink
  • follow => 0: find follows the symlink
  • follow => 1: find follows the symlink

• File::Find 1.40

  • follow unset: find does not follow the symlink
  • follow => 0: find does not follow the symlink
  • follow => 1: find follows the symlink

It looks to me like the functionality is correct for 1.40.
I see the documentation for 1.37 has the warning: "This is a no-op on Win32" for the 'follow' option. I'm not sure if that means that the module is not expected to follow symlinks or that the option doesn't work. It seems that the functionality to follow symlinks does work (on Windows 10 at least), but the option to disable it doesn't.
Interestingly, although the behaviour seems to have been fixed in 1.40, the caveat in the documentation is still there.

[xenu]

the caveat in the documentation is still there.

I noticed it too, which is why this PR removes it :)

[sisyphus]

The OS supports it, they're just not enabled. Hence symlink returns 0.

Ok - If no-one beats me to it, I'll update crenz/Module-Find#9 accordingly.
Use of Win32::IsSymlinkCreationAllowed() is apparently only available beginning perl-5.34.0 but I think it's possible to make use of symlink() in a way that does what is needed here, anyway.

Cheers,
Rob

[xenu]

Use of Win32::IsSymlinkCreationAllowed() is apparently only available beginning perl-5.34.0

That's also the version where support for symlinks was introduced. Basically, when you're on Windows and $Config{d_symlink} is true, Win32::IsSymlinkCreationAllowed() is guaranteed to be present.

my $can_symlinks_be_used = sub {
  return 0 if !$Config{d_symlink};

  if ($^O eq 'MSWin32') {
    require Win32;
    return Win32::IsSymlinkCreationAllowed();
  }
  else {
    return 1;
  }
}->();

[sisyphus]

Can/will this fix be backported to future 5.34.x and 5.36.x releases ?