Download Reference Manual
The Developer's Library for D
About Wiki Forums Source Search Contact

Changes between Version 4 and Version 5 of ChapterC

Show
Ignore:
Author:
sean (IP: 216.10.144.10)
Timestamp:
02/05/08 23:21:38 (16 years ago)
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • ChapterC

    v4 v5  
    11[wiki:CComments Leave Comments, Critiques, and Suggestions Here] 
    22 
    3 = Sailing the Stormy C
     3= Introduction
    44 
    5 Just as the sea sits between a ship and its rocky demise, so too does C provide a comfortable buffer between applications and hardware.  Many D programmers will be content to sail in the ship provided, and a few brave souls may wish explore the murky depths with naught but an assembler and a prayer, but the rest will need some basic tools to brave the C.  To accomplish this, Tango offers a set of C header modules intended to provide a means of interacting with both the standard C library and with core operating system C libraries, as well as a few simple tools for simplifying the process of passing data to and from C routines. 
     5Tango offers a set of header modules intended to provide a means of interacting with both the standard C library and with core operating system C libraries, as well as a few simple tools for simplifying the process of passing data to and from C routines. 
    66 
    77== C Header Conventions == 
    88 
    9 Unlike other Tango modules, C header modules names are lowercase. This is done for two reasons: first, it is important that these names match the original C header names as closely as possible to provide a consistent and predictable interface layout, and second, to make a clear distinction between C imports and native D imports.  This latter aspect serves to make C API use more obvious to code reviewers and should help to point out areas where D API support is weak.  In the few rare instances where module, function, or variable names were changed to avoid colliding with D keywords, the changes were made to be as invisible as possible, and each will be outlined below.  Also, when available, headers have been implemented according to the available spec rather than simply translating directly from an existing C library. This serves to dramatically reduce clutter, eliminate exposure of non-portable library extensions, and aid maintenance and readability. 
     9Unlike other Tango modules, C header modules names are lowercase. This is done for two reasons: first, it is important that these names match the original C header names as closely as possible to provide a consistent and predictable interface layout, and second, to make a clear distinction between C imports and native D imports. This latter aspect serves to make C API use more obvious to code reviewers and should help to point out areas where D API support is weak. In the few rare instances where module, function, or variable names were changed to avoid colliding with D keywords, the changes were made to be as invisible as possible, and each will be outlined below. Also, when available, headers have been implemented according to the available spec rather than simply translating directly from an existing C library. This serves to dramatically reduce clutter, eliminate exposure of non-portable library extensions, and aid maintenance and readability. 
    1010 
    1111== The Standard C Library == 
    2727 * '''wchar.d''' - 'wchar' is a keyword in D so this module is unavailable.  Instead, its contents have been spread across related modules according to category.  In general, the features of this module are available in the char-oriented module of the same purpose.  So string.h contains the wchar string-handling routines and so on. 
    2828 
    29 Currently, all core C types are assumed to be the same width as their corresponding D type except long and unsigned long, which commonly vary based on the underlying operating system and processor bus width. The 'config' module has been added to provide aliases for these types, which are named according to their D equivalent with a 'c_' prefix.  Therefore, a C long type name is represented as c_long, and a C unsigned long type name is represented as c_ulong.  This module may be used in instances where D type sizes must match their corresponding C type size. Other aliases will be added as needed, though there is currently no plan to support architectures with odd-sized bytes. 
     29Currently, all core C types are assumed to be the same width as their corresponding D type except long and unsigned long, which commonly vary based on the underlying operating system and processor bus width. The 'config' module has been added to provide aliases for these types, which are named according to their D equivalent with a 'c_' prefix. Therefore, a C long type name is represented as c_long, and a C unsigned long type name is represented as c_ulong. This module may be used in instances where D type sizes must match their corresponding C type size. Other aliases will be added as needed, though there is currently no plan to support architectures with odd-sized bytes. 
    3030 
    3131=== The Posix Library === 
    3232 
    33 Tango contains a partial implementation of the POSIX interface implemented according to the Open Group Base Specification Issue 6 (IEEE Std 1003.1), which is located in the tango.stdc.posix package. These headers have been implemented manually, and will be extended as needed.  The contents of each module have been segregated by categoy, beginning with a comment describing the category, followed by a comment block describing what belongs in the category, and ending with the actual code for that category.  Please note that while portable declarations of required features are available to all POSIX-compliant systems, the contents of many strucutres, the values of constants, and other details, have no common definition and therefore must be defined on a per-system basis.  Currently, Linux is is fairly well supported, but coverage of other systems is somewhat sparse. Submissions to this library are welcome but must be in the style of the current headers for inclusion. 
     33Tango contains a partial implementation of the POSIX interface implemented according to the Open Group Base Specification Issue 6 (IEEE Std 1003.1), which is located in the tango.stdc.posix package. The package exists in this location because the POSIX interface is specified as an extension to the standard C library and is not system-specific.  The POSIX headers have been implemented manually, and will be extended as needed. The contents of each module have been segregated by categoy, beginning with a comment describing the category, followed by a comment block describing what belongs in the category, and ending with the actual code for that category. Please note that while portable declarations of required features are available to all POSIX-compliant systems, the contents of many strucutres, the values of constants, and other details, have no common definition and therefore must be defined on a per-system basis. Currently, Linux is is fairly well supported, but coverage of other systems is somewhat sparse. Submissions to this library are welcome but must be in the style of the current headers for inclusion. 
    3434 
    3535== The System Library == 
    3636 
    37 Operating system-specific library code is located in the tango.sys package, segregated by system name. 
     37Operating system-specific library code is located in the tango.sys package, segregated by system name.  The packages are arranged in this way to clearly indicate when a platform-specific feature is being used, and which platform defines the feature. 
    3838 
    3939=== Windows API === 
    4040 
    41 The Windows Win32 API is located in tango.sys.win32. In general, these modules in this package are straightforward translations of the C header files of the same name, and Microsoft's documentation is directly applicable to them. Some additional helper modules are also included. 
    42 The module tango.sys.win32.UserGdi holds the core Windows API functions, and is generally all that is required for traditional Windows SDK programming. Importing this file is equivalent to the C code: 
     41The Windows Win32 API is located in tango.sys.win32. In general, the modules in this package are straightforward translations of the C header files of the same name, and Microsoft's documentation is directly applicable to them. Some additional helper modules are also included. The module tango.sys.win32.UserGdi holds the core Windows API functions, and is generally all that is required for traditional Windows SDK programming. Importing this file is equivalent to the C code: 
    4342 
    4443{{{ 
    4645 #include "windows.h" 
    4746}}} 
     47 
     48In the future, this package may also contain D code for creating services, interacting with the Windows Registry, and other common tasks. 
     49 
     50=== Linux API === 
     51 
     52The Linux API is located in tango.sys.linux and is intended to contain header modules for any features specific to Linux which are not defined in the POSIX spec.  Given the breadth of the POSIX feature set, this package is still relatively sparse, but it will be the destination for any kernel interface modules, support for /dev/epoll, and so on.  At the moment, this package also contains the self-named module "linux" which provides linux support for the features exposes in tango.sys.Common. 
     53 
     54=== Darwin API === 
     55 
     56The Darwin API is located in tango.sys.darwin and contains header modules for any features specific to Darwin (Mac OS X) which are not defined in the POSIX spec.  At the moment, this package only contains the self-named module "darwin" which provides darwin support for the features exposed in sys.Common.