Difference between revisions of "DIP12"

From D Wiki
Jump to: navigation, search
m
 
Line 83: Line 83:
 
== Copyright ==
 
== Copyright ==
 
This document has been placed in the Public Domain.
 
This document has been placed in the Public Domain.
 +
[[Category: DIP]]

Latest revision as of 18:53, 28 May 2014

Title: C API headers
DIP: 12
Version: 1
Status: Approved
Created: 2011-10-18
Last Modified: 2011-10-18
Author: Martin Nowak
Links: The CAPI Manifesto

Abstract

Create a place to gather D import files for publicly available C libraries.

Rationale

D is binary compatible with C ABI code. This allows to reuse the huge amount of high quality public C libraries. Providing a central place to publish D import files can leverage the tedious work of translating.

Description

A repository was created under [1]. It was proposed to use the following directory structure.

   deimos
   
       |--- library name
           |--- C
              |--- foo.h
                  |--- bar
                      |--- baz.h
           |--- D
              |--- foo.d
                  |--- bar
                      |--- baz.d


Each '#include <path/to/header.h>' should have a corresponding 'import path.to.header;'

Possibly all files could be rooted under a package 'cabi', i.e. 'import cabi.path.to.header;'.

The D import files should try to do as least modifications as possible to simplify updates of the C headers. This includes leaving comments intact.

Translated header should not require linkage of any D binary. Necessary D functions can be written as nullary templates.

   #define GET(x) x.value => int GET()(X x) { return x.value; }

Version tags should match the ones being used by the C headers.

The copyright for the D import files should match the one being used by the C header as they are derived work.

If the C header file has a name that is a D keyword, an underscore will be appended to the D module name.

If a C type name matches a C function name (stat), the type name will have a "_t" appended.

Open Questions

  • Who is going to maintain the repository?

Starting with the phobos dev team.

  • How will added/modified headers be reviewed/tested?
  • What can be reused of the dsource/bindings project?

Recommendations

Each library should contain a README in the root folder. The README file should contain exact source and version of the C library. Furthermore it should contain specific notes about the usage of the D import file.

Every library should contain a simple D example under CAPI/library/examples. This could be used for basic self testing.

Copyright

This document has been placed in the Public Domain.