Corrade::Main library new in 2019.10

Improves general user experience on Windows.

This library is built if CORRADE_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 Windows-specific variants)
makes it possible to create executables with add_executable(... WIN32 ...) and hide the console window again without requiring you to replace your main() with WinMain()
gives you char** argv in UTF-8, converting them from Windows-specific wide-char representation
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

When not to use Corrade::Main

If you're not on Windows, everything listed above works by default already. Linking to Corrade::Main via CMake on non-Windows systems is a no-op.

If you're on Windows but don't use the standard C main() function (or can't use it, for example in a MFC application), linking to Corrade::Main will fail with an error such as the following:

CorradeMain.lib(CorradeMain.cpp.obj) : error LNK2001: unresolved external symbol main

In that case the solution is to not link to Corrade::Main at all. Such cases likely involve GUI applications that don't need access to the console or argc / argv, so the features provided by Corrade::Main are not that useful.

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).

No GUI assertion dialogs for command-line apps

Console executables, i.e. ones without WIN32 in add_executable(), will no longer open an annoying GUI dialog in case of an assertion, but instead either directly jump into the debugger or exit the application. This also means that running command-line apps or tests in a non-interactive scenario (such as on a CI) will no longer make them "stuck" forever waiting for someone to close the dialog.

This applies only to console executables, WIN32 apps still open a dialog because without a console attached there's no other way to report that an assertion fired.

ANSI colors in console output

By default, for compatibility reasons, Corrade is built with the CMake option CORRADE_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.