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. |
---|