added build scripts
This commit is contained in:
283
BUILD.md
Normal file
283
BUILD.md
Normal file
@@ -0,0 +1,283 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user