The Design of Software (CLOSED)

A public forum for discussing the design of software, from the user interface to the code architecture. Now closed.

The "Design of Software" discussion group has been merged with the main Joel on Software discussion group.

The archives will remain online indefinitely.

Library filename convention


I would like to have your opinion on the following filename convention for libraries:

1) ProjectName-CompilerName-PlatformName-BuildType
\-> example: jace-vc90-win64-debug.dll

2) CompilerName/PlatformName/BuildType/ProjectName
\-> example: vc90/win64/debug/jace.dll

What are the benefits/problems with each convention?

Thank you,
Gili Send private email
Sunday, September 07, 2008
By the way, this same question also applies to whether you should add a version number as part of the library name versus omitting it.

Here is what I've seen so far:

Approach #1
- Multiple builds can coexist in the same directory
- Easy to identify what version you're using at runtime

- Difficult to "troubleshoot in the field": can't swap libraries after they've been compiled. Meaning you can't replace a release library with a debug one at runtime if you want to troubleshoot a problem.
\-> Question: is this even technically possible given the fact that you're mixing different MSVCRT libraries?

- This complicates Java libraries quite a bit, because now they have to calculate the library name at runtime versus simply invoking System.loadLibrary("jace")

Approach #2:
- Great for "troubleshooting in the field": can swap libraries at runtime (discussed above)
- Easy to load under Java regardless of what build you use: System.loadLibrary("jace")

- Difficult to identify what build your code depends on
- Files are scattered across multiple directories which makes them harder to operate on (deployment, etc)

Please let me know what you think!

Thank you,
Gili Send private email
Sunday, September 07, 2008
Personally I definitely like #1 more, because it's harder to link with the wrong thing, and you can tell later what DLL you're dealing with, just by looking at the file name. (This will seem like a complete non-issue until one day when you spend half an hour getting things confused because you got two files with the same name mixed up. You will feel perhaps a bit stupid afterwards, or at least I did anyway, and almost certainly feel as if your time was wasted...)

If you want to mix'n'match your DLLs at runtime, an environment variable/command line option/debug option in the GUI/etc. (whichever is most convenient) will usually sort this out. That's what I do, anyway, and I've found it to work well.

If you're switching between release DLLs and debug DLLs (etc.), the runtime library being used is a potential issue. For my part, as I've been bitten in the past by having to work around this kind of rubbish, my DLLs only ever expose C structs and functions and are anal about object ownership. I've found this to be entirely reliable, if a bit annoying to program.

I hear that modern versions of VC++ are better at this kind of thing, haven't tried it myself yet though...

Sunday, September 07, 2008
My ignorant opinion is that it's best simply to name the library by its function: Jace.dll.

If you include processor/version/etc. information, you have correctly said that you have to decide at runtime which library to call.  The "con" to naming it "jace.dll" is that it's easier to confuse version numbers but it's very easy to code "greater than or equal to" logic into your app so you basically have the same challenge with either scheme: do I determine at runtime whether the .dll version number is right, or do I determine at runtime whether the library exists?

Since you should be determining at runtime whether it exists anyway in order to gracefully exit if it does not, adding the "is it the right version?" code becomes trivial.

The upside to using "jace.dll" vs. a dependent naming scheme is that your code is simpler.

You can also place tags into the .dll so a function in your app can easily return the processor information on the fly, making it relatively simple to troubleshoot.
Karl Perry Send private email
Sunday, September 07, 2008
Is there a way to embed meta-data into DLLs (such as File Properties -> Details -> File Version under Windows) on a cross-platform basis (including *nix)?

Karl, say I use "jace.dll" how would verify at runtime if the DLL version number is right? Do I just make up my own convention or is there an existing way to do this?
Gili Send private email
Sunday, September 07, 2008
If you can ship it locally with the exe, then the unadorned name makes sense.  Those should also be the ones that might need loading dynamically.  (Plugins, for example.)

But if you're going to put it in a system location of some kind, it at very least needs the version of the internal ABI.

Depending on the language, it makes sense to add other things as well. x86 vs x86_64, debug runtime vs release runtime, stlport vs dinkumware, etc.
Rob Send private email
Sunday, September 07, 2008

