The CAPI Manifesto

[Gor Gyolchanyan]

OR

Maybe parallel to the CAPI, there could be the D-ified version of it,
that will be developed after the original CAPI.
This is, of course, not as urgent a the CAPI itself, but it would be
very useful to gradually help users get rid of unnecessarily dangerous
code.

On Mon, Oct 17, 2011 at 9:24 AM, Gor Gyolchanyan
<gor.f.gyolchanyan at gmail.com> wrote:
> I think there might be a few tricks to improve the C API without
> adding any new code.
> For example, replace by-pointer parameter declarations with _out_
> parameters when applicable (the underlying function signature is the
> same), replace const parameters with in parameters, etc.
> This won't change the C API a single bit (won't even add new code),
> but will vastly improve readability and sometimes safety of the API.
> In other cases, some minor additions could be made, for example:
> libjpeg provides API to register error handlers, instead of setting
> errno and such. Those kind of situations could be used to throw
> exceptions. It only takes a static this() and a few lines of code.
> In case those kind of modifications/additions are made, there could be
> a standard way to disable them and use the original version.
>
> On Mon, Oct 17, 2011 at 6:02 AM, Walter Bright
> <newshound2 at digitalmars.com> wrote:
>> Brad and I were talking about some D code that needed openssl support, when
>> we ran into the same old problem:
>>
>> No D files corresponding to the openssl C .h files.
>>
>> It's not that these are a big problem to create, it's just that they are not
>> done, and it tends to turn off people from using D. D is binary API
>> compatible with C, but only with a corresponding D import file. This, out of
>> the box, makes D *harder* to use than C.
>>
>> Lots of people roll their own, but that work is hard to find and haphazard.
>>
>> This problem keeps coming up again and again.
>>
>> So I propose creating, on github.com/D-Programming-Language, a new
>> repository called CAPI.
>>
>> The CAPI Manifesto
>> ------------------
>>
>> CAPI is a collection of C header files to publicly available C libraries
>> and their translations to D. The idea is that if, in C, to interface to a
>> library
>> one would write:
>>
>>   #include "foo.h"
>>
>> then the corresponding D code would look like:
>>
>>   import foo;
>>
>> Each C .h file would have a corresponding .d file. Each C directory would
>> have a corresponding D directory, for example:
>>
>>   #include "bar/foo.h"   // C
>>
>>   import bar.foo; // D
>>
>> The top level directory of each library will have two subdirectories:
>>
>>   C/
>>   D/
>>
>> and there will be a one-to-one correspondence of files and directory
>> structure
>> between them.
>>
>> The D import files will be a rote translation of the corresponding C .h
>> file.
>> No attempt will be made to fix, improve, or extend the C api. No attempt
>> will
>> be made to duplicate the C documentation, or replace it in any way. There
>> will be no unittests. Every effort will be made to avoid needing any D
>> specific
>> binary files.
>>
>> When an updated version of the C header files becomes available, those will
>> get checked into the C subdirectory tree, and then the corresponding D files
>> will get updated.
>>
>> Version tags used must match the version tags used by the C API files.
>>
>> The license used for the D versions should match the C ones, as they are a
>> derived work.
>>
>