Merge pull request #1796 from wilzbach/fix-17581

Fix Issue 17581 - Document behavior of -betterC

posix.mak

@@ -196,7 +196,7 @@ SPEC_ROOT=$(addprefix spec/, \
 	const3 function operatoroverloading template template-mixin contracts		\
 	version traits errors unittest garbage float iasm ddoc				\
 	interfaceToC cpp_interface objc_interface portability entity memory-safe-d \
-	abi simd)
+	abi simd betterc)
 SPEC_DD=$(addsuffix .dd,$(SPEC_ROOT))
 
 CHANGELOG_FILES=changelog/${NEXT_VERSION}_pre \

spec/betterc.dd

@@ -0,0 +1,59 @@
+Ddoc
+
+$(SPEC_S Better C,
+
+`-betterC` is a command-line flag for `dmd`,
+which restricts the compiler's support of certain runtime features.
+Notably, D programs or libraries compiled with `betterC` aren't linked with Druntime.
+The use of compile-time features is not restricted in any way.
+
+Limiting a program or library to this subset of runtime features is useful
+when targeting constrained environments where the use of such features is not practical or possible.
+Additionally, this also makes embedding D libraries in larger projects easier by:
+
+$(OL
+    $(LI Simplifying the process of integration at the build-system level)
+    $(LI Removing the need to ensure that Druntime is properly initialized on calls to the library, when an initialization step is not performed before the library is used.)
+    $(LI Mixing memory management strategies (GC + manual memory management) can sometimes be tricky, hence removing D's GC from the equation may be a good solution)
+)
+
+---
+extern(C) void main()
+{
+    import core.stdc.stdio : printf;
+    printf("Hello betterC\n");
+}
+---
+
+$(CONSOLE
+> dmd -betterC hello.d $(AMP)$(AMP) ./hello
+Hello betterC
+)
+
+$(H2 $(LNAME2 consequences, Consequences))
+
+As no Druntime is available, many D features won't work.
+For example:
+
+$(OL
+    $(LI Garbage Collection)
+    $(LI Thread-local storage)
+    $(LI TypeInfo and ModuleInfo)
+    $(LI Classes)
+    $(LI Built-in threading (e.g. $(MREF core, thread)))
+    $(LI Dynamic arrays (but not slices) and associative arrays)
+    $(LI Exceptions)
+    $(LI `switch` with strings)
+    $(LI `final switch`)
+    $(LI `synchronized` and $(MREF core, sync))
+    $(LI Static module constructors or deconstructors)
+    $(LI Struct deconstructors)
+    $(LI `unittest` (testing can be as usual with the `-betterC` flag))
+)
+
+$(SPEC_SUBNAV_PREV simd, Vector Extensions)
+
+)
+
+Macros:
+    TITLE=Better C

spec/footer_gen.d

@@ -49,7 +49,7 @@ void main()
             navString ~= text("PREV_NEXT ", entries[i - 1].name.stripExtension, ", ", entries[i - 1].title, ", ",
                 entries[i + 1].name.stripExtension, ", ", entries[i + 1].title);
         else
-            navString ~= text("PREV_NEXT ", entries[i - 1].name.stripExtension, ", ", entries[i - 1].title);
+            navString ~= text("PREV ", entries[i - 1].name.stripExtension, ", ", entries[i - 1].title);
 
         navString ~= ")";
         writefln("%s: %s", entry.name, navString);

spec/simd.dd

@@ -246,7 +246,7 @@ $(H2 $(LNAME2 x86_64_vec, X86 And X86$(UNDERSCORE)64 Vector Extension Implementa
 $(H3 $(LNAME2 vector_op_intrinsics, Vector Operation Intrinsics))
 
 	$(P See $(CORE_SIMD) for the supported intrinsics.)
-$(SPEC_SUBNAV_PREV abi, Application Binary Interface)
+$(SPEC_SUBNAV_PREV_NEXT abi, Application Binary Interface, betterc, Better C)
 )
 
 Macros:

spec/spec.dd

@@ -48,7 +48,8 @@ $(TOC Table of Contents,
 		$(A entity.html, Named Character Entities),
 		$(A memory-safe-d.html, Memory Safety),
 		$(A abi.html, Application Binary Interface),
-		$(A simd.html, Vector Extensions)
+		$(A simd.html, Vector Extensions),
+		$(A betterc.html, Better C)
 	))
 )
 

spec/spec.ddoc

@@ -77,7 +77,8 @@ $(SUBNAV_TEMPLATE
             $(ROOT_DIR)spec/entity.html, Named Character Entities,
             $(ROOT_DIR)spec/memory-safe-d.html, Memory Safety,
             $(ROOT_DIR)spec/abi.html, Application Binary Interface,
-            $(ROOT_DIR)spec/simd.html, Vector Extensions
+            $(ROOT_DIR)spec/simd.html, Vector Extensions,
+            $(ROOT_DIR)spec/betterc.html, Better C
         )
     )
 )