C Library Implementation Notes:
===============================

C99 Conformance:
================
For full conformance with the ISO/IEC C99 language standard, clib needs
to be expanded with a number of additional functions and several entirely new
header files. Following are the header files specified by C99, with brief
notes on the estimated effort required to bring them to C99 conformance:

    assert.h    - C99 conforming
    complex.h   - Completely new; requires compiler changes (new types)
    ctype.h     - C99 conforming
    errno.h     - C99 conforming
    fenv.h      - Completely new; requires compiler changes (new #pragma)
    float.h     - Needs review, no significant changes expected
    inttypes.h  - C99 conforming
    iso646.h    - C99 conforming
    limits.h    - Needs review, no significant changes expected
    locale.h    - Needs review, no significant changes expected
    math.h      - Requires compiler changes (new #pragma), many new functions
    setjmp.h    - Needs review, no changes expected
    signal.h    - Needs review, no changes expected
    stdarg.h    - Needs review, C99 va_copy added, likely conforming.
    stdbool.h   - C99 conforming
    stddef.h    - Needs review, no changes expected
    stdint.h    - C99 conforming
    stdio.h     - Needs thorough review, but significant changes not expected
    stdlib.h    - Most new C99 functions already added, more may be needed
    string.h    - Needs review, no significant changes expected
    tgmath.h    - Completely new; defines no functions but needs complex.h
    time.h      - Needs review, no changes expected
    wchar.h     - Needs review, no significant changes expected
    wctype.h    - Needs review, no significant changes expected

Each function newly implemented also requires the addition of a corresponding
regression test. The tests need not necessarily be exhaustive, their main
purpose is to verify that a function works across all supported platforms and
in the long term, verify that a function still works correctly after changes
to clib/compiler.


Old Implementation Notes:
=========================
Following are old Sybase/Watcom implementation notes, updated where appropriate
to reflect current clib status.

Distilled Wisdom:
=================
 -  try to put all source for a given function in one place
 -  excessive conditional compilation obscures things (witness heap component)
 -  want to be able to invoke one command to build a top level library

Major To Do Items:
==================
 -  map out the sequence of events that occur in the runtime support system
    during program execution startup and shut down

Previously Implemented Changes:
===============================
1.  Moved the math library out of the clib hierarchy.
    The math library has different requirements than the clib and should
    be separate.  This helps simplify the structure of the clib.

2.  The clib hierarchy now consists of two tiers. The upper tier contains
    no source code. It consists of a target hierarchy containing merged libraries
    and second tier directories containing component libraries.
    The target hierarchy is rooted in clib/library and contains
    a target directory structure.

3.  The clib hierarchy observes the following rules:
    a. all C source files go into a 'c' directory, .c extension
    b. all ASM source files go into a 'a' directory, .asm extension
    c. all header files go into a 'h' directory, .h extension
    d. all object files go into a target directory, .obj extension

4.  Source file names have suffixes as follows:
        generic         - name
        Intel 16 bit    - name086
        Intel 32 bit    - name386
        OS/2            - nameos2
        OS/2 1.x        - nameo16
        OS/2 2.x        - nameo32
        Win32 (NT)      - namewnt
        Win386          - namew32
        QNX             - nameqnx
        QNX 16          - nameq16
        QNX 32          - nameq32
        NetWare         - namenov
        Linux           - namelnx
        RDOS            - namerdu
    This leads to some slightly cramped names, but the intention is to have all
    source for a given function in one directory. A grep utility can be easily
    used to locate all the files that contain the function.

5.  The source tree is structured as follows:
        alias           - autogenerated function aliases (ultoa -> _ultoa etc.)
        alpha           - Alpha AXP specific functions
        bios            - BIOS wrapper functions
        cgsupp          - compiler support routines
        char            - character manipulation functions
        conio           - console I/O functions
        convert         - conversion manipulation functions
        defwin          - default windowing system
        direct          - directory management functions
        environ         - process environment functions
        file            - file manipulation functions
        fpu             - FPU management functions
        heap            - heap manipulation functions
        handleio        - handle level I/O functions
        intel           - Intel 80x86 specific functions
        kanji           - kanji support routines
        libwin32        - Win32 helper routines
        math            - integer math functions, FPE handler
        mbyte           - multibyte manipulation functions
        memory          - memory manipulation functions
        misc            - miscellaneous functions
        mthread         - multi-threading support functions
        posix           - POSIX functions (for Linux)
        ppc             - PowerPC specific functions
        process         - process primitive functions
        search          - searching and sorting functions
        startup         - run time startup functions
        streamio        - stream I/O functions
        string          - string manipulation functions
        time            - time functions
        win386          - Win386 support routines
        _dos            - MS-DOS functions
        rdos            - RDOS related functions
    This is based on the Overview section of the C Library Reference.
    Files that are specific to one platform, and have no analog on any
    other platform will be located the platform specific area.
    (i.e. intel,alpha,...)

6.  The following first tier target libraries will be built:
        DOS 16          - tiny,ms,mm,mc,ml,mh,overlay mm,overlay ml
        DOS 32          - register ms,stack ms
        OS/2 1.x        - ms,mm,mc,ml,mh,multi-thread ml,DLL ml
        OS/2 2.x        - multi-thread DLL register ms,
                          multi-thread DLL stack ms
        QNX 16          - ms,mm,mc,ml,mh,share
        QNX 32          - register ms
        Win 3.1         - ms,mm,mc,ml
        Win386          - multi-thread DLL register mf,
                          multi-thread DLL stack mf
        Win NT          - multi-thread DLL register ms,
                          multi-thread DLL stack ms
        NetWare         - mulit-thread stack ms
        Kanji 16        - ms,mm,mc,ml,mh
        Kanji 32        - register ms, stack ms
        Linux           - register ms, stack ms
        RDOS            - register mf, stack mf
    Some of these target systems are really -mf but we are building -ms.
    This is to avoid problems with calling into the -ms math library.
    It means that all calls out to user code (including startup) must
    be bracketed with a setup of the segment registers for FLAT and an
    assumption that the user code trashes the segment registers on return.
    This is required for the -r switch that is used to build the library.
    The remaining -mf libraries (Win386??) either don't have
    the math issue or have other issues.

7.  The following naming convention will be used for the first and
    second tier target hierarchies:

       <system>.<processor>\<model>_
                            [<convention>]              - optional
                            [<overlays>]                - optional
                            [<threading>]               - optional
                            [<dll>]                     - optional
                            [<share>]                   - optional
                            [<debug>]                   - optional

   where:
    <system> is one of:
        msdos|qnx|os2|windows|winnt|netware|kanji|linux
    <processor> is one of
        086|286|386|axp|ppc|mps|...
    <model> is one of:
        tiny            - mt
        small           - ms
        medium          - mm
        compact         - mc
        large           - ml
        huge            - mh
        flat            - mf
    <convention> is only used on 32 bit targets and is one of:
        register        - r
        stack           - s
    <overlays> is only used to designate 16 bit overlaid libs and
        is indicated by - ov
    <threading> is only used to designate 16 bit multi-thread libs and
        is indicated by - mt
    <dll> is only used to designate 16 bit DLL libs and is indicated
        by              - dll
    <share> is only used to designate shareable libs and is indicated
        by              - sh
    <debug> is only used to designate debugging libs and is indicated
        by              - d

    This scheme, coupled with the intended targets, produces the following
    first tier target hierarchy:
        msdos.086\
            mt ms mm mc ml mh mm_ov ml_ov
        msdos.286\
            ms mm mc ml mh ml_mt ml_dll
        msdos.386\
            ms_r ms_s
        os2.286\
            ms mm mc ml mh ml_mt ml_dll
        os2.386\
            ms_r ms_s ms_rd
        qnx.286\
            ms mm mc ml mh ml_sh
        qnx.386\
            ms_r
        windows.086\
            ms mm mc ml
        windows.386\
            mf_r mf_s
        winnt.386\
            ms_r ms_s ms_rd
        netware.386\
            ms_s
        kanji.086\
            ms mm mc ml mh
        kanji.386\
            ms_r ms_s
        linux.386\
            ms_r ms_s
        rdos.386\
            mf_r mf_s

8.  The makefile systems is organized around a tree structure.

    a.  There are three basic make operations:
          i) transform source into object (assemble,compile)
         ii) combine object into component library
        iii) combine component libraries into complete libraries
        The first 2 operations occur at the second tier of the directory
        structure, the last operation occurs at the top tier of the directory
        structure.

    b.  Each component library will have a two .mif files in the second
        tier.
        One will be optional and list any important dependancies.
        The other will list all the objects required for each of the
        required targets. It will be implemented with make macros
        (potentially nested) to ensure the following:
          i) no object file will be listed more than once
         ii) the addition of an object file will require exactly one change

    c.  Each component target directory will have a makefile that sets several
        options and then includes the .mif file which lists the source/object
        files and then includes one or more .mif files out of the root to
        drive the build.  No model.inc file will be required, thanks to
        the capabilities of wasm.exe.
        Finally, if there are dependancies, the dependancy file will be
        included.

    d.  Each complete target directory will have a makefile that lists the
        required component libraries and then includes a .mif file out of the
        root to drive the merging of the component libraries.

    e.  All other .mif files will reside in the root of the library.
        These .mif files will be organized around the concepts of building
        libraries and merging libraries.
        The building .mif files will attempt to factor out as much
        redundancy as possible, without obscuring the intent of the build.
        The intention is to allow modifications to the library build to be
        effected with a change to one .mif file.
        The merging .mif files will be driven by the list of component
        libraries required for the complete library.

    f.  The top level .mif files will also support the specification of
        extra_cflags, extra_aflags, extra_cppflags, extra_lflags, in the
        target makefiles to allow for special cases.

    g.  Support for controlled makes will be driven by keywords in the
        makefiles. Each makefile will contain several comments at the
        begining that can be used to list the targets that will require
        this library. The categories are as follows:
            all                                         - all targets
            tiny,small,compact,medium,large,huge,flat,
            nomodel                                     - memory model
            16bit,32bit                                 - code target
            stack,register                              - calling convention
            inline,calls                                - floating point
            heap,_dos,string,streamio,handleio,
            filesys,startup,process,cgsupp, kanji,mbyte,
            mthread,defwin,qnx                          - component of library
            overlay                                     - overlay libraries
            threading                                   - multi-thread library
            dll                                         - dll support
            share                                       - sharable library
            debug                                       - debugging library
            dos,os2,qnx,windows,win386,nt,netware,
            kanji,linux                                 - target system

        As an example, the o1lmt target directory will contain the following
            #pmake:all
            #pmake:large
            #pmake:threading
            #pmake:16bit
            #pmake:os2
        A pmake.exe will visit each target directory and run wmake.exe if
        the makefile contains all the specified targets.

        i.e.
            pmake.exe large threading os2 16bit
                Would sweep the clib and execute the makefile for OS/2 1.x
                large multi-thread libraries.
            pmake.exe all
                Would sweep the clib and execute the makefile for all targets
                since all makefiles will implicitly contain #target=all
            pmake.exe small dos 16bit
                Would sweep the clib and execute the makefile for all small
                dos 16 bit libraries.  This would effectively build the
                ``\lang\lib286\dos\clibs.lib'' file.