I think the only reason system DLLs are all decorated is because until recently the Microsoft convention was dumping all DLLs into System32. My understanding is that this is no longer the case with so-called "shared assemblies" and that you could have multiple libraries with the same name and the system will be smart enough to pick the right version (debug or release and a specific version number) based on your request. I have no idea how this compares to the *nix world...
Gili Send private email
Sunday, September 07, 2008
On Windows
DLLs that are COM/ActiveX objects can't have multiple copies on the same system, only the last registered one will be used. So a unique simple name is logic. Fortunately our libraries are not of that type.

.NET DLLs are strictly automatically linked to the compiled program using it. In other words Windows automatically make a lot of copies and they have all the same DLL name. I'm happy to not work much with .NET.

classic DLLs are searched in the application folder and system path, different names have a sense especially if they aren't binary compatible for any reason. I prefer to have my DLLs in the application folder, and a program that doesnt need any registration. Just folder copy allow the application copy and this is useful for making it Pen Drive Compatible. If the library is in my local folder then it was distributed with the application, so it is supposed to be compatible and no problems should be there using a unique simple name. If I need to do any testing I just copy there another version.

But if I have the unlucky wish to install my DLL in the system folder, making it shareable to many different applications then much care must be taken when releasing new versions. Binary compatibility with older applications must be warranted for maintaining the same file name, else a different name should be used.

Andrea Denzler Send private email
Monday, September 08, 2008
Certainly, what convention you use is dependent on whether multiple versions can exist in the same "directory".

It's possible that "compiler" as a separate attribute. If you need to distinguish the compiler, just change something else.

I've used type-project-version. "type" includes debug/release and platform/compliler.

I only change version when the library interface changes. If I change the version, I'm also working on phasing out the old (prior) version.

It's a nuisance to the users of the libraries if they have to keep changing their build process to accommodate changes in library names.

The library users don't typically care what compiler is used (as long as it works).
somebody else
Monday, September 08, 2008
It's possible that "compiler" as a separate attribute, isn't really necessary.
somebody else
Monday, September 08, 2008
Sure, the compiler is a necessary attribute.

If your executable was built with Visual Studio but someone builds a DLL with GCC or Borland's C++ Builder then noone will ever make them work together.

Basically, include anything that you think might realistically change and could realistically introduce incompatabilities that are more trouble than they're worth.

If this is an in-house-only thing, then the compiler issue may not matter. If you think you'll ever let third parties build DLLs, without giving them your complete source code, you need to make it easy to not screw up.

And therefore the release/debug tag is affected more by which run-time libraries you link to than by whether or not you're including debugging information and enabling or disabling the omptimiser. The run-time libraries affect compatability, the debugging info is just useful for yourself. And on Windows at least you can have a version information resource that includes as much additional data as you'ld like.

Also, on Windows, I believe that the delay load DLL feature lets you handle DLL loading features by selecting a different DLL to load. So you could build a system to let you selectively upgrade DLLs without changing the host application. it would be awkward though, of course.

Monday, September 08, 2008
What I said: "It's possible that "compiler" as a separate attribute, isn't really necessary.

That doesn't mean you should never include the compiler.


"If your executable was built with Visual Studio but someone builds a DLL with GCC or Borland's C++ Builder then noone will ever make them work together."

If this is common and you needed to support different compilers, distinguishing the compiler would make sense. (You should have be a good reason to support all that complexity.)

If it isn't common, you could include the distinction along with the platform.


"If this is an in-house-only thing, then the compiler issue may not matter."

    Here, you're saying "It is not necessary".

"Sure, the compiler is a necessary attribute."

    Here, you're saying: "It is necessary."

A contradiction.
somebody else
Tuesday, September 09, 2008
Good points all around.

Is there a way to retain the simplicity of simple naming (i.e. jace.dll) while making the contents easy to identify, even on Unix? I could always document exported symbols which identify the DLL but of course this isn't as easy to use as a "File -> Properties" dialog. Any ideas?
Gili Send private email
Wednesday, September 10, 2008
Either a contradiction, or perhaps the use of the word "if" sugegsts that in reality "it depends" is the only correct answer for all circumstances.

Wednesday, September 10, 2008
"Either a contradiction, or perhaps the use of the word "if" sugegsts that in reality "it depends" is the only correct answer for all circumstances."

No "if" in the second comment (which was pretty absolute).

"Depends" is correct but doesn't give any useful hints.

One thing I have seen is that people don't think of simplifying things to what they need. One thing to concider is reducing the number of libs to support and make sure you have a plan to phase-out obsolete versions.

Wednesday, September 10, 2008

This topic is archived. No further replies will be accepted.

Other recent topics Other recent topics
Powered by FogBugz