workflow_examples.md

Compiler Copilot - Example Workflows

This document provides example workflows for common use cases.

Workflow 1: Debugging a Crash

Scenario

Your program crashes and you want to understand why.

Steps

1. Start the interactive shell:

./compiler-copilot.sh

2. Analyze the crash:

copilot> analyze crash myprogram --core core.12345

The AI will:

• Load the core dump
• Extract backtrace, registers, and local variables
• Provide an analysis of the likely cause
• Suggest areas to investigate

3. Start an interactive debug session:

copilot> debug myprogram --debugger gdb

4. Set breakpoints and run:

copilot> breakpoint main
copilot> run

5. Ask for help:

copilot> explain what's happening at this breakpoint

Workflow 2: Analyzing Compiler Optimizations

Scenario

You suspect a compiler optimization is causing unexpected behavior.

Steps

1. Generate IR at different optimization levels:

copilot> generate ir mycode.c --opt O0
copilot> generate ir mycode.c --opt O2

2. Identify which pass caused the change:

copilot> identify pass mycode.c

The AI will:

• Compare IR at different optimization levels
• Identify which passes made significant changes
• Explain what each pass did

3. Get detailed explanation:

copilot> explain the loop unrolling optimization in my code

Workflow 3: Creating a Reproducible Test Case

Scenario

A customer reports an issue, and you need to create a minimal test case.

Steps

1. Describe the issue to the AI:

copilot> generate test for: segmentation fault when accessing array out of bounds in a loop

2. The AI generates a test case:

#include <stdio.h>

int main() {
    int arr[10];
    // This will cause a segfault
    for (int i = 0; i <= 10; i++) {
        arr[i] = i;
    }
    return 0;
}

3. Compile and verify:

copilot> compile test.c with debug info
copilot> debug test
copilot> run

Workflow 4: Understanding Assembly Output

Scenario

You want to understand what assembly code the compiler generates.

Steps

1. Generate assembly:

copilot> generate assembly mycode.c --opt O2

2. Ask for explanation:

copilot> explain the assembly code for function calculate_sum

3. Compare different optimization levels:

copilot> generate assembly mycode.c --opt O0
copilot> generate assembly mycode.c --opt O3
copilot> explain the differences between O0 and O3 assembly

Workflow 5: Fixing a Bug

Scenario

You've identified a bug and want help fixing it.

Steps

1. Analyze the problematic code:

copilot> suggest fix for buggy_function.c

Describe the issue:

The function crashes when input is NULL

2. Review the suggested fix: The AI will:

• Analyze the code
• Identify the root cause
• Suggest a fix with explanation
• Provide the corrected code

3. Apply the fix (if you agree):

copilot> apply fix to buggy_function.c

Workflow 6: Interactive Debugging Session

Scenario

Step-by-step debugging with AI assistance.

Steps

1. Start debugging:

copilot> debug myprogram --debugger lldb

2. Set breakpoints:

copilot> breakpoint process_data
copilot> breakpoint error_handler

3. Run and analyze:

copilot> run
copilot> show me the backtrace and explain what's happening

4. Inspect variables:

copilot> print all local variables and explain their values

5. Step through code:

copilot> step through the next 5 lines and explain each one

Workflow 7: Optimization Analysis

Scenario

Understand why your code isn't being optimized as expected.

Steps

1. Get optimization remarks:

copilot> analyze optimization remarks for mycode.c at O2

2. Generate and compare IR:

copilot> generate ir mycode.c --opt O0
copilot> generate ir mycode.c --opt O2
copilot> explain what optimizations were applied

3. Ask specific questions:

copilot> why wasn't my loop vectorized?
copilot> how can I make this code more optimization-friendly?

Natural Language Commands

You can also use natural language:

copilot> I have a segfault in my program, can you help me debug it?
copilot> Show me the LLVM IR for main.c and explain what the optimizer did
copilot> My program is slow, analyze the assembly and suggest improvements
copilot> Create a test case that reproduces a use-after-free bug
copilot> Why is my loop not being unrolled by the compiler?

Tips

1. Be specific: The more context you provide, the better the AI can help
2. Use the status command: Check your current session state with status
3. Combine commands: You can chain operations in natural language
4. Save important output: The shell maintains history, but save critical findings
5. Iterate: Use follow-up questions to dig deeper into issues

Advanced Usage

Custom Debugging Scripts

You can create scripts with multiple commands:

# debug_script.txt
debug myprogram
breakpoint main
run
backtrace
info locals
continue

Then run:

copilot> execute script debug_script.txt

Integration with CI/CD

Use Compiler Copilot in automated workflows:

./compiler-copilot.sh --batch << EOF
analyze crash $PROGRAM --core $CORE_FILE
generate report crash_analysis.md
EOF