DEV Community: Håkon Hægland

Using Google Drive with Perl

Håkon Hægland — Thu, 14 Oct 2021 22:23:47 +0000

I often use Google Drive to transfer files between devices, for example from my Mac to my Linux laptop. It works great, but there can be some boring repetitive work involved depending on how often you do the same operation. For example, when I want to transfer a file from the Mac, I open up a web browser (usually Google Chrome) and point it to drive.google.com, the Google Drive web interface. From here, I try to locate the directory I want to upload the file to which might involve some scrolling in the directory listing. After that, I need to click on the directory name to view its content. Next, I right-click on an empty area in the directory list and select "Upload files" from a drop-down menu. Then a file selection dialog appears and I have to locate the directory and file I want to upload in the dialog, and after some more mouse movements and clicks I finally press the "Ok" button to select the file. Similarly, on the other device (like my Linux laptop) where I want to download the file, I need to locate the file in web UI and then right-click it and select "Download" from the drop-down menu to download the file.

Luckily, Google has provided the Google Drive API that can be used by user scripts to communicate with the cloud server. So the first thing I wanted to check was if someone already had written Perl code that made use of this API. After a quick search on MetaCPAN I found a module Net::Google::Drive::Simple that looked promising. When reading through the module's documentation, I realized that the tricky part could be to get hold of an "access token". The script needs this token to be able to connect to the Google Drive API server. The module claimed that it could generate the access token from a secret credential token which I first had to obtain from Google Cloud. Then, when the module had generated this access token the rest should be fairly simple was my impression. Well.., let's see what happend 👾

Creating a Google account

In order to get the Google Drive credentials, the first thing you need to have is a Google account (obviously). This allows you to use Google developer products, including Google Cloud Console, Cloud SDK, Cloud Logging, and Cloud Monitoring. If you don't have a Google account, you can visit https://cloud.google.com/apis/docs/getting-started to get started. Creating a Google account, with some amount of cloud storage is free, see https://cloud.google.com/free for more information.

Creating a Google project

Next, to use the Cloud APIs you need to set up a Google project. A project is equivalent to a developer account. It serves as a resource container for your Google Cloud resources and provides an isolation boundary for your usage of Google Cloud services, so you can manage quota limits and billing independently at the project level. Usage telemetry and dashboards are grouped by projects as well. If you don't already have a project, you can create one using the Cloud Console, see this link for more information. Here is what I did to create a new project:

In the Google Cloud console, click the drop down menu in top left corner, and select "IAM & Admin" -> "Manage Resources",
from the "Select organization" drop-down list at the top of the page, you can select the organization in which you want to create a project. If you are a free trial user, skip this step, as this list does not appear.
Then click "Create Project", and in the "New Project" window that appears, enter a project name.

A project name can contain only letters, numbers, single quotes, hyphens, spaces, or exclamation points, and must be between 4 and 30 characters. I chose "DesktopApp" for the project name, and will use this name in the further discussion.
Enter the parent organization or folder in the "Location" box. That resource will be the hierarchical parent of the new project. If you do not have a parent folder, just leave "No organization" (as I did) in the "Location" box.
When you're finished entering new project details, click the "CREATE" button.

Enabling the Google Drive API

Next, in order to use Google Drive API from a script you need to enable it.

In the Google Cloud console, click the drop down menu in top left corner, and select "APIs & Services" -> "Library". Type "Google Drive" in the search bar. Select "Google Drive API" from the result list.
Select the "DesktopApp" project, by clicking project button in the top menu bar. If it already shows "DesktopApp", you can skip this step.
Click the "ENABLE" button.

Configure the app's scopes and the consent screen

The script that we will write to access Google Drive is called an "app". The "user" of the script is in our case the same as the writer (ourselves) of the script, but it need not be. You could send the script to someone else or publish it on the internet. In order for the app to get access to the user's Google Drive, the user must approve that script can access his drive under a certain "scope". For example, the user may give the script read-only access.

