nx_post_support/README.md

# NX Postprocessor Support

A comprehensive VS Code extension providing language support and remote debugging for NX CAM postprocessor development, including CDL, TCL, and DEF files.

## Features

- **Syntax Highlighting** - Full syntax highlighting for CDL, TCL, and DEF files
- **Code Formatting** - Automatic code formatting for all supported file types
- **Multi-language Support** - Supports NX CDL, TCL, and DEF file formats
- **Intelligent Code Analysis** - Linting and error detection for postprocessor code
- **Auto-completion** - Context-aware code completion for faster development
- **Signature Help** - Shows parameters and documentation for custom and NX procedures
- **NX Tcl Remote Debugger** - Breakpoints, stepping, call stack, scopes, variables, watches, evaluation, logpoints, hit conditions, and Tcl error stops directly in a running NX Post process

## Supported File Types

- `.cdl` - NX User Defined Event File
- `.tcl` - NX TCL postprocessor files
- `.def` - NX Definition files

## Installation

1. Install from the VS Code Marketplace
2. Install Python 3.11 or higher
3. Open any `.cdl`, `.tcl`, or `.def` file
4. The extension will automatically activate and provide language support

The former standalone `NX Tcl Remote Debugger` extension is no longer required. Disable or
uninstall `local-nx.nx-tcl-debug` before using the integrated debugger because both extensions
register the same `nx-tcl` debug type.

## Configuration

The extension can be configured through VS Code settings:

- `nx-post-support.interpreter` - Specify custom Python interpreter path for the language server
- `nx-post-support.formatter` - Enable/disable the TCL formatter (default: false)
- `nx-post-support.inlayHint` - Enable/disable inlay Hints (default: true)
- `nx-post-support.inlayHints.parameterNames` - Show parameter names for `all`, only `literals`, or `none` (default: `all`)
- `nx-post-support.inlayHints.suppressWhenArgumentMatchesName` - Hide redundant hints such as `value:` before `$value` (default: true)

TCL files default to unlimited inlay hint length so that VS Code does not
truncate later parameter names on a line. An explicit user setting for
`editor.inlayHints.maximumLength` still takes precedence.

## NX Tcl Remote Debugger

### Add a VS Code attach configuration

Create `.vscode/launch.json` through **Run and Debug: create a launch.json file** and select
**NX Tcl: Attach to NX Post**, or use this configuration:

```json
{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "nx-tcl",
      "request": "attach",
      "name": "Attach to NX Post Tcl",
      "host": "127.0.0.1",
      "port": 4711,
      "connectTimeout": 120000,
      "stopOnEntry": false,
      "breakOnError": true,
      "localRoot": "${workspaceFolder}"
    }
  ]
}
```

When VS Code and NX see the source through different roots, set `remoteRoot` to the root used by
NX and keep `localRoot` as the corresponding workspace root.

### Start debugging

1. Set breakpoints on executable Tcl or DEF commands.
2. Start **Attach to NX Post Tcl** in VS Code before running the postprocessor.
3. Start postprocessing in NX.
4. Use Continue, Step Over, Step Into, Step Out, Pause, Variables, Watch, and the Debug Console as
   with a normal source debugger.

Breakpoints remain active and stop at every real invocation. Use a hit condition such as `1` for
a one-time stop. Blank lines, comments, declarations, and multiline Tcl commands may be relocated
to the nearest executable command; VS Code shows the resolved line. Dynamic
`LIB_GE_command_buffer_edit_*` bodies are mapped back to their original source and owning Tcl
procedure.

## Usage

Simply open any supported file type and enjoy:

- Syntax highlighting
- Error detection and linting
- Code completion
- Code formatting (Format Document command)
- Hover information
- Signature help while entering procedure arguments
- Remote NX Tcl debugging with breakpoints and full stepping

## Development and debugging

Install the root and client dependencies before the first debug session:

```powershell
npm install
npm install --prefix client
npm run test:debugger
```

Use one of the checked-in VS Code launch configurations:

- **Run Extension** debugs the TypeScript extension host.
- **Debug Extension and Python** debugs both the TypeScript extension and the
  Python language server. This is the recommended configuration for LSP work.
- **Python Attach** attaches manually to an already running Python process.

The launch configuration creates a fresh non-minified bundle with embedded
source maps and opens `test/test.tcl` so the extension activates immediately.
For combined debugging, the Python adapter listens on `127.0.0.1:5678`; the
language server waits for that adapter before initialization. The NX
Postprocessor Support output channel reports `Python debug mode: enabled` and
shows `_debug_server.py` in the server command when the debug path is active.

## Contributing

This extension is actively maintained. For issues or feature requests, please visit our [repository](https://git.cbsk-tech.de/Christoph/nx_post_support.git).

## License

AGPL-3.0 License - see LICENSE file for details. The embedded NX Tcl Remote Debugger adapter
retains its MIT notice in `debugger/NX_TCL_DEBUGGER_LICENSE.txt`.