PSK-Proxy-Tunnel/BUILD.md

# PSK-Proxy-Tunnel Build Guide

This guide explains how to build single executable binaries for the PSK-Proxy-Tunnel project using the `pkg` tool.

## Prerequisites

- **Node.js**: Version 18.0.0 or higher
- **npm**: Usually comes with Node.js
- **Git**: To clone the repository

## Quick Start

### 1. Install Dependencies

```bash
npm install
```

### 2. Build for Current Platform

```bash
# macOS/Linux: auto-detect current platform via script
./build.sh

# Windows: auto-detect Windows via script
build.bat

# Or run a specific platform via npm
npm run build:macos      # macOS
npm run build:linux      # Linux
npm run build:windows    # Windows
```

### 3. Build for All Platforms

```bash
npm run build
```

## Build Scripts

### Using the Build Scripts

#### Unix/Linux/macOS
```bash
# Make the script executable
chmod +x build.sh

# Build for current platform
./build.sh

# Build for specific platform
./build.sh --platform macos
./build.sh --platform linux
./build.sh --platform windows

# Build for all platforms
./build.sh --all

# Clean build artifacts
./build.sh --clean

# Show help
./build.sh --help
```

#### Windows
```cmd
# Build for Windows (default)
build.bat

# Build for all platforms
build.bat --all

# Clean build artifacts
build.bat --clean

# Show help
build.bat --help
```

### Using npm Scripts Directly

```bash
# Build for specific platform
npm run build:macos
npm run build:linux
npm run build:windows

# Build for all platforms
npm run build

# Clean build artifacts
npm run clean
```

## Build Output

After building, you'll find the executables in the `dist/` directory:

```
dist/
├── psk-proxy-server-macos      # macOS server executable
├── psk-proxy-client-macos      # macOS client executable
├── psk-proxy-server-linux      # Linux server executable
├── psk-proxy-client-linux      # Linux client executable
├── psk-proxy-server-windows.exe # Windows server executable
└── psk-proxy-client-windows.exe # Windows client executable
```

## Platform-Specific Builds

### macOS
```bash
npm run build:macos
# Creates: psk-proxy-server-macos, psk-proxy-client-macos
```

### Linux
```bash
npm run build:linux
# Creates: psk-proxy-server-linux, psk-proxy-client-linux
```

### Windows
```bash
npm run build:windows
# Creates: psk-proxy-server-windows.exe, psk-proxy-client-windows.exe
```

## Cross-Platform Building

You can build for other platforms from any operating system:

```bash
# Build for all platforms from macOS
npm run build

# Build for all platforms from Linux
npm run build

# Build for all platforms from Windows
npm run build
```

## Using the Built Executables

### Server
```bash
# macOS/Linux
./dist/psk-proxy-server-macos --tunnel-port 8443 --tcp-port 8080 --host 0.0.0.0 --psk-file /path/to/psk.key

# Windows
.\dist\psk-proxy-server-windows.exe --tunnel-port 8443 --tcp-port 8080 --host 0.0.0.0 --psk-file C:\path\to\psk.key
```

### Client
```bash
# macOS/Linux
./dist/psk-proxy-client-macos --server-host server.example.com --server-port 8443 --origin-host 127.0.0.1 --origin-port 8080 --psk-file /path/to/psk.key --identity client1

# Windows
.\dist\psk-proxy-client-windows.exe --server-host server.example.com --server-port 8443 --origin-host 127.0.0.1 --origin-port 8080 --psk-file C:\path\to\psk.key --identity client1
```

## Build Configuration

The build configuration is defined in `package.json` under the `pkg` section:

```json
{
  "pkg": {
    "assets": [],
    "scripts": [],
    "targets": [
      "node18-macos-x64",
      "node18-linux-x64", 
      "node18-win-x64"
    ]
  }
}
```

### Available Targets

- `node18-macos-x64`: macOS 64-bit
- `node18-linux-x64`: Linux 64-bit
- `node18-win-x64`: Windows 64-bit

You can modify these targets to support different Node.js versions or architectures.

## Troubleshooting

### Common Issues

1. **"pkg command not found"**
   ```bash
   npm install -g pkg
   # or use the local version
   npx pkg proxy-server.js
   ```

2. **Build fails with permission errors**
   ```bash
   # Make sure the build script is executable
   chmod +x build.sh
   
   # Or run with sudo if needed
   sudo npm run build
   ```

3. **Executable doesn't run on target platform**
   - Ensure you're building for the correct target platform
   - Check that the target platform supports the Node.js version you're using
   - Verify the executable has proper permissions

4. **Missing dependencies in built executable**
   - The `pkg` tool automatically bundles Node.js built-in modules
   - External dependencies are included automatically
   - If you have custom assets, add them to the `pkg.assets` array

### Performance Considerations

- **File Size**: Single executables are larger than the source code because they include Node.js runtime
- **Startup Time**: Slightly slower startup compared to running with `node` directly
- **Memory Usage**: Similar to running with Node.js directly

### Security Notes

- Built executables contain your source code (though it's compiled)
- The `pkg` tool doesn't obfuscate or encrypt your code
- Consider this when distributing executables with sensitive information

## Advanced Configuration

### Custom pkg Options

You can customize the build process by modifying the `pkg` section in `package.json`:

```json
{
  "pkg": {
    "assets": [
      "config/*.json",
      "templates/*.html"
    ],
    "scripts": [
      "scripts/**/*.js"
    ],
    "targets": [
      "node18-macos-x64",
      "node18-linux-x64",
      "node18-win-x64"
    ],
    "outputPath": "custom-dist"
  }
}
```

### Environment Variables

You can set environment variables to customize the build:

```bash
# Set custom output directory
PKG_OUTPUT_PATH=./my-dist npm run build

# Set custom Node.js version
PKG_NODE_VERSION=16 npm run build
```

## Contributing

When adding new build targets or modifying the build process:

1. Update the `package.json` scripts
2. Update the build scripts (`build.sh` and `build.bat`)
3. Test builds on all target platforms
4. Update this documentation

## License

This build system is part of the PSK-Proxy-Tunnel project and follows the same license terms.