Perl::...Server(3pm)

📦
version 2.6.2 · 2 versions
, in debian trixie, ubuntu noble, ubuntu resolute, ubuntu stonking

✨ NAME ✨

okay so bestie, this page is all about Perl::LanguageServer — a Language Server and Debug Protocol Adapter for Perl 💖 (it ships as part of the User Contributed Perl Documentation, iykyk).

🌸 VERSION 🌸

Version 2.5.0 💅

🦋 SYNOPSIS 🦋

This is a Language Server and Debug Protocol Adapter for Perl.

It implements the Language Server Protocol, which hands syntax-checking, symbol search, etc. for Perl to your editor — think Visual Studio Code or Atom 👑

<https://microsoft.github.io/language-server-protocol/specification>

It also implements the Debug Adapter Protocol, which lets you debug with various editors/includes 🐛

<https://microsoft.github.io/debug-adapter-protocol/overview>

Should work with any Editor/IDE that support the Language-Server-Protocol. No cap.

To use both with Visual Studio Code, install the extension perl.

Any comments and patches are welcome 🫶

🎀 DOCUMENTATION 🎀

Language Server and Debug Protocol Adapter for Perl.

👑 Features 👑

  • Language Server
    • Syntax checking
    • Symbols in file
    • Symbols in workspace/directory
    • Goto Definition
    • Find References
    • Call Signatures
    • Supports multiple workspace folders
    • Document and selection formatting via perltidy
    • Run on remote system via ssh
    • Run inside docker container
    • Run inside kubernetes
  • Debugger
    • Run, pause, step, next, return
    • Support for coro threads
    • Breakpoints
    • Conditional breakpoints
    • Breakpoints can be set while program runs and for modules not yet loaded
    • Variable view, can switch to every stack frame or coro thread
    • Set variable
    • Watch variable
    • Tooltips with variable values
    • Evaluate perl code in debuggee, in context of every stack frame of coro thread
    • Automatically reload changed Perl modules while debugging
    • Debug multiple perl programs at once
    • Run on remote system via ssh
    • Run inside docker container
    • Run inside kubernetes

🧚 Requirements 🧚

You need to install the perl module Perl::LanguageServer to make this extension work, e.g. run cpan Perl::LanguageServer on your target system.

Please make sure to always run the newest version of Perl::LanguageServer as well, bestie 🙈

NOTE: Perl::LanguageServer depend on AnyEvent::AIO and Coro. There is a warning that this might not work with newer Perls. It works fine for Perl::LanguageServer. So just confirm the warning and install it.

Perl::LanguageServer depends on other Perl modules. It is a good idea to install most of then with your linux package manager.

e.g. on Debian/Ubuntu run:

sudo apt install libanyevent-perl libclass-refresh-perl libcompiler-lexer-perl \
libdata-dump-perl libio-aio-perl libjson-perl libmoose-perl libpadwalker-perl \
libscalar-list-utils-perl libcoro-perl

sudo cpan Perl::LanguageServer

e.g. on Centos 7 run:

sudo yum install perl-App-cpanminus perl-AnyEvent-AIO perl-Coro
sudo cpanm Class::Refresh
sudo cpanm Compiler::Lexer
sudo cpanm Hash::SafeKeys
sudo cpanm Perl::LanguageServer

In case any of the above packages are not available for your os version, just leave them out. The cpan command will install missing dependencies. In case the test fails, when running cpan install, you should try to run force install.

💜 Extension Settings 💜

This extension contributes the following settings:

  • perl.enable — enable/disable this extension
  • perl.sshAddr — ip address of remote system
  • perl.sshPort — optional, port for ssh to remote system
  • perl.sshUser — user for ssh login
  • perl.sshCmd — defaults to ssh on unix and plink on windows
  • perl.sshWorkspaceRoot — path of the workspace root on remote system
  • perl.perlCmd — defaults to perl
  • perl.perlArgs — additional arguments passed to the perl interpreter that starts the LanguageServer
  • useTaintForSyntaxCheck — if true, use taint mode for syntax check
  • perl.sshArgs — optional arguments for ssh
  • perl.pathMap — mapping of local to remote paths
  • perl.perlInc — array with paths to add to perl library path. This setting is used by the syntax checker and for the debuggee and also for the LanguageServer itself.
  • perl.fileFilter — array for filtering perl file, defaults to [.pm,.pl]
  • perl.ignoreDirs — directories to ignore, defaults to [.vscode, .git, .svn]
  • perl.debugAdapterPort — port to use for connection between vscode and debug adapter inside Perl::LanguageServer.
  • perl.debugAdapterPortRange — if debugAdapterPort is in use try ports from debugAdapterPort to debugAdapterPort + debugAdapterPortRange. Default 100.
  • perl.showLocalVars — if true, show also local variables in symbol view
  • perl.logLevel — Log level 0-2.
  • perl.logFile — If set, log output is written to the given logfile, instead of displaying it in the vscode output pane. Log output is always appended. Only use during debugging of LanguageServer itself.
  • perl.disableCache — If true, the LanguageServer will not cache the result of parsing source files on disk, so it can be used within readonly directories
  • perl.containerCmd — If set Perl::LanguageServer can run inside a container. Options are: 'docker', 'docker-compose', 'kubectl'
  • perl.containerArgs — arguments for containerCmd. Varies depending on containerCmd.
  • perl.containerMode — To start a new container, set to 'run', to execute inside an existing container set to 'exec'. Note: kubectl only supports 'exec'
  • perl.containerName — Image to start or container to exec inside or pod to use

