View mode: basic / threaded / horizontal-split · Log in · Help
September 19, 2006
Proposal for a standard for D library naming
(I'm reposting this, since my last post had some issues)

Since there aren't many libraries for D (that is, builds that produce 
.so files or the ilk), there's no standard on file naming for libraries. 
 I'd like to interject a standard before it starts getting chaotic (as 
with every other language there is).

Please respond with any opinions.


A Modest Proposal for Standardization in Naming of D Libraries
--------------------------------------------------------------
(by Gregor Richards)


Outline
-------

At present, there is to my knowledge no standard for naming D
libraries (that is, .a, .lib, .so and .dll files). There's no
immediate problem posed, as there is very little D code that forms
libraries - but with any luck, the amount of code doing so will
increase.

For background on me and why I'm interested in this, both my job and
several of my personal projects involve compilation and linking of
software in UNIX environments, so I'm constantly exposed to
inconsistent libraries.

My experience with the D community has shown that few people at the
moment seem to care about the creation of libraries, but I believe
that desire will increase as popularity does. I consider the fact
that there is no standard for naming to be a significant problem, as
a lack of a clear naming convention will likely make the entire
compilation process difficult (think of autoconf).

I intend to outline in this document a naming convention for library
files which will be easily parseable by both humans and software
(such as [d]build).

Note that this document does not currently target Windows .dll and
.lib files, as I know nothing whatsoever about them. If anyone would
like to step in and make modifications, feel free.


Don't Break from Convention
---------------------------

(This section applies only to UNIX)

The UNIX convention for naming of libraries is:

lib<name>.so.<major>.<minor>.<revision>

with symlinks for each of:

lib<name>.so.<major>.<minor>
lib<name>.so.<major>

and also a symlink of:

lib<name>.so

if the library has its headers installed. There is no compelling
reason to break from this standard, so it is left as such in this
document.

For .a files, the file name is more simple:

lib<name>.a


Packages and Libraries
----------------------

Package names should be directly reflected in the file name of the
library. Furthermore, the fact that this library is written in D
should also be in the name of the library. To this end, the basic
form is:

libD.<package name>.<extension>

Of course, packages are more complex than that, with subpackages,
etc. The division becomes more complex for packages such as:

a.*
a.b.*
a.c.*
a.d.*

Each library must only be inclusive of /modules/ in the package, not
subpackages (though it may be either at the creator's whimsy). One
way to comply would be to simply have a single file:

libD.a.<extension>

However, if one wanted to subdivide, it could also have several:

libD.a.b.<extension>
libD.a.c.<extension>
libD.a.d.<extension>

Now let's imagine the situation of the package 'a' having a module
named 'foo'. a.foo doesn't belong in its own library (we've already
determined that libraries correspond to packages), so it will go into
its own file:

libD.a.<extension>

With this subdivision, we now have four files:

libD.a.<extension>
libD.a.b.<extension>
libD.a.c.<extension>
libD.a.d.<extension>

Now, in all likelihood, one or all of the subpackages depend on
modules in the superpackage. Luckily, this is trivial to detect in a
build system. Since all of the imports will be iterated over, a list
of packages to test for can be built that is guaranteed to capture
everything (so long as the installation is complete).


Version Hell
------------

(Or DLL Hell as it's affectionately known on Windows)

Version Hell isn't too bad with UNIX-style .so files, so long as
people comply to this simple standard:

1) Only increase the major version if you've made non-backwards-
   compatible changes.
2) Increase the minor version when you've added but not removed
   symbols.
3) Increase the revision for all other changes.
4) Don't worry about D ABI changes - they're well beyond the scope of
   library naming convention.

I would recommend that a .DLL version of this spec incorporate some
sort of versioning similar to UNIX.


Build Tools
-----------

With this setup, a build tool (such as build) has a very trivial task
to generate a library name from an import. It simply needs to,
starting with the most specific and expanding to the most general,
check whether files corresponding to the name exist. So, if an import
for a.b.c.d.e.f.g had been specified and the imported file was not in
the included source, it would search (in this order):

libD.a.b.c.d.e.f.g.so
libD.a.b.c.d.e.f.g.a
libD.a.b.c.d.e.f.so
libD.a.b.c.d.e.f.a
libD.a.b.c.d.e.so
libD.a.b.c.d.e.a
libD.a.b.c.d.so
libD.a.b.c.d.a
libD.a.b.c.so
libD.a.b.c.a
libD.a.b.so
libD.a.b.a
libD.a.so
libD.a.a

If none of them were found, it fails. Because each file carries its
own dependencies, the build tool only needs to link against the one
it found (and know how to read .add files) to get all of the symbols
resolved.

The generation of these files is a bit more complex, but any build
tool would only need a tiny bit of input from the user (exactly where
to subdivide) to be able to produce them.


Questions?
----------

