README_DAP.md

Debug Adapter Protocol (DAP)

The debugging services are provided via a DAP server, which must be generated to connect to the editor's DAP implementation.

Server Generation and Launch

This document provides a method for generating a shadowJar to be used as a DAP server, assuming there are no faster or alternative methods that avoid creating new modules within the questionnaire-language project.

1. First, create a new directory inside questionnaire-language (e.g., questionnaire-language-DAP-server).

2. Add the build.gradle file below to the new directory.

3. Run gradle :questionnaire-language-DAP-server:shadowJar.

The resulting shadowJar will be located at questionnaire-language/questionnaire-language-DAP-server/build/lib/DAP-server-0.1.0-SNAPSHOT-all.jar.

build.gradle:

plugins {
    id 'java'
    id 'com.github.johnrengelman.shadow' version '8.1.1'
    id 'application'
}

application {
    mainClassName = 'it.unimi.di.adaptlab.debug.dap.DapLauncher'
}

ext {
    commonsGroup = "it.unimi.di.adaptlab"
    commonsVersion = "1.0.0-SNAPSHOT"
    dapVersion = "0.1.0-SNAPSHOT"
    neverlangVersion = "2.5.6-SNAPSHOT"
}

publishing {
    publications {
        shadow(MavenPublication) {
            groupId = "it.unimi.di.adaptlab"
        }
    }
}

dependencies {
    testImplementation platform('org.junit:junit-bom:5.10.0')
    testImplementation 'org.junit.jupiter:junit-jupiter'
    implementation "commonsGroup.debug:neverlang−dap:{dapVersion}"
}

shadowJar {
    archiveBaseName.set("DAP-server")
    archiveVersion.set("${dapVersion}")
}

To launch the DAP server, execute the following command:

java -jar questionnaire-language-DAP-server/build/lib/DAP-server-0.1.0-SNAPSHOT-all.jar

The server will then start listening on port 10909.

Editor Configuration

To enable debugging capabilities, the editor must be configured to connect to the DAP server. Below are the key values required for the DAP client setup:

• adapter type = "server"
• adapter host = 127.0.0.1
• adapter port = 10909
• command to debug the current file = /usr/bin/gradle questionnaire-language-compose-adapter:run --args="{FILENAME}"

Note: It is crucial that {FILENAME} is the full path to the file, relative to the current directory (typically the directory where the editor was opened). It is usually possible to set a path option in the DAP client's configuration to specify the directory from which the debug command will be launched.

The following is a configuration example written for the nvim-dap plugin:

return {
    "mfussenegger/nvim-dap",
    ft = { "qn", },
    config = function()
        local dap = require("dap")
        dap.adapters.qn = {
            type = "server",
            host = "127.0.0.1",
            port = 10909,
        }
        dap.configurations.qn = {
            {
                type = "qn",
                request = "launch",
                name = "Launch Questionnaire Language Dap",
                command = { "/usr/bin/gradle", "questionnaire-language-compose-adapter:run" },
                args = "--args=\"${file}\"",      -- Here ${file} is the name of the file relative to the workspaceFolder used below
                path = "${workspaceFolder}"        -- Here ${workspaceFolder} is the directory in which the editor has been opened
            },
        }
    end
}