The first time the script is trying to access the drive, the user is presented with a "consent screen" where they can select which scopes the script can use to access their drive. After the user has given their consent, the Google Cloud server returns an access token to the script which it can use to access the drive without asking the user for permission the next time. The access token will expire after a certain time, and then the script needs to refresh the token. The user can also revoke the access right of the script at a later time if they so wishes, then the script's access token becomes invalid and it cannot be refreshed. The script must then repeat the process with presenting the user with the consent screen in order to get further access. Read more about the OAuth2 protocol for authentication here.

Now, in order to setup what scopes should be presented to the user in the consent screen (see workspace/guides/create-credentials) do the following:

In the Google Cloud console, click the drop down menu in top left corner, and select "APIs & Services" -> "Credentials". The credential page for your project appears.
Select the "DesktopApp" project, by clicking project button in the top menu bar. If it already shows "DesktopApp", you can skip this step.
Click the "CONFIGURE CONSENT SCREEN" button on the right side. (If you have already configured the consent screen and want to modify it, you should instead click on "OAuth consent screen" in the left side bar)

Select the user type for the app. Click "External".
(If you are a google workspace user and wants the app to be internal to your organization, you could select "Internal" instead.)
Click the "CREATE" button
In the App information screen, type in a name for the app. This name will appear in the consent screen that is presented to the user during the authorization procedure.

Enter your email in the "User support email" field.
Skip the "App logo" field.
Also skip the "App domain" fields.
Also skip the "Authorized domains" field.
Enter your email address in the "Developer contact information" field.
Click the "SAVE AND CONTINUE" button
In the "Edit app registration" screen, click the "ADD OR REMOVE SCOPES" button.

From the popup window "Update selected scopes" click the checkmark next to the following scopes:
- .../auth/drive.file
- .../auth/drive.metadata.readonly
- .../auth/drive.readonly
Note that only the scopes you select in the popup window can be requested by the app. For instance, if the app later requests all of the above three scopes, the user will be presented with a consent screen with the three alternatives, like this:

The first alternative in the screen shot above corresponds to the drive.readonly scope, the second corresponds to the drive.metadata.readonly scope, and the third one corresponds to the drive.file scope.
Click the "UPDATE" button at the bottom of the window
Click "SAVE AND CONTINUE" in the "Edit app registration" screen.
In the "Test users" screen, click the "+ ADD USERS" button, and add yourself (your gmail address) to the list.
Click "SAVE AND CONTINUE".
The Summary screen is shown. Click the "BACK TO DASHBOARD" button.

Create credentials

In order for the app (the script) to obtain an access token, it needs to pass a set of credentials to to the Google authorization server. Together with the credentials, the script passes (as a parameter) the set of scopes that it would like to access. The authorization server then present the user of the script with a screen where they can log in with their Google account. After logging in, the user is asked whether they are willing to grant one or more permissions that your app is requesting. This process is called user consent as discussed in the previous section.

To obtain the set of credentials that the script should present to the authorization server (see: workspace/guides/create-credentials), we do the following:

In the Google cloud console, click the drop down menu in top left corner, and select "APIs & Services" -> "Credentials". The credential page for your project appears.
Select the "DesktopApp" project, by clicking project button in the top menu bar. If it already shows "DesktopApp", you can skip this step.
Click the "+ CREATE CREDENTIALS" button on the top of the
page. Select "OAuth Client ID" from the drop down menu.
Select "Desktop app" from the "Application type" drop down menu.
Select a client name in the "Name" field, or use the suggested name.
Click the "CREATE" button at the bottom of the page.
Click "OK" in the "OAuth client created" dialog box.
Next, still in the Google cloud console: click the drop down menu in top left corner, and select "APIs & Services" -> "Credentials". The credential page for your project appears.
Select the "DesktopApp" project, by clicking project button in the top menu bar. If it already shows "DesktopApp", you can skip this step.
Under "OAuth 2.0 Client IDs", click the download button under the "Actions" heading.
Select "DOWNLOAD JSON" in the popup window.
Rename the file as "credentials.json" on your computer.

Obtaining the access token

