Merge pull request #3028 from WalterBright/ImportC2

ImportC: add an outline

Author: WalterBright

spec/importc.dd

@@ -4,7 +4,166 @@ $(SPEC_S ImportC,
 
 $(HEADERNAV_TOC)
 
-$(P Documentation for ImportC coming soon!)
+    $(NOTE: This document is a work in progress.)
+
+    $(P ImportC is a C compiler embedded into the D implementation.
+    Its purpose is to enable direct importation of C files, without
+    needing to manually prepare a D file corresponding to the the declarations
+    in the C file. It enables directly compiling C files into modules, and
+    linking them in with D code to form an executable. It can be used
+    as a C compiler to compile and link 100% C programs.
+    )
+
+    $(P This is not a C reference manual nor programming tutorial.
+    It describes the specifics of the dialect of C that
+    ImportC is, and how to use it effectively.)
+
+
+$(H2 $(LNAME2 dialect, ImportC Dialect))
+
+    $(P There are many versions of C. ImportC is designed to be an
+    implementation of (LINK2 https://en.wikipedia.org/wiki/C11_(C_standard_revision), ISO/IEC 9899:1999),
+    which will hereafter be referred to as $(B C11).
+    References to the C11 Standard will be C11 followed by the paragraph number.
+    Prior versions, such as C99, C89, and K+R C, are not supported.
+    )
+
+    $(P Adjustment to the ImportC dialect is made to match the
+    behavior of the C compiler that the D compiler is matched to. For
+    example, on Win32 D is matched to the Digital Mars C compiler,
+    and can be matched to the Visual C compiler using the $(TT -mscoff32)
+    switch. Win64 D is matched to the Visual C compiler.
+    On Posix targets, the matching C compiler is Gnu C or Clang C.
+    )
+
+    $(P Further adjustment is made to take advantage of some of the D
+    implementation's capabilities.)
+
+    $(P This is all covered in the rest of this document.)
+
+
+$(H2 $(LNAME2 command-line, Invoking ImportC))
+
+    $(P The ImportC compiler can be invoked in two ways:)
+
+    $(UL
+    $(LI directly via the command line)
+    $(LI indirectly via importing a C file)
+    )
+
+    $(H3 ImportC Files on the Command Line)
+
+    $(H3 Importing C Files)
+
+
+$(H2 $(LNAME2 preprocessor, Preprocessor))
+
+    $(P ImportC does not have a preprocessor. It is designed to compile C
+    files after they have been first run through the C preprocessor.)
+
+    $(H3 Digital Mars C Preprocessor)
+
+    $(H3 Gnu C Preprocessor)
+
+    $(H3 Clang C Preprocessor)
+
+    $(H3 Warp C Preprocessor)
+
+
+$(H2 $(LNAME2 preprocessor-directives, Preprocessor Directives))
+
+    $(P Nevertheless, ImportC supports these preprocessor directives:)
+
+    $(H3 Line control)
+
+    $(P C11 6.10.4)
+
+    $(H3 Linemarker)
+
+    $(P $(LINK2 https://gcc.gnu.org/onlinedocs/gcc-11.1.0/cpp/Preprocessor-Output.html, linemarker)
+    directives are normally embedded in the output of C preprocessors.)
+
+$(H2 $(LINK2 limitations, Limitations))
+
+    $(H3 Exception Handling)
+
+    $(P ImportC is assumed to never throw exceptions. `setjmp` and `longjmp` are not supported.)
+
+    $(H3 Transitive Const)
+
+    $(P C11 specifies that `const` only applies locally. `const` in ImportC applies transitively,
+    meaning that although $(CCODE int *const p;) means in C11 that p is a const pointer to int,
+    in ImportC it means p is a const pointer to a const int.)
+
+$(H2 $(LINK2 extensions, Extensions))
+
+
+$(H2 $(LINK2 gnu-clang-extensions, Gnu and Clang Extensions))
+
+
+$(H2 $(LINK2 visualc-extensions, Visual C Extensions))
+
+
+$(H2 $(LINK2 digital-mars-extensions, Digital Mars C Extensions))
+
+
+$(H2 $(LINK2 d-side, ImportC from D's Point of View))
+
+    $(P There is no one-to-one mapping of C constructs to D constructs, although
+    it is very close. What follows is a description of how the D side views
+    the C declarations that are imported.)
+
+    $(H3 Module Name)
+
+    $(P The module name assigned to the ImportC file is the filename stripped
+    of its path and extension. This is just like the default module name assigned
+    to a D module that does not have a module declaration.)
+
+    $(H3 `extern (C)`)
+
+    $(P All C symbols are `extern (C)`.)
+
+    $(H3 Enums)
+
+    $(P The C enum:)
+
+    $(CCODE enum E { A, B = 2 };)
+
+    $(P appears to D code as:)
+
+    ---
+    enum E : int { A, B = 2 }
+    alias A = E.A;
+    alias B = E.B;
+    ---
+
+    $(P The `.min` and `.max` properties are available:)
+
+    ---
+    static assert(E.min == 0 && E.max == 2);
+    ---
+
+$(H2 $(LINK2 warnings, Warnings))
+
+    $(P Many suspicious C constructs normally cause warnings to be emitted by default by
+    typical compilers, such as:)
+
+    $(CCODE int *p = 3; // Warning: integer implicitly converted to pointer)
+
+    $(P ImportC does not emit warnings. The presumption is the user will be importing existing C
+    code developed using another C compiler, and it is written as intended.
+    If C11 says it is legal, ImportC accepts it.)
+
+$(H2 $(LINK2 importcpp, ImportC++))
+
+    $(P ImportC will not compile C++ code. For that, use ($TT dpp).)
+
+$(H2 $(LINK2 history, How ImportC Came About))
+
+$(H2 $(LINK2 internals, How ImportC Works))
+
+    $(P This is a description of how ImportC is implemented, intended
+    to remove the mystery of various design choices.)
 
 $(SPEC_SUBNAV_PREV_NEXT betterc, Better C, ob, Live Functions)
 )