🌈 Debugger Settings for launch.json 🌈

  • "type" — needs to be "perl"
  • "request" — only "launch" is supported (this is a restriction of perl itself)
  • "name" — name of this debug configuration
  • "program" — path to perl program to start
  • "stopOnEntry" — if true, program will stop on entry
  • "args" — optional, array or string with arguments for perl program
  • "env" — optional, object with environment settings
  • "cwd" — optional, change working directory before launching the debuggee
  • "reloadModules" — if true, automatically reload changed Perl modules while debugging
  • "sudoUser" — optional, if set run debug process with sudo -u <sudoUser>.
  • "useTaintForDebug" — optional, if true run debug process with -T (taint mode).
  • "containerCmd" — If set debugger runs inside a container. Options are: 'docker', 'docker-compose', 'podman', 'kubectl'
  • "containerArgs" — arguments for containerCmd. Varies depending on containerCmd.
  • "containerMode" — To start a new container, set to 'run', to debug inside an existing container set to 'exec'. Note: kubectl only supports 'exec'
  • "containerName" — Image to start or container to exec inside or pod to use
  • "pathMap" — mapping of local to remote paths for this debug session (overwrites global "perl.path_map")

🦋 Remote syntax check & debugging 🦋

If you developing on a remote machine, you can instruct the Perl::LanguageServer to run on that remote machine, so the correct modules etc. are available for syntax check and debugger is started on the remote machine. To do so set sshAddr and sshUser, preferably in your workspace configuration.

Example:

"sshAddr": "10.11.12.13",
"sshUser": "root"

Also set sshWorkspaceRoot, so the local workspace path can be mapped to the remote one.

Example: if your local path is \10.11.12.13\share\path\to\ws and on the remote machine you have /path/to/ws

"sshWorkspaceRoot": "/path/to/ws"

The other possibility is to provide a pathMap. This allows one to having multiple mappings.

Examples:

"perl.pathMap": [
    ["remote uri", "local uri"],
    ["remote uri", "local uri"]
]

"perl.pathMap": [
    [
    "file:///",
    "file:///home/systems/mountpoint/"
    ]
]

💅 Syntax check & debugging inside a container 💅

You can run the LanguageServer and/or debugger inside a container by setting "containerCmd" and "conatinerName". There are more container options, see above.

.vscode/settings.json

{
    "perl": {
        "enable": true,
        "containerCmd": "docker",
        "containerName": "perl_container",
    }
}

This will start the whole Perl::LanguageServer inside the container. This is espacally helpfull to make syntax check working, if there is a different setup inside and outside the container.

In this case you need to tell the Perl::LanguageServer how to map local paths to paths inside the container. This is done by setting "perl.pathMap" (see above).

Example:

"perl.pathMap": [
    [
    "file:///path/inside/the/container",
    "file:///local/path/outside/the/container"
    ]
]

It's also possible to run the LanguageServer outside the container and only the debugger inside the container. This is especially helpfull, when the container is not always running, while you are editing. To make only the debugger running inside the container, put "containerCmd", "conatinerName" and "pasth_map" in your "launch.json". You can have different setting for each debug session.

Normaly the arguments for the "containerCmd" are automatically build. In case you want to use an unsupported "containerCmd" you need to specifiy apropriate "containerArgs".

🍓 FAQ 🍓

Working directory is not defined

It is not defined what the current working directory is at the start of a perl program. So Perl::LanguageServer makes no assumptions about it. To solve the problem you can set the directory via cwd configuration parameter in launch.json for debugging.

Module not found when debugging or during syntax check

If you reference a module with a relative path or if you assume that the current working directory is part of the Perl search path, it will not work. Instead set the perl include path to a fixed absolute path. In your settings.json do something like:

        "perl.perlInc": [
            "/path/a/lib",
            "/path/b/lib",
            "/path/c/lib",
        ],