Now as we have the credentials, we can obtain the access token. I have rewritten the google-drive-init script provided by Net::Google::Drive::Simple slightly:

use v5.26; # Indented here-docs introduced in 5.26
use feature qw(say);
use strict;
use warnings;
use experimental qw(signatures);
use open qw(:std :encoding(utf-8));
use OAuth::Cmdline::GoogleDrive;
use OAuth::Cmdline::Mojo;
use JSON;
{
    my $credentials = read_credentials();
    my $token_dir = '.';
    # NOTE: if you change the scopes below, you should delete the previous
    #  access token file (.google-drive.yml) and then rerun this script..
    my @scopes  = (
        "drive.file",
        "drive.metadata.readonly",
        "drive.readonly"
    );
    my $scopes = join ' ', map { "https://www.googleapis.com/auth/$_" } @scopes;
    my $oauth = OAuth::Cmdline::GoogleDrive->new(
        client_id     => $credentials->{client_id},
        client_secret => $credentials->{client_secret},
        login_uri     => $credentials->{auth_uri},
        token_uri     => $credentials->{token_uri},
        scope         => $scopes,
        homedir       => $token_dir
    );
    print <<~'INFO_STR';
    Running the token collector web server at http://localhost:8082
    - Open your web browser and go to http://localhost:8082, then click the link
      "Login on google-drive" and fill out the OAuth consent screen granting
      your Perl scripts access to your google drive.
    - Click the check boxes for what the app can access (the scopes)
    - Then click "Continue"
    - When the message "Tokens saved in ./.google-drive.yml" appears, the
      access token was successfully generated and saved to the local file
      .google-drive.yml.
    - You can then quit the server (this script) by pressing CTRL-C.
    ----------------------------------------------------------------
    INFO_STR
    my $app = OAuth::Cmdline::Mojo->new(
        oauth => $oauth,
    );
    $app->start( 'daemon', '-l', $oauth->local_uri );
    # After you filled out the consent screens, you need to press CTRL-C in the shell
    #  window to exit this script.
    say "Server finished.";
    say "Done.";
}


sub read_credentials {
    my $fn = 'credentials.json';
    open ( my $fh, '<', $fn ) or die "Could not open file '$fn': $!";
    my $str = do { local $/; <$fh> };
    close $fh;
    my $json = JSON->new();
    my $hash = $json->decode( $str );
    die "$fn: Expected installed app" if !(exists $hash->{installed});
    return $hash->{installed};
}

If you run this script (after installing OAuth::Cmdline), the access token should be saved in a file .google-drive.yml in the current directory.

Uploading a file to Google Drive

Finally, we have the access token and we can start to use the module Net::Google::Drive::Simple. We will start by uploading a file to Google Drive. Unfortunately, when I tested the file_upload( $file, $dir_id ) method, it did not work as expected, see issue # 47. I created a pull request to fix the issue. Since the pull request has not yet been merged I suggest that you (if you want to upload files) install the module (Net::Google::Drive::Simple) like this:

git clone https://github.com/mschilli/net-google-drive-simple.git
cd net-google-drive-simple
git fetch origin pull/48/head:pr_48
git checkout pr_48
cpanm .

Now, create a dummy hello.txt file that we will upload to the root directory of Google Drive:

$ echo "Hello world!" > hello.txt

Then save the following script as upload.pl (in the same directory as you have the access token file):

use feature qw(say);
use strict;
use warnings;
use Net::Google::Drive::Simple;
use OAuth::Cmdline::GoogleDrive;

my $token_dir = '.';
my $oauth = OAuth::Cmdline::GoogleDrive->new(
    scope         => "https://www.googleapis.com/auth/drive.file",
    homedir       => $token_dir
);
my $gd = Net::Google::Drive::Simple->new( oauth => $oauth );
my $file = 'hello.txt';
my $parent = 'root';
my $file_id = $gd->file_upload( $file, $parent ) or die "Upload failed: $!";
say "Uploaded file: $file (id: $file_id) to directory with id: $parent";

Then run the script:

