feat: use-system-libc option

CMakeLists.txt

@@ -168,6 +168,9 @@ add_custom_command(
         ${CMAKE_CURRENT_SOURCE_DIR}/util/generate-config-info.py
         src/lib/Lib/ConfigOptions.json
         ${CMAKE_CURRENT_BINARY_DIR}
+    COMMAND
+        ${PYTHON_EXECUTABLE}
+        ${CMAKE_CURRENT_SOURCE_DIR}/util/generate-yaml-schema.py
     VERBATIM
     DEPENDS
         ${CMAKE_CURRENT_SOURCE_DIR}/util/generate-config-info.py
@@ -388,6 +391,7 @@ if (MRDOCS_BUILD_TESTS)
                 --generate=${testgenerator}
                 "--stdlib-includes=${LIBCXX_DIR}"
                 "--stdlib-includes=${STDLIB_INCLUDE_DIR}"
+                "--libc-includes=${CMAKE_SOURCE_DIR}/share/mrdocs/headers/libc-stubs"
                 --report=2
         )
         foreach (action IN ITEMS test create update)
@@ -402,6 +406,7 @@ if (MRDOCS_BUILD_TESTS)
                     --generate=${testgenerator}
                     "--stdlib-includes=${LIBCXX_DIR}"
                     "--stdlib-includes=${STDLIB_INCLUDE_DIR}"
+                    "--libc-includes=${CMAKE_SOURCE_DIR}/share/mrdocs/headers/libc-stubs"
                     --report=2
                 DEPENDS mrdocs-test
             )
@@ -550,12 +555,15 @@ if (MRDOCS_INSTALL)
     # share
     #-------------------------------------------------
     install(DIRECTORY ${LIBCXX_DIR}
-            DESTINATION ${CMAKE_INSTALL_DATAROOTDIR}/mrdocs/libcxx
+            DESTINATION ${CMAKE_INSTALL_DATAROOTDIR}/mrdocs/headers/libcxx
             FILES_MATCHING PATTERN "*")
     install(DIRECTORY ${STDLIB_INCLUDE_DIR}
-            DESTINATION ${CMAKE_INSTALL_DATAROOTDIR}/mrdocs/clang
+            DESTINATION ${CMAKE_INSTALL_DATAROOTDIR}/mrdocs/headers/clang
             FILES_MATCHING PATTERN "*")
-
+    install(DIRECTORY ${CMAKE_SOURCE_DIR}/share/mrdocs/headers/libc-stubs/
+            DESTINATION ${CMAKE_INSTALL_DATAROOTDIR}/mrdocs/headers/libc-stubs
+            FILES_MATCHING PATTERN "*")
+
     foreach (share_mrdocs_dir addons)
         install(DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}/share/mrdocs/${share_mrdocs_dir}
                 DESTINATION ${CMAKE_INSTALL_DATAROOTDIR}/mrdocs

docs/modules/ROOT/pages/usage.adoc

@@ -13,8 +13,10 @@ include::partial$workflow.adoc[]
 
 In summary:
 
-* Begin by specifying the <<config-file,configuration file>> and <<cli,command-line arguments>> to set up the options. The configuration options affect all processes.
-* The configuration options define a <<compilation-database, Compilation Database>>. All symbols are extracted with Clang to generate a unified corpus of symbols with their corresponding xref:page$commands.adoc[documentation].
+* Begin by specifying the <<config-file,configuration file>> and <<cli,command-line arguments>> to set up the options.
+The configuration options affect all processes.
+* The configuration options define a <<compilation-database, Compilation Database>>.
+All symbols are extracted with Clang to generate a unified corpus of symbols with their corresponding xref:page$commands.adoc[documentation].
 * Finally, This corpus is then fed to a xref:page$generators.adoc[Generator] that produces the desired documentation.
 
 For more details on each component, refer to the corresponding sections of this guide.
@@ -210,7 +212,7 @@ However, this ill-formed pattern is problematic:
 * the developer has to effectively maintain two versions of the code
 * the original source code becomes more and more unreadable
 
-Instead, when using MrDocs, the same function could be documented as:
+Instead, when using MrDocs, while the `\\__MRDOCS__` macro is still available for conditional compilation, the same function could be directly documented as:
 
 [source,c++]
 ----

docs/mrdocs.schema.json

@@ -179,6 +179,17 @@
       "title": "Use legible names",
       "type": "boolean"
     },