If anything is confusing here, please respond, and I will attempt to
clarify. It's all quite clear in my head :)
September 19, 2006
Re: Proposal for a standard for D library naming
On Mon, 18 Sep 2006 21:10:46 -0700, Gregor Richards wrote:

I was wondering if this sort of thing might be better on the D Wiki 

   http://www.prowiki.org/wiki4d/wiki.cgi?FrontPage

instead of this newsgroup. You could always put a link to the wiki entry on
the newsgroup, but the wiki is a good place to host discussions.



-- 
Derek
(skype: derek.j.parnell)
Melbourne, Australia
"Down with mediocrity!"
19/09/2006 3:00:48 PM
September 19, 2006
Re: Proposal for a standard for D library naming
Per Derek's suggestion, I've put this on wiki4d:

http://www.prowiki.org/wiki4d/wiki.cgi?LibraryNamingConvention

Feel free to respond via either medium.

 - Gregor Richards
September 19, 2006
Re: Proposal for a standard for D library naming
Gregor Richards wrote:

> (This section applies only to UNIX)
> 
> The UNIX convention for naming of libraries is:
> 
> lib<name>.so.<major>.<minor>.<revision>
> 
> with symlinks for each of:
> 
> lib<name>.so.<major>.<minor>
> lib<name>.so.<major>
> 
> and also a symlink of:
> 
> lib<name>.so
> 
> if the library has its headers installed. There is no compelling
> reason to break from this standard, so it is left as such in this
> document.

Not to rain on your parade, but Darwin libraries use:

lib<name>.<major>.<minor>.<revision>.dylib
lib<name>.<major>.<minor>.dylib ->
lib<name>.<major>.dylib ->
lib<name>.dylib ->

So you might want to make the "so" name flexible... ?

Using the -L and -l flags works as expected, though.
(With GDC that is, DMD uses those flags differently)

Everything else applies.
--anders


SIDE NOTE:
However, most Mac OS X libraries are instead packaged
as "frameworks" which include *both* libs and includes.
(Similar to how the Mac OS X applications are bundled up
as "apps" which include both executables and resources)

Frameworks are linked with the -framework flag, and the
headers are automatically searched for in the system dirs.
Don't think that the D libraries will ever be packaged as
frameworks, so it only applies to libs like OpenGL and SDL.
September 19, 2006
Re: Proposal for a standard for D library naming
Gregor Richards wrote:

> Package names should be directly reflected in the file name of the
> library. Furthermore, the fact that this library is written in D
> should also be in the name of the library. To this end, the basic
> form is:
> 
> libD.<package name>.<extension>

Why does the fact that it uses D have to be reflected in the name ?

I don't see any C++ libraries advertising that they are using that,
so I still need to remember to link them to libstdc++ or get errors.
Don't think it would be that bad to avoid prefixing them with "D.",
and instead get similar link errors from Phobos (and the D runtime).

So I would rather continue to name them as lib<name>.a/<name>.lib...

--anders
September 19, 2006
Re: Proposal for a standard for D library naming
Anders F Björklund wrote:
> Gregor Richards wrote:
> 
>> (This section applies only to UNIX)
>>
>> The UNIX convention for naming of libraries is:
>>
>> lib<name>.so.<major>.<minor>.<revision>
>>
>> with symlinks for each of:
>>
>> lib<name>.so.<major>.<minor>
>> lib<name>.so.<major>
>>
>> and also a symlink of:
>>
>> lib<name>.so
>>
>> if the library has its headers installed. There is no compelling
>> reason to break from this standard, so it is left as such in this
>> document.
> 
> 
> Not to rain on your parade, but Darwin libraries use:
> 
> lib<name>.<major>.<minor>.<revision>.dylib
> lib<name>.<major>.<minor>.dylib ->
> lib<name>.<major>.dylib ->
> lib<name>.dylib ->
> 
> So you might want to make the "so" name flexible... ?
> 
> Using the -L and -l flags works as expected, though.
> (With GDC that is, DMD uses those flags differently)
> 
> Everything else applies.
> --anders
> 
> 
> SIDE NOTE:
> However, most Mac OS X libraries are instead packaged
> as "frameworks" which include *both* libs and includes.
> (Similar to how the Mac OS X applications are bundled up
> as "apps" which include both executables and resources)
> 

I didn't mean to imply that these extensions were the only ones 
possible, I used them because they were the ones I knew about.


> Frameworks are linked with the -framework flag, and the
> headers are automatically searched for in the system dirs.
> Don't think that the D libraries will ever be packaged as
> frameworks, so it only applies to libs like OpenGL and SDL.
>

But it /doesn't/ apply to libraries like OpenGL and SDL, they're not 
written in D, and would still need to be manually included.


> Why does the fact that it uses D have to be reflected in the name ?
>

So that a unique namespace can be guaranteed - remember, these library 
names are to be not only human-understandable but machine-generatable.


> I don't see any C++ libraries advertising that they are using that,
> so I still need to remember to link them to libstdc++ or get errors.

This is a good thing?