$ perl upload.pl
Uploaded file: hello.txt (id: 1x5pc9_rvAFeLgkp0zLUeuKAIMWptplz9) to directory with id: root

to upload the hello.txt file to your Google Drive!

Downloading a file from Google Drive

It is not enough to simply specify the directory and filename to download a file. There can be multiple files with the same name in the same directory, however a file's ID is unique. When we uploaded the hello.txt the API returned the ID of the uploaded file, namely 1x5pc9_rvAFeLgkp0zLUeuKAIMWptplz9. Another way to determine the ID is to right click a file in the Google Drive UI and select "Get link" from the drop down menu. If you know that the file name is unique, a third way is to use the search() method. I first show how to download a file when you know the ID. The following script can download a file that the app created (if you want to download any file, you should replace the drive.file scope with the drive.readonly scope) :

use feature qw(say);
use strict;
use warnings;
use Net::Google::Drive::Simple;
use OAuth::Cmdline::GoogleDrive;

my $token_dir = '.';
my $oauth = OAuth::Cmdline::GoogleDrive->new(
    scope         => "https://www.googleapis.com/auth/drive.file",
    homedir       => $token_dir
);
my $gd = Net::Google::Drive::Simple->new( oauth => $oauth );
my $file_id = '1x5pc9_rvAFeLgkp0zLUeuKAIMWptplz9';
my $url = download_url($file_id);
say "Downloading from: $url";
my $save_fn = 'hello2.txt';
if ($gd->download($url, $save_fn)) {
    say "Downloaded file with id '$file_id' as '$save_fn'";
}
else {
    die "Failed to download $file_id: ", $gd->error();
}

sub download_url {
        'https://www.googleapis.com/drive/v2/files/'
      . $_[0]
      . '?alt=media&source=downloadUrl';
}

Alternatively, if you know that the file name is unique across the whole Google Drive and you don't want to look in the UI for the file ID, you can use the search() method like this:

use feature qw(say);
use strict;
use warnings;
use Net::Google::Drive::Simple;
use OAuth::Cmdline::GoogleDrive;

my $token_dir = '.';
my $oauth = OAuth::Cmdline::GoogleDrive->new(
    scope         =>  ( "https://www.googleapis.com/auth/drive.readonly" . ' '
                     . "https://www.googleapis.com/auth/drive.file"),
    homedir       => $token_dir
);
my $gd = Net::Google::Drive::Simple->new( oauth => $oauth );
my $fn = 'hello.txt';
my $children= $gd->search(
    { maxResults => 2 },
    { page => 1 },
    "title = '$fn'"
);
die "Multiple files matching '$fn' found." if @$children > 1;
die "No files matching '$fn' found." if @$children == 0;

my $child = $children->[0];
my $save_fn = 'hello2.txt';
if ($gd->download($child, $save_fn)) {
    say "Downloaded file with name '$fn' as '$save_fn'";
}
else {
    die "Failed to download $fn: ", $gd->error();
}

Handling of symlinks on Windows (Perl, MSYS2, Cygwin)

Håkon Hægland — Sun, 04 Jul 2021 16:14:53 +0000

After reading about the Perl language server module for VS Code,
I was eager to test it since I had been missing a possibility to debug Perl code from inside VS Code. In the past I have been using emacs as my primary editor for a long time, but am gradually using VS Code more and more now. VS Code has built-in debugging support for the Node.js runtime and can debug JavaScript, TypeScript. For debugging other languages one can install Debugger extensions in the VS Code Marketplace.

The Language Server and Debugger for Perl VS Code extension allows debugging of Perl scripts, see the link above for an extensive list of features. To use the extension you first need to install the Perl module Perl::LanguageServer. I first tried to install it on Ubuntu 21.04. The module installed fine here, but after installation the extension still did not work. I found that the reason was that I was using a custom perl installed with perlbrew. Fortunately, it was easy to fix by going into the extension settings and setting an absolute path to the binary:

