diff options
| author | Michael Kerrisk <mtk.manpages@gmail.com> | 2015-02-19 08:34:33 +0100 |
|---|---|---|
| committer | Michael Kerrisk <mtk.manpages@gmail.com> | 2015-02-19 08:34:33 +0100 |
| commit | 503734876f32cd1caa466a00ab99d84fca9aaf77 (patch) | |
| tree | 261acb8d24663a3474a3de572a645632efa61084 | |
| parent | 2549ca3631af86fac9249945104ff6cd94240daf (diff) | |
GSoC 2015 proposalv2015-02-19
| -rw-r--r-- | gsoc_2015.html | 222 |
1 files changed, 222 insertions, 0 deletions
diff --git a/gsoc_2015.html b/gsoc_2015.html new file mode 100644 index 0000000..73a5fba --- /dev/null +++ b/gsoc_2015.html @@ -0,0 +1,222 @@ +<html> +<head> +<link rel=stylesheet type="text/css" href="style.css" title="style"> +<title> +man-pages proposal for Google Summer of Code 2015 +</title> +</head> + +<body> + +<!--BEGIN-LINKS--> +<form method="get" action="http://www.google.com/search"> +<table border=0 cellpadding=0 cellspacing=0 width="100%"> +<tr> +<td align="left"> +<font size="-1"> + +Linux <em>man-pages</em>: +<a href="./index.html">home</a> | +<a href="./contributing.html">contributing</a> | +<a href="./reporting_bugs.html">bugs</a> | +<a href="./patches.html">patches</a> | +<a href="./download.html">download</a> || +<a href="http://man7.org/linux/man-pages/index.html">online pages</a></font> +</td> +<td align="right"> +<input type="text" name="q" size=10 maxlength=255 value=""> +<input type="hidden" name="sitesearch" value="man7.org/linux/man-pages"> +<input type="submit" name="sa" value="Search online pages"> +</td> +</tr> +</table> +</form> +<!--END-LINKS--> + + +<h1><em>man-pages</em> proposal for Google Summer of Code 2015</h1> + +<h2>The man-pages project</h2> +<p> + The Linux + <em>man-pages</em> project + documents the + <a href="http://en.wikipedia.org/wiki/Linux">Linux</a> + <a href="http://www.kernel.org/pub/linux/kernel">kernel</a> + and C library interfaces that are employed by user-space programs. + With respect to the C library, the primary focus is the + <a href="http://www.gnu.org">GNU</a> C library + (<a href="http://www.gnu.org/software/libc/">glibc</a>), + although, where known, + documentation of variations in other C libraries + available for Linux is also included. + Established in 1993, the project by now contains nearly + 1000 man pages that provide documentation of Linux system calls + (and other Linux kernel-user-space APIs, such as the + <span class="pathname">/proc</span> + filesystem), C library APIs, and various related topics. + The project is + <a href="maintaining.html">maintained</a> + by + <a href="http://man7.org/mtk/index.html">Michael Kerrisk</a> + and typically 10 to 20 volunteers make contributions to the + <a href="http://man7.org/linux/man-pages/changelog.html">releases</a> + that occur approxmately monthly. +</p> + +<h2>Problem background</h2> + +<p> + The GNU C library employs a range of + <a href="http://man7.org/linux/man-pages/man7/feature_test_macros.7.html">feature test macros</a> + (FTMs) + that are used by applications at compile time to control + the definitions and declarations exposed by the library header files. + Examples of FTMs include + <span class="const">_GNU_SOURCE</span>, + <span class="const">_POSIX_C_SOURCE</span>, + and + <span class="const">_XOPEN_SOURCE</span>. +</p> +<p> + Starting several years ago, the + <em>man-pages</em> project + began documenting the FTMs that must be defined in order + to obtain the declaration of each system call and library function + exposed via glibc headers. + That documentation includes changes in FTM requirements across + glibc versions and is by now reasonably complete, + albeit not completely up to date + (and hence the rationale for this proposal). + Some (more complex) + examples of the FTM documentation can be seen in the SYNOPSIS + at the top of various man pages such as + <a href="http://man7.org/linux/man-pages/man2/stat.2.html">stat(2)</a>, + <a href="http://man7.org/linux/man-pages/man2/fsync.2.html">fsync(2)</a>, + <a href="http://man7.org/linux/man-pages/man2/fsync.2.html">unshare(2)</a>, + <a href="http://man7.org/linux/man-pages/man3/getgrnam.3.html">getgrnam(3)</a>, + and + <a href="http://man7.org/linux/man-pages/man3/isfdtype.3.html">isfdtype(3)</a>. + +</p> + +<p> + The work to add this documentation to the man pages has been done + largely by hand, by visually inspecting the various header files + and checking against the FTM logic implemented in the + <span class="pathname"><a href="http://man7.org/linux/man-pages/man3/getgrnam.3.html"><features.h></a></span> + header file. + However, this approach is time-consuming and somewhat error-prone. + It is also + subject to bit rot as the glibc FTM requirements evolve + across releases. + In particular, starting with version 2.19 deprecated + two long-standing but no longer useful FTMs, + <span class="const">_BSD_SOURCE</span> + and + <span class="const">_SVID_SOURCE</span>, + and replaced them with a single + FTM, + <span class="const">_DEFAULT_SOURCE</span>. + The + <em>man-pages</em> project + has largely caught up with this change, which requires updates + to around 150 pages. +</p> +<p> + An automated solution that provided up-to-date information on the + FTM requirements of the functions exposed by glibc, + generated by a tool that parsed the header files, + would be very helpful. +</p> + +<h2>The problem to solve</h2> + +<p> + The goal of this project is to construct a parser for glibc + header files that can be used to answer the question: + "Which feature test macro definitions cause the definition of function + <span class="func">foo()</span> to be exposed by the glibc header files?". + (Note that, as shown in many of the pages linked to above, + it is often the case that any of multiple different FTMs can be defined + in order to obtain the declaration of a function from the header files, + and the parser should produce the set + of all of the possible combinations.) + The parser would take account of the C preprocessor conditionals + (<span class="code">#if</span>, + <span class="code">#ifdef</span>) + in the C header files that employ FTM-related macros + in order to generate the desired information. +</p> +<p> + The parser should work across multiple versions + of glibc and will thus probably need to encode + (perhaps via a table-driven approach) + some of the version-specific logic contained in + <span class="pathname"><a href="http://man7.org/linux/man-pages/man3/getgrnam.3.html"><features.h></a></span>, + which has steadily evolved with various versions of glibc. +</p> +<p> + Input for the parser would include: +</p> + <ul> + <li> + the glibc header files; + </li> + <li> + (probably) the glibc version number (since the range of FTMs + and the FTM logic encoded in + <span class="pathname"><a href="http://man7.org/linux/man-pages/man3/getgrnam.3.html"><features.h></a></span> + have changed across glibc versions); and + </li> + <li> + a list of names of functions for which FTM requirements are + to be generated. + </li> + </ul> +<p> + The parser should output information in a format + that can be easily incorporated into the man pages + (but the step of actually updating the man pages is <em>not</em> + something that is intended to be automated). +</p> + +<p> + Inasmuch as a scripting language will probably be useful + to write the parser, Python is the preferred choice. + That choice is based on the fact that the tool will need to be maintained + and modified as glibc evolves and some existing scripting + tools used by the + <em>man-pages</em> project + also employ Python. + Nevertheless, the choice of another scripting language + might be entertained if there is a good technical justification. +</p> + +<p> + +</p> + +<!--BEGIN-STATCOUNTER--> +<!-- SITETRACKING.linux_man-pages --> +<!-- Start of StatCounter Code --> +<script type="text/javascript"> +var sc_project=5618989; +var sc_invisible=1; +var sc_partition=60; +var sc_click_stat=1; +var sc_security="4f8507d7"; +</script> + +<script type="text/javascript" +src="http://www.statcounter.com/counter/counter.js"></script><noscript><div +class="statcounter"><a title="customisable counter" +href="http://www.statcounter.com/free_hit_counter.html" +target="_blank"><img class="statcounter" +src="http://c.statcounter.com/5618989/0/4f8507d7/1/" alt="customisable +counter" ></a></div></noscript> +<!-- End of StatCounter Code --> +<!--END-STATCOUNTER--> +</body> +</html> + |