Configuration Guide

Learn how to configure the z/TPF VS Code Extension to match your development environment and preferences.

Configuration Guide

Accessing Settings

Via VS Code Settings UI

Open Settings: Ctrl+, (Windows/Linux) or Cmd+, (macOS)
Search for “z/TPF”
Modify settings using the UI

Via settings.json

Open Command Palette: Ctrl+Shift+P / Cmd+Shift+P
Type “Preferences: Open Settings (JSON)”
Add z/TPF configuration:

{
  "ztpf.connection.host": "your-host.example.com",
  "ztpf.connection.port": 22,
  "ztpf.connection.username": "your-username"
}

Connection Settings

Basic Connection

Configure your z/TPF system connection:

{
  "ztpf.connection.host": "ztpf-dev.example.com",
  "ztpf.connection.port": 22,
  "ztpf.connection.username": "developer",
  "ztpf.connection.timeout": 30000,
  "ztpf.connection.keepAlive": true
}

Setting	Type	Default	Description
`host`	string	`""`	z/TPF system hostname or IP
`port`	number	`22`	SSH connection port
`username`	string	`""`	Your z/TPF username
`timeout`	number	`30000`	Connection timeout (ms)
`keepAlive`	boolean	`true`	Keep connection alive

Authentication

Configure authentication methods:

{
  "ztpf.connection.authMethod": "password",
  "ztpf.connection.privateKeyPath": "~/.ssh/id_rsa",
  "ztpf.connection.passphrase": "",
  "ztpf.connection.savePassword": false
}

Authentication Methods:

password - Username/password authentication
publickey - SSH key authentication
keyboard-interactive - Interactive authentication

Security Note: Passwords are stored securely in VS Code’s credential store. Never commit passwords to version control.

Connection Profiles

Create multiple connection profiles:

{
  "ztpf.connection.profiles": [
    {
      "name": "Development",
      "host": "ztpf-dev.example.com",
      "port": 22,
      "username": "dev-user"
    },
    {
      "name": "Testing",
      "host": "ztpf-test.example.com",
      "port": 22,
      "username": "test-user"
    },
    {
      "name": "Production",
      "host": "ztpf-prod.example.com",
      "port": 22,
      "username": "prod-user"
    }
  ],
  "ztpf.connection.activeProfile": "Development"
}

Editor Settings

Syntax Highlighting

Customize syntax highlighting:

{
  "ztpf.editor.syntax.enabled": true,
  "ztpf.editor.syntax.theme": "modern",
  "ztpf.editor.syntax.highlightRegisters": true,
  "ztpf.editor.syntax.highlightMacros": true,
  "ztpf.editor.syntax.highlightComments": true
}

Code Formatting

Configure automatic formatting:

{
  "ztpf.editor.formatOnSave": true,
  "ztpf.editor.formatOnType": false,
  "ztpf.editor.tabSize": 8,
  "ztpf.editor.insertSpaces": false,
  "ztpf.editor.trimTrailingWhitespace": true,
  "ztpf.editor.indentStyle": "classic"
}

Indent Styles:

classic - Traditional z/TPF indentation
modern - Modern structured indentation
custom - Use custom rules

IntelliSense

Configure code completion:

{
  "ztpf.intellisense.enabled": true,
  "ztpf.intellisense.suggestInstructions": true,
  "ztpf.intellisense.suggestRegisters": true,
  "ztpf.intellisense.suggestMacros": true,
  "ztpf.intellisense.triggerCharacters": [".", ",", " "],
  "ztpf.intellisense.maxSuggestions": 50
}

Build Settings

Build Configuration

Configure build behavior:

{
  "ztpf.build.autoSave": true,
  "ztpf.build.showOutput": true,
  "ztpf.build.clearOutputOnBuild": true,
  "ztpf.build.stopOnError": true,
  "ztpf.build.parallelBuilds": 4
}

Build Options

Set compiler options:

{
  "ztpf.build.compiler": "ztpf-asm",
  "ztpf.build.compilerArgs": [
    "-O2",
    "-Wall",
    "-Werror"
  ],
  "ztpf.build.outputDirectory": "./build",
  "ztpf.build.intermediateDirectory": "./obj"
}

Build Configurations

Define multiple build configurations:

{
  "ztpf.build.configurations": {
    "Debug": {
      "compilerArgs": ["-g", "-O0"],
      "defines": ["DEBUG=1"]
    },
    "Release": {
      "compilerArgs": ["-O3"],
      "defines": ["NDEBUG=1"]
    },
    "Test": {
      "compilerArgs": ["-g", "-O1"],
      "defines": ["TEST=1", "DEBUG=1"]
    }
  },
  "ztpf.build.activeConfiguration": "Debug"
}

Debug Settings

Debug Configuration

Configure debugging behavior:

{
  "ztpf.debug.stopOnEntry": false,
  "ztpf.debug.showDisassembly": false,
  "ztpf.debug.showRegisters": true,
  "ztpf.debug.showMemory": true,
  "ztpf.debug.maxStackDepth": 50
}

Breakpoint Settings

Configure breakpoint behavior:

{
  "ztpf.debug.breakpoints.enabled": true,
  "ztpf.debug.breakpoints.validateOnStart": true,
  "ztpf.debug.breakpoints.showInGutter": true,
  "ztpf.debug.breakpoints.allowConditional": true
}

Debug Output

Configure debug output:

{
  "ztpf.debug.output.showConsole": true,
  "ztpf.debug.output.showVariables": true,
  "ztpf.debug.output.showCallStack": true,
  "ztpf.debug.output.verbosity": "normal"
}

Verbosity Levels:

minimal - Essential information only
normal - Standard debug output
verbose - Detailed debug information
trace - All debug events