9. The following targets should be validated:
        DOS16
        DOS16 Pharlap286
        DOS16 16M
        DOS32 Pharlap386
        DOS32 DOS/4GW
        OS/2 1.x
        OS/2 2.x
        QNX 16
        QNX 32
        Windows 3.1
        Windows 3.1 default windowing
        Win386
        Win386 default windowing
        Windows NT
        NetWare 3.11
        NetWare 4.0

    Validation consists of the set of examples found in the C Library
    Reference plus the 'QA' tests which are part of clib.

Items Not Yet Addressed:
========================
-  Mapping of startup/shutdown events.


Appendix A:
===========

This is a summary of the switches to be used in build the CLIB:

Notes:
======
- make QNX source files conditionally include "shlib.h" when
  "defined(__QNX__) && defined(__SHARE__)"
- make files that are affected by \clib\dos\2h\dll.h conditionally include it
  when "defined(__OS2__) && defined(__DLL__)"
- define wasm.inc as interim to convert cmd switches to macros
  a. change -3r,-3s to STACK=0, STACK=1
  b. change -ms,-mm,-mc,-ml,-mh to _MODEL=...
  c. change 16 bit BIG_DATA -bt=WINDOWS to _DS_PEGGED
  d. change 32 bit -bt=OS2 to _OS220
  e. change 32 bit -bt=NT to _NT
  f. change 32 bit -bt=NETWARE to __NET386__