Include path works for syntax check and inside of debugger. C<perl.perlInc> should be an absolute path.

AnyEvent, Coro Warning during install

okay that's where this chunk of the page pauses, bestie — the rest is coming in the next parts 💖✨

You need to install the AnyEvent::IO and Coro

Okay so you do need to install both of these besties 💅 Just ignore the warning that it might not work. For Perl::LanguageServer it works fine. No cap. ✨

'richterger.perl' failed: options.port should be >= 0 and < 65536

Change port setting from string to integer — like, it wants a number, not a lil string. She's picky but she's worth it. 🎀

Error "Can't locate MODULE_NAME"

Please make sure the path to the module is in the perl.perlInc setting and use absolute path names in the perlInc settings. OR make sure you are running in the expected directory by setting the cwd setting in the lauch.json. 🫶

(Yes, lauch.json. That's the name in the original. We don't fix it. We respect it. 💀)

ERROR: Unknown perlmethod rpcnotsetTraceNotification

This is not an issue, that just means that not all features of the debugging protocol are implemented. Also it says ERROR, it's just a warning and you can safely ignore it. She's dramatic, not broken. 🦋

The debugger sometimes stops at random places

Upgrade to Version 2.4.0 ✨

Message about Perl::LanguageServer has crashed 5 times

This is a problem when more than one instance of Perl::LanguageServer is running. Upgrade to Version 2.4.0 solves this problem. 👑

The program I want to debug needs some input via stdin

You can read stdin from a file during debugging. To do so add the following parameter to your launch.json:

""args": [ "<", "/path/to/stdin.txt" ]"

e.g.

"{
    "type": "perl",
    "request": "launch",
    "name": "Perl-Debug",
    "program": "${workspaceFolder}/${relativeFile}",
    "stopOnEntry": true,
    "reloadModules": true,
    "env": {
        "REQUEST_METHOD": "POST",
        "CONTENT_TYPE": "application/x-www-form-urlencoded",
        "CONTENT_LENGTH": 34
    }
    "args": [ "<", "/path/to/stdin.txt" ] }"

Carton support

If you are using L<https://metacpan.org/pod/Carton> to manage dependencies, add the full path to the Carton lib dir to your workspace settings file at .vscode/settings.json. For example:

Linux

{
  "perl.perlInc": ["/home/myusername/projects/myprojectname/local/lib/perl5"]
}

Mac

{
  "perl.perlInc": ["/Users/myusername/projects/myprojectname/local/lib/perl5"]
}

🌸 Known Issues 🌸

Does not yet work on windows, due to issues with reading from stdin. I wasn't able to find a reliable way to do a non-blocking read from stdin on windows. I would be happy, if anyone knows how to do this in Perl. Send help bestie 🙈

Anyway, Perl::LanguageServer runs without problems inside of Windows Subsystem for Linux (WSL). ✨ slay

🦋 Release Notes 🦋

see CHANGELOG.md — she keeps receipts. 💅

⭐ More Info ⭐

  • Presentation at German Perl Workshop 2020:
https://github.com/richterger/Perl-LanguageServer/blob/master/docs/Perl-LanguageServer%20und%20Debugger%20f%C3%BCr%20Visual%20Studio%20Code%20u.a.%20Editoren%20-%20Perl%20Workshop%202020.pdf

For reporting bugs please use GitHub issues. 🐛

💜 References 💜

This is a Language Server and Debug Protocol Adapter for Perl

It implements the Language Server Protocol which provides syntax-checking, symbol search, etc. Perl to various editors, for example Visual Studio Code or Atom.

https://microsoft.github.io/language-server-protocol/specification

It also implements the Debug Adapter Protocol, which allows debugging with various editors/includes

https://microsoft.github.io/debug-adapter-protocol/overview

To use both with Visual Studio Code, install the extension perl 🌈

https://marketplace.visualstudio.com/items?itemName=richterger.perl

Any comments and patches are welcome. 🫶

Copyright 2018-2022 Gerald Richter.

This program is free software; you can redistribute it and/or modify it under the terms of the Artistic License (2.0). You may obtain a copy of the full license at:

L<http://www.perlfoundation.org/artistic_license_2_0>

Any use, modification, and distribution of the Standard or Modified Versions is governed by this Artistic License. By using, modifying or distributing the Package, you accept this license. Do not use, modify, or distribute the Package, if you do not accept this license.

If your Modified Version has been derived from a Modified Version made by someone other than you, you are nevertheless required to ensure that your Modified Version complies with the requirements of this license.

