newlib/HOWTO

   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      Please note that most files with documentation contain both an
  51 ANSI_SYNOPSIS and a TRAD_SYNOPSIS section.  The TRAD_SYNOPSIS section gets
  52 deleted (since at least 2000) by makedoc, so when working on files these
  53 can safely be deleted and if you're making a new file, there is no need
  54 to add the TRAD_SYNOPSIS section.
  55
  56      If writing a new function that requires documentation, the required
  57 sections are FUNCTION, INDEX, ANSI_SYNOPSIS (or SYNOPSIS), DESCRIPTION, RETURNS,
  58 and PORTABILITY.  BUGS and SEEALSO should be added as appropriate.
  59
  60      Source files which contain documentation are processed into ".def"
  61 files with the extracted information.  These .def files are noted in the
  62 makefiles as either CHEWOUT_FILES in the libc makefiles or chobj in the libm
  63 makefiles.  These .def files need to be included into an appropriate .tex
  64 file for inclusion in the manuals (one each for libc and libm).  Pay special
  65 attention under libc, as the manual is arranged by header file name, but not
  66 all header files are represented by directories (e.g.  wcsftime.c is found
  67 under libc/time, but goes under wchar.h in the manual.)
  68
  69 In summary, to add new documentation:
  70
  71 1.  Add properly-formatted comments to source file (e.g. src.c);
  72 2.  add "chewout" file to list in Makefile.am (CHEWOUT_FILES in libc or chobj in
  73     libm) (e.g. src.def), re-generate Makefile.in;
  74 3.  add file to something.tex;
  75 4.  make ChangeLog entry and generate patch.
  76
  77 EL/IX (ELIX_LEVEL_n, ELIX_n_SOURCES)
  78 ====================================
  79
  80      Some of the Makefiles contain definitions of ELIX_LEVEL_1 ... ELIX_LEVEL_4,
  81 and corresponding definitions for ELIX_1_SOURCES ... ELIX_4_SOURCES.
  82 These are referring to the EL/IX standards created by Red Hat for the
  83 purpose of Linux-based open standards for embedded development.  In brief,
  84 the intent is to define multiple levels for API functions that allows the
  85 user to size the library appropriately for their application--at least in
  86 terms of the predefined lists.  For full details, refer to the EL/IX home
  87 page at http://sources.redhat.com/elix/.  The likely best way to tell how to
  88 classify any new functions in terms of needing an ELIX level qualification
  89 is to ask Jeff Johnston.  To see how it works and try classification on your
  90 own, refer to the API specification on the web site,
  91
  92 http://sources.redhat.com/elix/api/current/api.pdf.
  93
  94 (Unfortunately, it is not complete with respect to either the C99 or POSIX
  95 standards, so particular C and POSIX functions may or may not be found.)
  96
  97      The following definitions of the levels are from the (draft) standard.
  98
  99 Level 1
 100      RTOS compatible layer.  Functions available in both Linux and a
 101 typical deeply embedded operating system (eCos, RTEMS, VxWorks, pSOS, VRTX32,
 102 etc.).  Some functions may have reduced or modified semantics.
 103
 104 Level 2
 105      Linux single process only. Includes level 1 plus any functions from Linux
 106 that are not easily implemented on an RTOS.  Also full implementations of
 107 reduced functions in Level 1.
 108
 109 Level 3
 110      Linux multiprocess for embedded applications.  This is basically POSIX.1
 111 with some of the functions that are obviously not for embedded applications
 112 (such as job control) removed.
 113
 114 Level 4
 115      Full POSIX or Linux compliance.  Essentially these are functions that are
 116 present in a standard Linux kernel but are irrelevant to an embedded system.
 117 These functions do not form part of the EL/IX API.