# Windows Platform

Complete guide to building C++ libraries for Windows with CCGO.

## Overview

CCGO provides comprehensive Windows support with:

- **Multiple toolchains**: MSVC (Visual Studio) and MinGW (GCC)
- **Multiple architectures**: x86, x64, ARM64
- **Output formats**: Static libraries (.lib), Dynamic libraries (.dll)
- **Build methods**: Local (Visual Studio/MinGW) or Docker (cross-platform)
- **IDE support**: Visual Studio project generation
- **Subsystems**: Console and Windows subsystems
- **Runtime libraries**: Static and dynamic CRT linking

## Prerequisites

### Option 1: Local Build (Windows Required)

**For MSVC:**
- Windows 10+ (64-bit)
- Visual Studio 2019+ with C++ workload
- CMake 3.20+

**Installation:**

```powershell
# Install Visual Studio from visualstudio.microsoft.com
# Select "Desktop development with C++" workload

# Install CMake
# Download from cmake.org or use chocolatey
choco install cmake

# Verify installation
cmake --version
cl.exe
```

**For MinGW:**
- Windows 10+ (64-bit)
- MinGW-w64 or MSYS2
- CMake 3.20+

**Installation:**

```powershell
# Install MSYS2 from msys2.org
# Then install MinGW-w64
pacman -S mingw-w64-x86_64-gcc mingw-w64-x86_64-cmake

# Add to PATH
# C:\msys64\mingw64\bin

# Verify
gcc --version
g++ --version
```

### Option 2: Docker Build (Any OS)

Build Windows libraries on Linux or macOS using Docker with MinGW.

**Required:**
- Docker Desktop installed and running
- 5GB+ disk space for Docker image

**Advantages:**
- Build on any operating system
- No Windows license required
- Consistent build environment
- MinGW-w64 cross-compilation

**Limitations:**
- MinGW only (no MSVC)
- Cannot run/test Windows apps
- Larger initial download (~1.2GB image)

