Corrade::Main library

Improves general user experience on Windows.

This library is built if WITH_MAIN is enabled when building Corrade. To use this library with CMake, you need to request the Main component of the Corrade package and link your application executable to the Corrade::Main target:

find_package(Corrade REQUIRED Main)

add_executable(your-app WIN32 main.cpp) # use WIN32 to hide the console window
target_link_libraries(your-app PRIVATE Corrade::Main)

See also Downloading and building Corrade and Using Corrade with CMake for more information.

If you're on Windows, linking to the Corrade::Main library does the following:

  • allows you to always use the standard main() (instead of _tmain(), wWinMain() and other atrocities)
  • makes it possible to create executables with add_executable(... WIN32 ...) and hide the console window again without requiring you to do any sad things to your main function
  • gives you char** argv in UTF-8, converting them from Windows-specific wide-char APIs
  • sets up console output to be in UTF-8 as well, so special characters and non-ASCII alphabets display correctly
  • if CORRADE_UTILITY_USE_ANSI_COLORS is enabled, enables processing of ANSI escape codes in the console, so Utility::Debug colored output and other advanced terminal features work properly

Standard main() with UTF-8 command-line arguments

When you link to Corrade Main, you can keep using the standard int main(int argc, char** argv) as you would do on Unix systems and you get the argv in UTF-8. The library does this by providing a "shim" wmain() / wWinMain(), converting the wide-char argv to UTF-8 and then passing that to your standard main().

WIN32 apps without console window lurking in the background

Executables created with add_executable(... WIN32 ...) "just work" and there's no console window lurking in the background anymore. Nevertheless, you still get UTF-8 encoded argc / argv in your usual main(). Standard output isn't captured anywhere by default, for debugging purposes you can either temporarily remove the WIN32 option and rebuild or use console redirection (app.exe > stdout.txt and app.exe 2> stderr.txt works as expected).

ANSI colors in console output

By default, for compatibility reasons, Corrade is built with the CMake option UTILITY_USE_ANSI_COLORS disabled, meaning colored output is done through direct WINAPI calls only when writing directly to the console. Those APIs provide only a limited subset of the ANSI escape code feature set and stop working as soon as you redirect the output to a file or a pipe.

With the CORRADE_UTILITY_USE_ANSI_COLORS option enabled, the colored output is printed the same way as on Unix terminals. Recent versions of Windows 10 support that natively, however it's needed to enable this feature explicitly in the console that's running the application by passing ENABLE_VIRTUAL_TERMINAL_PROCESSING to SetConsoleMode(). The Corrade Main library does that in the wmain() / wWinMain() shim.

UTF-8 console output encoding

With Corrade being designed in a way that UTF-8 is the standard encoding, it makes sense to have the console output encoding set to UTF-8 as well. Corrade Main does that by calling SetConsoleOutputCP() with CP_UTF8 in the wmain() / wWinMain() shim.

Usage without CMake

When you don't use CMake, simply linking to the CorradeMain.lib is not enough to achieve the desired effect — additionally you need to tell the linker to choose a different entry point. That's done by passing /ENTRY:wmainCRTStartup to it for console apps and /ENTRY:wWinMainCRTStartup for GUI apps.