+    "libc-includes": {
+      "default": [
+        "<mrdocs-root>/share/mrdocs/headers/libc-stubs"
+      ],
+      "description": "When `use-system-libc` is disabled, the C standard library headers are available in these paths.",
+      "items": {
+        "type": "string"
+      },
+      "title": "Standard Library include paths",
+      "type": "array"
+    },
     "multipage": {
       "default": true,
       "description": "Generates a multipage documentation. The output directory must be a directory. This option acts as a hint to the generator to create a multipage documentation. Whether the hint is followed or not depends on the generator.",
@@ -225,14 +236,14 @@
     },
     "stdlib-includes": {
       "default": [
-        "<mrdocs-root>/share/mrdocs/libcxx",
-        "<mrdocs-root>/share/mrdocs/clang"
+        "<mrdocs-root>/share/mrdocs/headers/libcxx",
+        "<mrdocs-root>/share/mrdocs/headers/clang"
       ],
-      "description": "Standard Library include paths. These paths are used to replace the standard library paths provided by the compiler.",
+      "description": "When `use-system-stdlib` is disabled, the C++ standard library headers are available in these paths.",
       "items": {
         "type": "string"
       },
-      "title": "Standard Library include paths",
+      "title": "C++ Standard Library include paths",
       "type": "array"
     },
     "system-includes": {
@@ -250,10 +261,16 @@
       "title": "Path for the tagfile",
       "type": "string"
     },
