PHASE_BUILD_SWITCHES.md

# Phase Build Switches Documentation

**Date:** 2026-02-06  
**Purpose:** Independent build switches for each phase to enable isolation and debugging

## Overview

Each phase of the GPL replacement plan has its own independent build switch. This allows:
- **Isolation**: Test each phase independently
- **Debugging**: Easily identify which phase is causing problems
- **Incremental Development**: Enable phases as they're completed
- **Regression Testing**: Test each phase separately to identify regressions

## Available Phase Switches

### Phase 2: Foundation Utilities
- **Flag**: `--enable-phase2`
- **Macro**: `OCTAVE_USE_PHASE2`
- **Location**: `liboctave/util`
- **Purpose**: Enable Phase 2 proprietary implementations

### Phase 3: Array and Matrix Operations
- **Flag**: `--enable-phase3`
- **Macro**: `OCTAVE_USE_PHASE3`
- **Location**: `liboctave/array`
- **Purpose**: Enable Phase 3 proprietary implementations

### Phase 4: Numeric Operations
- **Flag**: `--enable-phase4`
- **Macro**: `OCTAVE_USE_PHASE4`
- **Location**: `liboctave/numeric`
- **Purpose**: Enable Phase 4 proprietary implementations

### Phase 5: System Operations
- **Flag**: `--enable-phase5`
- **Macro**: `OCTAVE_USE_PHASE5`
- **Location**: `liboctave/system`
- **Purpose**: Enable Phase 5 proprietary implementations

### Phase 6: Interpreter Core
- **Flag**: `--enable-phase6`
- **Macro**: `OCTAVE_USE_PHASE6`
- **Location**: `libinterp`
- **Purpose**: Enable Phase 6 proprietary implementations

## Global Switch

### GPL Replacement (All Phases)
- **Flag**: `--enable-gpl-replacement`
- **Macro**: `OCTAVE_USE_GPL_REPLACEMENT`
- **Purpose**: Enable all proprietary implementations at once
- **Note**: Equivalent to enabling all phases individually

## Usage Examples

### Enable Single Phase
```bash
# Test Phase 2 only
./configure --enable-phase2
make

# Test Phase 3 only
./configure --enable-phase3
make
```

### Enable Multiple Phases
```bash
# Enable Phase 2 and Phase 3
./configure --enable-phase2 --enable-phase3
make
```

### Enable All Phases
```bash
# Option 1: Use global switch
./configure --enable-gpl-replacement
make

# Option 2: Enable all phases individually
./configure --enable-phase2 --enable-phase3 --enable-phase4 --enable-phase5 --enable-phase6
make
```

## Benefits

### 1. Isolation
Each phase can be tested independently without interference from other phases.

### 2. Debugging
When a problem occurs, you can quickly identify which phase is causing it:
```bash
# Test Phase 2
./configure --enable-phase2 && make && make test
# If it fails, the problem is in Phase 2

# Test Phase 3
./configure --enable-phase3 && make && make test
# If it fails, the problem is in Phase 3
```

### 3. Incremental Development
Enable phases as they're completed:
```bash
# Phase 2 is complete, Phase 3 is in progress
./configure --enable-phase2 --enable-phase3
```

### 4. Regression Testing
Test each phase separately to identify regressions:
```bash
# Test Phase 2
./configure --enable-phase2 && make test

# Test Phase 3
./configure --enable-phase3 && make test
```

### 5. Flexibility
Mix and match phases as needed for specific testing scenarios.

## Implementation

### In configure.ac
Each phase switch is defined in `configure.ac`:
```autoconf
AC_ARG_ENABLE([phase2],
  [AS_HELP_STRING([--enable-phase2],
    [enable Phase 2: proprietary foundation utilities (liboctave/util)])],
  [...])
```

### In Code
Use the macros to conditionally compile phase-specific code:
```cpp
#ifdef OCTAVE_USE_PHASE2
  // Phase 2 proprietary implementation
#else
  // Original GPL code
#endif
```

### In Makefiles
Use AM_CONDITIONAL to conditionally include phase-specific files:
```makefile
if AMCOND_PHASE2
  # Include Phase 2 files
endif
```

## Testing Strategy

### Phase Isolation Testing
1. Enable only the phase you're testing
2. Run the test suite
3. If tests pass, the phase is working correctly
4. If tests fail, the problem is isolated to that phase

### Cross-Phase Testing
1. Enable multiple phases
2. Run the test suite
3. If tests fail, disable phases one by one to identify the problematic phase

### Regression Testing
1. Enable all phases
2. Run the full test suite
3. Compare results with individual phase tests

## Notes

- Phase switches are **independent** - enabling one doesn't require enabling others
- Phase switches are **additive** - you can enable multiple phases at once
- The global `--enable-gpl-replacement` switch enables all phases
- Each phase can be developed and tested independently
- This structure makes it easy to identify which phase is causing problems