[libc-commits] [libc] [libc][docs] adds macro handling, POSIX status, and validation to docgen (PR #89421)
Michael Flanders via libc-commits
libc-commits at lists.llvm.org
Wed May 22 15:09:06 PDT 2024
https://github.com/Flandini updated https://github.com/llvm/llvm-project/pull/89421
>From 6e5a1440166bb280f7465fbe57492d4ce6d62371 Mon Sep 17 00:00:00 2001
From: Michael Flanders <flanders.michaelk at gmail.com>
Date: Thu, 18 Apr 2024 11:26:11 -0700
Subject: [PATCH 01/10] [libc][docs] adds macro handling, POSIX status, and
validation to docgen
docgen now lists macro implementation status in the generated rst files.
Adds POSIX definition link property to docgen json API (`posix-definition`)
and changes the `defined` property of docgen json API to `c-definition`. Now
that docgen's api is getting more specified, adds validation checks to docgen
to start codifying the docgen api spec.
To make sure this all looks good, I've added POSIX definition links to signal.h
as a tester. I'll attach the generated html file below for folks to preview.
---
libc/docs/ctype.rst | 25 +++-
libc/docs/fenv.rst | 117 ++++++++++++++-
libc/docs/signal.rst | 170 +++++++++++++++++++++-
libc/docs/stdbit.rst | 166 ++++++++++++++++++++-
libc/docs/threads.rst | 57 +++++++-
libc/utils/docgen/ctype.json | 28 ++--
libc/utils/docgen/docgen.py | 257 +++++++++++++++++++++++++++------
libc/utils/docgen/fenv.json | 72 ++++-----
libc/utils/docgen/signal.json | 145 ++++++++++++++++---
libc/utils/docgen/stdbit.json | 176 +++++++++++-----------
libc/utils/docgen/threads.json | 54 +++----
11 files changed, 1023 insertions(+), 244 deletions(-)
diff --git a/libc/docs/ctype.rst b/libc/docs/ctype.rst
index 7d77dadccc9ba..e87116f10bfbd 100644
--- a/libc/docs/ctype.rst
+++ b/libc/docs/ctype.rst
@@ -1,7 +1,11 @@
.. include:: check.rst
-ctype.h Functions
-=================
+=======
+ctype.h
+=======
+
+Functions
+=========
.. list-table::
:widths: auto
@@ -10,46 +14,61 @@ ctype.h Functions
* - Function
- Implemented
- - Standard
+ - C Standard
+ - POSIX Standard
* - isalnum
- |check|
- 7.4.1.1
+ -
* - isalpha
- |check|
- 7.4.1.2
+ -
* - isblank
- |check|
- 7.4.1.3
+ -
* - iscntrl
- |check|
- 7.4.1.4
+ -
* - isdigit
- |check|
- 7.4.1.5
+ -
* - isgraph
- |check|
- 7.4.1.6
+ -
* - islower
- |check|
- 7.4.1.7
+ -
* - isprint
- |check|
- 7.4.1.8
+ -
* - ispunct
- |check|
- 7.4.1.9
+ -
* - isspace
- |check|
- 7.4.1.10
+ -
* - isupper
- |check|
- 7.4.1.11
+ -
* - isxdigit
- |check|
- 7.4.1.12
+ -
* - tolower
- |check|
- 7.4.2.1
+ -
* - toupper
- |check|
- 7.4.2.2
+ -
diff --git a/libc/docs/fenv.rst b/libc/docs/fenv.rst
index 1dee5515e1174..22bef37d9c844 100644
--- a/libc/docs/fenv.rst
+++ b/libc/docs/fenv.rst
@@ -1,7 +1,11 @@
.. include:: check.rst
-fenv.h Functions
-================
+======
+fenv.h
+======
+
+Macros
+======
.. list-table::
:widths: auto
@@ -10,55 +14,162 @@ fenv.h Functions
* - Function
- Implemented
- - Standard
+ - C Standard
+ - POSIX Standard
+ * - FE_ALL_EXCEPT
+ - |check|
+ - 7.6.12
+ -
+ * - FE_DEC_DOWNWARD
+ -
+ - 7.6.14
+ -
+ * - FE_DEC_TONEAREST
+ -
+ - 7.6.14
+ -
+ * - FE_DEC_TONEARESTFROMZERO
+ -
+ - 7.6.14
+ -
+ * - FE_DEC_TOWARDZERO
+ -
+ - 7.6.14
+ -
+ * - FE_DEC_UPWARD
+ -
+ - 7.6.14
+ -
+ * - FE_DFL_ENV
+ - |check|
+ - 7.6.17
+ -
+ * - FE_DFL_MODE
+ -
+ - 7.6.11
+ -
+ * - FE_DIVBYZERO
+ - |check|
+ - 7.6.9
+ -
+ * - FE_DOWNARD
+ -
+ - 7.6.13
+ -
+ * - FE_INEXACT
+ - |check|
+ - 7.6.9
+ -
+ * - FE_INVALID
+ - |check|
+ - 7.6.9
+ -
+ * - FE_OVERFLOW
+ - |check|
+ - 7.6.9
+ -
+ * - FE_TONEAREST
+ - |check|
+ - 7.6.13
+ -
+ * - FE_TONEARESTFROMZERO
+ -
+ - 7.6.13
+ -
+ * - FE_TOWARDZERO
+ - |check|
+ - 7.6.13
+ -
+ * - FE_UNDERFLOW
+ - |check|
+ - 7.6.9
+ -
+ * - FE_UPWARD
+ - |check|
+ - 7.6.13
+ -
+ * - __STDC_VERSION_FENV_H__
+ -
+ - 7.6.5
+ -
+
+Functions
+=========
+
+.. list-table::
+ :widths: auto
+ :align: center
+ :header-rows: 1
+
+ * - Function
+ - Implemented
+ - C Standard
+ - POSIX Standard
* - fe_dec_getround
-
- 7.6.5.3
+ -
* - fe_dec_setround
-
- 7.6.5.6
+ -
* - feclearexcept
- |check|
- 7.6.4.1
+ -
* - fegetenv
- |check|
- 7.6.6.1
+ -
* - fegetexceptflag
- |check|
- 7.6.4.2
+ -
* - fegetmode
-
- 7.6.5.1
+ -
* - fegetround
- |check|
- 7.6.5.2
+ -
* - feholdexcept
- |check|
- 7.6.6.2
+ -
* - feraiseexcept
- |check|
- 7.6.4.3
+ -
* - fesetenv
- |check|
- 7.6.6.3
+ -
* - fesetexcept
- |check|
- 7.6.4.4
+ -
* - fesetexceptflag
- |check|
- 7.6.4.5
+ -
* - fesetmode
-
- 7.6.5.4
+ -
* - fesetround
- |check|
- 7.6.5.5
+ -
* - fetestexcept
- |check|
- 7.6.4.7
+ -
* - fetestexceptflag
- |check|
- 7.6.4.6
+ -
* - feupdateenv
- |check|
- 7.6.6.4
+ -
diff --git a/libc/docs/signal.rst b/libc/docs/signal.rst
index 7903bb439cb33..15d0aaaae3400 100644
--- a/libc/docs/signal.rst
+++ b/libc/docs/signal.rst
@@ -1,7 +1,160 @@
.. include:: check.rst
-signal.h Functions
-==================
+========
+signal.h
+========
+
+Macros
+======
+
+.. list-table::
+ :widths: auto
+ :align: center
+ :header-rows: 1
+
+ * - Function
+ - Implemented
+ - C Standard
+ - POSIX Standard
+ * - SIGABRT
+ - |check|
+ - 7.14.3
+ - https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html
+ * - SIGALRM
+ - |check|
+ -
+ - https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html
+ * - SIGBUS
+ - |check|
+ -
+ - https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html
+ * - SIGCHLD
+ - |check|
+ -
+ - https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html
+ * - SIGCONT
+ - |check|
+ -
+ - https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html
+ * - SIGFPE
+ - |check|
+ - 7.14.3
+ - https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html
+ * - SIGHUP
+ - |check|
+ -
+ - https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html
+ * - SIGILL
+ - |check|
+ - 7.14.3
+ - https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html
+ * - SIGINT
+ - |check|
+ - 7.14.3
+ - https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html
+ * - SIGKILL
+ - |check|
+ -
+ - https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html
+ * - SIGPIPE
+ - |check|
+ -
+ - https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html
+ * - SIGPOLL
+ - |check|
+ -
+ - https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html
+ * - SIGPROF
+ - |check|
+ -
+ - https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html
+ * - SIGQUIT
+ - |check|
+ -
+ - https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html
+ * - SIGRTMAX
+ - |check|
+ -
+ - https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html
+ * - SIGRTMIN
+ - |check|
+ -
+ - https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html
+ * - SIGSEGV
+ - |check|
+ - 7.14.3
+ - https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html
+ * - SIGSTOP
+ - |check|
+ -
+ - https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html
+ * - SIGSYS
+ - |check|
+ -
+ - https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html
+ * - SIGTERM
+ - |check|
+ - 7.14.3
+ - https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html
+ * - SIGTRAP
+ - |check|
+ -
+ - https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html
+ * - SIGTSTP
+ - |check|
+ -
+ - https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html
+ * - SIGTTIN
+ - |check|
+ -
+ - https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html
+ * - SIGTTOU
+ - |check|
+ -
+ - https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html
+ * - SIGURG
+ - |check|
+ -
+ - https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html
+ * - SIGUSR1
+ - |check|
+ -
+ - https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html
+ * - SIGUSR2
+ - |check|
+ -
+ - https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html
+ * - SIGVTALRM
+ - |check|
+ -
+ - https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html
+ * - SIGXCPU
+ - |check|
+ -
+ - https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html
+ * - SIGXFSZ
+ - |check|
+ -
+ - https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html
+ * - SIG_DFL
+ - |check|
+ - 7.14.3
+ - https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html
+ * - SIG_ERR
+ - |check|
+ - 7.14.3
+ - https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html
+ * - SIG_HOLD
+ -
+ -
+ - https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html
+ * - SIG_IGN
+ - |check|
+ - 7.14.3
+ - https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html
+
+Functions
+=========
.. list-table::
:widths: auto
@@ -10,34 +163,45 @@ signal.h Functions
* - Function
- Implemented
- - Standard
+ - C Standard
+ - POSIX Standard
* - kill
- |check|
-
+ - https://pubs.opengroup.org/onlinepubs/9699919799/functions/kill.html
* - raise
- |check|
- 7.14.2.1
+ - https://pubs.opengroup.org/onlinepubs/9699919799/functions/raise.html
* - sigaction
- |check|
-
+ - https://pubs.opengroup.org/onlinepubs/9699919799/functions/sigaction.html
* - sigaddset
- |check|
-
+ - https://pubs.opengroup.org/onlinepubs/9699919799/functions/sigaddset.html
* - sigaltstack
- |check|
-
+ - https://pubs.opengroup.org/onlinepubs/9699919799/functions/sigaltstack.html
* - sigdelset
- |check|
-
+ - https://pubs.opengroup.org/onlinepubs/9699919799/functions/sigdelset.html
* - sigemptyset
- |check|
-
+ - https://pubs.opengroup.org/onlinepubs/9699919799/functions/sigemptyset.html
* - sigfillset
- |check|
-
+ - https://pubs.opengroup.org/onlinepubs/9699919799/functions/sigfillset.html
* - signal
- |check|
- 7.14.1.1
+ - https://pubs.opengroup.org/onlinepubs/9699919799/functions/signal.html
* - sigprocmask
- |check|
-
+ - https://pubs.opengroup.org/onlinepubs/9699919799/functions/sigprocmask.html
diff --git a/libc/docs/stdbit.rst b/libc/docs/stdbit.rst
index 0a12b2b6d7b51..47c3a00e2ba6c 100644
--- a/libc/docs/stdbit.rst
+++ b/libc/docs/stdbit.rst
@@ -1,7 +1,96 @@
.. include:: check.rst
-stdbit.h Functions
-==================
+========
+stdbit.h
+========
+
+Macros
+======
+
+.. list-table::
+ :widths: auto
+ :align: center
+ :header-rows: 1
+
+ * - Function
+ - Implemented
+ - C Standard
+ - POSIX Standard
+ * - __STDC_ENDIAN_BIG__
+ - |check|
+ - 7.18.2.2
+ -
+ * - __STDC_ENDIAN_LITTLE__
+ - |check|
+ - 7.18.2.2
+ -
+ * - __STDC_ENDIAN_NATIVE__
+ - |check|
+ - 7.18.2.2
+ -
+ * - __STDC_VERSION_STDBIT_H__
+ - |check|
+ - 7.18.1.2
+ -
+ * - stdc_bit_ceil
+ - |check|
+ - 7.18.16.1
+ -
+ * - stdc_bit_floor
+ - |check|
+ - 7.18.15.1
+ -
+ * - stdc_bit_width
+ - |check|
+ - 7.18.14.1
+ -
+ * - stdc_count_ones
+ - |check|
+ - 7.18.12.1
+ -
+ * - stdc_count_zeros
+ - |check|
+ - 7.18.11.1
+ -
+ * - stdc_first_leading_one
+ - |check|
+ - 7.18.8.1
+ -
+ * - stdc_first_leading_zero
+ - |check|
+ - 7.18.7.1
+ -
+ * - stdc_first_trailing_one
+ - |check|
+ - 7.18.10.1
+ -
+ * - stdc_first_trailing_zero
+ - |check|
+ - 7.18.9.1
+ -
+ * - stdc_has_single_bit
+ - |check|
+ - 7.18.13.1
+ -
+ * - stdc_leading_ones
+ - |check|
+ - 7.18.4.1
+ -
+ * - stdc_leading_zeros
+ - |check|
+ - 7.18.3.1
+ -
+ * - stdc_trailing_ones
+ - |check|
+ - 7.18.6.1
+ -
+ * - stdc_trailing_zeros
+ - |check|
+ - 7.18.5.1
+ -
+
+Functions
+=========
.. list-table::
:widths: auto
@@ -10,214 +99,285 @@ stdbit.h Functions
* - Function
- Implemented
- - Standard
+ - C Standard
+ - POSIX Standard
* - stdc_bit_ceil_uc
- |check|
- 7.18.16
+ -
* - stdc_bit_ceil_ui
- |check|
- 7.18.16
+ -
* - stdc_bit_ceil_ul
- |check|
- 7.18.16
+ -
* - stdc_bit_ceil_ull
- |check|
- 7.18.16
+ -
* - stdc_bit_ceil_us
- |check|
- 7.18.16
+ -
* - stdc_bit_floor_uc
- |check|
- 7.18.15
+ -
* - stdc_bit_floor_ui
- |check|
- 7.18.15
+ -
* - stdc_bit_floor_ul
- |check|
- 7.18.15
+ -
* - stdc_bit_floor_ull
- |check|
- 7.18.15
+ -
* - stdc_bit_floor_us
- |check|
- 7.18.15
+ -
* - stdc_bit_width_uc
- |check|
- 7.18.14
+ -
* - stdc_bit_width_ui
- |check|
- 7.18.14
+ -
* - stdc_bit_width_ul
- |check|
- 7.18.14
+ -
* - stdc_bit_width_ull
- |check|
- 7.18.14
+ -
* - stdc_bit_width_us
- |check|
- 7.18.14
+ -
* - stdc_count_ones_uc
- |check|
- 7.18.12
+ -
* - stdc_count_ones_ui
- |check|
- 7.18.12
+ -
* - stdc_count_ones_ul
- |check|
- 7.18.12
+ -
* - stdc_count_ones_ull
- |check|
- 7.18.12
+ -
* - stdc_count_ones_us
- |check|
- 7.18.12
+ -
* - stdc_count_zeros_uc
- |check|
- 7.18.11
+ -
* - stdc_count_zeros_ui
- |check|
- 7.18.11
+ -
* - stdc_count_zeros_ul
- |check|
- 7.18.11
+ -
* - stdc_count_zeros_ull
- |check|
- 7.18.11
+ -
* - stdc_count_zeros_us
- |check|
- 7.18.11
+ -
* - stdc_first_leading_one_uc
- |check|
- 7.18.8
+ -
* - stdc_first_leading_one_ui
- |check|
- 7.18.8
+ -
* - stdc_first_leading_one_ul
- |check|
- 7.18.8
+ -
* - stdc_first_leading_one_ull
- |check|
- 7.18.8
+ -
* - stdc_first_leading_one_us
- |check|
- 7.18.8
+ -
* - stdc_first_leading_zero_uc
- |check|
- 7.18.7
+ -
* - stdc_first_leading_zero_ui
- |check|
- 7.18.7
+ -
* - stdc_first_leading_zero_ul
- |check|
- 7.18.7
+ -
* - stdc_first_leading_zero_ull
- |check|
- 7.18.7
+ -
* - stdc_first_leading_zero_us
- |check|
- 7.18.7
+ -
* - stdc_first_trailing_one_uc
- |check|
- 7.18.10
+ -
* - stdc_first_trailing_one_ui
- |check|
- 7.18.10
+ -
* - stdc_first_trailing_one_ul
- |check|
- 7.18.10
+ -
* - stdc_first_trailing_one_ull
- |check|
- 7.18.10
+ -
* - stdc_first_trailing_one_us
- |check|
- 7.18.10
+ -
* - stdc_first_trailing_zero_uc
- |check|
- 7.18.9
+ -
* - stdc_first_trailing_zero_ui
- |check|
- 7.18.9
+ -
* - stdc_first_trailing_zero_ul
- |check|
- 7.18.9
+ -
* - stdc_first_trailing_zero_ull
- |check|
- 7.18.9
+ -
* - stdc_first_trailing_zero_us
- |check|
- 7.18.9
+ -
* - stdc_has_single_bit_uc
- |check|
- 7.18.13
+ -
* - stdc_has_single_bit_ui
- |check|
- 7.18.13
+ -
* - stdc_has_single_bit_ul
- |check|
- 7.18.13
+ -
* - stdc_has_single_bit_ull
- |check|
- 7.18.13
+ -
* - stdc_has_single_bit_us
- |check|
- 7.18.13
+ -
* - stdc_leading_ones_uc
- |check|
- 7.18.4
+ -
* - stdc_leading_ones_ui
- |check|
- 7.18.4
+ -
* - stdc_leading_ones_ul
- |check|
- 7.18.4
+ -
* - stdc_leading_ones_ull
- |check|
- 7.18.4
+ -
* - stdc_leading_ones_us
- |check|
- 7.18.4
+ -
* - stdc_leading_zeros_uc
- |check|
- 7.18.3
+ -
* - stdc_leading_zeros_ui
- |check|
- 7.18.3
+ -
* - stdc_leading_zeros_ul
- |check|
- 7.18.3
+ -
* - stdc_leading_zeros_ull
- |check|
- 7.18.3
+ -
* - stdc_leading_zeros_us
- |check|
- 7.18.3
+ -
* - stdc_trailing_ones_uc
- |check|
- 7.18.6
+ -
* - stdc_trailing_ones_ui
- |check|
- 7.18.6
+ -
* - stdc_trailing_ones_ul
- |check|
- 7.18.6
+ -
* - stdc_trailing_ones_ull
- |check|
- 7.18.6
+ -
* - stdc_trailing_ones_us
- |check|
- 7.18.6
+ -
* - stdc_trailing_zeros_uc
- |check|
- 7.18.5
+ -
* - stdc_trailing_zeros_ui
- |check|
- 7.18.5
+ -
* - stdc_trailing_zeros_ul
- |check|
- 7.18.5
+ -
* - stdc_trailing_zeros_ull
- |check|
- 7.18.5
+ -
* - stdc_trailing_zeros_us
- |check|
- 7.18.5
+ -
diff --git a/libc/docs/threads.rst b/libc/docs/threads.rst
index 78e17e9fdec3a..360b29a64abd8 100644
--- a/libc/docs/threads.rst
+++ b/libc/docs/threads.rst
@@ -1,7 +1,32 @@
.. include:: check.rst
-threads.h Functions
-===================
+=========
+threads.h
+=========
+
+Macros
+======
+
+.. list-table::
+ :widths: auto
+ :align: center
+ :header-rows: 1
+
+ * - Function
+ - Implemented
+ - C Standard
+ - POSIX Standard
+ * - ONCE_FLAG_INIT
+ -
+ - 7.28.1.3
+ -
+ * - TSS_DTOR_ITERATIONS
+ -
+ - 7.28.1.3
+ -
+
+Functions
+=========
.. list-table::
:widths: auto
@@ -10,79 +35,105 @@ threads.h Functions
* - Function
- Implemented
- - Standard
+ - C Standard
+ - POSIX Standard
* - call_once
- |check|
- 7.28.2.1
+ -
* - cnd_broadcast
- |check|
- 7.28.3.1
+ -
* - cnd_destroy
- |check|
- 7.28.3.2
+ -
* - cnd_init
- |check|
- 7.28.3.3
+ -
* - cnd_signal
- |check|
- 7.28.3.4
+ -
* - cnd_timedwait
-
- 7.28.3.5
+ -
* - cnd_wait
- |check|
- 7.28.3.6
+ -
* - mtx_destroy
- |check|
- 7.28.4.1
+ -
* - mtx_init
- |check|
- 7.28.4.2
+ -
* - mtx_lock
- |check|
- 7.28.4.3
+ -
* - mtx_timedlock
-
- 7.28.4.4
+ -
* - mtx_trylock
-
- 7.28.4.5
+ -
* - mtx_unlock
- |check|
- 7.28.4.6
+ -
* - thrd_create
- |check|
- 7.28.5.1
+ -
* - thrd_current
- |check|
- 7.28.5.2
+ -
* - thrd_detach
- |check|
- 7.28.5.3
+ -
* - thrd_equal
- |check|
- 7.28.5.4
+ -
* - thrd_exit
- |check|
- 7.28.5.5
+ -
* - thrd_join
- |check|
- 7.28.5.6
+ -
* - thrd_sleep
-
- 7.28.5.7
+ -
* - thrd_yield
-
- 7.28.5.8
+ -
* - tss_create
- |check|
- 7.28.6.1
+ -
* - tss_delete
- |check|
- 7.28.6.2
+ -
* - tss_get
- |check|
- 7.28.6.3
+ -
* - tss_set
- |check|
- 7.28.6.4
+ -
diff --git a/libc/utils/docgen/ctype.json b/libc/utils/docgen/ctype.json
index 25eeb683846cf..af97e4bbbc0a2 100644
--- a/libc/utils/docgen/ctype.json
+++ b/libc/utils/docgen/ctype.json
@@ -1,46 +1,46 @@
{
"functions": {
"isalnum": {
- "defined": "7.4.1.1"
+ "c-definition": "7.4.1.1"
},
"isalpha": {
- "defined": "7.4.1.2"
+ "c-definition": "7.4.1.2"
},
"isblank": {
- "defined": "7.4.1.3"
+ "c-definition": "7.4.1.3"
},
"iscntrl": {
- "defined": "7.4.1.4"
+ "c-definition": "7.4.1.4"
},
"isdigit": {
- "defined": "7.4.1.5"
+ "c-definition": "7.4.1.5"
},
"isgraph": {
- "defined": "7.4.1.6"
+ "c-definition": "7.4.1.6"
},
"islower": {
- "defined": "7.4.1.7"
+ "c-definition": "7.4.1.7"
},
"isprint": {
- "defined": "7.4.1.8"
+ "c-definition": "7.4.1.8"
},
"ispunct": {
- "defined": "7.4.1.9"
+ "c-definition": "7.4.1.9"
},
"isspace": {
- "defined": "7.4.1.10"
+ "c-definition": "7.4.1.10"
},
"isupper": {
- "defined": "7.4.1.11"
+ "c-definition": "7.4.1.11"
},
"isxdigit": {
- "defined": "7.4.1.12"
+ "c-definition": "7.4.1.12"
},
"tolower" : {
- "defined": "7.4.2.1"
+ "c-definition": "7.4.2.1"
},
"toupper": {
- "defined": "7.4.2.2"
+ "c-definition": "7.4.2.2"
}
}
}
diff --git a/libc/utils/docgen/docgen.py b/libc/utils/docgen/docgen.py
index 23d45305fe513..43fa6c8e3dfcf 100755
--- a/libc/utils/docgen/docgen.py
+++ b/libc/utils/docgen/docgen.py
@@ -9,61 +9,160 @@
# ==-------------------------------------------------------------------------==#
from argparse import ArgumentParser, Namespace
from pathlib import Path
-from typing import Dict
+from typing import Dict, Generator
import sys
import json
-def load_api(hname: str) -> Dict:
- p = Path(__file__).parent / Path(hname).with_suffix(".json")
- api = p.read_text(encoding="utf-8")
- return json.loads(api)
+class DocgenAPIFormatError(Exception):
+ """Raised on fatal formatting errors with a description of a formatting error"""
-# TODO: we may need to get more sophisticated for less generic implementations.
-# Does libc/src/{hname minus .h suffix}/{fname}.cpp exist?
-def is_implemented(hname: str, fname: str) -> bool:
- path = Path(
- Path(__file__).parent.parent.parent,
- "src",
- hname.rstrip(".h")
- )
+class Header:
+ """
+ Maintains implementation information about a standard header file:
+ * where does its implementation dir live
+ * where is its macros file
+ * where is its docgen json file
- if not path.exists():
- raise FileNotFoundError(f"implementation dir does not exist: {path}")
+ By convention, the macro-only part of a header file is in a header-specific
+ file somewhere in the directory tree with root at
+ ``$LLVM_PROJECT_ROOT/libc/include/llvm-libc-macros``. Docgen expects that
+ if a macro is implemented, that it appears in a string
+ ``#define MACRO_NAME`` in some ``*-macros.h`` file in the directory tree..
+ Docgen searches for this string in the file to set the implementation status
+ shown in the generated rst docs rendered as html for display at
+ <libc.llvm.org>.
- if not path.is_dir():
- raise NotADirectoryError(f"implementation dir is not a dir: {path}")
+ By convention, each function for a header is implemented in a function-specific
+ cpp file somewhere in the directory tree with root at, e.g,
+ ``$LLVM_PROJECT_ROOT/libc/src/fenv``. Some headers have architecture-specific
+ implementations, like ``math``, and some don't, like ``fenv``. Docgen uses the
+ presence of this function-specific cpp file to set the implementation status
+ shown in the generated rst docs rendered as html for display at
+ <libc.llvm.org>.
+ """
- # Recursively search for the target source file in the subdirectories under
- # libc/src/{hname}.
- for _ in path.glob("**/" + fname + ".cpp"):
- return True
+ def __init__(self, header_name: str):
+ """
+ :param header_name: e.g., ``"threads.h"`` or ``"signal.h"``
+ """
+ self.name = header_name
+ self.stem = header_name.rstrip(".h")
+ self.libc_root = Path(__file__).parent.parent.parent
+ self.docgen_root = Path(__file__).parent
+ self.docgen_json = self.docgen_root / Path(header_name).with_suffix(".json")
+ self.fns_dir = Path(self.libc_root, "src", self.stem)
+ self.macros_dir = Path(self.libc_root, "include", "llvm-libc-macros")
- return False
+ def macro_file_exists(self) -> bool:
+ for _ in self.__get_macro_files():
+ return True
+ return False
-def print_functions(header: str, functions: Dict):
- for key in sorted(functions.keys()):
- print(f" * - {key}")
+ def fns_dir_exists(self) -> bool:
+ return self.fns_dir.exists() and self.fns_dir.is_dir()
- if is_implemented(header, key):
- print(" - |check|")
- else:
- print(" -")
+ def implements_fn(self, fn_name: str) -> bool:
+ for _ in self.fns_dir.glob(f"**/{fn_name}.cpp"):
+ return True
- # defined is optional. Having any content is optional.
- if functions[key] is not None and "defined" in functions[key]:
- print(f' - {functions[key]["defined"]}')
- else:
- print(" -")
+ return False
+ def implements_macro(self, m_name: str) -> bool:
+ """
+ Some macro files are in, e.g.,
+ ``$LLVM_PROJECT_ROOT/libc/include/llvm-libc-macros/fenv-macros.h``,
+ but others are in subdirectories, e.g., ``signal.h`` has the macro
+ definitions in
+ ``$LLVM_PROJECT_ROOT/libc/include/llvm-libc-macros/linux/signal-macros.h``.
-def print_header(header: str, api: Dict):
- print(".. include:: check.rst\n")
- fns = f"{header} Functions"
- print(fns)
- print("=" * (len(fns)))
+ :param m_name: name of macro, e.g., ``FE_ALL_EXCEPT``
+ """
+ for f in self.__get_macro_files():
+ if f"#define {m_name}" in f.read_text():
+ return True
+
+ return False
+
+ def __get_macro_files(self) -> Generator[Path, None, None]:
+ return self.macros_dir.glob(f"**/{self.stem}-macros.h")
+
+
+def check_api(header: Header, api: Dict):
+ """
+ Checks that docgen json files are properly formatted. If there are any
+ fatal formatting errors, raises exceptions with error messages useful for
+ fixing formatting. Warnings are printed to stderr on non-fatal formatting
+ errors. The code that runs after ``check_api(api)`` is called expects that
+ ``check_api`` executed without raising formatting exceptions so the json
+ matches the formatting specified here.
+
+ The json file may contain:
+ * an optional macros object
+ * an optional functions object
+
+ Formatting of ``macros`` and ``functions`` objects
+ ==================================================
+
+ If a macros or functions object is present, then it may contain nested
+ objects. Each of these nested objects should have a name matching a macro
+ or function's name, and each nested object must have the property:
+ ``"c-definition"`` or ``"posix-definition"``.
+
+ Description of properties
+ =========================
+ The defined property is intended to be a reference to a part of the
+ standard that defines the function or macro. For the ``"c-definition"`` property,
+ this should be a C standard section number. For the ``"posix-definition"`` property,
+ this should be a link to the definition.
+
+ :param api: docgen json file contents parsed into a dict
+ """
+ errors = []
+ cdef = "c-definition"
+ pdef = "posix-definition"
+
+ # Validate macros
+ if "macros" in api:
+ if not header.macro_file_exists():
+ print(
+ f"warning: Macro definitions are listed for {header.name}, but no macro file can be found in the directory tree rooted at {header.macros_dir}. All macros will be listed as not implemented.",
+ file=sys.stderr,
+ )
+
+ macros = api["macros"]
+
+ for name, obj in macros.items():
+ if not (cdef in obj or pdef in obj):
+ err = f'error: Macro {name} does not contain at least one required property: "{cdef}" or "{pdef}"'
+ errors.append(err)
+
+ # Validate functions
+ if "functions" in api:
+ if not header.fns_dir_exists():
+ print(
+ f"warning: Function definitions are listed for {header.name}, but no function implementation directory exists at {header.fns_dir}. All functions will be listed as not implemented.",
+ file=sys.stderr,
+ )
+
+ fns = api["functions"]
+ for name, obj in fns.items():
+ if not (cdef in obj or pdef in obj):
+ err = f'error: function {name} does not contain at least one required property: "{cdef}" or "{pdef}"'
+ errors.append(err)
+
+ if errors:
+ raise DocgenAPIFormatError("\n".join(errors))
+
+
+def load_api(header: Header) -> Dict:
+ api = header.docgen_json.read_text(encoding="utf-8")
+ return json.loads(api)
+
+
+def print_tbl_dir():
print(
f"""
.. list-table::
@@ -73,10 +172,78 @@ def print_header(header: str, api: Dict):
* - Function
- Implemented
- - Standard"""
+ - C Standard
+ - POSIX Standard"""
)
- # TODO: how do we want to signal implementation of macros?
- print_functions(header, api["functions"])
+
+
+def print_functions_rst(header: Header, functions: Dict):
+ tbl_hdr = "Functions"
+ print(tbl_hdr)
+ print("=" * len(tbl_hdr))
+
+ print_tbl_dir()
+
+ for name in sorted(functions.keys()):
+ print(f" * - {name}")
+
+ if header.fns_dir_exists() and header.implements_fn(name):
+ print(" - |check|")
+ else:
+ print(" -")
+
+ if "c-definition" in functions[name]:
+ print(f' - {functions[name]["c-definition"]}')
+ else:
+ print(" -")
+
+ if "posix-definition" in functions[name]:
+ print(f' - {functions[name]["posix-definition"]}')
+ else:
+ print(" -")
+
+
+def print_macros_rst(header: Header, macros: Dict):
+ tbl_hdr = "Macros"
+ print(tbl_hdr)
+ print("=" * len(tbl_hdr))
+
+ print_tbl_dir()
+
+ for name in sorted(macros.keys()):
+ print(f" * - {name}")
+
+ if header.macro_file_exists() and header.implements_macro(name):
+ print(" - |check|")
+ else:
+ print(" -")
+
+ if "c-definition" in macros[name]:
+ print(f' - {macros[name]["c-definition"]}')
+ else:
+ print(" -")
+
+ if "posix-definition" in macros[name]:
+ print(f' - {macros[name]["posix-definition"]}')
+ else:
+ print(" -")
+
+
+def print_impl_status_rst(header: Header, api: Dict):
+ print(".. include:: check.rst\n")
+
+ print("=" * len(header.name))
+ print(header.name)
+ print("=" * len(header.name))
+ print()
+
+ # the macro and function sections are both optional
+ if "macros" in api:
+ print_macros_rst(header, api["macros"])
+ print()
+
+ if "functions" in api:
+ print_functions_rst(header, api["functions"])
def parse_args() -> Namespace:
@@ -88,6 +255,8 @@ def parse_args() -> Namespace:
if __name__ == "__main__":
args = parse_args()
- api = load_api(args.header_name)
+ header = Header(args.header_name)
+ api = load_api(header)
+ check_api(header, api)
- print_header(args.header_name, api)
+ print_impl_status_rst(header, api)
diff --git a/libc/utils/docgen/fenv.json b/libc/utils/docgen/fenv.json
index 9aa3f641ddc94..788b196c053bc 100644
--- a/libc/utils/docgen/fenv.json
+++ b/libc/utils/docgen/fenv.json
@@ -1,114 +1,114 @@
{
"macros": {
"__STDC_VERSION_FENV_H__": {
- "defined": "7.6.5"
+ "c-definition": "7.6.5"
},
"FE_DIVBYZERO": {
- "defined": "7.6.9"
+ "c-definition": "7.6.9"
},
"FE_INEXACT": {
- "defined": "7.6.9"
+ "c-definition": "7.6.9"
},
"FE_INVALID": {
- "defined": "7.6.9"
+ "c-definition": "7.6.9"
},
"FE_OVERFLOW": {
- "defined": "7.6.9"
+ "c-definition": "7.6.9"
},
"FE_UNDERFLOW": {
- "defined": "7.6.9"
+ "c-definition": "7.6.9"
},
"FE_ALL_EXCEPT": {
- "defined": "7.6.12"
+ "c-definition": "7.6.12"
},
"FE_DFL_MODE": {
- "defined": "7.6.11"
+ "c-definition": "7.6.11"
},
"FE_DOWNARD": {
- "defined": "7.6.13"
+ "c-definition": "7.6.13"
},
"FE_TONEAREST": {
- "defined": "7.6.13"
+ "c-definition": "7.6.13"
},
"FE_TONEARESTFROMZERO": {
- "defined": "7.6.13"
+ "c-definition": "7.6.13"
},
"FE_TOWARDZERO": {
- "defined": "7.6.13"
+ "c-definition": "7.6.13"
},
"FE_UPWARD": {
- "defined": "7.6.13"
+ "c-definition": "7.6.13"
},
"FE_DEC_DOWNWARD": {
- "defined": "7.6.14"
+ "c-definition": "7.6.14"
},
"FE_DEC_TONEAREST": {
- "defined": "7.6.14"
+ "c-definition": "7.6.14"
},
"FE_DEC_TONEARESTFROMZERO": {
- "defined": "7.6.14"
+ "c-definition": "7.6.14"
},
"FE_DEC_TOWARDZERO": {
- "defined": "7.6.14"
+ "c-definition": "7.6.14"
},
"FE_DEC_UPWARD": {
- "defined": "7.6.14"
+ "c-definition": "7.6.14"
},
"FE_DFL_ENV": {
- "defined": "7.6.17"
+ "c-definition": "7.6.17"
}
},
"functions": {
"feclearexcept": {
- "defined": "7.6.4.1"
+ "c-definition": "7.6.4.1"
},
"fegetexceptflag": {
- "defined": "7.6.4.2"
+ "c-definition": "7.6.4.2"
},
"feraiseexcept": {
- "defined": "7.6.4.3"
+ "c-definition": "7.6.4.3"
},
"fesetexcept": {
- "defined": "7.6.4.4"
+ "c-definition": "7.6.4.4"
},
"fesetexceptflag": {
- "defined": "7.6.4.5"
+ "c-definition": "7.6.4.5"
},
"fetestexceptflag": {
- "defined": "7.6.4.6"
+ "c-definition": "7.6.4.6"
},
"fetestexcept": {
- "defined": "7.6.4.7"
+ "c-definition": "7.6.4.7"
},
"fegetmode": {
- "defined": "7.6.5.1"
+ "c-definition": "7.6.5.1"
},
"fegetround": {
- "defined": "7.6.5.2"
+ "c-definition": "7.6.5.2"
},
"fe_dec_getround": {
- "defined": "7.6.5.3"
+ "c-definition": "7.6.5.3"
},
"fesetmode": {
- "defined": "7.6.5.4"
+ "c-definition": "7.6.5.4"
},
"fesetround": {
- "defined": "7.6.5.5"
+ "c-definition": "7.6.5.5"
},
"fe_dec_setround": {
- "defined": "7.6.5.6"
+ "c-definition": "7.6.5.6"
},
"fegetenv": {
- "defined": "7.6.6.1"
+ "c-definition": "7.6.6.1"
},
"feholdexcept": {
- "defined": "7.6.6.2"
+ "c-definition": "7.6.6.2"
},
"fesetenv": {
- "defined": "7.6.6.3"
+ "c-definition": "7.6.6.3"
},
"feupdateenv": {
- "defined": "7.6.6.4"
+ "c-definition": "7.6.6.4"
}
}
}
diff --git a/libc/utils/docgen/signal.json b/libc/utils/docgen/signal.json
index d5380d348b7d6..337b0c19717b7 100644
--- a/libc/utils/docgen/signal.json
+++ b/libc/utils/docgen/signal.json
@@ -1,47 +1,152 @@
{
"macros": {
"SIG_DFL": {
- "defined": "7.14.3"
+ "c-definition": "7.14.3",
+ "posix-definition": "https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html"
},
"SIG_ERR": {
- "defined": "7.14.3"
+ "c-definition": "7.14.3",
+ "posix-definition": "https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html"
+ },
+ "SIG_HOLD": {
+ "posix-definition": "https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html"
},
"SIG_IGN": {
- "defined": "7.14.3"
+ "c-definition": "7.14.3",
+ "posix-definition": "https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html"
+ },
+ "SIGRTMIN": {
+ "posix-definition": "https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html"
+ },
+ "SIGRTMAX": {
+ "posix-definition": "https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html"
},
"SIGABRT": {
- "defined": "7.14.3"
+ "c-definition": "7.14.3",
+ "posix-definition": "https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html"
+ },
+ "SIGALRM": {
+ "posix-definition": "https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html"
+ },
+ "SIGBUS": {
+ "posix-definition": "https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html"
+ },
+ "SIGCHLD": {
+ "posix-definition": "https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html"
+ },
+ "SIGCONT": {
+ "posix-definition": "https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html"
},
"SIGFPE": {
- "defined": "7.14.3"
+ "c-definition": "7.14.3",
+ "posix-definition": "https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html"
+ },
+ "SIGHUP": {
+ "posix-definition": "https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html"
},
"SIGILL": {
- "defined": "7.14.3"
+ "c-definition": "7.14.3",
+ "posix-definition": "https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html"
},
"SIGINT": {
- "defined": "7.14.3"
+ "c-definition": "7.14.3",
+ "posix-definition": "https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html"
+ },
+ "SIGKILL": {
+ "posix-definition": "https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html"
+ },
+ "SIGPIPE": {
+ "posix-definition": "https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html"
+ },
+ "SIGPIPE": {
+ "posix-definition": "https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html"
+ },
+ "SIGQUIT": {
+ "posix-definition": "https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html"
},
"SIGSEGV": {
- "defined": "7.14.3"
+ "c-definition": "7.14.3",
+ "posix-definition": "https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html"
+ },
+ "SIGSTOP": {
+ "posix-definition": "https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html"
},
"SIGTERM": {
- "defined": "7.14.3"
+ "c-definition": "7.14.3",
+ "posix-definition": "https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html"
+ },
+ "SIGTSTP": {
+ "posix-definition": "https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html"
+ },
+ "SIGTTIN": {
+ "posix-definition": "https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html"
+ },
+ "SIGTTOU": {
+ "posix-definition": "https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html"
+ },
+ "SIGUSR1": {
+ "posix-definition": "https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html"
+ },
+ "SIGUSR2": {
+ "posix-definition": "https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html"
+ },
+ "SIGPOLL": {
+ "posix-definition": "https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html"
+ },
+ "SIGPROF": {
+ "posix-definition": "https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html"
+ },
+ "SIGSYS": {
+ "posix-definition": "https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html"
+ },
+ "SIGTRAP": {
+ "posix-definition": "https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html"
+ },
+ "SIGURG": {
+ "posix-definition": "https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html"
+ },
+ "SIGVTALRM": {
+ "posix-definition": "https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html"
+ },
+ "SIGXCPU": {
+ "posix-definition": "https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html"
+ },
+ "SIGXFSZ": {
+ "posix-definition": "https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html"
}
},
"functions": {
"signal": {
- "defined": "7.14.1.1"
+ "c-definition": "7.14.1.1",
+ "posix-definition": "https://pubs.opengroup.org/onlinepubs/9699919799/functions/signal.html"
},
"raise": {
- "defined": "7.14.2.1"
- },
- "kill": null,
- "sigaction": null,
- "sigaddset": null,
- "sigaltstack": null,
- "sigdelset": null,
- "sigemptyset": null,
- "sigfillset": null,
- "sigprocmask": null
+ "c-definition": "7.14.2.1",
+ "posix-definition": "https://pubs.opengroup.org/onlinepubs/9699919799/functions/raise.html"
+ },
+ "kill": {
+ "posix-definition": "https://pubs.opengroup.org/onlinepubs/9699919799/functions/kill.html"
+ },
+ "sigaction": {
+ "posix-definition": "https://pubs.opengroup.org/onlinepubs/9699919799/functions/sigaction.html"
+ },
+ "sigaddset": {
+ "posix-definition": "https://pubs.opengroup.org/onlinepubs/9699919799/functions/sigaddset.html"
+ },
+ "sigaltstack": {
+ "posix-definition": "https://pubs.opengroup.org/onlinepubs/9699919799/functions/sigaltstack.html"
+ },
+ "sigdelset": {
+ "posix-definition": "https://pubs.opengroup.org/onlinepubs/9699919799/functions/sigdelset.html"
+ },
+ "sigemptyset": {
+ "posix-definition": "https://pubs.opengroup.org/onlinepubs/9699919799/functions/sigemptyset.html"
+ },
+ "sigfillset": {
+ "posix-definition": "https://pubs.opengroup.org/onlinepubs/9699919799/functions/sigfillset.html"
+ },
+ "sigprocmask": {
+ "posix-definition": "https://pubs.opengroup.org/onlinepubs/9699919799/functions/sigprocmask.html"
+ }
}
}
diff --git a/libc/utils/docgen/stdbit.json b/libc/utils/docgen/stdbit.json
index 88106cf0e4f97..25060c1ff9fd8 100644
--- a/libc/utils/docgen/stdbit.json
+++ b/libc/utils/docgen/stdbit.json
@@ -1,270 +1,270 @@
{
"macros": {
"__STDC_VERSION_STDBIT_H__": {
- "defined": "7.18.1.2"
+ "c-definition": "7.18.1.2"
},
"__STDC_ENDIAN_LITTLE__": {
- "defined": "7.18.2.2"
+ "c-definition": "7.18.2.2"
},
"__STDC_ENDIAN_BIG__": {
- "defined": "7.18.2.2"
+ "c-definition": "7.18.2.2"
},
"__STDC_ENDIAN_NATIVE__": {
- "defined": "7.18.2.2"
+ "c-definition": "7.18.2.2"
},
"stdc_leading_zeros": {
- "defined": "7.18.3.1"
+ "c-definition": "7.18.3.1"
},
"stdc_leading_ones": {
- "defined": "7.18.4.1"
+ "c-definition": "7.18.4.1"
},
"stdc_trailing_zeros": {
- "defined": "7.18.5.1"
+ "c-definition": "7.18.5.1"
},
"stdc_trailing_ones": {
- "defined": "7.18.6.1"
+ "c-definition": "7.18.6.1"
},
"stdc_first_leading_zero": {
- "defined": "7.18.7.1"
+ "c-definition": "7.18.7.1"
},
"stdc_first_leading_one": {
- "defined": "7.18.8.1"
+ "c-definition": "7.18.8.1"
},
"stdc_first_trailing_zero": {
- "defined": "7.18.9.1"
+ "c-definition": "7.18.9.1"
},
"stdc_first_trailing_one": {
- "defined": "7.18.10.1"
+ "c-definition": "7.18.10.1"
},
"stdc_count_zeros": {
- "defined": "7.18.11.1"
+ "c-definition": "7.18.11.1"
},
"stdc_count_ones": {
- "defined": "7.18.12.1"
+ "c-definition": "7.18.12.1"
},
"stdc_has_single_bit": {
- "defined": "7.18.13.1"
+ "c-definition": "7.18.13.1"
},
"stdc_bit_width": {
- "defined": "7.18.14.1"
+ "c-definition": "7.18.14.1"
},
"stdc_bit_floor": {
- "defined": "7.18.15.1"
+ "c-definition": "7.18.15.1"
},
"stdc_bit_ceil": {
- "defined": "7.18.16.1"
+ "c-definition": "7.18.16.1"
}
},
"functions": {
"stdc_leading_zeros_uc": {
- "defined": "7.18.3"
+ "c-definition": "7.18.3"
},
"stdc_leading_zeros_us": {
- "defined": "7.18.3"
+ "c-definition": "7.18.3"
},
"stdc_leading_zeros_ui": {
- "defined": "7.18.3"
+ "c-definition": "7.18.3"
},
"stdc_leading_zeros_ul": {
- "defined": "7.18.3"
+ "c-definition": "7.18.3"
},
"stdc_leading_zeros_ull": {
- "defined": "7.18.3"
+ "c-definition": "7.18.3"
},
"stdc_leading_ones_uc": {
- "defined": "7.18.4"
+ "c-definition": "7.18.4"
},
"stdc_leading_ones_us": {
- "defined": "7.18.4"
+ "c-definition": "7.18.4"
},
"stdc_leading_ones_ui": {
- "defined": "7.18.4"
+ "c-definition": "7.18.4"
},
"stdc_leading_ones_ul": {
- "defined": "7.18.4"
+ "c-definition": "7.18.4"
},
"stdc_leading_ones_ull": {
- "defined": "7.18.4"
+ "c-definition": "7.18.4"
},
"stdc_trailing_zeros_uc": {
- "defined": "7.18.5"
+ "c-definition": "7.18.5"
},
"stdc_trailing_zeros_us": {
- "defined": "7.18.5"
+ "c-definition": "7.18.5"
},
"stdc_trailing_zeros_ui": {
- "defined": "7.18.5"
+ "c-definition": "7.18.5"
},
"stdc_trailing_zeros_ul": {
- "defined": "7.18.5"
+ "c-definition": "7.18.5"
},
"stdc_trailing_zeros_ull": {
- "defined": "7.18.5"
+ "c-definition": "7.18.5"
},
"stdc_trailing_ones_uc": {
- "defined": "7.18.6"
+ "c-definition": "7.18.6"
},
"stdc_trailing_ones_us": {
- "defined": "7.18.6"
+ "c-definition": "7.18.6"
},
"stdc_trailing_ones_ui": {
- "defined": "7.18.6"
+ "c-definition": "7.18.6"
},
"stdc_trailing_ones_ul": {
- "defined": "7.18.6"
+ "c-definition": "7.18.6"
},
"stdc_trailing_ones_ull": {
- "defined": "7.18.6"
+ "c-definition": "7.18.6"
},
"stdc_first_leading_zero_uc": {
- "defined": "7.18.7"
+ "c-definition": "7.18.7"
},
"stdc_first_leading_zero_us": {
- "defined": "7.18.7"
+ "c-definition": "7.18.7"
},
"stdc_first_leading_zero_ui": {
- "defined": "7.18.7"
+ "c-definition": "7.18.7"
},
"stdc_first_leading_zero_ul": {
- "defined": "7.18.7"
+ "c-definition": "7.18.7"
},
"stdc_first_leading_zero_ull": {
- "defined": "7.18.7"
+ "c-definition": "7.18.7"
},
"stdc_first_leading_one_uc": {
- "defined": "7.18.8"
+ "c-definition": "7.18.8"
},
"stdc_first_leading_one_us": {
- "defined": "7.18.8"
+ "c-definition": "7.18.8"
},
"stdc_first_leading_one_ui": {
- "defined": "7.18.8"
+ "c-definition": "7.18.8"
},
"stdc_first_leading_one_ul": {
- "defined": "7.18.8"
+ "c-definition": "7.18.8"
},
"stdc_first_leading_one_ull": {
- "defined": "7.18.8"
+ "c-definition": "7.18.8"
},
"stdc_first_trailing_zero_uc": {
- "defined": "7.18.9"
+ "c-definition": "7.18.9"
},
"stdc_first_trailing_zero_us": {
- "defined": "7.18.9"
+ "c-definition": "7.18.9"
},
"stdc_first_trailing_zero_ui": {
- "defined": "7.18.9"
+ "c-definition": "7.18.9"
},
"stdc_first_trailing_zero_ul": {
- "defined": "7.18.9"
+ "c-definition": "7.18.9"
},
"stdc_first_trailing_zero_ull": {
- "defined": "7.18.9"
+ "c-definition": "7.18.9"
},
"stdc_first_trailing_one_uc": {
- "defined": "7.18.10"
+ "c-definition": "7.18.10"
},
"stdc_first_trailing_one_us": {
- "defined": "7.18.10"
+ "c-definition": "7.18.10"
},
"stdc_first_trailing_one_ui": {
- "defined": "7.18.10"
+ "c-definition": "7.18.10"
},
"stdc_first_trailing_one_ul": {
- "defined": "7.18.10"
+ "c-definition": "7.18.10"
},
"stdc_first_trailing_one_ull": {
- "defined": "7.18.10"
+ "c-definition": "7.18.10"
},
"stdc_count_zeros_uc": {
- "defined": "7.18.11"
+ "c-definition": "7.18.11"
},
"stdc_count_zeros_us": {
- "defined": "7.18.11"
+ "c-definition": "7.18.11"
},
"stdc_count_zeros_ui": {
- "defined": "7.18.11"
+ "c-definition": "7.18.11"
},
"stdc_count_zeros_ul": {
- "defined": "7.18.11"
+ "c-definition": "7.18.11"
},
"stdc_count_zeros_ull": {
- "defined": "7.18.11"
+ "c-definition": "7.18.11"
},
"stdc_count_ones_uc": {
- "defined": "7.18.12"
+ "c-definition": "7.18.12"
},
"stdc_count_ones_us": {
- "defined": "7.18.12"
+ "c-definition": "7.18.12"
},
"stdc_count_ones_ui": {
- "defined": "7.18.12"
+ "c-definition": "7.18.12"
},
"stdc_count_ones_ul": {
- "defined": "7.18.12"
+ "c-definition": "7.18.12"
},
"stdc_count_ones_ull": {
- "defined": "7.18.12"
+ "c-definition": "7.18.12"
},
"stdc_has_single_bit_uc": {
- "defined": "7.18.13"
+ "c-definition": "7.18.13"
},
"stdc_has_single_bit_us": {
- "defined": "7.18.13"
+ "c-definition": "7.18.13"
},
"stdc_has_single_bit_ui": {
- "defined": "7.18.13"
+ "c-definition": "7.18.13"
},
"stdc_has_single_bit_ul": {
- "defined": "7.18.13"
+ "c-definition": "7.18.13"
},
"stdc_has_single_bit_ull": {
- "defined": "7.18.13"
+ "c-definition": "7.18.13"
},
"stdc_bit_width_uc": {
- "defined": "7.18.14"
+ "c-definition": "7.18.14"
},
"stdc_bit_width_us": {
- "defined": "7.18.14"
+ "c-definition": "7.18.14"
},
"stdc_bit_width_ui": {
- "defined": "7.18.14"
+ "c-definition": "7.18.14"
},
"stdc_bit_width_ul": {
- "defined": "7.18.14"
+ "c-definition": "7.18.14"
},
"stdc_bit_width_ull": {
- "defined": "7.18.14"
+ "c-definition": "7.18.14"
},
"stdc_bit_floor_uc": {
- "defined": "7.18.15"
+ "c-definition": "7.18.15"
},
"stdc_bit_floor_us": {
- "defined": "7.18.15"
+ "c-definition": "7.18.15"
},
"stdc_bit_floor_ui": {
- "defined": "7.18.15"
+ "c-definition": "7.18.15"
},
"stdc_bit_floor_ul": {
- "defined": "7.18.15"
+ "c-definition": "7.18.15"
},
"stdc_bit_floor_ull": {
- "defined": "7.18.15"
+ "c-definition": "7.18.15"
},
"stdc_bit_ceil_uc": {
- "defined": "7.18.16"
+ "c-definition": "7.18.16"
},
"stdc_bit_ceil_us": {
- "defined": "7.18.16"
+ "c-definition": "7.18.16"
},
"stdc_bit_ceil_ui": {
- "defined": "7.18.16"
+ "c-definition": "7.18.16"
},
"stdc_bit_ceil_ul": {
- "defined": "7.18.16"
+ "c-definition": "7.18.16"
},
"stdc_bit_ceil_ull": {
- "defined": "7.18.16"
+ "c-definition": "7.18.16"
}
}
}
diff --git a/libc/utils/docgen/threads.json b/libc/utils/docgen/threads.json
index aef6ffaf75bae..8591cbde55a49 100644
--- a/libc/utils/docgen/threads.json
+++ b/libc/utils/docgen/threads.json
@@ -1,87 +1,87 @@
{
"macros": {
"ONCE_FLAG_INIT": {
- "defined": "7.28.1.3"
+ "c-definition": "7.28.1.3"
},
"TSS_DTOR_ITERATIONS": {
- "defined": "7.28.1.3"
+ "c-definition": "7.28.1.3"
}
},
"functions": {
"call_once": {
- "defined": "7.28.2.1"
+ "c-definition": "7.28.2.1"
},
"cnd_broadcast": {
- "defined": "7.28.3.1"
+ "c-definition": "7.28.3.1"
},
"cnd_destroy": {
- "defined": "7.28.3.2"
+ "c-definition": "7.28.3.2"
},
"cnd_init": {
- "defined": "7.28.3.3"
+ "c-definition": "7.28.3.3"
},
"cnd_signal": {
- "defined": "7.28.3.4"
+ "c-definition": "7.28.3.4"
},
"cnd_timedwait": {
- "defined": "7.28.3.5"
+ "c-definition": "7.28.3.5"
},
"cnd_wait": {
- "defined": "7.28.3.6"
+ "c-definition": "7.28.3.6"
},
"mtx_destroy": {
- "defined": "7.28.4.1"
+ "c-definition": "7.28.4.1"
},
"mtx_init": {
- "defined": "7.28.4.2"
+ "c-definition": "7.28.4.2"
},
"mtx_lock": {
- "defined": "7.28.4.3"
+ "c-definition": "7.28.4.3"
},
"mtx_timedlock": {
- "defined": "7.28.4.4"
+ "c-definition": "7.28.4.4"
},
"mtx_trylock": {
- "defined": "7.28.4.5"
+ "c-definition": "7.28.4.5"
},
"mtx_unlock": {
- "defined": "7.28.4.6"
+ "c-definition": "7.28.4.6"
},
"thrd_create": {
- "defined": "7.28.5.1"
+ "c-definition": "7.28.5.1"
},
"thrd_current": {
- "defined": "7.28.5.2"
+ "c-definition": "7.28.5.2"
},
"thrd_detach": {
- "defined": "7.28.5.3"
+ "c-definition": "7.28.5.3"
},
"thrd_equal": {
- "defined": "7.28.5.4"
+ "c-definition": "7.28.5.4"
},
"thrd_exit": {
- "defined": "7.28.5.5"
+ "c-definition": "7.28.5.5"
},
"thrd_join": {
- "defined": "7.28.5.6"
+ "c-definition": "7.28.5.6"
},
"thrd_sleep": {
- "defined": "7.28.5.7"
+ "c-definition": "7.28.5.7"
},
"thrd_yield": {
- "defined": "7.28.5.8"
+ "c-definition": "7.28.5.8"
},
"tss_create": {
- "defined": "7.28.6.1"
+ "c-definition": "7.28.6.1"
},
"tss_delete": {
- "defined": "7.28.6.2"
+ "c-definition": "7.28.6.2"
},
"tss_get": {
- "defined": "7.28.6.3"
+ "c-definition": "7.28.6.3"
},
"tss_set": {
- "defined": "7.28.6.4"
+ "c-definition": "7.28.6.4"
}
}
}
>From 857a3ee7c5f1f6ea7253dab18dc1fcb526869e0d Mon Sep 17 00:00:00 2001
From: Michael Flanders <flanders.michaelk at gmail.com>
Date: Mon, 22 Apr 2024 15:48:18 -0500
Subject: [PATCH 02/10] Remove typo in docgen.py docs
Co-authored-by: Nick Desaulniers <nickdesaulniers at users.noreply.github.com>
---
libc/utils/docgen/docgen.py | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/libc/utils/docgen/docgen.py b/libc/utils/docgen/docgen.py
index 43fa6c8e3dfcf..ac62558c51a82 100755
--- a/libc/utils/docgen/docgen.py
+++ b/libc/utils/docgen/docgen.py
@@ -29,7 +29,7 @@ class Header:
file somewhere in the directory tree with root at
``$LLVM_PROJECT_ROOT/libc/include/llvm-libc-macros``. Docgen expects that
if a macro is implemented, that it appears in a string
- ``#define MACRO_NAME`` in some ``*-macros.h`` file in the directory tree..
+ ``#define MACRO_NAME`` in some ``*-macros.h`` file in the directory tree.
Docgen searches for this string in the file to set the implementation status
shown in the generated rst docs rendered as html for display at
<libc.llvm.org>.
>From fd63dce806442ba9183c8199b9ab5e8a95beaf22 Mon Sep 17 00:00:00 2001
From: Michael Flanders <flanders.michaelk at gmail.com>
Date: Mon, 22 Apr 2024 15:48:55 -0500
Subject: [PATCH 03/10] Refactor docgen.py header setting directories
Co-authored-by: Nick Desaulniers <nickdesaulniers at users.noreply.github.com>
---
libc/utils/docgen/docgen.py | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/libc/utils/docgen/docgen.py b/libc/utils/docgen/docgen.py
index ac62558c51a82..cf6529e19d915 100755
--- a/libc/utils/docgen/docgen.py
+++ b/libc/utils/docgen/docgen.py
@@ -49,8 +49,8 @@ def __init__(self, header_name: str):
"""
self.name = header_name
self.stem = header_name.rstrip(".h")
- self.libc_root = Path(__file__).parent.parent.parent
self.docgen_root = Path(__file__).parent
+ self.libc_root = self.docgen_root.parent.parent
self.docgen_json = self.docgen_root / Path(header_name).with_suffix(".json")
self.fns_dir = Path(self.libc_root, "src", self.stem)
self.macros_dir = Path(self.libc_root, "include", "llvm-libc-macros")
>From 0833de193ad21a1f83587dfcde61a458d6a018a4 Mon Sep 17 00:00:00 2001
From: Michael Flanders <flanders.michaelk at gmail.com>
Date: Mon, 22 Apr 2024 16:04:33 -0500
Subject: [PATCH 04/10] move docgen Header class to a separate module
---
libc/utils/docgen/__init__.py | 7 +++
libc/utils/docgen/docgen.py | 78 ++--------------------------------
libc/utils/docgen/header.py | 80 +++++++++++++++++++++++++++++++++++
3 files changed, 91 insertions(+), 74 deletions(-)
create mode 100644 libc/utils/docgen/__init__.py
create mode 100644 libc/utils/docgen/header.py
diff --git a/libc/utils/docgen/__init__.py b/libc/utils/docgen/__init__.py
new file mode 100644
index 0000000000000..1bba8b44c060c
--- /dev/null
+++ b/libc/utils/docgen/__init__.py
@@ -0,0 +1,7 @@
+# ====- __init__.py for docgen -------------------------------*- python -*---==#
+#
+# Part of the LLVM Project, 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
+#
+# ==-------------------------------------------------------------------------==#
diff --git a/libc/utils/docgen/docgen.py b/libc/utils/docgen/docgen.py
index cf6529e19d915..f7168044cc6e9 100755
--- a/libc/utils/docgen/docgen.py
+++ b/libc/utils/docgen/docgen.py
@@ -9,87 +9,17 @@
# ==-------------------------------------------------------------------------==#
from argparse import ArgumentParser, Namespace
from pathlib import Path
-from typing import Dict, Generator
+from typing import Dict
import sys
import json
+from header import Header
+
class DocgenAPIFormatError(Exception):
"""Raised on fatal formatting errors with a description of a formatting error"""
-
-class Header:
- """
- Maintains implementation information about a standard header file:
- * where does its implementation dir live
- * where is its macros file
- * where is its docgen json file
-
- By convention, the macro-only part of a header file is in a header-specific
- file somewhere in the directory tree with root at
- ``$LLVM_PROJECT_ROOT/libc/include/llvm-libc-macros``. Docgen expects that
- if a macro is implemented, that it appears in a string
- ``#define MACRO_NAME`` in some ``*-macros.h`` file in the directory tree.
- Docgen searches for this string in the file to set the implementation status
- shown in the generated rst docs rendered as html for display at
- <libc.llvm.org>.
-
- By convention, each function for a header is implemented in a function-specific
- cpp file somewhere in the directory tree with root at, e.g,
- ``$LLVM_PROJECT_ROOT/libc/src/fenv``. Some headers have architecture-specific
- implementations, like ``math``, and some don't, like ``fenv``. Docgen uses the
- presence of this function-specific cpp file to set the implementation status
- shown in the generated rst docs rendered as html for display at
- <libc.llvm.org>.
- """
-
- def __init__(self, header_name: str):
- """
- :param header_name: e.g., ``"threads.h"`` or ``"signal.h"``
- """
- self.name = header_name
- self.stem = header_name.rstrip(".h")
- self.docgen_root = Path(__file__).parent
- self.libc_root = self.docgen_root.parent.parent
- self.docgen_json = self.docgen_root / Path(header_name).with_suffix(".json")
- self.fns_dir = Path(self.libc_root, "src", self.stem)
- self.macros_dir = Path(self.libc_root, "include", "llvm-libc-macros")
-
- def macro_file_exists(self) -> bool:
- for _ in self.__get_macro_files():
- return True
-
- return False
-
- def fns_dir_exists(self) -> bool:
- return self.fns_dir.exists() and self.fns_dir.is_dir()
-
- def implements_fn(self, fn_name: str) -> bool:
- for _ in self.fns_dir.glob(f"**/{fn_name}.cpp"):
- return True
-
- return False
-
- def implements_macro(self, m_name: str) -> bool:
- """
- Some macro files are in, e.g.,
- ``$LLVM_PROJECT_ROOT/libc/include/llvm-libc-macros/fenv-macros.h``,
- but others are in subdirectories, e.g., ``signal.h`` has the macro
- definitions in
- ``$LLVM_PROJECT_ROOT/libc/include/llvm-libc-macros/linux/signal-macros.h``.
-
- :param m_name: name of macro, e.g., ``FE_ALL_EXCEPT``
- """
- for f in self.__get_macro_files():
- if f"#define {m_name}" in f.read_text():
- return True
-
- return False
-
- def __get_macro_files(self) -> Generator[Path, None, None]:
- return self.macros_dir.glob(f"**/{self.stem}-macros.h")
-
-
+
def check_api(header: Header, api: Dict):
"""
Checks that docgen json files are properly formatted. If there are any
diff --git a/libc/utils/docgen/header.py b/libc/utils/docgen/header.py
new file mode 100644
index 0000000000000..7d1e4ebe58214
--- /dev/null
+++ b/libc/utils/docgen/header.py
@@ -0,0 +1,80 @@
+# ====- Information about standard headers used by docgen ----*- python -*--==#
+#
+# Part of the LLVM Project, 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
+#
+# ==-------------------------------------------------------------------------==#
+from pathlib import Path
+from typing import Generator
+
+class Header:
+ """
+ Maintains implementation information about a standard header file:
+ * where does its implementation dir live
+ * where is its macros file
+ * where is its docgen json file
+
+ By convention, the macro-only part of a header file is in a header-specific
+ file somewhere in the directory tree with root at
+ ``$LLVM_PROJECT_ROOT/libc/include/llvm-libc-macros``. Docgen expects that
+ if a macro is implemented, that it appears in a string
+ ``#define MACRO_NAME`` in some ``*-macros.h`` file in the directory tree.
+ Docgen searches for this string in the file to set the implementation status
+ shown in the generated rst docs rendered as html for display at
+ <libc.llvm.org>.
+
+ By convention, each function for a header is implemented in a function-specific
+ cpp file somewhere in the directory tree with root at, e.g,
+ ``$LLVM_PROJECT_ROOT/libc/src/fenv``. Some headers have architecture-specific
+ implementations, like ``math``, and some don't, like ``fenv``. Docgen uses the
+ presence of this function-specific cpp file to set the implementation status
+ shown in the generated rst docs rendered as html for display at
+ <libc.llvm.org>.
+ """
+
+ def __init__(self, header_name: str):
+ """
+ :param header_name: e.g., ``"threads.h"`` or ``"signal.h"``
+ """
+ self.name = header_name
+ self.stem = header_name.rstrip(".h")
+ self.docgen_root = Path(__file__).parent
+ self.libc_root = self.docgen_root.parent.parent
+ self.docgen_json = self.docgen_root / Path(header_name).with_suffix(".json")
+ self.fns_dir = Path(self.libc_root, "src", self.stem)
+ self.macros_dir = Path(self.libc_root, "include", "llvm-libc-macros")
+
+ def macro_file_exists(self) -> bool:
+ for _ in self.__get_macro_files():
+ return True
+
+ return False
+
+ def fns_dir_exists(self) -> bool:
+ return self.fns_dir.exists() and self.fns_dir.is_dir()
+
+ def implements_fn(self, fn_name: str) -> bool:
+ for _ in self.fns_dir.glob(f"**/{fn_name}.cpp"):
+ return True
+
+ return False
+
+ def implements_macro(self, m_name: str) -> bool:
+ """
+ Some macro files are in, e.g.,
+ ``$LLVM_PROJECT_ROOT/libc/include/llvm-libc-macros/fenv-macros.h``,
+ but others are in subdirectories, e.g., ``signal.h`` has the macro
+ definitions in
+ ``$LLVM_PROJECT_ROOT/libc/include/llvm-libc-macros/linux/signal-macros.h``.
+
+ :param m_name: name of macro, e.g., ``FE_ALL_EXCEPT``
+ """
+ for f in self.__get_macro_files():
+ if f"#define {m_name}" in f.read_text():
+ return True
+
+ return False
+
+ def __get_macro_files(self) -> Generator[Path, None, None]:
+ return self.macros_dir.glob(f"**/{self.stem}-macros.h")
>From fdea97de404f14fd951df1789449910d9c51f79d Mon Sep 17 00:00:00 2001
From: Michael Flanders <flanders.michaelk at gmail.com>
Date: Mon, 22 Apr 2024 16:10:22 -0500
Subject: [PATCH 05/10] address review comments
---
libc/utils/docgen/docgen.py | 2 +-
libc/utils/docgen/header.py | 6 ++++++
2 files changed, 7 insertions(+), 1 deletion(-)
diff --git a/libc/utils/docgen/docgen.py b/libc/utils/docgen/docgen.py
index f7168044cc6e9..1b582c7b3a7c4 100755
--- a/libc/utils/docgen/docgen.py
+++ b/libc/utils/docgen/docgen.py
@@ -157,6 +157,7 @@ def print_macros_rst(header: Header, macros: Dict):
print(f' - {macros[name]["posix-definition"]}')
else:
print(" -")
+ print()
def print_impl_status_rst(header: Header, api: Dict):
@@ -170,7 +171,6 @@ def print_impl_status_rst(header: Header, api: Dict):
# the macro and function sections are both optional
if "macros" in api:
print_macros_rst(header, api["macros"])
- print()
if "functions" in api:
print_functions_rst(header, api["functions"])
diff --git a/libc/utils/docgen/header.py b/libc/utils/docgen/header.py
index 7d1e4ebe58214..3b03a14e5f184 100644
--- a/libc/utils/docgen/header.py
+++ b/libc/utils/docgen/header.py
@@ -77,4 +77,10 @@ def implements_macro(self, m_name: str) -> bool:
return False
def __get_macro_files(self) -> Generator[Path, None, None]:
+ """
+ This function uses a glob on, e.g., ``"**/fcntl.macros.h"`` because the
+ macro file might be located in a subdirectory:
+ libc/include/llvm-libc-macros/fcntl-macros.h
+ libc/include/llvm-libc-macros/linux/fcntl-macros.h
+ """
return self.macros_dir.glob(f"**/{self.stem}-macros.h")
>From a3fb6a2de3809a2c769ecc481a8e316b389f7653 Mon Sep 17 00:00:00 2001
From: Michael Flanders <flanders.michaelk at gmail.com>
Date: Mon, 22 Apr 2024 16:13:07 -0500
Subject: [PATCH 06/10] black formatting
---
libc/utils/docgen/docgen.py | 2 +-
libc/utils/docgen/header.py | 1 +
2 files changed, 2 insertions(+), 1 deletion(-)
diff --git a/libc/utils/docgen/docgen.py b/libc/utils/docgen/docgen.py
index 1b582c7b3a7c4..a7e4c5ba1c279 100755
--- a/libc/utils/docgen/docgen.py
+++ b/libc/utils/docgen/docgen.py
@@ -19,7 +19,7 @@
class DocgenAPIFormatError(Exception):
"""Raised on fatal formatting errors with a description of a formatting error"""
-
+
def check_api(header: Header, api: Dict):
"""
Checks that docgen json files are properly formatted. If there are any
diff --git a/libc/utils/docgen/header.py b/libc/utils/docgen/header.py
index 3b03a14e5f184..dde210078db27 100644
--- a/libc/utils/docgen/header.py
+++ b/libc/utils/docgen/header.py
@@ -8,6 +8,7 @@
from pathlib import Path
from typing import Generator
+
class Header:
"""
Maintains implementation information about a standard header file:
>From 9fb808a48064b88e3d2f80a8531141d6496d8eb6 Mon Sep 17 00:00:00 2001
From: Michael Flanders <flanders.michaelk at gmail.com>
Date: Mon, 22 Apr 2024 16:50:26 -0500
Subject: [PATCH 07/10] wip: long table names
---
libc/docs/ctype.rst | 4 ++--
libc/docs/fenv.rst | 8 ++++----
libc/docs/signal.rst | 8 ++++----
libc/docs/stdbit.rst | 8 ++++----
libc/docs/threads.rst | 8 ++++----
libc/utils/docgen/docgen.py | 4 ++--
6 files changed, 20 insertions(+), 20 deletions(-)
diff --git a/libc/docs/ctype.rst b/libc/docs/ctype.rst
index e87116f10bfbd..d55d63d75a7c8 100644
--- a/libc/docs/ctype.rst
+++ b/libc/docs/ctype.rst
@@ -14,8 +14,8 @@ Functions
* - Function
- Implemented
- - C Standard
- - POSIX Standard
+ - C23 Standard Section
+ - POSIX 2018 Standard Section
* - isalnum
- |check|
- 7.4.1.1
diff --git a/libc/docs/fenv.rst b/libc/docs/fenv.rst
index 22bef37d9c844..16fae27cb2c0a 100644
--- a/libc/docs/fenv.rst
+++ b/libc/docs/fenv.rst
@@ -14,8 +14,8 @@ Macros
* - Function
- Implemented
- - C Standard
- - POSIX Standard
+ - C23 Standard Section
+ - POSIX 2018 Standard Section
* - FE_ALL_EXCEPT
- |check|
- 7.6.12
@@ -103,8 +103,8 @@ Functions
* - Function
- Implemented
- - C Standard
- - POSIX Standard
+ - C23 Standard Section
+ - POSIX 2018 Standard Section
* - fe_dec_getround
-
- 7.6.5.3
diff --git a/libc/docs/signal.rst b/libc/docs/signal.rst
index 15d0aaaae3400..8e7a1a94a117d 100644
--- a/libc/docs/signal.rst
+++ b/libc/docs/signal.rst
@@ -14,8 +14,8 @@ Macros
* - Function
- Implemented
- - C Standard
- - POSIX Standard
+ - C23 Standard Section
+ - POSIX 2018 Standard Section
* - SIGABRT
- |check|
- 7.14.3
@@ -163,8 +163,8 @@ Functions
* - Function
- Implemented
- - C Standard
- - POSIX Standard
+ - C23 Standard Section
+ - POSIX 2018 Standard Section
* - kill
- |check|
-
diff --git a/libc/docs/stdbit.rst b/libc/docs/stdbit.rst
index 47c3a00e2ba6c..c565b3fc296ea 100644
--- a/libc/docs/stdbit.rst
+++ b/libc/docs/stdbit.rst
@@ -14,8 +14,8 @@ Macros
* - Function
- Implemented
- - C Standard
- - POSIX Standard
+ - C23 Standard Section
+ - POSIX 2018 Standard Section
* - __STDC_ENDIAN_BIG__
- |check|
- 7.18.2.2
@@ -99,8 +99,8 @@ Functions
* - Function
- Implemented
- - C Standard
- - POSIX Standard
+ - C23 Standard Section
+ - POSIX 2018 Standard Section
* - stdc_bit_ceil_uc
- |check|
- 7.18.16
diff --git a/libc/docs/threads.rst b/libc/docs/threads.rst
index 360b29a64abd8..2818afed11fa7 100644
--- a/libc/docs/threads.rst
+++ b/libc/docs/threads.rst
@@ -14,8 +14,8 @@ Macros
* - Function
- Implemented
- - C Standard
- - POSIX Standard
+ - C23 Standard Section
+ - POSIX 2018 Standard Section
* - ONCE_FLAG_INIT
-
- 7.28.1.3
@@ -35,8 +35,8 @@ Functions
* - Function
- Implemented
- - C Standard
- - POSIX Standard
+ - C23 Standard Section
+ - POSIX 2018 Standard Section
* - call_once
- |check|
- 7.28.2.1
diff --git a/libc/utils/docgen/docgen.py b/libc/utils/docgen/docgen.py
index a7e4c5ba1c279..a3beef27c3b35 100755
--- a/libc/utils/docgen/docgen.py
+++ b/libc/utils/docgen/docgen.py
@@ -102,8 +102,8 @@ def print_tbl_dir():
* - Function
- Implemented
- - C Standard
- - POSIX Standard"""
+ - C23 Standard Section
+ - POSIX 2018 Standard Section"""
)
>From c38a5a9395a63245bf42d1c89c9735cf09c56ac2 Mon Sep 17 00:00:00 2001
From: Michael Flanders <flanders.michaelk at gmail.com>
Date: Mon, 22 Apr 2024 18:40:30 -0500
Subject: [PATCH 08/10] remove empty __init__.py
---
libc/utils/docgen/__init__.py | 7 -------
1 file changed, 7 deletions(-)
delete mode 100644 libc/utils/docgen/__init__.py
diff --git a/libc/utils/docgen/__init__.py b/libc/utils/docgen/__init__.py
deleted file mode 100644
index 1bba8b44c060c..0000000000000
--- a/libc/utils/docgen/__init__.py
+++ /dev/null
@@ -1,7 +0,0 @@
-# ====- __init__.py for docgen -------------------------------*- python -*---==#
-#
-# Part of the LLVM Project, 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
-#
-# ==-------------------------------------------------------------------------==#
>From 255064b77697c581d7d59a9004afaadf84e2539d Mon Sep 17 00:00:00 2001
From: Michael Flanders <flanders.michaelk at gmail.com>
Date: Mon, 22 Apr 2024 18:42:31 -0500
Subject: [PATCH 09/10] Revert "wip: long table names"
This reverts commit 9fb808a48064b88e3d2f80a8531141d6496d8eb6.
Did not mean to commit this.
---
libc/docs/ctype.rst | 4 ++--
libc/docs/fenv.rst | 8 ++++----
libc/docs/signal.rst | 8 ++++----
libc/docs/stdbit.rst | 8 ++++----
libc/docs/threads.rst | 8 ++++----
libc/utils/docgen/docgen.py | 4 ++--
6 files changed, 20 insertions(+), 20 deletions(-)
diff --git a/libc/docs/ctype.rst b/libc/docs/ctype.rst
index d55d63d75a7c8..e87116f10bfbd 100644
--- a/libc/docs/ctype.rst
+++ b/libc/docs/ctype.rst
@@ -14,8 +14,8 @@ Functions
* - Function
- Implemented
- - C23 Standard Section
- - POSIX 2018 Standard Section
+ - C Standard
+ - POSIX Standard
* - isalnum
- |check|
- 7.4.1.1
diff --git a/libc/docs/fenv.rst b/libc/docs/fenv.rst
index 16fae27cb2c0a..22bef37d9c844 100644
--- a/libc/docs/fenv.rst
+++ b/libc/docs/fenv.rst
@@ -14,8 +14,8 @@ Macros
* - Function
- Implemented
- - C23 Standard Section
- - POSIX 2018 Standard Section
+ - C Standard
+ - POSIX Standard
* - FE_ALL_EXCEPT
- |check|
- 7.6.12
@@ -103,8 +103,8 @@ Functions
* - Function
- Implemented
- - C23 Standard Section
- - POSIX 2018 Standard Section
+ - C Standard
+ - POSIX Standard
* - fe_dec_getround
-
- 7.6.5.3
diff --git a/libc/docs/signal.rst b/libc/docs/signal.rst
index 8e7a1a94a117d..15d0aaaae3400 100644
--- a/libc/docs/signal.rst
+++ b/libc/docs/signal.rst
@@ -14,8 +14,8 @@ Macros
* - Function
- Implemented
- - C23 Standard Section
- - POSIX 2018 Standard Section
+ - C Standard
+ - POSIX Standard
* - SIGABRT
- |check|
- 7.14.3
@@ -163,8 +163,8 @@ Functions
* - Function
- Implemented
- - C23 Standard Section
- - POSIX 2018 Standard Section
+ - C Standard
+ - POSIX Standard
* - kill
- |check|
-
diff --git a/libc/docs/stdbit.rst b/libc/docs/stdbit.rst
index c565b3fc296ea..47c3a00e2ba6c 100644
--- a/libc/docs/stdbit.rst
+++ b/libc/docs/stdbit.rst
@@ -14,8 +14,8 @@ Macros
* - Function
- Implemented
- - C23 Standard Section
- - POSIX 2018 Standard Section
+ - C Standard
+ - POSIX Standard
* - __STDC_ENDIAN_BIG__
- |check|
- 7.18.2.2
@@ -99,8 +99,8 @@ Functions
* - Function
- Implemented
- - C23 Standard Section
- - POSIX 2018 Standard Section
+ - C Standard
+ - POSIX Standard
* - stdc_bit_ceil_uc
- |check|
- 7.18.16
diff --git a/libc/docs/threads.rst b/libc/docs/threads.rst
index 2818afed11fa7..360b29a64abd8 100644
--- a/libc/docs/threads.rst
+++ b/libc/docs/threads.rst
@@ -14,8 +14,8 @@ Macros
* - Function
- Implemented
- - C23 Standard Section
- - POSIX 2018 Standard Section
+ - C Standard
+ - POSIX Standard
* - ONCE_FLAG_INIT
-
- 7.28.1.3
@@ -35,8 +35,8 @@ Functions
* - Function
- Implemented
- - C23 Standard Section
- - POSIX 2018 Standard Section
+ - C Standard
+ - POSIX Standard
* - call_once
- |check|
- 7.28.2.1
diff --git a/libc/utils/docgen/docgen.py b/libc/utils/docgen/docgen.py
index a3beef27c3b35..a7e4c5ba1c279 100755
--- a/libc/utils/docgen/docgen.py
+++ b/libc/utils/docgen/docgen.py
@@ -102,8 +102,8 @@ def print_tbl_dir():
* - Function
- Implemented
- - C23 Standard Section
- - POSIX 2018 Standard Section"""
+ - C Standard
+ - POSIX Standard"""
)
>From ad1a5838b6519674aa1bf5e504946cd950878bc5 Mon Sep 17 00:00:00 2001
From: Michael Flanders <flanders.michaelk at gmail.com>
Date: Wed, 22 May 2024 17:08:50 -0500
Subject: [PATCH 10/10] revert last revert, but change to POSIX.1-2017
---
libc/docs/ctype.rst | 4 ++--
libc/docs/fenv.rst | 8 ++++----
libc/docs/signal.rst | 8 ++++----
libc/docs/stdbit.rst | 8 ++++----
libc/docs/threads.rst | 8 ++++----
libc/utils/docgen/docgen.py | 4 ++--
6 files changed, 20 insertions(+), 20 deletions(-)
diff --git a/libc/docs/ctype.rst b/libc/docs/ctype.rst
index e87116f10bfbd..828785c9b6708 100644
--- a/libc/docs/ctype.rst
+++ b/libc/docs/ctype.rst
@@ -14,8 +14,8 @@ Functions
* - Function
- Implemented
- - C Standard
- - POSIX Standard
+ - C23 Standard Section
+ - POSIX.1-2017 Standard Section
* - isalnum
- |check|
- 7.4.1.1
diff --git a/libc/docs/fenv.rst b/libc/docs/fenv.rst
index 22bef37d9c844..e7a5a3fb2c815 100644
--- a/libc/docs/fenv.rst
+++ b/libc/docs/fenv.rst
@@ -14,8 +14,8 @@ Macros
* - Function
- Implemented
- - C Standard
- - POSIX Standard
+ - C23 Standard Section
+ - POSIX.1-2017 Standard Section
* - FE_ALL_EXCEPT
- |check|
- 7.6.12
@@ -103,8 +103,8 @@ Functions
* - Function
- Implemented
- - C Standard
- - POSIX Standard
+ - C23 Standard Section
+ - POSIX.1-2017 Standard Section
* - fe_dec_getround
-
- 7.6.5.3
diff --git a/libc/docs/signal.rst b/libc/docs/signal.rst
index 15d0aaaae3400..d1a7cb6095602 100644
--- a/libc/docs/signal.rst
+++ b/libc/docs/signal.rst
@@ -14,8 +14,8 @@ Macros
* - Function
- Implemented
- - C Standard
- - POSIX Standard
+ - C23 Standard Section
+ - POSIX.1-2017 Standard Section
* - SIGABRT
- |check|
- 7.14.3
@@ -163,8 +163,8 @@ Functions
* - Function
- Implemented
- - C Standard
- - POSIX Standard
+ - C23 Standard Section
+ - POSIX.1-2017 Standard Section
* - kill
- |check|
-
diff --git a/libc/docs/stdbit.rst b/libc/docs/stdbit.rst
index 47c3a00e2ba6c..71f9bbfd1d000 100644
--- a/libc/docs/stdbit.rst
+++ b/libc/docs/stdbit.rst
@@ -14,8 +14,8 @@ Macros
* - Function
- Implemented
- - C Standard
- - POSIX Standard
+ - C23 Standard Section
+ - POSIX.1-2017 Standard Section
* - __STDC_ENDIAN_BIG__
- |check|
- 7.18.2.2
@@ -99,8 +99,8 @@ Functions
* - Function
- Implemented
- - C Standard
- - POSIX Standard
+ - C23 Standard Section
+ - POSIX.1-2017 Standard Section
* - stdc_bit_ceil_uc
- |check|
- 7.18.16
diff --git a/libc/docs/threads.rst b/libc/docs/threads.rst
index 360b29a64abd8..63cd6c40e1455 100644
--- a/libc/docs/threads.rst
+++ b/libc/docs/threads.rst
@@ -14,8 +14,8 @@ Macros
* - Function
- Implemented
- - C Standard
- - POSIX Standard
+ - C23 Standard Section
+ - POSIX.1-2017 Standard Section
* - ONCE_FLAG_INIT
-
- 7.28.1.3
@@ -35,8 +35,8 @@ Functions
* - Function
- Implemented
- - C Standard
- - POSIX Standard
+ - C23 Standard Section
+ - POSIX.1-2017 Standard Section
* - call_once
- |check|
- 7.28.2.1
diff --git a/libc/utils/docgen/docgen.py b/libc/utils/docgen/docgen.py
index a7e4c5ba1c279..25e22d4d58778 100755
--- a/libc/utils/docgen/docgen.py
+++ b/libc/utils/docgen/docgen.py
@@ -102,8 +102,8 @@ def print_tbl_dir():
* - Function
- Implemented
- - C Standard
- - POSIX Standard"""
+ - C23 Standard Section
+ - POSIX.1-2017 Standard Section"""
)
More information about the libc-commits
mailing list