+    "use-system-libc": {
+      "default": false,
+      "description": "To achieve reproducible results, MrDocs bundles the LibC headers with its definitions. To use the C standard library available in the system instead, set this option to true.",
+      "title": "Use the system C standard library",
+      "type": "boolean"
+    },
     "use-system-stdlib": {
       "default": false,
-      "description": "True if the compiler has to use just the system standard library. When set to true, the compiler uses the system standard library instead of the standard library provided by the compiler.",
-      "title": "Use the system standard library",
+      "description": "To achieve reproducible results, MrDocs bundles the LibC++ headers. To use the C++ standard library available in the system instead, set this option to true.",
+      "title": "Use the system C++ standard library",
       "type": "boolean"
     },
     "verbose": {

share/mrdocs/addons/generator/adoc/partials/symbol.adoc.hbs

@@ -98,7 +98,7 @@
 
 {{#each symbol.doc.exceptions}}
 | `{{exception}}`
-| {{description}}
+| {{{description}}}
 {{/each}}
 |===
 
@@ -137,7 +137,7 @@
 
 {{#each symbol.doc.tparams}}
 | *{{name}}*
-| {{description}}
+| {{{description}}}
 {{/each}}
 |===
 
@@ -152,7 +152,7 @@
 
 {{#each allTParams as |param|}}
 | *{{param.name}}*
-| {{param.description}}
+| {{{param.description}}}
 {{/each}}
 |===
 
@@ -169,7 +169,7 @@
 
 {{#each symbol.doc.params}}
 | *{{name}}*
-| {{description}}
+| {{{description}}}
 {{/each}}
 |===
 
@@ -184,7 +184,7 @@
 
 {{#each allParams as |param|}}
 | *{{param.name}}*
-| {{param.description}}
+| {{{param.description}}}
 {{/each}}
 |===
 

share/mrdocs/headers/libc-stubs/assert.h

@@ -0,0 +1,16 @@
+//
+// Licensed under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//
+// Copyright (c) 2024 Alan de Freitas ([email protected])
+//
+// Official repository: https://github.com/cppalliance/mrdocs
+//
+
+#ifndef MRDOCS_SHARE_HEADERS_LIBC_STUBS_ASSERT_H
+#define MRDOCS_SHARE_HEADERS_LIBC_STUBS_ASSERT_H
+
+#define assert(...) ((void)0)
+
+#endif // MRDOCS_SHARE_HEADERS_LIBC_STUBS_ASSERT_H

share/mrdocs/headers/libc-stubs/complex.h

@@ -0,0 +1,120 @@
+//
+// Licensed under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//
+// Copyright (c) 2024 Alan de Freitas ([email protected])
+//
+// Official repository: https://github.com/cppalliance/mrdocs
+//
+
+#ifndef MRDOCS_SHARE_HEADERS_LIBC_STUBS_COMPLEX_H
+#define MRDOCS_SHARE_HEADERS_LIBC_STUBS_COMPLEX_H
+
+// Types
+#define imaginary _Imaginary
+#define complex _Complex
+
+// Constants
+#define _Imaginary_I ((float _Imaginary)1.0)
+#define _Complex_I ((float _Complex)1.0)
+#define I _Complex_I
+
+// Manipulation
+#define CMPLX(x, y) ((double _Complex)((x) + _Complex_I * (y)))
+#define CMPLXF(x, y) ((float _Complex)((x) + _Complex_I * (y)))
+#define CMPLXL(x, y) ((long double _Complex)((x) + _Complex_I * (y)))
+
+double creal(double _Complex z);
+float crealf(float _Complex z);
+long double creall(long double _Complex z);
+
+double cimag(double _Complex z);
+float cimagf(float _Complex z);
+long double cimagl(long double _Complex z);
+
+double cabs(double _Complex z);
+float cabsf(float _Complex z);
+long double cabsl(long double _Complex z);
+
+double carg(double _Complex z);
+float cargf(float _Complex z);
+long double cargl(long double _Complex z);
+
+double _Complex conj(double _Complex z);
+float _Complex conjf(float _Complex z);
+long double _Complex conjl(long double _Complex z);
+
+double _Complex cproj(double _Complex z);
+float _Complex cprojf(float _Complex z);
+long double _Complex cprojl(long double _Complex z);
+
+// Exponential functions
+double _Complex cexp(double _Complex z);
+float _Complex cexpf(float _Complex z);
+long double _Complex cexpl(long double _Complex z);
+
+double _Complex clog(double _Complex z);
+float _Complex clogf(float _Complex z);
+long double _Complex clogl(long double _Complex z);
+
+// Power functions
+double _Complex cpow(double _Complex x, double _Complex y);
+float _Complex cpowf(float _Complex x, float _Complex y);
+long double _Complex cpowl(long double _Complex x, long double _Complex y);
+
+double _Complex csqrt(double _Complex z);
+float _Complex csqrtf(float _Complex z);
+long double _Complex csqrtl(long double _Complex z);
+
+// Trigonometric functions
+double _Complex csin(double _Complex z);
+float _Complex csinf(float _Complex z);
+long double _Complex csinl(long double _Complex z);
+
+double _Complex ccos(double _Complex z);
+float _Complex ccosf(float _Complex z);
+long double _Complex ccosl(long double _Complex z);
+
+double _Complex ctan(double _Complex z);
+float _Complex ctanf(float _Complex z);
+long double _Complex ctanl(long double _Complex z);
+
+double _Complex casin(double _Complex z);
+float _Complex casinf(float _Complex z);
+long double _Complex casinl(long double _Complex z);
+
+double _Complex cacos(double _Complex z);
+float _Complex cacosf(float _Complex z);
+long double _Complex cacosl(long double _Complex z);
+
+double _Complex catan(double _Complex z);
+float _Complex catanf(float _Complex z);
+long double _Complex catanl(long double _Complex z);
+
+// Hyperbolic functions
+double _Complex csinh(double _Complex z);
+float _Complex csinhf(float _Complex z);
+long double _Complex csinhl(long double _Complex z);
+
+double _Complex ccosh(double _Complex z);
+float _Complex ccoshf(float _Complex z);
+long double _Complex ccoshl(long double _Complex z);
+
+double _Complex ctanh(double _Complex z);
+float _Complex ctanhf(float _Complex z);
+long double _Complex ctanhl(long double _Complex z);
+
+double _Complex casinh(double _Complex z);
+float _Complex casinhf(float _Complex z);
+long double _Complex casinhl(long double _Complex z);
+
+double _Complex cacosh(double _Complex z);
+float _Complex cacoshf(float _Complex z);
+long double _Complex cacoshl(long double _Complex z);
+
+double _Complex catanh(double _Complex z);
+float _Complex catanhf(float _Complex z);
+long double _Complex catanhl(long double _Complex z);
+
+#endif // MRDOCS_SHARE_HEADERS_LIBC_STUBS_COMPLEX_H

share/mrdocs/headers/libc-stubs/ctype.h

@@ -0,0 +1,32 @@
+//
+// Licensed under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//
+// Copyright (c) 2024 Alan de Freitas ([email protected])
+//
+// Official repository: https://github.com/cppalliance/mrdocs
+//
+
+#ifndef MRDOCS_SHARE_HEADERS_LIBC_STUBS_CTYPE_H
+#define MRDOCS_SHARE_HEADERS_LIBC_STUBS_CTYPE_H
+
+// Character classification
+int isalnum( int ch );
+int isalpha( int ch );
+int islower( int ch );
+int isupper( int ch );
+int isdigit( int ch );
+int isxdigit( int ch );
+int iscntrl( int ch );
+int isgraph( int ch );
+int isspace( int ch );
+int isblank( int ch );
+int isprint( int ch );
+int ispunct( int ch );
+
+// Character manipulation
+int tolower( int ch );
+int toupper( int ch );
+
+#endif // MRDOCS_SHARE_HEADERS_LIBC_STUBS_CTYPE_H

share/mrdocs/headers/libc-stubs/errno.h

@@ -0,0 +1,35 @@
+//
+// Licensed under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//
+// Copyright (c) 2024 Alan de Freitas ([email protected])
+//
+// Official repository: https://github.com/cppalliance/mrdocs
+//
+
+#ifndef MRDOCS_SHARE_HEADERS_LIBC_STUBS_ERRNO_H
+#define MRDOCS_SHARE_HEADERS_LIBC_STUBS_ERRNO_H
+
+#include "stddef.h"
+
+// Define errno as a thread-local variable
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+// Thread-local storage for errno
+extern __thread errno_t __errno;
+
+#ifdef __cplusplus
+}
+#endif
+
+// Error codes
+#define EDOM 1
+#define ERANGE 2
+#define EILSEQ 3
+
+#define errno (__errno)
+
+#endif // MRDOCS_SHARE_HEADERS_LIBC_STUBS_ERRNO_H