This license does not grant you the right to use any trademark, service mark, tradename, or logo of the Copyright Holder.

This license includes the non-exclusive, worldwide, free-of-charge patent license to make, have made, use, offer to sell, sell, import and otherwise transfer the Package with respect to any patent claims licensable by the Copyright Holder that are necessarily infringed by the Package. If you institute patent litigation (including a cross-claim or counterclaim) against any party alleging that the Package constitutes direct or contributory patent infringement, then this Artistic License to you shall terminate on the date that such litigation is filed.

Disclaimer of Warranty: THE PACKAGE IS PROVIDED BY THE COPYRIGHT HOLDER AND CONTRIBUTORS "AS IS' AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES. THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT ARE DISCLAIMED TO THE EXTENT PERMITTED BY YOUR LOCAL LAW. UNLESS REQUIRED BY LAW, NO COPYRIGHT HOLDER OR CONTRIBUTOR WILL BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING IN ANY WAY OUT OF THE USE OF THE PACKAGE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Legal bestie stays legal — we don't touch a single word of the fine print, we just put a lil sparkle next to it. 💅✨

✨ Change Log ✨

okay bestie, gather round, because this is the receipts section 💅 every single glow-up this thing has ever had, in order, no cap. Dates in quotes, issue numbers in parens, contributor credits in brackets — all of it, exactly as it happened 🫶

