• Matthew Caron (22/22) Nov 20 2012 Apologies if this is a "generic D" question, but I can't find an answer
• Jacob Carlborg (17/35) Nov 20 2012 This is a fairly generic D question which would have fit better in the
• Matthew Caron (28/42) Nov 21 2012 Thank you very much.

Matthew Caron <Matt.Caron redlion.net> writes:

Apologies if this is a "generic D" question, but I can't find an answer 
in any of the D documentation, and folks on this list are quite helpful.

The precompiled-library-and-header paradigm is very common in C. Is 
there a similar one in D? I've used wxd, which is a port of wxWidgets to 
D, and it builds a static .a library, which gets you half there, but 
there is no equivalent header file that gets included - just the wx.d 
file. Basically, if I'm linking against a D library, from where does the 
user-readable documentation for that library come? Is it incumbent upon 
the provider to provide Doxygen-style documentation?

(This came out of a lunchtime discussion at work - the statement was 
made that "at least the C headers keep you honest. You can't use it 
without something that a human can read". Not technically true, but the 
point is well taken. While complete source code availability doesn't 
matter for many cases (purely open source or purely internal 
commercial), it does matter when you have a company writing a library to 
be used by a client and they want a binary library + an API definition 
exposed via a header file).

Thanks in advance.
-- 
Matthew Caron, Software Build Engineer
Sixnet, a Red Lion business | www.sixnet.com
+1 (518) 877-5173 x138 office

Jacob Carlborg <doob me.com> writes:

On 2012-11-20 22:58, Matthew Caron wrote:
 Apologies if this is a "generic D" question, but I can't find an answer
 in any of the D documentation, and folks on this list are quite helpful.

This is a fairly generic D question which would have fit better in the 
digitalmars.D newsgroup. But I'll answer it here anyway :)

 The precompiled-library-and-header paradigm is very common in C. Is
 there a similar one in D? I've used wxd, which is a port of wxWidgets to
 D, and it builds a static .a library, which gets you half there, but
 there is no equivalent header file that gets included - just the wx.d
 file. Basically, if I'm linking against a D library, from where does the
 user-readable documentation for that library come? Is it incumbent upon
 the provider to provide Doxygen-style documentation?

The precompiled-library-and-header paradigm can be used in D as well. 
It's just not that common. In D there is, what's called, D interface 
files (.di) in stead of header files. You can do any of

* Just use the source together with a pre-compiled library (should 
probably be renamed to .di in that case)
* Manually create di files
* Automatically generate di files with the -H flag (I don't know if GDC 
uses the same flag for this)

Generating documentation from ddoc (similar to Doxygen) comments is 
preferred to do, but not many libraries do that. You can use the -D flag 
to do that, if the library do have ddoc comments.

 (This came out of a lunchtime discussion at work - the statement was
 made that "at least the C headers keep you honest. You can't use it
 without something that a human can read". Not technically true, but the
 point is well taken. While complete source code availability doesn't
 matter for many cases (purely open source or purely internal
 commercial), it does matter when you have a company writing a library to
 be used by a client and they want a binary library + an API definition
 exposed via a header file).

 Thanks in advance.

See above.

-- 
/Jacob Carlborg

Matthew Caron <Matt.Caron redlion.net> writes:

On 11/21/2012 02:24 AM, Jacob Carlborg wrote:
 This is a fairly generic D question which would have fit better in the
 digitalmars.D newsgroup.

Ah. I will subscribe to it.

 But I'll answer it here anyway :)

Thank you very much.

 The precompiled-library-and-header paradigm can be used in D as well.
 It's just not that common. In D there is, what's called, D interface
 files (.di) in stead of header files. You can do any of

 * Just use the source together with a pre-compiled library (should
 probably be renamed to .di in that case)
 * Manually create di files
 * Automatically generate di files with the -H flag (I don't know if GDC
 uses the same flag for this)

Ah, thank you.

Now that I knew what I was looking for, I was able to find it in 
Alexandescu's book (though, in hindsight, the index item "header files" 
points you in the correct direction). For the archives, section 11.1.9 
Module Summaries starting on p 349 explains it well.

 Generating documentation from ddoc (similar to Doxygen) comments is
 preferred to do, but not many libraries do that. You can use the -D flag
 to do that, if the library do have ddoc comments.

Yeah, the issue with this (politically) is that the idea of providing a 
library + doxygen style output to customers makes many at my firm recoil 
in horror. Even though they see the value in doxygen docs, and we 
provide them to our customers, the lack of a .h file (or equivalent) is 
seen as making D unacceptable for real work. Now that I can point to .di 
files, the powers that be are happy - even if they are never used.

A small group of us are actually making a lot of headway in promoting D. 
Getting a working cross compiler built helped a lot, and its inclusion 
into mainline gcc will help even more, because it then would likely 
trickle into toolchains provided by chip vendors (since all they do 
these days is build gcc with all the options turned on). This all 
amounts to D being able to be a real, viable option for development.

(Note that our "embedded" systems are actually industrially ruggedized 
Linux machines, so we're not talking bare metal RTOS here. Hell, we run 
Perl in them.)

Thanks for the help.

-- 
Matthew Caron, Software Build Engineer
Sixnet, a Red Lion business | www.sixnet.com
+1 (518) 877-5173 x138 office