Hi,

I wrote some guidelines for writing a Deimos interface. It's still very
rough but it's a start. I'd like to add it to dlang.org to give
contributors better guidance, ultimately hoping to see more
contributions to Deimos.
Besides comments to improve my poor phrasing I'd especially seek to get
a complete list of recommendations to follow. Please comment.

http://jkm.github.com/phobos/deimos.html

Jens

On 03/20/2013 05:04 PM, Jens Mueller wrote:
> Hi,
>
> I wrote some guidelines for writing a Deimos interface. It's still very
> rough but it's a start. I'd like to add it to dlang.org to give
> contributors better guidance, ultimately hoping to see more
> contributions to Deimos.
> Besides comments to improve my poor phrasing I'd especially seek to get
> a complete list of recommendations to follow. Please comment.
>
> http://jkm.github.com/phobos/deimos.html
>
> Jens

Typo!
"git clone git://github.com/D-Programming-Deimos/openssl.git dmd -Iopenssl/ -lopenssl ... "

-Iopenssl/ -L-lssl

On 03/20/2013 05:04 PM, Jens Mueller wrote:
> Hi,
>
> I wrote some guidelines for writing a Deimos interface. It's still very
> rough but it's a start. I'd like to add it to dlang.org to give
> contributors better guidance, ultimately hoping to see more
> contributions to Deimos.
> Besides comments to improve my poor phrasing I'd especially seek to get
> a complete list of recommendations to follow. Please comment.
>
> http://jkm.github.com/phobos/deimos.html
>
> Jens

"""
Each must follow the directory structure
"""

nitpick, maybe add a colon after that fragment?

"""
So far, each C header file was renamed to a D module. Next the contents of each module will be adjusted. In general following the advices from interfacing to c is recommended.

The D files should try to do as least modifications as possible to simplify updates of the C headers. This includes leaving comments intact. The copyright for the D files should match the one being used by the C header as they are derived work.
""

Maybe just a little more detail?
Again a nitpick.  But I'd like to see a few "real world" examples of some of the trickier constructs mixed in.  Even if you left all the details to "interfacing to c", an example or two would clarify things IMO.


"""
In particular,

    Replace C's include

    Each #include needs to have a corresponding import path.to.header;
"""

That has certainly not been my experience.  Often one D import will map to a couple of c includes.

I would suggest amending that statement.  It sounds too much like a hard rule(necessary to be considered for inclusion into Deimos) to me.  YMMV.

On 2013-03-21 07:59, 1100110 wrote:

> """
> In particular,
>
>      Replace C's include
>
>      Each #include needs to have a corresponding import path.to.header;
> """
>
> That has certainly not been my experience.  Often one D import will map
> to a couple of c includes.
>
> I would suggest amending that statement.  It sounds too much like a hard
> rule(necessary to be considered for inclusion into Deimos) to me.  YMMV.

I would say that each #include should have _at least_ one corresponding import. Then there could be additional imports as well.

Sure, there could be unnecessary includes but that's not very likely.

-- 
/Jacob Carlborg

On 2013-03-21 11:00, Jacob Carlborg wrote:

> I would say that each #include should have _at least_ one corresponding
> import. Then there could be additional imports as well.
>
> Sure, there could be unnecessary includes but that's not very likely.

Forgot to say, I usually just remove all includes and then add imports using trails-and-error.

-- 
/Jacob Carlborg

On 2013-03-20 23:04, Jens Mueller wrote:
> Hi,
>
> I wrote some guidelines for writing a Deimos interface. It's still very
> rough but it's a start. I'd like to add it to dlang.org to give
> contributors better guidance, ultimately hoping to see more
> contributions to Deimos.
> Besides comments to improve my poor phrasing I'd especially seek to get
> a complete list of recommendations to follow. Please comment.

"Versioning" - Version tags should _not_ match the ones used by the C headers. The should be translated, as close as possible, to:

http://dlang.org/version.html#PredefinedVersions

Some might be better translated to static-if blocks.

-- 
/Jacob Carlborg

On 03/21/2013 05:00 AM, Jacob Carlborg wrote:
> On 2013-03-21 07:59, 1100110 wrote:
>
>> """
>> In particular,
>>
>> Replace C's include
>>
>> Each #include needs to have a corresponding import path.to.header;
>> """
>>
>> That has certainly not been my experience. Often one D import will map
>> to a couple of c includes.
>>
>> I would suggest amending that statement. It sounds too much like a hard
>> rule(necessary to be considered for inclusion into Deimos) to me. YMMV.
>
> I would say that each #include should have _at least_ one corresponding
> import. Then there could be additional imports as well.
>
> Sure, there could be unnecessary includes but that's not very likely.
>

Oh, we aren't on the same page.
Here, I'm curious as to how you would translate these into D.

#include <stdbool.h>
#include <stdarg.h>	/* we need va_list */
#include <stddef.h>	/* we want wchar_t */

> Sure, there could be unnecessary includes but that's not very likely.

Two out of Three of those are a builtin type(bool and wchar), and the other one is...  Well... I'm not sure, but no one's missed it yet.(pretty sure it was a hack to get around something in C.)
(Any good reads on D's Variadic Functions by chance?)

So it actually seems to be pretty likely in practice.

About as likely as any given C project to roll their own boolean type.
Which apparently is *really high*.  =P




"""
Forgot to say, I usually just remove all includes and then add imports using trails-and-error.
"""

Grep and locate are your friends.  As well as "replace all".  ;)
But yeah, that's the way to do it.

On 2013-03-21 13:01, 1100110 wrote:

> Oh, we aren't on the same page.
> Here, I'm curious as to how you would translate these into D.
>
> #include <stdbool.h>
> #include <stdarg.h>    /* we need va_list */
> #include <stddef.h>    /* we want wchar_t */

Right, that's a good point. You still need stddef if you don't want to change wchar_t to wchar. BTW, can't wchar_t sometimes be the same as dchar?

-- 
/Jacob Carlborg

On 03/21/2013 07:09 AM, Jacob Carlborg wrote:
> On 2013-03-21 13:01, 1100110 wrote:
>
>> Oh, we aren't on the same page.
>> Here, I'm curious as to how you would translate these into D.
>>
>> #include <stdbool.h>
>> #include <stdarg.h> /* we need va_list */
>> #include <stddef.h> /* we want wchar_t */
>
> Right, that's a good point. You still need stddef if you don't want to
> change wchar_t to wchar. BTW, can't wchar_t sometimes be the same as dchar?
>

That does sound vaguely familiar...
Yes, it's size is 16 on Windows and 32 on Linux and OSX.

My bad, dchar then. (with wchar for Windows)

On Wednesday, 20 March 2013 at 22:04:50 UTC, Jens Mueller wrote:
> Hi,
>
> I wrote some guidelines for writing a Deimos interface. It's still very
> rough but it's a start. I'd like to add it to dlang.org to give
> contributors better guidance, ultimately hoping to see more
> contributions to Deimos.
> Besides comments to improve my poor phrasing I'd especially seek to get
> a complete list of recommendations to follow. Please comment.
>
> http://jkm.github.com/phobos/deimos.html
>
> Jens

 From the first paragraph of the linked documentation:

"Its aim is to integrate already available C libraries. Since D
is binary compatible with C ABI code a plentiful of libraries is
potentially available in D. ".

I would recommend something along the lines of:

"Its aim is to integrate existing C libraries. Since D is binary
compatible with C ABI code, this makes a wealth of existing
functionality available in D with limited effort."

I tried to use the "Improve this page" link to make this
suggestion, but GitHub gave me a "Page Not Found" error.

Craig