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

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

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