www.digitalmars.com         C & C++   DMDScript  

digitalmars.D - Proposal for Deimos documentation

reply Jens Mueller <jens.k.mueller gmx.de> writes:
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
Mar 20 2013
next sibling parent reply 1100110 <0b1100110 gmail.com> writes:
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
Mar 20 2013
parent Jens Mueller <jens.k.mueller gmx.de> writes:
1100110 wrote:

 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


Thanks. Will fix.

Jens
Mar 21 2013
prev sibling next sibling parent reply 1100110 <0b1100110 gmail.com> writes:
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.
Mar 20 2013
next sibling parent reply Jacob Carlborg <doob me.com> writes:
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
Mar 21 2013
next sibling parent Jacob Carlborg <doob me.com> writes:
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
Mar 21 2013
prev sibling parent reply 1100110 <0b1100110 gmail.com> writes:
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.
Mar 21 2013
parent reply Jacob Carlborg <doob me.com> writes:
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
Mar 21 2013
parent reply 1100110 <0b1100110 gmail.com> writes:
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)
Mar 21 2013
parent reply Jacob Carlborg <doob me.com> writes:
On 2013-03-21 14:53, 1100110 wrote:


 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)


Or just use wchar_t and it will work correctly, I assume.

-- 
/Jacob Carlborg
Mar 21 2013
parent 1100110 <0b1100110 gmail.com> writes:
On 03/21/2013 10:25 AM, Jacob Carlborg wrote:

 On 2013-03-21 14:53, 1100110 wrote:


 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)


 Or just use wchar_t and it will work correctly, I assume.


Ok, you win.

But I'm still up by one!
Mar 21 2013
prev sibling next sibling parent Jens Mueller <jens.k.mueller gmx.de> writes:
1100110 wrote:

 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?


Probably.


 """
 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?


Where do you want 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.


An example would help here. I was wondering whether anybody has
encountered a tricky example.


 """
 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.


Do you have any examples where one import handles many C headers. I
haven't seen such cases and I wonder why you should need them.

Jens
Mar 21 2013
prev sibling parent Jens Mueller <jens.k.mueller gmx.de> writes:
Jens Mueller wrote:

 1100110 wrote:

 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


 """
 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.


 
 Do you have any examples where one import handles many C headers. I
 haven't seen such cases and I wonder why you should need them.


Please ignore this. I now see what you are saying.
In general it'll be nice to have a list of these replacements for
standard C headers.

Jens
Mar 21 2013
prev sibling next sibling parent reply Jacob Carlborg <doob me.com> writes:
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
Mar 21 2013
parent reply Jens Mueller <jens.k.mueller gmx.de> writes:
Jacob Carlborg wrote:

 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.


My bad. The sentence does not belong there. It belongs to "Tag the
library version". Though I'm not sure how to do this yet.
Will fix. Thanks.

Jens
Mar 21 2013
parent reply Jacob Carlborg <doob me.com> writes:
On 2013-03-21 15:35, Jens Mueller wrote:


 My bad. The sentence does not belong there. It belongs to "Tag the
 library version". Though I'm not sure how to do this yet.
 Will fix. Thanks.


Perhaps we could create list that maps C defines to D versions. Example, 
for Mac OS X the __APPLE__ define is used, in D what would be version(OSX).

-- 
/Jacob Carlborg
Mar 21 2013
parent reply Jens Mueller <jens.k.mueller gmx.de> writes:
Jacob Carlborg wrote:

 On 2013-03-21 15:35, Jens Mueller wrote:
 

My bad. The sentence does not belong there. It belongs to "Tag the
library version". Though I'm not sure how to do this yet.
Will fix. Thanks.


 
 Perhaps we could create list that maps C defines to D versions.
 Example, for Mac OS X the __APPLE__ define is used, in D what would
 be version(OSX).


That would be very helpful. But these are not portable in C, right?
Anyway I should add a link to D versioning and some example.

Jens
Mar 21 2013
parent Jacob Carlborg <doob me.com> writes:
On 2013-03-21 16:40, Jens Mueller wrote:


 That would be very helpful. But these are not portable in C, right?
 Anyway I should add a link to D versioning and some example.


No, they are vendor and platform specific. But they are reliable.

-- 
/Jacob Carlborg
Mar 21 2013
prev sibling parent reply "Craig Dillabaugh" <cdillaba cg.scs.carleton.ca> writes:
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
Mar 21 2013
parent Jens Mueller <jens.k.mueller gmx.de> writes:
Craig Dillabaugh wrote:

 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."


Much better. More of this please.


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


Sorry. This does not work. Probably I should make it work.

Jens
Mar 21 2013