Apache Daffodil™ Extension for Visual Studio Code: Development

Apache Daffodil™ Extension for Visual Studio Code: Development

Prerequisites

Requirements

For development, there are some additional prerequisites that are required for building the Apache Daffodil™ Extension for Visual Studio Code:

• Install SBT 0.13.8 or higher
• Install Node 10 or higher
• Install Yarn
• Install pandoc

Open a terminal window in VS Code and run:

npm install typescript

Suggestions

1. After TypeScript is installed, to automatically recompile code when it changes, run:

npm run watch

As watch runs, fix any problems that arise in the Problems tab.

2. Run the Apache Daffodil™ Extension for Visual Studio Code in debug mode.

Build the Apache Daffodil™ Extension for Visual Studio Code and Run It as a Developer

• Clone the project https://github.com/apache/daffodil-vscode.git
• Open the project folder in VS Code.
• Run yarn to update the local dependencies.
• Press F5 (or launch "Extension" under the "Run and Debug" pane) to build and launch the extension in another VS Code window.
• In that newly loaded window, named "sampleWorkspace", you can then debug schema files using the local version of the extension.

The local Apache Daffodil™ Extension for Visual Studio Code downloads and caches the Apache Daffodil™ Debugger corresponding to the latest extension release. If you want to test a local version of the Apache Daffodil Debugger, you need to:

• add "useExistingServer": true to the configuration in your launch.json in the sample workspace;
• launch the backend debugger locally, using a launch configuration like below:

  {
    "type": "scala",
    "name": "DAPodil",
    "request": "launch",
    "mainClass": "org.apache.daffodil.debugger.dap.DAPodil",
    "args": []
  }

  This will start the debug adapter and await a connection from the Apache Daffodil VS Code Extension (usually on TCP port 4711); and
• debug your schema file, as long as it has the useExistingServer setting above.

Running the Automated Test Suite

The Apache Daffodil VS Code Extension comes with an automated test suite. Run it as follows:

yarn test

Testing Against a Specific Version of VS Code

By default, the test suite will use the earliest supported release of VS Code. To test against any specific version of VS Code (in this example, VS Code version 1.74.3), execute the test suite as follows, setting DAFFODIL_TEST_VSCODE_VERSION to the desired version:

DAFFODIL_TEST_VSCODE_VERSION=1.74.3 yarn test

Set DAFFODIL_TEST_VSCODE_VERSION to stable to use the latest stable release, or to insiders to use the latest (nightly) insiders build.

TLS Certificate Issues

HTTPS TLS certificates are verified by default. When running the test suite in certain environments (e.g., company VPN that uses endpoint protection), TLS certificate verifications may fail with a self-signed certificate error. If this is the case, either have node trust the endpoint protection certificate, or use one of these workarounds to disable the certificate verification:

NODE_TLS_REJECT_UNAUTHORIZED=0 yarn test

or

node ./out/tests/runTest.js --disable_cert_verification

WARNING: Do not export NODE_TLS_REJECT_UNAUTHORIZED=0 into your environment as it will disable TLS certificate verification on all node HTTPS connections done in that shell session.

Building the Documentation

To build docx (Word formatted) documentation, from the top of the cloned repository, run:

cd docs && make all

Reviewing and Verifying Dependency Bot Updates

For GitHub CI action updates (pull requests that start with Bump actions/...), make sure the affected workflows still operate as expected (they are automatically CI tested). GitHub CI actions update workflow YAML files, and are part of the CI infrastructure and not a code dependency. These should be relatively quick and easy to assess compared to code dependencies.

If the updates are not GitHub CI action updates, then additional scrutiny is required. When reviewing and verifying dependency bot updates that are part the software supply chain being distributed, please use the following checklist:

• Do all automated continuous integration checks pass?
• Is the update a patch, minor, or major update?
• Is the license still compatible with ASF License Policy?
• Have any changes been made to LICENSE/NOTICE files that need to be incorporated?
• Have any transitive dependencies been added or changed?

---