See [Docker Builds](#docker-builds) section for details.

## Quick Start

### Basic Build

```bash
# Build for x64 with default toolchain
ccgo build windows

# Build with Docker (MinGW cross-compile)
ccgo build windows --docker

# Specify toolchain
ccgo build windows --toolchain msvc      # MSVC (Windows only)
ccgo build windows --toolchain mingw     # MinGW
ccgo build windows --toolchain auto      # Both toolchains (default)

# Specify architecture
ccgo build windows --arch x86            # 32-bit
ccgo build windows --arch x64            # 64-bit (default)
ccgo build windows --arch arm64          # ARM64

# Build types
ccgo build windows --build-type debug    # Debug build
ccgo build windows --build-type release  # Release build (default)

# Link types
ccgo build windows --build-as static    # Static library only
ccgo build windows --build-as shared    # DLL only
ccgo build windows --build-as both      # Both types (default)
```

### Generate Visual Studio Project

```bash
# Generate Visual Studio solution
ccgo build windows --ide-project

# Open in Visual Studio
start cmake_build/windows/msvc/MyLib.sln
```

## Output Structure

### Default Output (`target/windows/`)

```
target/windows/
├── MyLib_Windows_SDK-1.0.0.zip          # Main package
│   ├── lib/
│   │   ├── static/
│   │   │   ├── msvc/
│   │   │   │   └── mylib.lib            # MSVC static library
│   │   │   └── mingw/
│   │   │       └── libmylib.a           # MinGW static library
│   │   └── shared/
│   │       ├── msvc/
│   │       │   ├── mylib.dll            # MSVC DLL
│   │       │   └── mylib.lib            # Import library
│   │       └── mingw/
│   │           ├── libmylib.dll         # MinGW DLL
│   │           └── libmylib.dll.a       # Import library
│   ├── bin/                             # DLLs (for runtime)
│   │   ├── msvc/
│   │   │   └── mylib.dll
│   │   └── mingw/
│   │       └── libmylib.dll
│   ├── include/
│   │   └── mylib/                       # Header files
│   │       ├── mylib.h
│   │       └── version.h
│   └── build_info.json                  # Build metadata
│
└── MyLib_Windows_SDK-1.0.0-SYMBOLS.zip  # Debug symbols
    └── symbols/
        ├── msvc/
        │   └── mylib.pdb                # MSVC debug symbols
        └── mingw/
            └── libmylib.dll.debug       # MinGW debug symbols
```

### Library Types

**Static library:**
- MSVC: `.lib` file
- MinGW: `.a` file
- Linked at compile time
- Larger executable
- No runtime dependencies

**Dynamic library (DLL):**
- MSVC: `.dll` + `.lib` (import library)
- MinGW: `.dll` + `.dll.a` (import library)
- Loaded at runtime
- Smaller executable
- Requires DLL at runtime

### Build Metadata

`build_info.json` contains:

```json
{
  "project": {
    "name": "MyLib",
    "version": "1.0.0",
    "description": "My Windows library"
  },
  "build": {
    "platform": "windows",
    "architectures": ["x64"],
    "toolchains": ["msvc", "mingw"],
    "build_type": "release",
    "link_types": ["static", "shared"],
    "timestamp": "2024-01-15T10:30:00Z",
    "ccgo_version": "0.1.0",
    "msvc_version": "19.38",
    "mingw_version": "13.2.0"
  },
  "outputs": {
    "libraries": {
      "msvc": {
        "static": "lib/static/msvc/mylib.lib",
        "shared": "lib/shared/msvc/mylib.dll"
      },
      "mingw": {
        "static": "lib/static/mingw/libmylib.a",
        "shared": "lib/shared/mingw/libmylib.dll"
      }
    },
    "headers": "include/mylib/",
    "symbols": {
      "msvc": "symbols/msvc/mylib.pdb",
      "mingw": "symbols/mingw/libmylib.dll.debug"
    }
  }
}
```

## MSVC vs MinGW

### MSVC (Microsoft Visual C++)

**Pros:**
- Official Microsoft compiler
- Best Windows integration
- Excellent debugging with Visual Studio
- Better optimization for Windows
- Compatible with Windows SDK

**Cons:**
- Windows-only
- Requires Visual Studio installation
- Larger toolchain

**When to use:**
- Windows-specific development
- Need Visual Studio integration
- Maximum Windows performance
- Using Windows SDK APIs

### MinGW (Minimalist GNU for Windows)

**Pros:**
- GCC-based (cross-platform compatible)
- Can cross-compile from Linux/macOS
- Smaller toolchain
- Open source
- Compatible with Unix tools

**Cons:**
- Some Windows APIs not fully supported
- Potentially slower than MSVC
- Less Windows-specific optimization

**When to use:**
- Cross-platform development
- Building on non-Windows systems
- Want GCC compatibility
- Don't need advanced Windows APIs

## Using Libraries in C++

### Linking Static Library

**CMakeLists.txt (MSVC):**

```cmake
# Find library
find_library(MYLIB_LIBRARY
    NAMES mylib
    PATHS "path/to/lib/static/msvc"
)

# Link to target
target_link_libraries(myapp PRIVATE ${MYLIB_LIBRARY})
target_include_directories(myapp PRIVATE "path/to/include")
```

**CMakeLists.txt (MinGW):**

```cmake
find_library(MYLIB_LIBRARY
    NAMES mylib libmylib.a
    PATHS "path/to/lib/static/mingw"
)

target_link_libraries(myapp PRIVATE ${MYLIB_LIBRARY})
target_include_directories(myapp PRIVATE "path/to/include")
```

### Linking Dynamic Library

**CMakeLists.txt:**

```cmake
# Link import library
target_link_libraries(myapp PRIVATE "path/to/lib/shared/msvc/mylib.lib")

# Copy DLL to output directory
add_custom_command(TARGET myapp POST_BUILD
    COMMAND ${CMAKE_COMMAND} -E copy_if_different
        "path/to/bin/msvc/mylib.dll"
        $<TARGET_FILE_DIR:myapp>
)
```

**Using in code:**

```cpp
#include <mylib/mylib.h>

int main() {
    // DLL functions are automatically resolved
    mylib::MyClass obj;
    obj.do_work();
    return 0;
}
```

## Docker Builds

Build Windows libraries on any OS using Docker with MinGW:

### Prerequisites

```bash
# Install Docker Desktop
# Download from: https://www.docker.com/products/docker-desktop/

# Verify Docker is running
docker ps
```

### Build with Docker

```bash
# First build downloads prebuilt image (~1.2GB)
ccgo build windows --docker

# Subsequent builds are fast
ccgo build windows --docker --arch x64

# All standard options work (MinGW only)
ccgo build windows --docker --build-as static
```

### How It Works

1. CCGO uses prebuilt `ccgo-builder-windows` image from Docker Hub
2. Project directory mounted into container
3. Build runs with MinGW-w64 cross-compiler
4. Output written to host filesystem

### Limitations

- **MinGW only**: Cannot build with MSVC in Docker
- **Cannot run**: No Windows runtime in Docker
- **Cannot test**: Cannot execute Windows binaries

## Platform Configuration

### CCGO.toml Settings

```toml
[package]
name = "mylib"
version = "1.0.0"

[library]
type = "both"                  # static, shared, or both

[build]
cpp_standard = "17"            # C++ standard

[windows]
subsystem = "console"          # console or windows
runtime_library = "MD"         # MT, MD, MTd, MDd (MSVC only)
windows_sdk_version = "10.0"   # Windows SDK version
```

### CMake Variables

When building for Windows:

```cmake
${PLATFORM}                    # "windows"
${ARCHITECTURE}                # "x86", "x64", or "arm64"
${BUILD_TYPE}                  # "Debug" or "Release"
${LINK_TYPE}                   # "static", "shared", or "both"
${TOOLCHAIN}                   # "msvc" or "mingw"
${WINDOWS_SUBSYSTEM}           # "console" or "windows"
${MSVC_RUNTIME_LIBRARY}        # "MD", "MT", etc. (MSVC only)
```

### Conditional Compilation

```cpp
// Platform detection
#ifdef _WIN32
    // Windows-specific code
    #include <windows.h>

    #ifdef _WIN64
        // 64-bit Windows
    #else
        // 32-bit Windows
    #endif
#endif

// Compiler detection
#ifdef _MSC_VER
    // MSVC-specific code
    #pragma warning(disable: 4996)
#elif defined(__MINGW32__) || defined(__MINGW64__)
    // MinGW-specific code
#endif

// DLL export/import
#ifdef MYLIB_EXPORTS
    #define MYLIB_API __declspec(dllexport)
#else
    #define MYLIB_API __declspec(dllimport)
#endif

// Usage
class MYLIB_API MyClass {
public:
    void do_work();
};
```

## Best Practices

### 1. Support Both Toolchains

Build with both MSVC and MinGW:

```bash
# Build both (default)
ccgo build windows --toolchain auto
```

### 2. Use Proper DLL Export

Always use `__declspec(dllexport/dllimport)`:

```cpp
// mylib_export.h
#ifdef _WIN32
    #ifdef MYLIB_EXPORTS
        #define MYLIB_API __declspec(dllexport)
    #else
        #define MYLIB_API __declspec(dllimport)
    #endif
#else
    #define MYLIB_API
#endif
```

### 3. Handle Runtime Libraries

Choose correct CRT linking:

```toml
[windows]
runtime_library = "MD"  # Dynamic CRT (recommended)
# runtime_library = "MT"  # Static CRT (larger, no dependencies)
```

### 4. Include DLLs in Distribution

Always include DLLs with your binaries:

```
distribution/
├── myapp.exe
├── mylib.dll            # Your DLL
└── vcruntime140.dll     # MSVC runtime (if needed)
```

### 5. Test on Target Windows

Always test on actual Windows systems:
- Different Windows versions (10, 11)
- Different architectures (x86, x64)
- With and without Visual Studio installed

## Troubleshooting

### MSVC Not Found

```
Error: Could not find MSVC compiler
```

**Solution:**

```powershell
# Install Visual Studio with C++ workload
# Or install Build Tools

# Verify
where cl.exe

# Add to PATH if needed
$env:PATH += ";C:\Program Files\Microsoft Visual Studio\2022\Community\VC\Tools\MSVC\14.38.33130\bin\Hostx64\x64"
```

### MinGW Not Found

```
Error: Could not find MinGW compiler
```

**Solution:**

```bash
# Install MSYS2/MinGW
# Add to PATH
export PATH="/c/msys64/mingw64/bin:$PATH"

# Verify
gcc --version
g++ --version
```

### DLL Not Found

```
Error: The code execution cannot proceed because mylib.dll was not found
```

**Solutions:**

1. Copy DLL to executable directory
2. Add DLL directory to PATH:
```powershell
$env:PATH += ";C:\path\to\dlls"
```

3. Use delayed loading (MSVC):
```cmake
target_link_options(myapp PRIVATE "/DELAYLOAD:mylib.dll")
```

### Symbol Not Found

```
Error: unresolved external symbol
```

**Solutions:**

1. Check DLL exports:
```powershell
dumpbin /EXPORTS mylib.dll
```

2. Verify __declspec(dllexport):
```cpp
class __declspec(dllexport) MyClass { ... };
```

3. Use .def file for exports:
```
LIBRARY mylib
EXPORTS
    MyFunction
    MyClass
```

## Performance Tips

### 1. Use Link-Time Optimization

```toml
[build]
cxxflags = ["/GL"]           # MSVC
ldflags = ["/LTCG"]          # MSVC
# cxxflags = ["-flto"]       # MinGW
```

### 2. Enable Optimizations

```toml
[build]
cxxflags = [
    "/O2",                   # MSVC: Optimize for speed
    "/arch:AVX2"             # Use AVX2 instructions
]
```

### 3. Static CRT for Standalone

For deployment without Visual C++ redistributable:

```toml
[windows]
runtime_library = "MT"       # Static CRT
```

## Migration Guides

### From Visual Studio Project

**Before:**
```
MyLib.vcxproj
MyLib.sln
```

**After:**

1. Create CCGO project:
```bash
ccgo new mylib
```

2. Copy source files to `src/`

3. Configure CCGO.toml:
```toml
[windows]
subsystem = "console"
runtime_library = "MD"
```

4. Build:
```bash
ccgo build windows
```

### From CMake

**CMakeLists.txt:**
```cmake
project(mylib)
add_library(mylib src/mylib.cpp)
```

**CCGO.toml:**
```toml
[package]
name = "mylib"
version = "1.0.0"
```

Then: `ccgo build windows`

## See Also

- [Build System](../features/build-system.md)
- [Dependency Management](../features/dependency-management.md)
- [CCGO.toml Reference](../reference/ccgo-toml.md)
- [Platforms Overview](index.md)