Next, I was curious to see if it also would install on Windows. Even if my preferred platform is Linux, I occasionally use Windows. For example when trying to answer questions on Stack Overflow that are related to Perl and Windows. I am using Windows 10 (run from Ubuntu through KVM), Home edition, 21H1, and Strawberry perl version 5.32.1. As anticipated, I quickly ran into issues with installing dependent modules, in particular IO::AIO was difficult.

I downloaded the source and tried to install IO::AIO manually (not using cpanm) first:

>perl Makefile.PL
[...]
*** It seems you are running perl version 5.032001, likely the "official" or
*** "standard" version. While there is nothing wrong with doing that,
*** standard perl versions 5.022 and up are not supported by IO::AIO.
*** While this might be fatal, it might also be all right - if you run into
*** problems, you might want to downgrade your perl or switch to the
*** stability branch.
***
*** If everything works fine, you can ignore this message.
***
***
*** Stability canary mini-FAQ:
***
*** Do I need to do anything?
***    With luck, no. While some distributions are known to fail
***    already, most should probably work. This message is here
***    to alert you that your perl is not supported by IO::AIO,
***    and if things go wrong, you either need to downgrade, or
***    sidegrade to the stability variant of your perl version,
***    or simply live with the consequences.
***
[...]

*** Your platform is not standards compliant. To get this module working, you need to
*** download and install win32 pthread (http://sourceware.org/pthreads-win32/).
***

Generating a gmake-style Makefile
Writing Makefile for IO::AIO
Writing MYMETA.yml and MYMETA.json

Apparently it wants me to install POSIX Threads for Windows. I also noticed that the Makefile.PL is calling GNU Autotools configure script which, as far as I know, cannot be run without a POSIX subsystem like Cygwin or MSYS2.

Since I already had Cygwin and MSYS2 installed, I decided to give MSYS2 a try. According to wikipedia, MSYS2 ("minimal system 2") is a software distribution and a development platform for Windows, based on Mingw-w64 and Cygwin, that helps to deploy code from the Unix world on Windows. Instead of providing a full environment like Cygwin does, MSYS2 focuses on being a development and deployment platform.

From the MSYS2 terminal window, also using perl version 5.32.1 (but still a different binary than the perl used by the CMD prompt):

$ perl Makefile.PL
[...]
*** The stability canary says: (nothing, it was driven away by harsh weather)
***
*** It seems you are running perl version 5.032001, likely the "official" or
*** "standard" version. While there is nothing wrong with doing that,
*** standard perl versions 5.022 and up are not supported by IO::AIO.
*** While this might be fatal, it might also be all right - if you run into
*** problems, you might want to downgrade your perl or switch to the
*** stability branch.
***
*** If everything works fine, you can ignore this message.
***
[...]
Continue anyways?  [y]
configure: loading site script /etc/config.site
checking for gcc... gcc
checking whether the C compiler works... yes
checking for C compiler default output file name... a.exe
checking for suffix of executables... .exe
checking whether we are cross compiling... no
checking for suffix of object files... o
checking whether we are using the GNU C compiler... yes
checking whether gcc accepts -g... yes
checking for gcc option to accept ISO C89... none needed
checking how to run the C preprocessor... gcc -E
[...]
checking for st_birthtimespec... yes
checking for st_gen... no
checking for statx... no
checking for accept4... yes
configure: creating ./config.status
config.status: creating config.h
Generating a Unix-style Makefile
Writing Makefile for IO::AIO
Writing MYMETA.yml and MYMETA.json
$ make
$ make test
[...]
t/03_errors.t ... 1/12 # Failed test 9 in t/03_errors.t at line 57
#  t/03_errors.t line 57 is:       ok (!$_[0]);
# Failed test 10 in t/03_errors.t at line 58
#  t/03_errors.t line 58 is:       ok ("\\test\\" eq readlink $some_link);
t/03_errors.t ... Failed 2/12 subtests
[...]

And more failed tests were to come. Most fails were due to an unexpected behavior of symlinks on Windows and MSYS2. Even if I was able to fix the issue with IO::AIO, there were other issues with other modules also needed by Perl::LanguageServer.

Despite this setback, I saw it as an opportunity to learn more about symlinks on Windows. Apparently there were similar issues with other modules that also needed to be fixed. As I was working with a pull request to file-copy-recursive-reduced I was encouraged to write this blog post.

Symlinks on Windows (MSYS2 and Cygwin)

A symlink is a file that contains a reference to another file or directory in the form of an absolute or relative path. The referenced text string is automatically followed by the operating system as a path to another file or directory. This other file or directory is called the "target". So the symlink is a second file that exists independently of its target. If a symlink is deleted, its target remains unaffected. If a symlink points to a target, and sometime later that target is moved, renamed or deleted, the symlink is not automatically updated or deleted, but continues to exist and still points to the now non-existing target. Symlinks pointing to non-existing targets are called broken symlinks.

On Unix-like operating systems, the target does not have to exist when a symlink is created, so broken symlinks can even be created initially. The ability to create broken symlinks is particularly useful when copying directories. Usually, the algorithm used to copy a directory just copies the files in the order returned by the readdir() system call and since it is legal to create broken symlinks it does not need to copy the target of a relative symlink before the symlink itself is copied.

So on Unix-like operating systems symlinks and broken symlinks can always be created, whereas on Windows this is not always the case. Early versions of Windows did not have symlinks of any kind, Windows 95 introduced file shortcuts, Windows XP introduced native symlinks (only enabled by default for kernel mode programs), and starting with Windows 10 Insider build 14972, native symlinks could be created without needing to elevate the console as administrator (to enable this, go to the Windows settings app and choose "Update & Security" -> "For developers", and turn on "Developer mode").

Even if the Windows shortcut file is just a metafile used by the Windows File Explorer, it has been used by Cygwin to emulate symlinks. However, the Cygwin shortcut file cannot be read properly by the File Explorer since it lacks many of the expected header fields, whereas a shortcut file created in the File Explorer can be read by Cygwin.

In addition to this, in Cygwin and MSYS2 there is a further complication to the creation of symlinks. In Cygwin, creation of symlinks depends on an environment variable called CYGWIN. Depending of the content of this environment variable, the creation of broken symlinks may fail, or the creation of non-broken symlinks may fail if developer mode (see discussion above) is not activated. The environment variable also regulates whether the symlink will be created as a shortcut file or as a native symlink.

Behavior of `ln -s` on Cygwin

The behavior of the ln --symbolic <target> <destination> command in Cygwin depends on the environment variable CYGWIN which is used to configure many global settings for the Cygwin runtime system. It contains options separated by blank characters. The option that is important for the ln -s command is called winsymlinks. According to the Cygwin documentation, there are four cases for the winsymlinks option to consider:

winsymlinks is not defined. (Note: this behavior differs from that of MSYS2, see below). This is called the default behavior for Cygwin.
a) If native symlinks are enabled (see discussion above), then this is equivalent to setting winsymlinks to native (e.g. CYGWIN=winsymlinks:native), see 3) below.
b) If native symlinks are not enabled, this is equivalent to setting winsymlinks to lnk see 2) below.
winsymlinks is empty (CYGWIN=winsymlinks) or winsymlinks is set to lnk (e.g. CYGWIN=winsymlinks:lnk)
Whether <target> exists or not, ln -s creates as a Windows shortcut file.
winsymlinks:native
a) If native symlinks are enabled, and whether <target> exists or not, creates <destination> as a native Windows symlink. Note, this is most similar to the behavior of ln -s on *nix.
b) If native symlinks are not enabled, it is equivalent to setting winsymlinks to lnk, see 2) above.
winsymlinks:nativestrict
a) If native symlinks are enabled and <target> exists, creates <destination> as a native Windows symlink,
b) else if native symlinks are not enabled or if <target> does not exist, ln -s fails.

