add Windows console omf startup description

spec/windows.dd

@@ -8,6 +8,55 @@ $(P This covers Windows programming with 32 bit OMF, 32 bit Mscoff,
 64 bit Mscoff, console programs, GUI programs, and DLLs.
 )
 
+$(H2 All Console Programs)
+
+ $(P A D console program is specified by having a function with D linkage at module level called `main`.
+ When the compiler sees this, it triggers the mixin template `core.internal.entrypoint._d_cmain`
+ to be added. The `_d_cmain` template looks like:
+ )
+ ---
+ template _d_cmain()
+ {
+ extern(C)
+ {
+ int _d_run_main(int argc, char **argv, void* mainFunc);
+
+ int _Dmain(char[][] args);
+
+ int main(int argc, char **argv)
+ {
+ return _d_run_main(argc, argv, &_Dmain);
+ }
+
+ // Solaris, for unknown reasons, requires both a main() and an _main()
+ version (Solaris)
+ {
+ int _main(int argc, char** argv)
+ {
+ return main(argc, argv);
+ }
+ }
+ }
+ }
+ ---
+ $(P The `main` function in it, because it is marked as `extern(C)`, is the entry point of a
+ C console program. The executable starts up as a C executable, with the C runtime library
+ initializing and then the C main() function is called.)
+ $(P The C runtime library will runs any D functions tagged with `pragma(crt_constructor)` as
+ part of its initialization, and before it calls C `main()`. The order in which these
+ are run is not specified.)
+ $(P The C `main` function then calls the D runtime library function `_d_run_main`, passing it
+ `argc` and `argv`, and the address of `_Dmain`. The compiler renames the D `main` function in
+ the source code to `_Dmain`.)
+ $(P `_d_run_main` then initializes the D runtime library, converts `argc` and `argv` to `args`,
+ and calls the D `main` function.)
+ $(P When the D `main` function returns, control is back in `_d_run_main` which shuts down the
+ D runtime library, and then returns to the C `main`, which then returns to the C library
+ which shuts down the C runtime library, then exits the program.)
+ $(P The C runtime library runs any D functions tagged with `pragma(crt_destructor)` as
+ part of its shutdown, in the reverse order that the `pragma(crt_constructor)`s were run.
+ )
+
 $(H2 $(LNAME2 mscoff, Windows 32 and 64 bit MSCOFF Programs))
 
  $(P 32 bit and 64 bit MSCOFF programs use the Microsoft Visual C/C++ compiler as the Associated
@@ -30,8 +79,19 @@ $(H2 $(LNAME2 omf, Windows 32 bit OMF Programs))
  to link them.
  )
 
+
 $(H3 $(LNAME2 omf-console, Console Programs))
 
+ $(P The existence of a C `main` function causes the compiler to insert in the object file:)
+
+ $(UL
+ $(LI a directive in the object file which tells $(TT Optlink) to search the Digital Mars C runtime library $(TT snn.lib)
+ to resolve any undefined symbols)
+ $(LI 2. a reference to $(TT __acrtused_con) which appears in the C runtime library, causing $(TT Optlink)
+ to pull in the C runtime library code)
+ )
+
+
 $(H3 $(LNAME2 omf-windows, Windows GUI Programs))
 
 $(H3 $(LNAME2 omf-dlls, DLLs))
@@ -43,4 +103,3 @@ Macros:
  CHAPTER=43
  TITLE=Windows Programming
  CATEGORY_SPEC=$0
-