PINT GUI Development Environment

A development container setup for building PINT (Pulsar Timing) GUI applications using PyQt6.

Overview

This project provides a complete development environment for PINT GUI development, including:

• Python 3.11 with PyQt6
• PINT pulsar timing library
• X11 forwarding for GUI applications on macOS
• All necessary dependencies pre-installed
• AI-assisted development workflow

Documentation

• docs/ - Project documentation and notes
• docs/logging.md - Comprehensive logging system documentation
• ai_assistant/ - AI assistant system documentation
• CHANGELOG.md - Project changelog

Prerequisites

macOS Requirements

• macOS 10.15 (Catalina) or later
• Apple Silicon (M1/M2/M3) or Intel Mac
• Docker Desktop for Mac
• Visual Studio Code with Dev Containers extension
• XQuartz (for GUI display)

Setup Instructions

1. Install Docker Desktop

1. Download Docker Desktop from docker.com
2. Install and start Docker Desktop
3. Ensure Docker is running before proceeding

2. Install Visual Studio Code

1. Download VS Code from code.visualstudio.com
2. Install the "Dev Containers" extension by Microsoft
3. Restart VS Code after installation

3. Install XQuartz (Critical for GUI Applications)

1. Download XQuartz from xquartz.org
2. Install XQuartz (requires admin password)
3. IMPORTANT: After installation, you MUST reboot your Mac for XQuartz to work properly
4. After reboot, open XQuartz from Applications > Utilities
5. Go to XQuartz > Preferences > Security
6. Check "Allow connections from network clients"
7. CRITICAL: You must reboot again after enabling this setting

4. Verify XQuartz Configuration

After the second reboot, verify XQuartz is properly configured:

ps aux | grep Xquartz

You should see --listen tcp in the output. If you see --nolisten tcp, XQuartz is not properly configured and you need to reboot again.

5. Clone and Open Project

1. Clone this repository:

   git clone <repository-url>
   cd pylk

2. Open in VS Code:

   code .

6. Open in Dev Container

1. VS Code should detect the .devcontainer folder
2. Click "Reopen in Container" when prompted
3. Or use Command Palette (Cmd+Shift+P) > "Dev Containers: Reopen in Container"

Running the Application

⚠️ Important: X11 Forwarding Setup

After every reboot, you need to allow X11 connections from Docker:

xhost +localhost

This is required for GUI applications to work in the Docker container.

🔧 Automatic X11 Detection

The application now includes automatic X11 forwarding detection and user-friendly error handling:

• Automatic Detection: The app checks if X11 forwarding is working before starting
• Interactive Fix: If X11 issues are detected, you'll be prompted to fix them automatically
• Helpful Messages: Clear error messages with specific instructions
• Graceful Fallback: The app exits cleanly if X11 cannot be fixed

When you run pylk, you may see:

🔧 Detecting X11 forwarding issues...
⚠️  X11 Forwarding Issue Detected

The GUI cannot be displayed because X11 forwarding is not properly configured.
This is common in Docker containers after a reboot.

Would you like to attempt to fix this automatically? [y/N]

Simply type y and press Enter to let the app try to fix the issue automatically.

Start the GUI Application

Once the container is running, you can start the PINT GUI:

# Activate the virtual environment
source .venv/bin/activate

# Run the main application
pylk

Alternative: Run pintk directly

# Run the PINT GUI tool
pintk

Troubleshooting

GUI Display Issues

If you get "couldn't connect to display" errors:

1. First, try the X11 forwarding command (most common fix):

   xhost +localhost

2. Check XQuartz is running:

   ps aux | grep Xquartz

   Should show --listen tcp

3. Verify DISPLAY variable:

   echo $DISPLAY

   Should show host.docker.internal:0

4. If still not working:

   • Reboot your Mac
   • Ensure XQuartz is set to "Allow connections from network clients"
   • Check that Docker Desktop is running

Container Build Issues

If the container fails to build:

1. Check Docker is running:

   docker --version

2. Clean Docker cache:

   docker system prune -a

3. Rebuild container:

   • Command Palette > "Dev Containers: Rebuild Container"

Python Package Issues

If Python packages are not found:

1. Check virtual environment:

   which python
   source .venv/bin/activate

2. Verify system packages:

   python -c "import PyQt6; print('PyQt6 OK')"
   python -c "import pint; print('PINT OK')"

AI-Assisted Development

This project uses AI-assisted development workflows for efficient feature implementation:

• Human Workflow: See development-workflow.md for the complete workflow
• AI Roles: See prompts/roles/ for AI role definitions
• Templates: See prompts/templates/ for reusable prompt templates
• Rules: See prompts/shared/rules.md for shared behavioral rules

Quick Start with AI

1. The human crafts a prompt using prompt_engineer.md
2. The human makes the AI execute using feature_implementer.md
3. The AI implements milestones with PAUSE checkpoints
4. The human verifies each milestone with make fast
5. The human uses AI roles for review, fixes, and commits

📋 For complete workflow details, see development-workflow.md

Development

Project Structure

pylk/
├── .devcontainer/          # Dev container configuration
│   ├── Dockerfile         # Container image definition
│   └── devcontainer.json  # VS Code dev container settings
├── pylk/                  # Main application code
│   └── app.py            # Main application entry point
├── CHANGELOG.md          # Project changelog
└── README.md             # This file

Adding Dependencies

To add new Python packages:

1. Edit .devcontainer/devcontainer.json
2. Add packages to postCreateCommand
3. Rebuild the container

Customizing the Container

Modify .devcontainer/Dockerfile to:

• Add system packages
• Change Python version
• Install additional tools

Architecture Notes

Why This Setup?

• PyQt6: Modern Qt6 bindings for Python
• System Packages: PyQt6 installed via apt for better compatibility
• Virtual Environment: Isolated Python environment with system package access
• X11 Forwarding: Enables GUI applications to run in containers on macOS

Display Forwarding

The container uses X11 forwarding to display GUI applications:

• DISPLAY=host.docker.internal:0 routes display to macOS
• XQuartz acts as the X11 server on macOS
• .Xauthority is mounted for authentication

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test in the dev container
5. Submit a pull request

License

[Add your license information here]

Support

For issues with:

• Dev Container: Check VS Code Dev Containers documentation
• XQuartz: Check XQuartz documentation and ensure proper reboot
• Docker: Check Docker Desktop documentation
• PINT: Check PINT documentation

Known Issues

• macOS Apple Silicon: Requires XQuartz and proper reboot sequence
• Memory Usage: PyQt6 compilation can be memory-intensive
• Display Latency: X11 forwarding may have slight display lag

---

Note: This development environment is specifically optimized for macOS with Apple Silicon. For other platforms, you may need to adjust the X11 forwarding configuration.