QUICKSTART.md

Compiler Copilot - Quick Start Guide

Get up and running with Compiler Copilot in 5 minutes!

🚀 Installation

Step 1: Clone the Repository

git clone <repository-url>
cd CompilerCopilot

Step 2: Run Setup

chmod +x setup.sh
./setup.sh

This will:

• Create a Python virtual environment
• Install all dependencies
• Set up directory structure
• Create configuration template

Step 3: Configure

cp config/env.example config/.env

Edit config/.env and set at minimum:

# Required: Choose your debugger
DEBUGGER_PATH=/usr/bin/gdb
DEBUGGER_TYPE=gdb

# Required: Set compiler paths
CLANG_PATH=/usr/bin/clang
LLVM_PATH=/usr/lib/llvm-14

# Required: Choose LLM provider and add API key
LLM_PROVIDER=watsonx
LLM_API_KEY=your_api_key_here
LLM_MODEL=ibm/granite-13b-chat-v2

Step 4: Activate and Run

source venv/bin/activate
./compiler-copilot.sh

🎯 First Commands

Once the shell starts, try these commands:

1. Check Status

copilot> status

2. Get Help

copilot> help

3. Try the Sample Program

copilot> generate ir examples/sample_program.c --opt O2

4. Start a Debug Session

copilot> debug examples/sample_program --debugger gdb
copilot> run

5. Ask a Question

copilot> explain what LLVM IR is

📚 Common Workflows

Debugging a Crash

# Compile with debug info
gcc -g myprogram.c -o myprogram

# Start Compiler Copilot
./compiler-copilot.sh

# In the shell:
copilot> debug myprogram
copilot> run
# (program crashes)
copilot> analyze the crash and tell me what happened

Analyzing Optimizations

copilot> generate ir mycode.c --opt O0
copilot> generate ir mycode.c --opt O2
copilot> explain the differences and which passes were applied

Creating a Test Case

copilot> generate test for: use-after-free in linked list
# AI generates a test case
# Copy the code to a file and compile

🔧 Troubleshooting

"Command not found: gdb"

Install GDB:

# Ubuntu/Debian
sudo apt-get install gdb

# macOS
brew install gdb

# Fedora/RHEL
sudo dnf install gdb

"Import error: mcp"

Reinstall dependencies:

source venv/bin/activate
pip install -r requirements.txt

"LLM API error"

Check your API key in config/.env:

# Make sure it's set correctly
LLM_API_KEY=your_actual_api_key

"Permission denied: ./compiler-copilot.sh"

Make it executable:

chmod +x compiler-copilot.sh
chmod +x setup.sh

💡 Tips

1. Use Tab Completion: Press Tab to see available commands
2. Natural Language: Just describe what you want to do
3. Check History: Use Up/Down arrows to navigate command history
4. Save Output: Important findings can be copied from the terminal
5. Multiple Sessions: You can run multiple instances in different terminals

🎓 Learning Path

Beginner

1. Start with help command
2. Try the sample program
3. Experiment with IR generation
4. Ask questions in natural language

Intermediate

1. Debug real programs
2. Analyze optimization passes
3. Generate test cases
4. Compare different optimization levels

Advanced

1. Integrate with your workflow
2. Create custom scripts
3. Contribute new features
4. Extend with new tools

📖 Next Steps

• Read examples/workflow_examples.md for detailed workflows
• Check ARCHITECTURE.md to understand the internals
• See CONTRIBUTING.md to contribute

🆘 Getting Help

• In-shell help: Type help
• Documentation: Check README.md and other docs
• Issues: Open a GitHub issue
• Questions: Use GitHub Discussions

✅ Verification

To verify everything is working:

# 1. Activate environment
source venv/bin/activate

# 2. Run the shell
./compiler-copilot.sh

# 3. In the shell, run:
copilot> status
# Should show your configuration

copilot> generate ir examples/sample_program.c
# Should generate IR code

copilot> explain what this tool does
# Should get an AI response

If all three work, you're ready to go! 🎉

🚦 Quick Reference

Command	Description
help	Show all commands
status	Show current session status
debug <program>	Start debugging
generate ir <file>	Generate LLVM IR
generate assembly <file>	Generate assembly
analyze crash <exe>	Analyze crash
explain <topic>	Get explanation
quit	Exit the shell

Happy debugging! 🐛🔍