- modify net386 C source so that
  a. -bt=NETWARE works for __NET386__

Common All:
===========
wlib:                   -q -n -b (-s -t)-> build machine
C flags:                -r -fpr -w3 -zq -zc -zl -zld -fpc
wasm include:           clib
wasm flags:             -q

==============================================================================
MS-DOS Settings:
================
wasm flags:             -ms
                        -mm
                        -mc
                        -ml
                 (huge) -ml
                        -3r
                        -3s
                        -fpi87 (on some floating point files)
C include:              ..\h \clib\h \hdr\dos
C flags:                -ms     -nt=_TEXT
                        -mm
                        -mc -zu -nt=_TEXT
              (overlay) -mm     -of
                        -ml -zu
              (overlay) -ml -zu -of
                        -mh -zu
                        -ms -5r
                        -ms -5s
special case C flags:   -oasl -s (for certain files)
                        -oax (for all other files)
                        -of (for certain 16 bit files)

==============================================================================
QNX Settings:
=============
wasm flags:             -bt=QNX
                        -ms
                        -mm
                        -mc
                        -ml
                        -mh
                        -ms -3r
C include:              ..\h \clib\h \clib\ansi\h \hdr\qnx
C flags:                -bt=QNX
                        -ms     -nt=_TEXT
                        -mm
                        -mc -zu -nt=_TEXT
                        -ml -zu
                        -mh -zu
                (share) -ml -zu -d__SHARE__
                        -ms -5r