🌸 2.6.2 — "2023-12-23"

  • stopped using given/when/smartmatch because those features are deprecated in perl 5.38 (#199) [real-dam] — yeah we jumped ship before the ship sank, iconic behaviour honestly 💀

🌸 2.6.1 — "2023-07-26"

  • Fix: formatting with perltidy was broken in 2.6.0 — we did a little oopsie and then we fixed the oopsie 🙈

🌸 2.6.0 — "2023-07-23"

  • added a debug setting for running as a different user — go peek at the sudoUser setting (#174) [wielandp]
  • you can now use a string for debuggee arguments (#149, #173) [wielandp]
  • added stdin redirection (#166) [wielandp]
  • added a link to issues in the META files (#168) [szabgab/issues]
  • added support for podman 🫙✨
  • added support for running Perl::LanguageServer on the outside, but the debugger on the inside of a container — glow-up inside a glow-up 🧚
  • added the useTaintForSyntaxCheck setting — if true, use taint mode for syntax check (#172) [wielandp]
  • added the useTaintForDebug setting — if true, use taint mode inside the debugger (#181) [wielandp]
  • added the debug adapter request "source", which lets you display the source of eval or files that aren't available to vscode (#180) [wielandp]
  • Fix: spelling (#170, #171) [pkg-perl-tools]
  • Fix: convert the charset encoding of debugger output according to the current locale (#167) [wielandp]
  • Fix: fixed diagnostic notifications override on clients (based on #185) [bmeneg]

🌸 2.5.0 — "2023-02-05"

  • set the minimal Perl version to 5.16 (#91)
  • by default the environment from vscode will be passed to the debuggee, the syntax check and perltidy
  • added the configuration "disablePassEnv" to not pass environment variables
  • support for the "logLevel" and "logFile" settings via the LanguageServer protocol, and not only via command line options (#97) [schellj]
  • Fix: "No DB::DB routine defined" (#91) [peterdragon]
  • Fix: typos and spelling in the README (#159) [dseynhae]
  • Fix: updated the call to gensym(), to fix a 'strict subs' error (#164) [KohaAloha]
  • converted indentation from tabs to spaces and removed trailing whitespaces — spring cleaning fr fr 🧹

🌸 2.4.0 — "2022-11-18"

  • picks a different port for debugAdapterPort if it's already in use — this avoids trouble with starting "Perl::LanguageServer" if another instance of "Perl::LanguageServer" is running on the same machine (thanks to hakonhagland) 👑
  • added the configuration "debugAdapterPortRange", for choosing the range of ports for dynamic port assignment
  • added support for using the LanguageServer and debugger inside a container — currently docker containers and containers running inside kubernetes are supported
  • when starting a debugger session and "stopOnEntry" is false, it no longer switches to the sourcefile where the debugger would stop when "stopOnEntry" is true
  • added some FAQs in the README
  • Fix: debugger stopped at random locations 💀
  • Fix: debugAdapterPort is now numeric
  • Fix: debugging loop with each statement (#107)
  • Fix: display of arrays in the variables pane on mac (#120)
  • Fix: encoding for "perltidy" (#127)
  • Fix: return an error if "perltidy" fails, so text isn't removed by a failing formatting request (#87)
  • Fix: FindBin does not work when checking syntax (#16)

🌸 2.3.0 — "2021-09-26"

  • the Arguments section in Variable lists is now @ARGV and @_ during debugging (#105)
  • @_ is now correctly evaluated inside the debugger console
  • $#foo is now correctly evaluated inside the debugger console
  • the default debug configuration is now automatically provided, without needing to create a "launch.json" first (#103)
  • added the option "cacheDir" to specify the location of the cache dir (#113)
  • Fix: debugger outputted an invalid thread reference, causing a "no such coroutine" message, so watchs and code from the debug console weren't expanded properly
  • Fix: LanguageServer hung when multiple requests were sent at once from VSCode to LanguageServer
  • Fix: the cwd parameter for the debugger in launch.json had no effect (#99)
  • Fix: correctly handle paths with drive letters on windows
  • Fix: sshArgs parameter was not declared as array (#109)
  • disabled syntax check on windows, because it blocks the whole process when running on windows, until handling of child's processes is fixed
  • fixed spelling (#86, #96, #101) [chrstphrchvz, davorg, aluaces]

🌸 2.2.0 — "2021-02-21"

  • the parser now supports Moose method modifiers before, after and around, so they can be used in the symbol view and within reference search
  • support for Format Document and Format Selection via perltidy
  • added the logFile config option
  • added the perlArgs config option to pass options to the Perl interpreter — plus some documentation for config options
  • added the disableCache config option to make LanguageServer usable with readonly directories
  • updated dependencies package.json & package-lock.json
  • Fix: deep recursion in SymbolView/Parser which was caused by function prototypes — this also solves #65
  • Fix: duplicate req id's that caused cleanup of still-running threads, which in turn caused the LanguageServer to hang
  • prevented dereferencing an undefined value (#63) [Heiko Jansen]
  • Fix: datatype of cwd config options (#47)
  • use the perlInc setting also for LanguageServer itself (based only on pull request #54 from ALANVF)
  • catch Exceptions during display of variables inside the debugger
  • Fix: detecting duplicate LanguageServer processes
  • Fix: spelling in documentation (#56) [Christopher Chavez]
  • removed the notice about Compiler::Lexer 0.22 bugs (#55) [Christopher Chavez]
  • README: typo and grammar fixes — added Carton lib path instructions (#40) [szTheory]
  • README: Markdown code block formatting (#42) [szTheory]
  • Makefile.PL: added META_MERGE with GitHub info (#32) [Christopher Chavez]
  • search.cpan.org retired, replaced with metacpan.org (#31) [Christopher Chavez]

🌸 2.1.0 — "2020-06-27"

  • improved the Symbol Parser (fixed parsing of anonymous subs)
  • showLocalSymbols
  • function names in the breadcrump
  • Signature Help for function/method arguments
  • added the Presentation on Perl Workshop 2020 to repos
  • removed Compiler::Lexer from the distribution since the version is available on CPAN
  • made stdout unbuffered while debugging
  • made the debugger use the perlInc setting
  • Fix: fileFilter setting
  • sort Arrays numerically in the variables view of the debugger
  • use rootUri if workspaceFolders isn't given
  • Fix: env config setting
  • recognised changes in the config of perlCmd

🌸 2.0.2 — "2020-01-22"

  • Plugin: Fix: command line parameters for plink
  • Perl::LanguageServer: Fix: handling of multiple parallel requests, improved symlink handling, added support for UNC paths in path mapping, improved logging for logLevel = 1

🌸 2.0.1 — "2020-01-14"

added support for reloading a Perl module while debugging, made the log level configurable, and made sure tooltips don't call functions ✨

🌸 2.0.0 — "2020-01-01"

added the Perl debugger 🎉

🌸 0.9.0 — "2019-05-03"

fixed issues in the Perl part, and made sure to update Perl::LanguageServer from cpan

🌸 0.0.3 — "2018-09-08"

fixed the issue with not reading enough from stdin, which caused LanguageServer to hang sometimes 😭

🌸 0.0.2 — "2018-07-21"

fixed the quitting issue when starting Perl::LanguageServer — more fixes are in the Perl part

🌸 0.0.1 — "2018-07-13"

Initial Version 🌱 the origin story, the main character debut, we love to see it

and that's the whole saga bestie 💖 from a tiny 0.0.1 seed to a fully-fledged 2.6.2. character development: immaculate.

okay so that's genuinely it — this page came to you courtesy of perl v5.36.0, dated 2023-12-23, and it lives under Perl::...Server(3pm) in the User Contributed Perl Documentation corner of the internet 🎀 go forth and debug slayfully, ily, bye 💅🦋

📦 where this page comes from