[444] | 1 | This HOWTO file contains notes for maintainers and contributors to Newlib. |
---|
| 2 | For information on using Newlib (building, installing), see README. (In |
---|
| 3 | particular, the "Regenerating Configuration Files" section in README is of |
---|
| 4 | interest to both users and contributors.) |
---|
| 5 | |
---|
| 6 | (This file could probably use some other "sections" in addition to the |
---|
| 7 | initially-provided sections. Please help by adding as appropriate.) |
---|
| 8 | |
---|
| 9 | DOCUMENTATION |
---|
| 10 | ============= |
---|
| 11 | |
---|
| 12 | All the documentation for Newlib comes as part of the machine-readable |
---|
| 13 | distribution. Functions are documented in the source files, although not |
---|
| 14 | every file contains documentation, as many functions share manual page |
---|
| 15 | information. For example, lround(), lroundf(), llround(), and llroundf() |
---|
| 16 | share a single man page, which is in the source for lround(). The documentation |
---|
| 17 | is written partially in a custom format and partially in Texinfo format. |
---|
| 18 | |
---|
| 19 | The custom part comprises makedoc.c and doc.str, both of which are in the |
---|
| 20 | doc directory. doc.str is a macro file that can be used to define things to |
---|
| 21 | be done by makedoc, using building blocks that are built into makedoc.c. |
---|
| 22 | The basic function of makedoc is two-fold. First, it recognizes comments in |
---|
| 23 | the proper format to pull out of source files. Second, it adds some Texinfo |
---|
| 24 | commands as well as translating certain sequences into the appropriate |
---|
| 25 | Texinfo commands. Refer to makedoc.c and doc.str for what these are. |
---|
| 26 | (makedoc.c is not particularly-well commented.) Another way to see how they |
---|
| 27 | work is to simply examine the source files with documentation comments. |
---|
| 28 | |
---|
| 29 | (A couple of examples that use some of the fancier options: |
---|
| 30 | libm/common/s_isnan.c ("o+" variable-"bullet" list), |
---|
| 31 | libc/stdio/sprintf.c ("O+" bullet list; "." for example code).) |
---|
| 32 | |
---|
| 33 | In addition to the makedoc.c stuff, Texinfo commands can be directly |
---|
| 34 | used. Texinfo is a documentation system that uses a single source file to |
---|
| 35 | produce both on-line information and a printed manual. You can use one of the |
---|
| 36 | Info formatting commands to create the on-line version of the documentation |
---|
| 37 | and TeX (or `texi2roff') to typeset the printed version. While Newlib contains |
---|
| 38 | a copy of the texinfo package (texinfo.tex), the manual for it is not |
---|
| 39 | included. The latest one may be found at |
---|
| 40 | |
---|
| 41 | http://www.gnu.org/software/texinfo/manual/texinfo/texinfo.html |
---|
| 42 | |
---|
| 43 | (which could be for a newer version of texinfo.tex than is included in Newlib). |
---|
| 44 | |
---|
| 45 | In addition to Texinfo commands, straight TeX commands can also be used, |
---|
| 46 | but these, however, should be carefully limited and be given alternates for |
---|
| 47 | when a non-printed manual is produced--such as when info pages are produced. |
---|
| 48 | For an example of this kind of usage, see libm/common/s_logb.c. |
---|
| 49 | |
---|
| 50 | If writing a new function that requires documentation, the required |
---|
| 51 | sections are FUNCTION, INDEX, SYNOPSIS, DESCRIPTION, RETURNS, |
---|
| 52 | and PORTABILITY. BUGS and SEEALSO should be added as appropriate. |
---|
| 53 | |
---|
| 54 | Source files which contain documentation are processed into ".def" |
---|
| 55 | files with the extracted information. These .def files are noted in the |
---|
| 56 | makefiles as CHEWOUT_FILES. These .def files need to be included into an |
---|
| 57 | appropriate .tex file for inclusion in the manuals (one each for libc and libm). |
---|
| 58 | Pay special attention under libc, as the manual is arranged by header file name, |
---|
| 59 | but not all header files are represented by directories (e.g. wcsftime.c is |
---|
| 60 | found under libc/time, but goes under wchar.h in the manual.) |
---|
| 61 | |
---|
| 62 | In summary, to add new documentation: |
---|
| 63 | |
---|
| 64 | 1. Add properly-formatted comments to source file (e.g. src.c); |
---|
| 65 | 2. add "chewout" file to CHEWOUT_FILES list in Makefile.am (e.g. src.def), |
---|
| 66 | re-generate Makefile.in; |
---|
| 67 | 3. add file to something.tex; |
---|
| 68 | 4. make ChangeLog entry and generate patch. |
---|
| 69 | |
---|
| 70 | EL/IX (ELIX_LEVEL_n, ELIX_n_SOURCES) |
---|
| 71 | ==================================== |
---|
| 72 | |
---|
| 73 | Some of the Makefiles contain definitions of ELIX_LEVEL_1 ... ELIX_LEVEL_4, |
---|
| 74 | and corresponding definitions for ELIX_1_SOURCES ... ELIX_4_SOURCES. |
---|
| 75 | These are referring to the EL/IX standards created by Red Hat for the |
---|
| 76 | purpose of Linux-based open standards for embedded development. In brief, |
---|
| 77 | the intent is to define multiple levels for API functions that allows the |
---|
| 78 | user to size the library appropriately for their application--at least in |
---|
| 79 | terms of the predefined lists. For full details, refer to the EL/IX home |
---|
| 80 | page at http://sourceware.org/elix/. The likely best way to tell how to |
---|
| 81 | classify any new functions in terms of needing an ELIX level qualification |
---|
| 82 | is to ask Jeff Johnston. To see how it works and try classification on your |
---|
| 83 | own, refer to the API specification on the web site, |
---|
| 84 | |
---|
| 85 | http://sourceware.org/elix/api/current/api.pdf. |
---|
| 86 | |
---|
| 87 | (Unfortunately, it is not complete with respect to either the C99 or POSIX |
---|
| 88 | standards, so particular C and POSIX functions may or may not be found.) |
---|
| 89 | |
---|
| 90 | The following definitions of the levels are from the (draft) standard. |
---|
| 91 | |
---|
| 92 | Level 1 |
---|
| 93 | RTOS compatible layer. Functions available in both Linux and a |
---|
| 94 | typical deeply embedded operating system (eCos, RTEMS, VxWorks, pSOS, VRTX32, |
---|
| 95 | etc.). Some functions may have reduced or modified semantics. |
---|
| 96 | |
---|
| 97 | Level 2 |
---|
| 98 | Linux single process only. Includes level 1 plus any functions from Linux |
---|
| 99 | that are not easily implemented on an RTOS. Also full implementations of |
---|
| 100 | reduced functions in Level 1. |
---|
| 101 | |
---|
| 102 | Level 3 |
---|
| 103 | Linux multiprocess for embedded applications. This is basically POSIX.1 |
---|
| 104 | with some of the functions that are obviously not for embedded applications |
---|
| 105 | (such as job control) removed. |
---|
| 106 | |
---|
| 107 | Level 4 |
---|
| 108 | Full POSIX or Linux compliance. Essentially these are functions that are |
---|
| 109 | present in a standard Linux kernel but are irrelevant to an embedded system. |
---|
| 110 | These functions do not form part of the EL/IX API. |
---|