Skip to content

VIRTUAL_ENV_GUIDE.md

Latest commit

 

History

History
283 lines (218 loc) · 7.51 KB

VIRTUAL_ENV_GUIDE.md

File metadata and controls

283 lines (218 loc) · 7.51 KB
Raw

Virtual Environment Guide for Compiler Copilot

What is a Virtual Environment?

A Python virtual environment (venv) is an isolated Python environment that allows you to install packages without affecting your system Python installation. Think of it as a sandbox for your project.

Why Use a Virtual Environment?

✅ Isolation: Dependencies don't conflict with system packages ✅ Reproducibility: Same environment on any machine ✅ Clean: Easy to delete and recreate ✅ Safe: Won't break system Python tools

Does It Affect Local Debugging?

NO - The virtual environment does NOT affect your ability to debug locally. Here's why:

What the Virtual Environment Contains:

  • Python interpreter (copy/link to system Python)
  • Project dependencies (prompt_toolkit, rich, ibm-watsonx-ai, etc.)
  • Project code (Compiler Copilot)

What It Does NOT Affect:

  • ✅ Your debugger (GDB/LLDB) - runs natively on your system
  • ✅ Your compiler (Clang/LLVM) - runs natively on your system
  • ✅ Your programs being debugged - run natively
  • ✅ System tools (nm, objdump, readelf) - run natively
  • ✅ File system access - full access to your machine
  • ✅ Network access - full network connectivity

How It Works in Practice

1. Setup (One Time)

./setup.sh
# This creates venv/ directory with Python packages

2. Activation (Each Session)

source venv/bin/activate
# Your prompt changes to show (venv)

3. Running Compiler Copilot

./compiler-copilot.sh
# Runs the interactive shell

4. What Happens When You Debug

┌─────────────────────────────────────────────────────┐
│  Compiler Copilot Shell (Python in venv)            │
│  - Interprets your commands                         │
│  - Talks to IBM BOB                                 │
│  - Displays results                                 │
└──────────────┬──────────────────────────────────────┘
               │
               ▼
┌─────────────────────────────────────────────────────┐
│  GDB/LLDB (Native System Process)                   │
│  - Runs on your actual machine                      │
│  - Debugs your actual programs                      │
│  - Full system access                               │
└──────────────┬──────────────────────────────────────┘
               │
               ▼
┌─────────────────────────────────────────────────────┐
│  Your Program (Native)                              │
│  - Runs on your actual machine                      │
│  - Uses your actual files                           │
│  - Full system access                               │
└─────────────────────────────────────────────────────┘

Example: Debugging a Local Program

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

# 2. Start Compiler Copilot
./compiler-copilot.sh

# 3. In the shell, debug your local program
copilot> debug /home/user/myproject/myprogram
# GDB starts and debugs your ACTUAL program on your ACTUAL machine

copilot> run
# Your program runs NATIVELY on your machine

copilot> backtrace
# GDB shows ACTUAL backtrace from your program

copilot> examine /home/user/myproject/source.c
# Reads your ACTUAL source file

The Virtual Environment Only Affects:

  1. Python Package Imports

    from rich.console import Console  # Loaded from venv/
from ibm_watsonx_ai import APIClient  # Loaded from venv/

  2. Python Interpreter

    which python  # Points to venv/bin/python

It Does NOT Affect:

  1. System Commands

    which gdb      # /usr/bin/gdb (system)
which clang    # /usr/bin/clang (system)
which nm       # /usr/bin/nm (system)

  2. File Access

    # Can access ANY file on your system
/home/user/projects/
/opt/compiler/
/tmp/

  3. Network

    # Full network access
- IBM BOB API calls
- Git operations
- Package downloads

Common Scenarios

Scenario 1: Debugging a Customer Issue

# Your customer's code is at /customer/issue/code.c
source venv/bin/activate
./compiler-copilot.sh

copilot> debug /customer/issue/program
# Debugs the ACTUAL customer program
# Reads ACTUAL customer files
# Uses ACTUAL system GDB

Scenario 2: Analyzing Compiler Output

copilot> generate ir /customer/issue/code.c
# Uses ACTUAL system Clang
# Reads ACTUAL customer file
# Generates IR on your ACTUAL machine

Scenario 3: Using System Tools

copilot> run nm /customer/issue/binary
# Uses ACTUAL system nm
# Analyzes ACTUAL customer binary

Deactivation

When you're done:

deactivate
# Exits the virtual environment
# Your system returns to normal

Benefits for Your Use Case

✅ Side-by-Side Debugging

  • Shell runs in one terminal
  • You can open another terminal for manual commands
  • Both access the same files and programs

✅ Same Machine Execution

  • Everything runs on YOUR machine
  • No containers, no VMs, no remote execution
  • Direct access to all your tools

✅ Repository Integration

  • Set REPO_PATH in config/.env
  • Access any repository on your machine
  • Full file system access

Configuration for Your Machine

Edit config/.env:

# Point to YOUR tools on YOUR machine
DEBUGGER_PATH=/usr/bin/gdb
CLANG_PATH=/usr/bin/clang
NM_PATH=/usr/bin/nm
OBJDUMP_PATH=/usr/bin/objdump

# Point to YOUR repository
REPO_PATH=/home/user/my-compiler-project

# IBM BOB credentials
IBM_BOB_API_KEY=your_key
IBM_BOB_PROJECT_ID=your_project

Troubleshooting

"Command not found" after activation

Problem: System commands not found Solution: Virtual environment doesn't affect system commands. Check your PATH:

echo $PATH
# Should include /usr/bin, /usr/local/bin, etc.

"Cannot access file"

Problem: File permission issues Solution: Virtual environment doesn't change permissions. Check file access:

ls -la /path/to/file
# Fix permissions if needed

"GDB not working"

Problem: GDB issues Solution: Virtual environment doesn't affect GDB. Check GDB directly:

which gdb
gdb --version
# Install if needed: sudo apt-get install gdb

Summary

The virtual environment is ONLY for Python packages.

It does NOT:

  • ❌ Containerize your environment
  • ❌ Isolate your file system
  • ❌ Affect system tools
  • ❌ Limit network access
  • ❌ Change how GDB/LLDB work
  • ❌ Affect your programs

It ONLY:

  • ✅ Manages Python packages
  • ✅ Keeps dependencies organized
  • ✅ Makes the project portable

You have FULL access to your machine, files, and tools!

Quick Reference

# Setup (once)
./setup.sh

# Start session
source venv/bin/activate
./compiler-copilot.sh

# Debug anything on your machine
copilot> debug /any/path/to/program
copilot> analyze /any/path/to/file

# End session
deactivate

The virtual environment is just a Python package manager - nothing more!