# Project vs Standalone Mode

CppLab IDE operates in two distinct modes, each optimized for different development workflows.

## Mode Overview

| Feature | **Standalone Mode** | **Project Mode** |
|---------|--------------------|--------------------|
| **Scope** | Single file | Multiple files |
| **Configuration** | In-memory (session) | Persistent (`cpplab_project.json`) |
| **Toolchain** | Session default | Saved per project |
| **Standard** | Session default | Saved per project |
| **Build Output** | Temp directory | `build/` subdirectory |
| **Workflow** | Quick experiments | Full applications |
| **File Browser** | Hidden | Visible (project tree) |

## Standalone Mode

### Purpose

Standalone mode is designed for:
- **Quick experiments**: Testing code snippets
- **Learning**: Trying out language features
- **Single-file programs**: Simple utilities
- **Algorithm development**: Focus on logic, not structure

### Activation

**Method 1: Open Single File**
```
File → Open File... → Select .c or .cpp file
```

**Method 2: New File**
```
File → New → Select template
```

**Method 3: Drag & Drop**
```
Drag .c or .cpp file into IDE window
```

### UI Layout

```
┌────────────────────────────────────────────────┐
│ ≡ File  Edit  Build  Run  Help     🔧 ⚙       │ ← Toolbar
├────────────────────────────────────────────────┤
│ Toolchain: mingw32 ▼    Standard: C++17 ▼     │
├────────────────────────────────────────────────┤
│                                                │
│         [Editor Area - test.cpp]               │
│                                                │
│  1  #include <iostream>                        │
│  2                                             │
│  3  int main() {                               │
│  4      std::cout << "Hello!\n";               │
│  5      return 0;                              │
│  6  }                                          │
│                                                │
├────────────────────────────────────────────────┤
│ [Build][Problems][Console]                     │ ← Bottom Panel
└────────────────────────────────────────────────┘
```

**Key Points:**
- No file browser on left
- Editor takes full width
- Toolchain/Standard selection in toolbar
- Bottom panel for build output

### Build Behavior

**Build Directory**: Uses temporary directory
```
Windows: %TEMP%\cpplab_build\<filename>\
Example: C:\Users\User\AppData\Local\Temp\cpplab_build\test.cpp\
```

**Build Command**:
```bash
g++ test.cpp -o test.exe -std=c++17 -Wall -Wextra
```

**Output Files**:
```
test.cpp           ← Source (in original location)
test.exe           ← Executable (in temp dir)
test.o             ← Object file (in temp dir)
```

### Configuration Persistence

**Session-Level** (not saved between IDE restarts):
- Toolchain selection
- Standard selection
- Editor state (cursor position, undo history)

**Not Persisted**:
- File path (must reopen)
- Build settings
- Run configurations

### Example Workflow

**Step 1**: Create test file
```cpp
// test.cpp
#include <iostream>

int main() {
    std::cout << "Fibonacci: ";
    int a = 0, b = 1;
    for (int i = 0; i < 10; ++i) {
        std::cout << a << " ";
        int next = a + b;
        a = b;
        b = next;
    }
    std::cout << "\n";
    return 0;
}
```

**Step 2**: Open in standalone mode
```
File → Open File → test.cpp
```

**Step 3**: Build and run
```
Build → Build File (Ctrl+B)
Build → Run (Ctrl+R)
```

**Output**:
```
Fibonacci: 0 1 1 2 3 5 8 13 21 34
```

### Graphics Support in Standalone Mode

**Graphics File** (with `#include <graphics.h>`):

```cpp
// graphics_demo.cpp
#include <graphics.h>

int main() {
    int gd = DETECT, gm;
    initgraph(&gd, &gm, "");
    
    circle(250, 200, 100);
    outtextxy(200, 200, "Hello Graphics!");
    
    getch();
    closegraph();
    return 0;
}
```

**Auto-Detection**:
- IDE scans for `#include <graphics.h>`
- Automatically selects **mingw32** toolchain
- Adds `-lgdi32 -lcomdlg32 -luuid -loleaut32 -lole32` linker flags

**Build Command** (automatic):
```bash
g++ graphics_demo.cpp -o graphics_demo.exe -std=c++17 ^
    -lgdi32 -lcomdlg32 -luuid -loleaut32 -lole32
```

### Limitations

- ❌ No multi-file compilation
- ❌ No incremental builds
- ❌ Configuration not saved
- ❌ No custom build flags (without project)
- ❌ No project-wide refactoring

## Project Mode

### Purpose

Project mode is designed for:
- **Full applications**: Multi-file programs
- **Library development**: Reusable components
- **Long-term projects**: Saved configuration
- **Team collaboration**: Shared project structure
- **Custom build settings**: Advanced compiler flags

### Activation