Behavior of `ln -s` on MSYS2

Similiarly to the CYGWIN environment variable, the MSYS environment variable is used to configure global settings for the MSYS2 runtime system (since MSYS2 is based on Cygwin). The four cases for the winsymlinks option to consider is:

winsymlinks is not defined. The default behavior for MSYS2. (Note: this is not similar to Cygwin)
a) If <target> exists, <target> is (surprise!!) copied to <destination>, so <destination> does not become a symlink but simply a copy of <target>, this happens whether <target> is a file or a directory, or whether native symlinks are enabled or not.
b) If <target> does not exist, ln -s fails.
winsymlinks or winsymlinks:lnk : (Similar to Cygwin, see above)
winsymlinks:native : (Similar to Cygwin, see above)
winsymlinks:nativestrict : (Similar to Cygwin, see avove)

Behavior of symlinks in Perl on Windows (MSYS2 and Cygwin)

In both MSYS2 and Cygwin,

     perl -MConfig -E'say $Config{d_symlink}'

prints define (meaning the symlink call is implemented), whereas in regular windows (CMD prompt and $^O eq "MSWin32") with e.g. strawberry perl, $Config{d_symlink} is only defined for perl versions >= 5.33.5, see perldelta.

So the perl symlink function "works" on MSYS2 and Cygwin, and for newer versions of MSWin32. However, since the newest Strawberry perl release is currently at 5.32.1, I was not able to test how symlinks behave with MSWin32. I will therefore in the following focus on Cygwin and MSYS2.

