Perl README
Language Server and Debugger 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
- 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
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.
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
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. On a multi user system every user must use a different port.
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"
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 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
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 to have multiple mappings.
Examples:
"sshpathMap": [
['remote uri', 'local uri'],
['remote uri', 'local uri']
]
"perl.pathMap": [
[
"file:///",
"file:///home/systems/mountpoint/"
]
]
Syntax check & debugging inside a container
It's possible to use the ssh settings also for containers. The example below is for docker-compose but there's nothing prevent you from tuning it to do docker exec, kubectl exec, machinectl shell or whatnot.
.vscode/settings.json
{
"perl": {
"enable": true,
"sshAddr": "dummy",
"sshUser": "dummy",
"sshCmd": "bin/shell-into-appserver.sh",
"sshWorkspaceRoot": "/home/code (directory in the container)",
"logLevel": 0,
}
}
bin/shell-into-appserver.sh:
#!/usr/bin/env bash
COMMAND=$(echo "$@" | sed 's/^.*perl /perl /')
docker-compose exec -u "$UID" -T [SERVICE NAME] $COMMAND
Carton support
If you are using 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.
Release Notes
see CHANGELOG.md
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