gsoc_2015.html - pub/scm/docs/man-pages/website - Git at Google

 <html>
 <head>
 <link rel=stylesheet type="text/css" href="style.css" title="style">
 <title>
 man-pages proposal for Google Summer of Code 2015
 GSoC 2015 proposal: a feature test macro parser for glibc source code
 </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>: &nbsp;
 <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> &nbsp; || &nbsp;
 <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>GSoC 2015 proposal: a feature test macro parser for glibc source code</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 approximately 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">&lt;features.h&gt;</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">&lt;features.h&gt;</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">&lt;features.h&gt;</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>

 <h2>Mechanics</h2>

 <p>
     <strong>Mentor</strong>:
     <a href="http://man7.org/mtk/index.html">Michael Kerrisk</a>
     (<em>man-pages</em> project maintainer),
     <span class="email">mtk.manpages@gmail.com</span>
 </p>

 <p>
    <strong>Technologies</strong>: (probably) Python, C preprocessor
 </p>

 <p>
    <strong>Expected results</strong>: a parser
 </p>

 <p>
    <strong>Knowledge prerequisites</strong>: good knowledge of
    the chosen scripting language (probably Python);
    basic understanding of the operation of the C preprocessor
 </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>
	<html>
	<head>
	<link rel=stylesheet type="text/css" href="style.css" title="style">
	<title>
	man-pages proposal for Google Summer of Code 2015
	GSoC 2015 proposal: a feature test macro parser for glibc source code
	</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>GSoC 2015 proposal: a feature test macro parser for glibc source code</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 approximately 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>

	<h2>Mechanics</h2>

	<p>
	<strong>Mentor</strong>:
	<a href="http://man7.org/mtk/index.html">Michael Kerrisk</a>
	(<em>man-pages</em> project maintainer),
	<span class="email">mtk.manpages@gmail.com</span>
	</p>

	<p>
	<strong>Technologies</strong>: (probably) Python, C preprocessor
	</p>

	<p>
	<strong>Expected results</strong>: a parser
	</p>

	<p>
	<strong>Knowledge prerequisites</strong>: good knowledge of
	the chosen scripting language (probably Python);
	basic understanding of the operation of the C preprocessor
	</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>