This HOWTO file contains notes for maintainers and contributors to Newlib. For information on using Newlib (building, installing), see README. (In particular, the "Regenerating Configuration Files" section in README is of interest to both users and contributors.) (This file could probably use some other "sections" in addition to the initially-provided sections. Please help by adding as appropriate.) DOCUMENTATION ============= All the documentation for Newlib comes as part of the machine-readable distribution. Functions are documented in the source files, although not every file contains documentation, as many functions share manual page information. For example, lround(), lroundf(), llround(), and llroundf() share a single man page, which is in the source for lround(). The documentation is written partially in a custom format and partially in Texinfo format. The custom part comprises makedoc.c and doc.str, both of which are in the doc directory. doc.str is a macro file that can be used to define things to be done by makedoc, using building blocks that are built into makedoc.c. The basic function of makedoc is two-fold. First, it recognizes comments in the proper format to pull out of source files. Second, it adds some Texinfo commands as well as translating certain sequences into the appropriate Texinfo commands. Refer to makedoc.c and doc.str for what these are. (makedoc.c is not particularly-well commented.) Another way to see how they work is to simply examine the source files with documentation comments. (A couple of examples that use some of the fancier options: libm/common/s_isnan.c ("o+" variable-"bullet" list), libc/stdio/sprintf.c ("O+" bullet list; "." for example code).) In addition to the makedoc.c stuff, Texinfo commands can be directly used. Texinfo is a documentation system that uses a single source file to produce both on-line information and a printed manual. You can use one of the Info formatting commands to create the on-line version of the documentation and TeX (or `texi2roff') to typeset the printed version. While Newlib contains a copy of the texinfo package (texinfo.tex), the manual for it is not included. The latest one may be found at http://www.gnu.org/software/texinfo/manual/texinfo/texinfo.html (which could be for a newer version of texinfo.tex than is included in Newlib). In addition to Texinfo commands, straight TeX commands can also be used, but these, however, should be carefully limited and be given alternates for when a non-printed manual is produced--such as when info pages are produced. For an example of this kind of usage, see libm/common/s_logb.c. Please note that most files with documentation contain both an ANSI_SYNOPSIS and a TRAD_SYNOPSIS section. The TRAD_SYNOPSIS section gets deleted (since at least 2000) by makedoc, so when working on files these can safely be deleted and if you're making a new file, there is no need to add the TRAD_SYNOPSIS section. If writing a new function that requires documentation, the required sections are FUNCTION, INDEX, ANSI_SYNOPSIS (or SYNOPSIS), DESCRIPTION, RETURNS, and PORTABILITY. BUGS and SEEALSO should be added as appropriate. Source files which contain documentation are processed into ".def" files with the extracted information. These .def files are noted in the makefiles as CHEWOUT_FILES. These .def files need to be included into an appropriate .tex file for inclusion in the manuals (one each for libc and libm). Pay special attention under libc, as the manual is arranged by header file name, but not all header files are represented by directories (e.g. wcsftime.c is found under libc/time, but goes under wchar.h in the manual.) In summary, to add new documentation: 1. Add properly-formatted comments to source file (e.g. src.c); 2. add "chewout" file to CHEWOUT_FILES list in Makefile.am (e.g. src.def), re-generate Makefile.in; 3. add file to something.tex; 4. make ChangeLog entry and generate patch. EL/IX (ELIX_LEVEL_n, ELIX_n_SOURCES) ==================================== Some of the Makefiles contain definitions of ELIX_LEVEL_1 ... ELIX_LEVEL_4, and corresponding definitions for ELIX_1_SOURCES ... ELIX_4_SOURCES. These are referring to the EL/IX standards created by Red Hat for the purpose of Linux-based open standards for embedded development. In brief, the intent is to define multiple levels for API functions that allows the user to size the library appropriately for their application--at least in terms of the predefined lists. For full details, refer to the EL/IX home page at http://sourceware.org/elix/. The likely best way to tell how to classify any new functions in terms of needing an ELIX level qualification is to ask Jeff Johnston. To see how it works and try classification on your own, refer to the API specification on the web site, http://sourceware.org/elix/api/current/api.pdf. (Unfortunately, it is not complete with respect to either the C99 or POSIX standards, so particular C and POSIX functions may or may not be found.) The following definitions of the levels are from the (draft) standard. Level 1 RTOS compatible layer. Functions available in both Linux and a typical deeply embedded operating system (eCos, RTEMS, VxWorks, pSOS, VRTX32, etc.). Some functions may have reduced or modified semantics. Level 2 Linux single process only. Includes level 1 plus any functions from Linux that are not easily implemented on an RTOS. Also full implementations of reduced functions in Level 1. Level 3 Linux multiprocess for embedded applications. This is basically POSIX.1 with some of the functions that are obviously not for embedded applications (such as job control) removed. Level 4 Full POSIX or Linux compliance. Essentially these are functions that are present in a standard Linux kernel but are irrelevant to an embedded system. These functions do not form part of the EL/IX API.