> Don't think it would be that bad to avoid prefixing them with "D.",
> and instead get similar link errors from Phobos (and the D runtime).

But what's the advantage? The D prefix is more of a note that a D 
package name is coming than something to say "this is written in D"

eg if you wrote a library in D that exports a C interface, you may be 
inclined to name it in a more traditional way, as that library is for 
use by C (or D), so the D build tool does not necessarily need to 
generate the paths in the same way.


>
> So I would rather continue to name them as lib<name>.a/<name>.lib...
>

The entire idea behind my naming proposal is that it makes everything 
100% computer and human generatable while adding very little confusion. 
 Having things named lib<name>.<extension> makes associating packages 
and libraries difficult.

Because C/++ don't have such a nice, structured package style, they 
don't have a naming convention for library files (there really couldn't 
be one), but I think that's a terrible reason to not use a naming 
convention for D.  It would building, even against libraries, 
ridiculously easy.


> --anders

 - Gregor Richards
September 19, 2006
Re: Proposal for a standard for D library naming
Gregor Richards wrote:
> Anders F Björklund wrote:
>  > I don't see any C++ libraries advertising that they are using that,
>  > so I still need to remember to link them to libstdc++ or get errors.
> 
> This is a good thing?
> 
> 

Another reason for the D prefix is for bindings.  Many bindings will 
have package names similar to their C library names - so similar in fact 
that the names could overlap if there was nothing to uniquely identify 
the D one.  And if the names overlapped, it would need to break the 
naming convention, which would defeat the whole purpose of having a 
naming convention in the first place :)

 - Gregor Richards
September 19, 2006
Re: Proposal for a standard for D library naming
Gregor Richards wrote:

>> So you might want to make the "so" name flexible... ?
> 
> I didn't mean to imply that these extensions were the only ones 
> possible, I used them because they were the ones I knew about.

No problem, just thought I'd add to the little list since
Mac OS X is identified by GDC as being a "Unix" platform...

>> So I would rather continue to name them as lib<name>.a/<name>.lib...
> 
> The entire idea behind my naming proposal is that it makes everything 
> 100% computer and human generatable while adding very little confusion. 
>  Having things named lib<name>.<extension> makes associating packages 
> and libraries difficult.

Think I missed the "auto-generated" part of the proposal... :-)

Currently I have the "wx" modules defined in a libwxd.a (or wxd.lib),
partly since wx is already the C++ library and wxc are the C wrappers.

Guess I could change that to libD.wx.a, but it looks somewhat strange.

> Because C/++ don't have such a nice, structured package style, they 
> don't have a naming convention for library files (there really couldn't 
> be one), but I think that's a terrible reason to not use a naming 
> convention for D.  It would building, even against libraries, 
> ridiculously easy.

Actually I don't find it that hard, and e.g. the difference in
which flags to use between DMD and GDC to be more "trouble"...

--anders
September 19, 2006
Re: Proposal for a standard for D library naming
Gregor Richards wrote:

> Another reason for the D prefix is for bindings.  Many bindings will 
> have package names similar to their C library names - so similar in fact 
> that the names could overlap if there was nothing to uniquely identify 
> the D one.  And if the names overlapped, it would need to break the 
> naming convention, which would defeat the whole purpose of having a 
> naming convention in the first place :)

Yes, this is a very valid reason. I used a d suffix, for same reason.

--anders
September 19, 2006
Re: Proposal for a standard for D library naming
Anders F Björklund wrote:
> Gregor Richards wrote:
>>
>>
>> The entire idea behind my naming proposal is that it makes everything 
>> 100% computer and human generatable while adding very little 
>> confusion.  Having things named lib<name>.<extension> makes 
>> associating packages and libraries difficult.
> 
> 
> Think I missed the "auto-generated" part of the proposal... :-)
> 
> Currently I have the "wx" modules defined in a libwxd.a (or wxd.lib),
> partly since wx is already the C++ library and wxc are the C wrappers.
> 
> Guess I could change that to libD.wx.a, but it looks somewhat strange.
> 

Yes, but if you've ever seen the naming convention, it would be easily 
recognizeable.

Also, I wouldn't be particularly opposed to moving the 'D' to the end, I 
just think that makes the suffixing a but confusing *shrugs*


>> Because C/++ don't have such a nice, structured package style, they 
>> don't have a naming convention for library files (there really 
>> couldn't be one), but I think that's a terrible reason to not use a 
>> naming convention for D.  It would building, even against libraries, 
>> ridiculously easy.
> 
> 
> Actually I don't find it that hard, and e.g. the difference in
> which flags to use between DMD and GDC to be more "trouble"...
> 

Remember, the entire purpose of this is for a build tool (say, build) to 
conform to a standard.  Only the build tool needs to figure out the 
flags for DMD/GDC, the person compiling should get the libraries "for free."


> --anders

 - Gregor Richards
« First   ‹ Prev
1 2 3 4
Top | Discussion index | About this forum | D home