main(): Take the user's main() function as a function pointer.

This allows us to move the UTF-16 → UTF-8 conversion into the DLL for
a dynamic build, and keep the actual definitions of the entry points so
small that they don't even need system headers, making them easily
expandable for other types of entry points.

Author: nmlgc

README.md

@@ -50,7 +50,10 @@ The following functions are wrapped in this way:
 	 * GetFileVersionInfoEx()
 
 ### Building ###
-Replace all inclusions of `windows.h` or `stdio.h` with `win32_utf8.h` in your existing native Win32 code. The rest differs between static and dynamic linking:
+* Replace all inclusions of `windows.h` or `stdio.h` with `win32_utf8.h` in your existing native Win32 code.
+* If your program is a standalone executable and not a (static or dynamic) library, see the [Custom `main()` function](#custom-main-function) section for details on how to get UTF-8 command-line parameters in `argv`.
+
+The rest differs between static and dynamic linking:
 
 #### Static linking ####
 Make sure that `win32_utf8_build_static.c` is compiled as part of your sources.
@@ -63,9 +66,18 @@ For dynamic linking or other more special use cases, a project file for Visual C
 To generate a DLL in a different compiler, simply compile `win32_utf8_build_dynamic.c`.
 
 #### Custom `main()` function ####
-When including `win32_utf8.h` (or the smaller `src/entry.h`), a later definition of `main()` is renamed to `win32_utf8_main()`. That function will in turn be called by win32_utf8's own `main()` function, defined in `src/entry.c`, which retrieves the Unicode command line, converts it to UTF-8, and transparently passes that to your actual `main()` function using the classic `argc` / `argv` scheme.
+Together with win32_utf8's entry point wrappers, changing the name and parameter list of your `main()` function to
+
+```c
+int __cdecl win32_utf8_main(int argc, const char *argv[])
+```
+
+guarantees that all strings in `argv` will be in UTF-8. `src/entry.h`, which is included as part of `win32_utf8.h`, redefines `main` as `win32_utf8_main` and thereby eliminates the need for another preprocessor conditional block around `main()` in cross-platform console applications.
+
+You then need to provide the *actual* entry point by compiling the correct `entry_*.c` file from this repository as part of your sources:
+* `entry_main.c` if your program runs in the console subsystem.
 
-When linking win32_utf8 statically as described above, `src/entry.c` is automatically compiled in as part of `win32_utf8_build_static.c`, so this should cause no further problems. For dynamic linking, however, `src/entry.c` has to be added to every target project's own sources as well.
+It can either be a separate translation unit, or `#include`d into an existing one. Also, make sure that your compiler's subsystem settings match the entry point file.
 
 #### Compiler support ####
 **Visual C++** and **MinGW** compile the code just fine. Cygwin is not supported, as [it lacks Unicode versions of certain C runtime functions because they're not part of the POSIX standard](https://www.cygwin.com/ml/cygwin/2006-03/msg00539.html). (Of course, using MinGW's `gcc` through Cygwin works just fine.)

entry_main.c

@@ -0,0 +1,17 @@
+/**
+  * Win32 UTF-8 wrapper
+  *
+  * ----
+  *
+  * main() entry point.
+  * Compile or #include this file as part of your sources
+  * if your program runs in the console subsystem.
+  */
+
+#include "src/entry.h"
+#undef main
+
+int __cdecl main(void)
+{
+	return win32_utf8_entry(win32_utf8_main);
+}

src/entry.c

@@ -3,32 +3,19 @@
   *
   * ----
   *
-  * Wrappers for certain entry points.
+  * Entry point wrapper, converting the command-line parameters to UTF-8.
   */
 
-#ifndef WIN32_UTF8_MAIN_UNIT
-#include "win32_utf8.h"
-#endif
-
-#define main win32_utf8_main
-
-#undef main
-
-// This reference is also why we can't just compile this file for dynamic
-// builds as well, as those can't possibly resolve it.
-int __cdecl win32_utf8_main(int argc, const char *argv[]);
-
-int __cdecl main(int argc, const char *argv[])
+int win32_utf8_entry(main_t *user_main)
 {
-	extern void win32_utf8_init(void);
-	extern void win32_utf8_exit(void);
-
 	int ret;
 	int argc_w = 0;
 	char **argv_u = CommandLineToArgvU(GetCommandLineW(), &argc_w);
 	if(argv_u) {
+		assert(user_main);
+
 		win32_utf8_init();
-		ret = win32_utf8_main(argc_w, (const char**)argv_u);
+		ret = user_main(argc_w, (const char**)argv_u);
 		win32_utf8_exit();
 		LocalFree(argv_u);
 	} else {

src/entry.h

@@ -3,7 +3,16 @@
   *
   * ----
   *
-  * Wrappers for certain entry points.
+  * Entry point wrapper, converting the command-line parameters to UTF-8.
   */
 
+// User-defined, subsystem-independent main function. Compile or #include one
+// of the entry_*.c files from the top directory, depending on which entry
+// point you want to use.
+int __cdecl win32_utf8_main(int argc, const char *argv[]);
 #define main win32_utf8_main
+
+typedef int __cdecl main_t(int argc, const char *argv[]);
+
+// Performs the conversion and calls [user_main] with an UTF-8 argv.
+int win32_utf8_entry(main_t *user_main);

win32_utf8.def

@@ -1,6 +1,7 @@
 EXPORTS
 	w32u8_set_fallback_codepage @1
 	w32u8_get_wrapped_functions
+	win32_utf8_entry
 
 	; Macros
 	; ------

win32_utf8.vcxproj

@@ -110,6 +110,7 @@
     <ClCompile Include="win32_utf8_build_static.c">
       <ExcludedFromBuild Condition="'$(ConfigurationType)'=='DynamicLibrary'">true</ExcludedFromBuild>
     </ClCompile>
+    <None Include="entry_main.c" />
     <None Include="src\build.c" />
     <None Include="src\entry.c" />
     <None Include="src\comdlg32_dll.c" />

win32_utf8_build_dynamic.c

@@ -7,3 +7,9 @@
   */
 
 #include "src/build.c"
+
+// Dynamic builds call these in DllMain().
+#define win32_utf8_init()
+#define win32_utf8_exit()
+
+#include "src/entry.c"