It would be nice if one could easily check from within a Perl script if developer mode was on and thus native symlinks were enabled. However, the only way I found was to use XS (a C extension) to check the value of the registry key SOFTWARE\Microsoft\Windows\CurrentVersion\AppModelUnlock.

For the further discussion below, consider the Perl statement:

  symlink $target, $dest;

If $dest exists, the symlink command always fails (returning a value of 0 and setting $!). So consider the case where $dest does not exist: There are four cases for the winsymlinks option contained in the MSYS or CYGWIN environment variable to consider, as was done above for the ln -s command. It turns out that symlink behaves identically to the ln -s command, and when ln -s fails, symlink also fails and returns a value of 0 and sets $! (ERRNO).

Also note that the environment variables MSYS or CYGWIN cannot/should not be changed from within the Perl script itself. I am not sure why this does not work, but I tested it and it showed undefined behavior in my tests. So the variables should be set before perl is run, e.g. on the command line:

  MSYS=winsymlinks:native perl p.pl

What about the perl -l operator ? Tests show that it does not differentiate between a Windows shortcut file and a native symlink file. So

  say "symlink" if -l "foobar";

prints "symlink" for both file types. Further, there seems to be no tool available to determine which of the two file types a given symlink file is. This means that when copying a symlink file, it is difficult to determine if the destination should be a native symlink or a windows shortcut. Hence, copying a symlink can silently convert a native symlink to a shortcut file depending on the setting of the CYGWIN or MSYS environment variable and this is also how the cp command in MSYS2 (or Cygwin)

 cp -a source destination

works.

Summary

The behavior of symlinks is more complicated on Windows than on Linux. This is mainly a problem for programs that needs to copy directories. These programs may fail unexpectedly if they do not handle the different options in the CYGWIN or MSYS2 environment variables. If the user does not set the environment variables, the default (meaning that the user did not set the CYGWIN variable) behavior on Cygwin is such that it will never fail if the target of the symlink does not exist or if native symlinks are not enabled. However, the default behavior on MSYS2 is different. MSYS2 will by default not create a symlink when a symlink is apparently created by calling ln -s. Instead it creates a copy of the target file. If the target file does not exist, ln -s fails.

Epilouge

I was in the end able to install Perl::LanguageServer on MSYS2, but when VS Code tried to use it, it crashed. I believe it was due to the module IO::AIO, but I have not looked further into the issue. I also discovered a new Perl module called PLS. This module is currently under active development and implements features like auto-completion. However, it currently does not implement the Debug Adapter Protocol so debugging is not available. This module also installed fine from my Windows CMD prompt (it uses IO::Async instead of IO::AIO), but it does not run from VS Code when I tested it. From the discussion on reddit I guess this problem will hopefully be fixed soon.