special case C flags:   -oasl -s (for certain files)
                        -oax (for all other files)
                        -of (for certain 16 bit files)

==============================================================================
OS/2 Settings:
==============
wasm flags:             -bt=OS2
                        -ms
                        -mm
                        -mc
                        -ml
                        -mh
                   (mt) -ml -d__MT__
                  (dll) -ml -d__MT__
                        -ms -3r -d__MT__? (some 32bit asm files)
                        -ms -3s -d__MT__? (some 32bit asm files)
16bit C include:        ..\h \clib\dos\h \clib\h \hdr\dos \watcom\h
32bit C include:        ..\h \clib\dos\h \clib\h \hdr\dos \watcom\os220_h
                        \watcom\h
C flags:                -bt=OS2
                        -ms     -nt=_TEXT
                        -mm
                        -mc -zu -nt=_TEXT
                        -ml -zu
                        -mh -zu
                   (mt) -ml -zu -d__MT__
                  (dll) -ml -zu -d__MT__ -d__DLL__
                        -ms -5r -d__MT__ -d__OS220__
                        -ms -5s -d__MT__ -d__OS220__
special case C flags:   -osl -s (for certain files)
                        -ox (for all other files)
                        -of (for certain 16 bit files)

==============================================================================
Windows Settings:
=================
wasm flags:             -bt=WINDOWS
                        -ms
                        -mm
                        -mc
                        -ml
                        -mf? -3r
                        -mf? -3s
C include:              ..\h \clib\h \hdr\dos
C flags:                -bt=WINDOWS
                        -ms     -nt=_TEXT
                        -mm
                        -mc -zu -nt=_TEXT
                        -ml -zu
                        -mf? -5r
                        -mf? -5s
special case C flags:   -oasl -s (for certain files)
                        -oax (for other files)
                        -of (for certain files)

==============================================================================
NT Settings:
============
wasm flags:             -bt=NT -ms -d__MT__
                        -3r
                        -3s
C include:              ..\h \clib\h \clib\dos\nth \hdr\dos \watcom\nt_h
                        \watcom\h
C flags:                -bt=NT -ms -d__MT__
                        -5r
                        -5s
special case flags:     -oasl -s (for certain files)
                        -oax (for rest of files)

==============================================================================
NetWare Settings:
=================
wasm flags:             -bt=NETWARE -ms -3s
C include:              \clib\h ..\h \hdr\dos
common C flags:         -bt=NETWARE -ms -5s -ox -d__far= -d__MT__

==============================================================================
Windows Supervisor 32 bit: wind386\(w3r,w3s)
==========================
wasm flags:             -bt=WINDOWS -ms
                        -3r
                        -3s
C include:              ..\h \clib\h \hdr\dos
common C flags:         -bt=WINDOWS -ms -ox
                        5r
                        5s


==============================================================================
RDOS Settings:
============
wasm flags:             -bt=rdos
                        -3r
                        -3s
C include:              ..\h \clib\h \hdr\dos
                        \watcom\h
C flags:                -bt=rdos -bm
                        -3r
                        -3s