**Method 1: Create New Project**
```
File → New Project
┌──────────────────────────────┐
│ Project Name: MyApp          │
│ Location: C:\Projects\       │
│ Language: ◉ C++  ○ C         │
│ Standard: [C++17      ▼]     │
│ Type: ◉ Console  ○ Graphics  │
└──────────────────────────────┘
[Create]
```

**Method 2: Open Existing Project**
```
File → Open Project → Select folder with cpplab_project.json
```

### UI Layout

```
┌──────────────────────────────────────────────────────┐
│ ≡ File  Edit  Build  Run  Help     🔧 ⚙             │
├────────────────────────────────────────────────────────┤
│ Toolchain: mingw64 ▼    Standard: C++17 ▼             │
├────────────┬─────────────────────────────────────────┤
│ PROJECT    │                                         │
│ ▼ MyApp    │         [Editor Area - main.cpp]        │
│   src/     │                                         │
│     main.cpp                                        │
│     utils.cpp  #include <iostream>                 │
│     utils.h    #include "utils.h"                  │
│   build/   │                                         │
│     main.o │   int main() {                          │
│     utils.o│       greet("World");                   │
│            │       return 0;                          │
│            │   }                                      │
│            │                                         │
├────────────┴─────────────────────────────────────────┤
│ [Build][Problems][Console]                           │
└──────────────────────────────────────────────────────┘
```

**Key Points:**
- File browser on left showing project tree
- Editor takes remaining width
- Bottom panel for build output
- All project files visible

### Project Structure

**Standard Console Project**:
```
MyApp/
├── cpplab_project.json    ← Configuration file
├── src/
│   ├── main.cpp           ← Entry point
│   ├── utils.cpp          ← Implementation
│   └── utils.h            ← Header
└── build/                 ← Build artifacts
    ├── main.o
    ├── utils.o
    └── MyApp.exe
```

**Graphics Project**:
```
GraphicsApp/
├── cpplab_project.json
├── src/
│   ├── main.cpp
│   ├── drawing.cpp
│   └── drawing.h
└── build/
    ├── main.o
    ├── drawing.o
    └── GraphicsApp.exe
```

### Configuration File

**File**: `cpplab_project.json`

```json
{
  "name": "MyApp",
  "language": "cpp",
  "standard": "c++17",
  "project_type": "console",
  "toolchain": "mingw64",
  "compile_flags": ["-Wall", "-Wextra", "-O2"],
  "link_flags": [],
  "include_directories": [],
  "library_directories": [],
  "libraries": [],
  "sources": [
    "src/main.cpp",
    "src/utils.cpp"
  ]
}
```

**Field Descriptions**:

| Field | Type | Description | Example |
|-------|------|-------------|---------|
| `name` | string | Project display name | `"MyApp"` |
| `language` | string | `"c"` or `"cpp"` | `"cpp"` |
| `standard` | string | Language standard | `"c++17"`, `"c11"` |
| `project_type` | string | `"console"`, `"graphics"`, `"openmp"` | `"console"` |
| `toolchain` | string | `"mingw32"` or `"mingw64"` | `"mingw64"` |
| `compile_flags` | array | Additional compiler flags | `["-O2", "-g"]` |
| `link_flags` | array | Additional linker flags | `["-static"]` |
| `sources` | array | List of source files | `["src/main.cpp"]` |

### Build Behavior

**Build Directory**: Project subdirectory
```
MyApp/
└── build/
    ├── main.o           ← Object files
    ├── utils.o
    └── MyApp.exe        ← Final executable
```

**Build Command** (multi-file):
```bash
# Compile each source file
g++ -c src/main.cpp -o build/main.o -std=c++17 -Wall -Wextra -O2
g++ -c src/utils.cpp -o build/utils.o -std=c++17 -Wall -Wextra -O2

# Link
g++ build/main.o build/utils.o -o build/MyApp.exe
```

**Incremental Builds**:
- Only recompiles changed files
- Checks modification timestamps
- Speeds up large projects

### Configuration Persistence

**Fully Persisted** (saved in `cpplab_project.json`):
- [x] Toolchain selection
- [x] Standard selection
- [x] Project type
- [x] Compile/link flags
- [x] Source file list
- [x] Include/library paths

**Session-Level**:
- Editor state (cursor position)
- Open files
- Undo history

### Example Workflow

**Step 1**: Create project
```
File → New Project
Name: Calculator
Type: Console
Language: C++
Standard: C++17
```

**Step 2**: Project structure created
```
Calculator/
├── cpplab_project.json
└── src/
    └── main.cpp
```

**Step 3**: Add source files
```cpp
// src/main.cpp
#include <iostream>
#include "math_ops.h"

int main() {
    std::cout << "10 + 5 = " << add(10, 5) << "\n";
    std::cout << "10 - 5 = " << subtract(10, 5) << "\n";
    return 0;
}
```

