deargui-vpl/docs/CONSOLE_VARIANT_SETUP.md

Console Variant Setup Summary

What Was Changed

This document summarizes the changes made to support building both GUI and console variants of Windows applications.

Files Modified

1. examples/CMakeLists.txt

Added:

• CMake option BUILD_CONSOLE_VARIANTS (default: ON)
• Logic in add_example_executable macro to create console variants on Windows
• Console variants get -console suffix (e.g., blueprints-example-console)

Key Changes:

# New option at the top
option(BUILD_CONSOLE_VARIANTS "Also build console variants of applications on Windows" ON)

# New code at end of add_example_executable macro
if (WIN32 AND BUILD_CONSOLE_VARIANTS)
    set(_ConsoleTargetName ${name}-console)
    add_executable(${_ConsoleTargetName} ...)
    target_compile_definitions(${_ConsoleTargetName} PRIVATE _CONSOLE)
    # ... same properties and resource copying as GUI variant
endif()

2. scripts/build.sh

Updated:

• Added support for optional console argument
• Usage: ./scripts/build.sh [Debug|Release] [console]

Examples:

# Build GUI variant (default)
./scripts/build.sh Debug

# Build console variant
./scripts/build.sh Debug console

# Build Release console variant
./scripts/build.sh Release console

3. New Files

docs/console-variants.md

• Complete documentation on console variants
• Usage examples
• Comparison table
• When to use which variant

run-console.sh

• Quick script to build and run console variant
• Equivalent to run.sh but for console variant

How It Works

CMake Configuration

1. When BUILD_CONSOLE_VARIANTS=ON (default) on Windows:

   • For each example, TWO executables are created
   • GUI variant: Uses WIN32 flag, calls WinMain()
   • Console variant: No WIN32 flag, defines _CONSOLE, calls main()

2. Both variants:

   • Share the same source files
   • Link to the same libraries
   • Output to the same directory (build/bin)
   • Have the same debug postfix (_d)

Entry Point Selection

In examples/application/source/entry_point.cpp:

#if defined(_WIN32) && !defined(_CONSOLE)
// GUI variant: uses WinMain()
int WINAPI WinMain(...)
{
    // Handles console attachment/allocation
    // Uses WindowsCommandLineParser with MessageBox on error
}
#else
// Console variant: uses main()
int main(int argc, char** argv)
{
    // Standard console entry point
    // Uses CommandLineParser
}
#endif

Quick Start

Build Both Variants

# Configure (creates both GUI and console targets)
cmake -S examples -B build -G "Visual Studio 16 2019" -A x64

# Build GUI variant
cmake --build build --config Debug --target blueprints-example

# Build console variant
cmake --build build --config Debug --target blueprints-example-console

# Or use the build script
./scripts/build.sh Debug          # GUI variant
./scripts/build.sh Debug console  # Console variant

Visual Studio Startup Project

By default, the console variant is set as the startup project in Visual Studio. This means when you open build\imgui-node-editor.sln and press F5, it will debug the console variant.

To change this behavior:

# Use GUI variant as default startup project
cmake -S examples -B build -DUSE_CONSOLE_AS_STARTUP=OFF

# Use console variant as default startup project (default)
cmake -S examples -B build -DUSE_CONSOLE_AS_STARTUP=ON

You can also manually change the startup project in Visual Studio: Right-click the project → "Set as StartUp Project".

Run

# GUI variant (existing workflow)
./run.sh
# or
./build/bin/blueprints-example_d.exe

# Console variant (new)
./run-console.sh
# or
./build/bin/blueprints-example-console_d.exe

Visual Studio

After running CMake, the Visual Studio solution will contain both projects:

• blueprints-example (GUI)
• blueprints-example-console (Console)

Set either as the startup project and press F5 to debug.

Disable Console Variants

If you don't want to build console variants:

cmake -S examples -B build -G "Visual Studio 16 2019" -A x64 -DBUILD_CONSOLE_VARIANTS=OFF

This will only create the GUI variants (original behavior).

Benefits

For Development

• Immediate console output: See logs without attaching debugger or checking files
• Easier debugging: Standard console I/O redirection works
• Script integration: Better for automation and testing

For Production

• GUI variant unchanged: End users get clean GUI experience
• No breaking changes: Existing build scripts work as before
• Optional: Can be disabled with CMake flag

Implementation Notes

1. No code changes required: The existing entry_point.cpp already has both main() and WinMain() implementations
2. Preprocessor-based: Selection between entry points is done via _CONSOLE define
3. Minimal overhead: Console variants use simpler entry point without WinMain complexity
4. Automatic: All examples get console variants automatically when macro is used

Testing

To verify the console variant works:

# Build and run console variant
./scripts/build.sh Debug console
./build/bin/blueprints-example-console_d.exe --help

# You should see help text immediately in the console
# Compare with GUI variant which may open a message box or create new console

Future Enhancements

Possible improvements:

1. Add CMake target to build both variants at once
2. Create combined run.sh that detects which variant to use
3. Add CI/CD integration examples
4. Per-target control of console variant generation