Remote File Settings

File Synchronization

Configure file sync behavior:

{
  "ztpf.remote.autoSync": true,
  "ztpf.remote.syncOnSave": true,
  "ztpf.remote.syncInterval": 5000,
  "ztpf.remote.conflictResolution": "prompt"
}

Conflict Resolution:

prompt - Ask user what to do
local - Prefer local changes
remote - Prefer remote changes
newest - Use newest version

File Watching

Configure file watching:

{
  "ztpf.remote.watchFiles": true,
  "ztpf.remote.watchInterval": 2000,
  "ztpf.remote.watchExclude": [
    "**/.git/**",
    "**/node_modules/**",
    "**/build/**"
  ]
}

File Transfer

Configure file transfer settings:

{
  "ztpf.remote.transfer.compression": true,
  "ztpf.remote.transfer.maxFileSize": 10485760,
  "ztpf.remote.transfer.timeout": 60000,
  "ztpf.remote.transfer.retries": 3
}

Performance Settings

Caching

Configure caching behavior:

{
  "ztpf.performance.cache.enabled": true,
  "ztpf.performance.cache.maxSize": 104857600,
  "ztpf.performance.cache.ttl": 3600000,
  "ztpf.performance.cache.clearOnDisconnect": false
}

Resource Limits

Set resource limits:

{
  "ztpf.performance.maxConcurrentConnections": 5,
  "ztpf.performance.maxFileSize": 10485760,
  "ztpf.performance.maxSearchResults": 1000,
  "ztpf.performance.lazyLoadThreshold": 100
}

Logging & Diagnostics

Logging Configuration

Configure logging:

{
  "ztpf.logging.enabled": true,
  "ztpf.logging.level": "info",
  "ztpf.logging.outputChannel": true,
  "ztpf.logging.file": "",
  "ztpf.logging.maxFileSize": 10485760
}

Log Levels:

error - Errors only
warn - Warnings and errors
info - Informational messages
debug - Debug information
trace - Detailed trace logs

Diagnostics

Enable diagnostic features:

{
  "ztpf.diagnostics.enabled": true,
  "ztpf.diagnostics.showInProblems": true,
  "ztpf.diagnostics.validateOnType": false,
  "ztpf.diagnostics.validateOnSave": true,
  "ztpf.diagnostics.maxProblems": 100
}

Workspace Settings

Workspace Configuration

Configure workspace-specific settings in .vscode/settings.json:

{
  "ztpf.workspace.root": "${workspaceFolder}",
  "ztpf.workspace.sourceDirectory": "src",
  "ztpf.workspace.buildDirectory": "build",
  "ztpf.workspace.includeDirectories": [
    "include",
    "macros"
  ]
}

Project Files

Configure project file handling:

{
  "ztpf.project.configFile": ".ztpfrc",
  "ztpf.project.autoDetect": true,
  "ztpf.project.fileExtensions": [
    ".asm",
    ".mac",
    ".inc",
    ".tpf"
  ]
}

Advanced Settings

Experimental Features

Enable experimental features:

{
  "ztpf.experimental.enableNewParser": false,
  "ztpf.experimental.enableAIAssist": false,
  "ztpf.experimental.enableAdvancedRefactoring": false
}

Warning: Experimental features may be unstable. Use with caution in production environments.

Custom Commands

Define custom commands:

{
  "ztpf.customCommands": [
    {
      "name": "Deploy to Dev",
      "command": "deploy-dev.sh",
      "args": ["${file}"]
    },
    {
      "name": "Run Tests",
      "command": "run-tests.sh",
      "args": ["${workspaceFolder}"]
    }
  ]
}

Configuration Examples

Minimal Configuration

Basic setup for getting started:

{
  "ztpf.connection.host": "ztpf-dev.example.com",
  "ztpf.connection.username": "developer",
  "ztpf.editor.formatOnSave": true
}

Development Configuration

Optimized for development:

{
  "ztpf.connection.host": "ztpf-dev.example.com",
  "ztpf.connection.username": "developer",
  "ztpf.editor.formatOnSave": true,
  "ztpf.build.autoSave": true,
  "ztpf.build.activeConfiguration": "Debug",
  "ztpf.debug.stopOnEntry": false,
  "ztpf.remote.autoSync": true,
  "ztpf.logging.level": "debug"
}

Production Configuration

Optimized for production work:

{
  "ztpf.connection.host": "ztpf-prod.example.com",
  "ztpf.connection.username": "prod-user",
  "ztpf.editor.formatOnSave": true,
  "ztpf.build.stopOnError": true,
  "ztpf.build.activeConfiguration": "Release",
  "ztpf.remote.conflictResolution": "prompt",
  "ztpf.logging.level": "warn"
}

Environment Variables

The extension supports these environment variables:

Variable	Description
`ZTPF_HOST`	Override connection host
`ZTPF_PORT`	Override connection port
`ZTPF_USER`	Override username
`ZTPF_HOME`	z/TPF home directory
`ZTPF_CONFIG`	Path to config file

Set in your shell or .env file:

export ZTPF_HOST=ztpf-dev.example.com
export ZTPF_USER=developer
export ZTPF_HOME=/home/developer/ztpf

Troubleshooting Configuration

Reset to Defaults

To reset all settings to defaults:

Open Command Palette
Run “z/TPF: Reset Configuration”
Confirm the reset

Validate Configuration

Check your configuration:

Open Command Palette
Run “z/TPF: Validate Configuration”
Review any warnings or errors

Export/Import Settings

Export settings:

Command Palette > z/TPF: Export Settings

Import settings:

Command Palette > z/TPF: Import Settings

Next Steps

Review Features to explore capabilities
Check Getting Started for usage examples
Visit GitHub for more resources