```cpp
// src/math_ops.h
#ifndef MATH_OPS_H
#define MATH_OPS_H

int add(int a, int b);
int subtract(int a, int b);

#endif
```

```cpp
// src/math_ops.cpp
#include "math_ops.h"

int add(int a, int b) {
    return a + b;
}

int subtract(int a, int b) {
    return a - b;
}
```

**Step 4**: Build project
```
Build → Build Project (Ctrl+F7)
```

**Output**:
```
Building project: Calculator
Compiling src/main.cpp... [OK]
Compiling src/math_ops.cpp... [OK]
Linking... [OK]
Build succeeded in 1.2 seconds
Executable: Calculator/build/Calculator.exe
```

**Step 5**: Run
```
Build → Run (Ctrl+R)

Output:
10 + 5 = 15
10 - 5 = 5
```

### Advanced Project Types

#### Graphics Project

**Auto-Configuration**:
```json
{
  "name": "GraphicsDemo",
  "project_type": "graphics",
  "toolchain": "mingw32",
  "link_flags": [
    "-lgdi32",
    "-lcomdlg32",
    "-luuid",
    "-loleaut32",
    "-lole32"
  ]
}
```

**Automatic When**:
- Project type set to "Graphics"
- OR source contains `#include <graphics.h>`

#### OpenMP Project

**Auto-Configuration**:
```json
{
  "name": "ParallelApp",
  "project_type": "openmp",
  "toolchain": "mingw64",
  "compile_flags": ["-fopenmp"],
  "link_flags": ["-fopenmp"]
}
```

**Automatic When**:
- Project type set to "OpenMP"
- OR source contains `#pragma omp` directives

## Mode Comparison

### When to Use Standalone Mode

[x] **Use standalone when:**
- Learning C/C++ basics
- Testing small code snippets
- Solving programming challenges
- Writing single-file utilities
- Rapid prototyping
- No need to save configuration

❌ **Don't use standalone for:**
- Multi-file applications
- Long-term projects
- Team collaboration
- Complex build requirements

### When to Use Project Mode

[x] **Use project mode when:**
- Building full applications
- Working with multiple source files
- Need persistent configuration
- Custom compiler/linker flags
- Team-based development
- Version control integration

❌ **Don't use project mode for:**
- Quick experiments (overhead)
- Single-file tests
- Temporary code snippets

## Switching Between Modes

### From Standalone to Project

**Scenario**: You wrote `calculator.cpp` in standalone mode and want to convert it to a project.

**Steps**:

1. **Create project**:
   ```
   File → New Project
   Name: Calculator
   Location: C:\Projects\Calculator
   ```

2. **Copy standalone file**:
   ```
   Copy calculator.cpp to C:\Projects\Calculator\src\
   ```

3. **Update project config**:
   ```json
   {
     "sources": ["src/calculator.cpp"]
   }
   ```

4. **Build as project**:
   ```
   Build → Build Project
   ```

### From Project to Standalone

**Scenario**: You want to test a single file from a project in isolation.

**Steps**:

1. **Open file directly**:
   ```
   File → Open File → src/main.cpp
   ```

2. **Note**: Opens in standalone mode (ignores project context)

3. **Build as standalone**:
   ```
   Build → Build File (Ctrl+B)
   ```

## Implementation Details

### Mode Detection

**File**: `src/cpplab/app.py`

```python
def is_project_mode(self) -> bool:
    """Check if currently in project mode."""
    return self.current_project is not None

def load_project(self, project_path: Path):
    """Load project and switch to project mode."""
    config_file = project_path / "cpplab_project.json"
    if not config_file.exists():
        raise FileNotFoundError("Not a valid project")
    
    with open(config_file) as f:
        self.current_project = json.load(f)
    
    # Update UI
    self._populate_project_tree()
    self._update_toolchain_combo()
    self._update_standard_combo()
    self.fileTreeDock.show()  # Show project browser

def open_standalone_file(self, file_path: Path):
    """Open file in standalone mode."""
    self.current_project = None
    self.editor.open_file(file_path)
    
    # Update UI
    self.fileTreeDock.hide()  # Hide project browser
```

### Project Tree Population

```python
def _populate_project_tree(self):
    """Populate file tree with project contents."""
    if not self.current_project:
        return
    
    project_root = Path(self.current_project["root"])
    self.fileTreeModel = QFileSystemModel()
    self.fileTreeModel.setRootPath(str(project_root))
    self.fileTreeView.setModel(self.fileTreeModel)
    self.fileTreeView.setRootIndex(
        self.fileTreeModel.index(str(project_root))
    )
```

---

**Next**: [Build System Details](Build-System-Details.md)  
**Previous**: [Language Standards Support](Language-Standards-Support.md)