-
Notifications
You must be signed in to change notification settings - Fork 12.6k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
[libc][docs][POSIX] flush out documentation for the POSIX defined headers #122006
Comments
Hi! This issue may be a good introductory issue for people new to working on LLVM. If you would like to work on this issue, your first steps are:
If you have any further questions about this issue, don't hesitate to ask via a comment in the thread below. |
@llvm/issue-subscribers-libc Author: Nick Desaulniers (nickdesaulniers)
If you go to https://pubs.opengroup.org/onlinepubs/9799919799/, then `14. Headers` in the bottom left, you get a list of headers mandated by POSIX. I'd like to document them from https://libc.llvm.org/headers/index.html. We do so by manually curating some metadata about functions and preprocessor defines in yaml files. The yaml files are currently in https://github.com/llvm/llvm-project/tree/main/libc/utils/docgen. https://github.com/llvm/llvm-project/blob/main/libc/utils/docgen/arpa/inet.yaml is an example of arpa/inet.h as per POSIX. POSIX also tries to be a superset of C (though FWICT POSIX1.2024 missed C23 additions...), so most headers we have entries for already (though we should triple check since POSIX can add functions to existing C standard headers).
Once we've added entries for the new POSIX headers, you should configure your build with the 2 additional cmake flags:
Then you can do Good pull requests should implement one header at a time, and not send a PR that implements documentation for more than one header at a time. If that means that this issue is a "meta" issue for which multiple PRs will link against, so be it. |
@llvm/issue-subscribers-good-first-issue Author: Nick Desaulniers (nickdesaulniers)
If you go to https://pubs.opengroup.org/onlinepubs/9799919799/, then `14. Headers` in the bottom left, you get a list of headers mandated by POSIX. I'd like to document them from https://libc.llvm.org/headers/index.html. We do so by manually curating some metadata about functions and preprocessor defines in yaml files. The yaml files are currently in https://github.com/llvm/llvm-project/tree/main/libc/utils/docgen. https://github.com/llvm/llvm-project/blob/main/libc/utils/docgen/arpa/inet.yaml is an example of arpa/inet.h as per POSIX. POSIX also tries to be a superset of C (though FWICT POSIX1.2024 missed C23 additions...), so most headers we have entries for already (though we should triple check since POSIX can add functions to existing C standard headers).
Once we've added entries for the new POSIX headers, you should configure your build with the 2 additional cmake flags:
Then you can do Good pull requests should implement one header at a time, and not send a PR that implements documentation for more than one header at a time. If that means that this issue is a "meta" issue for which multiple PRs will link against, so be it. |
Looks like a good issue to start with, could I work on this? |
From my understanding, what i want to do is:
Now, i got some questions,
|
Please correct me if i misunderstand something, somewhere. Thanks! |
Sure! I'll add you as an assignee. Feel free to work through as many as you'd like. Happy to add others to help out if folks are interested, since this is an embarrassingly parallel problem!
Yep, each header should have a corresponding
s/index.rs/index.rst/ but yes, good catch! I forgot to mention that in the bug description. Please keep that list alphabetically sorted, too.
The intent of that field is when a function/macro has a definition as per the ISO C spec, what section should folks look at to understand what that function's specified semantics are. If a function is POSIX only, and not in ISO C, then the c23 standard section is optional, and may be omitted. |
Hey @nickdesaulniers , i just made a pull request for including (aio.h) and do i have to create a separate PR for every header ? |
Hi @nickdesaulniers, I would also like to work on this issue and help contribute, It would be great If you could assign me also on this, @StarOne01 Would like to work together as there are many headers to be listed. Thanks! |
Hey @marcury122 , let's work on this in parallel, please tell me which header(s) you gonna work on |
yeah Sure! Before that I have a doubt, any of the two can please let me know @nickdesaulniers @StarOne01, If you could list me the reference, it would be helpful and we can start working on it. Thanks! |
Also do we have to list all the headers from the list of 86 headers on the webpage https://pubs.opengroup.org/onlinepubs/9799919799/ and then 14.headers, that are missing from the libc/utils/docgen folder or we have to list only those which are included on the webpage https://libc.llvm.org/headers/index.html |
I did see a few mentions in the POSIX's reference itself, also I found this, to be helpful or a quick search does the job.
Yes, we would need to list all the headers in the header section of the POSIX reference and check the existing functions and macros for changes. |
Okay thanks. I will take the headers devctl.h and dlfcn.h |
Done, thanks for volunteering!
Bookmark this page: https://www.open-std.org/jtc1/sc22/wg14/www/projects#9899 The latest C standard draft is what I would consider to be the most up to date specification of the C programming language. Note: the latest standard draft is updated somewhat frequently these days, which is why I recommend bookmarking the page I did; it is updated periodically with new drafts. Ah...7.4.1.1 is a mistake I made in ctype. It should be 7.4.2.1 (etc). Want to send a patch to fix that?
Ideally, yes please.
Go for it! Thanks again for volunteering. |
I happen to have a local patch for pthread, so I'll finish that off and get it posted. |
Got it! |
…X standards (#122411) This pull request introduces the following changes to the project with reference to ( #122006 ): 1. **Documentation Update**: - Added a new YAML file `in.yaml` to document network protocol and address macros. - The `in.yaml` file includes the following macros: - `IPPROTO_IP` - `IPPROTO_IPV6` - `IPPROTO_ICMP` - `IPPROTO_RAW` - `IPPROTO_TCP` - `IPPROTO_UDP` - `INADDR_ANY` - `INADDR_BROADCAST` - `INET_ADDRSTRLEN` - `IPV6_JOIN_GROUP` - `IPV6_LEAVE_GROUP` - `IPV6_MULTICAST_HOPS` - `IPV6_MULTICAST_IF` - `IPV6_MULTICAST_LOOP` - `IPV6_UNICAST_HOPS` - `IPV6_V6ONLY` - `IN6_IS_ADDR_UNSPECIFIED` - `IN6_IS_ADDR_LOOPBACK` - `IN6_IS_ADDR_MULTICAST` - `IN6_IS_ADDR_LINKLOCAL` - `IN6_IS_ADDR_SITELOCAL` - `IN6_IS_ADDR_V4MAPPED` - `IN6_IS_ADDR_V4COMPAT` - `IN6_IS_ADDR_MC_NODELOCAL` - `IN6_IS_ADDR_MC_LINKLOCAL` - `IN6_IS_ADDR_MC_SITELOCAL` - `IN6_IS_ADDR_MC_ORGLOCAL` - `IN6_IS_ADDR_MC_GLOBAL` _I believe, all these macros are necessary and should be documented._ 2. **CMake Configuration Update**: - Updated the `CMakeLists.txt` file to create the necessary directory for the `netinet` headers. - Included the `netinet/in` documentation in the Sphinx build configuration. 3. **Index Update**: - Updated the `index.rst` file to include a reference to the newly added `netinet/in` documentation. **Purpose**: - This pull request adds documentation for network protocol and address macros in the `netinet/in` header. - Updates the CMake configuration to support the new documentation. **Testing**: - Verified that the new YAML file is correctly referenced in the `index.rst`. - Ensured that the documentation builds without errors and includes the new network interface documentation. This pull request ensures that the `netinet/in` header macros are documented and included in the project's documentation, and updates the CMake configuration to support these changes.
…ds (#122406) This pull request introduces the following changes to the project with reference to issue ( #122006 ): 1. **Documentation Update**: - Added a new YAML file `if.yaml` under `net` to document network interface functions and macros. - The `if.yaml` file includes the following functions and macros: - Functions: - `if_freenameindex` - `if_indextoname` - `if_nameindex` - `if_nametoindex` - Macros: - `IF_NAMESIZE` 2. **CMake Configuration Update**: - Updated the `CMakeLists.txt` file to create the necessary directory for the `net` headers. - Included the `net/if` documentation in the Sphinx build configuration. 3. **Index Update**: - Updated the `index.rst` file to include a reference to the newly added `net/if` documentation. **Purpose**: - This pull request adds documentation for network interface functions and macros, ensuring they are included in the project's documentation. - Updates the CMake configuration to support the new documentation. **Testing**: - Verified that the new YAML file is correctly referenced in the `index.rst`. - Ensured that the documentation builds without errors and includes the new network interface documentation. Co-authored-by: Nick Desaulniers <ndesaulniers@google.com>
…ions docs (#123004) These changes ensure that the termios header is documented properly with respect to the issue ( llvm/llvm-project#122006 ) .
Having a target named pthreads is breaking when multiple runtimes are enabled. Disable this target for now so that the builds go back to green (and sites get updated). Link: llvm/llvm-zorg#359 (comment) Link: llvm#122006 Link: llvm#122497 Link: llvm#123821
Having a target named pthreads is breaking when multiple runtimes are enabled. Disable this target for now so that the builds go back to green (and sites get updated). Link: llvm/llvm-zorg#359 (comment) Link: #122006 Link: #122497 Link: #123821
…lementations doc (#123068) These changes ensure that the unistd header is documented properly with respect to the issue ( llvm/llvm-project#122006 ) .
[libc][docs] add cpio to documentation and include related functi… These changes ensure that the cpio header is documented properly with respect to the issue (#122006 ). **Changes:** 1. **cpio.yaml**: Created a new YAML file for cpio with functions and related macros. 2. **CMakeLists.txt**: Added cpio to the documentation directories. 3. **index.rst**: Included `cpio` in the documentation index. --------- Co-authored-by: siya <siya@Siya.com>
[libc][docs] add cpio to documentation and include related functi… These changes ensure that the cpio header is documented properly with respect to the issue (llvm/llvm-project#122006 ). **Changes:** 1. **cpio.yaml**: Created a new YAML file for cpio with functions and related macros. 2. **CMakeLists.txt**: Added cpio to the documentation directories. 3. **index.rst**: Included `cpio` in the documentation index. --------- Co-authored-by: siya <siya@Siya.com>
… (#123798) [libc][docs] add cpio to documentation and include related functi… These changes ensure that the cpio header is documented properly with respect to the issue (llvm/llvm-project#122006 ). **Changes:** 1. **cpio.yaml**: Created a new YAML file for cpio with functions and related macros. 2. **CMakeLists.txt**: Added cpio to the documentation directories. 3. **index.rst**: Included `cpio` in the documentation index. --------- Co-authored-by: siya <siya@Siya.com> GitOrigin-RevId: f116ea0580ab60a8d876a8e69d39e73ea3210218 Original-Revision: 4ca5d779a5a794c3a7e08e282f2822d35fd70666 Roller-URL: https://cr-buildbucket.appspot.com/build/8724818472990707457 CQ-Do-Not-Cancel-Tryjobs: true Change-Id: I83e3d5b2390c1c6e394755dd14121c51300a165d Reviewed-on: https://fuchsia-review.googlesource.com/c/fuchsia/+/1192690
[libc][docs] add cpio to documentation and include related functi… These changes ensure that the cpio header is documented properly with respect to the issue (llvm/llvm-project#122006 ). **Changes:** 1. **cpio.yaml**: Created a new YAML file for cpio with functions and related macros. 2. **CMakeLists.txt**: Added cpio to the documentation directories. 3. **index.rst**: Included `cpio` in the documentation index. --------- Co-authored-by: siya <siya@Siya.com> GitOrigin-RevId: f116ea0580ab60a8d876a8e69d39e73ea3210218 Original-Revision: 4ca5d779a5a794c3a7e08e282f2822d35fd70666 Change-Id: I140acb3c170cffbe111b450291f66699b9c64629
…] Add cpio.h header. (#123798) [libc][docs] add cpio to documentation and include related functi… These changes ensure that the cpio header is documented properly with respect to the issue (llvm/llvm-project#122006 ). **Changes:** 1. **cpio.yaml**: Created a new YAML file for cpio with functions and related macros. 2. **CMakeLists.txt**: Added cpio to the documentation directories. 3. **index.rst**: Included `cpio` in the documentation index. --------- Co-authored-by: siya <siya@Siya.com> GitOrigin-RevId: 2636ca898412185939d24f825da3d94d9a13457a Original-Revision: 4ca5d779a5a794c3a7e08e282f2822d35fd70666 Original-Reviewed-on: https://fuchsia-review.googlesource.com/c/fuchsia/+/1192690 Original-Revision: 997a3198a33fae6dd8d95b1015b13ba931b687cb Change-Id: I34d3667c9b54e5587b3bf6beb2653d564c47fe51
…initions (#126413) These changes ensure that the sys/statvfs header is documented properly with respect to the issue ( llvm/llvm-project#122006 ) .
…tation and YAML definitions (#126413) These changes ensure that the sys/statvfs header is documented properly with respect to the issue ( llvm/llvm-project#122006 ) . GitOrigin-RevId: 83ead16376d0bb037abb4ce42597a48bc9d84c73 Original-Revision: 83d663f0989231081d7bc5ed47c0c548d1d9fb8c Change-Id: Ib3d3f696ba3faa83af6b639e722a4200ac800fe3
…] Add sys/statvfs to documentation and YAML definitions (#126413) These changes ensure that the sys/statvfs header is documented properly with respect to the issue ( llvm/llvm-project#122006 ) . GitOrigin-RevId: 275b054614a89bf6a651168b5465a1c086ab7cb5 Original-Revision: 83d663f0989231081d7bc5ed47c0c548d1d9fb8c Original-Reviewed-on: https://fuchsia-review.googlesource.com/c/fuchsia/+/1203484 Original-Revision: f03ff8d8014dd37fce378ecad67808fad744cd28 Change-Id: Ie8d1cac6bddfd0efe8e80519eccbce1bd6ab1036
… documentation and YAML definitions (#126413) These changes ensure that the sys/statvfs header is documented properly with respect to the issue ( llvm/llvm-project#122006 ) . GitOrigin-RevId: 83ead16376d0bb037abb4ce42597a48bc9d84c73 Original-Revision: 83d663f0989231081d7bc5ed47c0c548d1d9fb8c Roller-URL: https://cr-buildbucket.appspot.com/build/8723293557253046913 CQ-Do-Not-Cancel-Tryjobs: true Change-Id: I6c55b8adbb1d1f6d3b797da06494f90293a1e064 Reviewed-on: https://fuchsia-review.googlesource.com/c/fuchsia/+/1203484
With reference to this issue, how do we figure out the removed ones ? |
They appear in older versions of the POSIX docs, but I think it's out of scope for this issue to track down such removed APIs. |
I could help with that, if that's necessary. |
…lvm#126413) These changes ensure that the sys/statvfs header is documented properly with respect to the issue ( llvm#122006 ) .
If you go to https://pubs.opengroup.org/onlinepubs/9799919799/, then
14. Headers
in the bottom left, you get a list of headers mandated by POSIX. I'd like to document them from https://libc.llvm.org/headers/index.html. We do so by manually curating some metadata about functions and preprocessor defines in yaml files. The yaml files are currently in https://github.com/llvm/llvm-project/tree/main/libc/utils/docgen. https://github.com/llvm/llvm-project/blob/main/libc/utils/docgen/arpa/inet.yaml is an example of arpa/inet.h as per POSIX. POSIX also tries to be a superset of C (though FWICT POSIX1.2024 missed C23 additions...), so most headers we have entries for already (though we should triple check since POSIX can add functions to existing C standard headers).Once we've added entries for the new POSIX headers, you should configure your build with the 2 additional cmake flags:
-DLLVM_ENABLE_SPHINX=ON
-DLIBC_INCLUDE_DOCS=ON
Then you can do
ninja docs-libc-html
to build html you can view locally in{build_dir}/libc/docs/html/headers/**.html
.Good pull requests should implement one header at a time, and not send a PR that implements documentation for more than one header at a time. If that means that this issue is a "meta" issue for which multiple PRs will link against, so be it.
The text was updated successfully, but these errors were encountered: