Upgrading C++Builder 12.2: Tip #6, Handling Libraries with AutoLinking

Welcome to a series of tips and tricks for taking advantage of the new Windows 64-bit Modern toolchain in C++Builder / RAD Studio 12.2! This builds on a webinar we did sharing a bunch of useful information on why and how the new C++Builder matters to you, where this was the very end (so go watch the start!)

Tip #6: Handling Libraries with AutoLinking

Do you link libraries into your app like this screenshot?

It’s common to add a library (a .lib or .a file) to a project by adding it in the Projects view. Which makes sense to do! And this works fine, if you build for a single platform.

If you try to build for Win32 and Win64 at once, or are upgrading (say to the new Win64 Modern C++ toolchain, hint hint) then you’ll run into a problem. Libraries are very toolchain-dependent because they are a collection of object files. Win32 uses OMF format objects, legacy Win64 uses ELF64 format objects, and the spiffy new Win64 uses COFF format objects. You can’t use any of these with one of the other toolchains. And if you add both the 32-bit and 64-bit libraries to your project directly, one or other of the platforms will see a file it can’t handle.

So if you have MyLibrary.lib (Win32), MyLibrary.a (legacy Win64), and libMyLibrary.lib (possible new Win64 name, see below), how do you link the right one? All you want to do is link in a library. Shouldn’t be hard.

Enter — AUTOLINKING.

Auto-linking takes the stem of a library name (above, ‘MyLibrary’) and finds the right one and links to it. In code, add:
[crayon-675a41e280e95632424393/]
That’s it.

For Win32, it will look for MyLibrary.lib. For legacy Win64, it will look for MyLibrary.a. For the new Win64, it will actually look for multiple variants, because it knows it might be a normal static library, a DLL import library, a package import library, and might have .lib and .a suffixes and possibly a ‘lib’ prefix. That would be a lot to worry about yourself, but the new toolchain does it all for you and if anything matching that exists, it will find it and link it.

In the screenshot above, trying to link to “libvtkCommMath-9.3.dll.a”, for the new Win64 platform use
[crayon-675a41e280ea6981515425/]
The ‘lib’ prefix and ‘.dll.a’ suffix will be automatically checked for and found.

Fun fact: Auto-linking happens all the time under the hood: it’s how the right component packages are linked to (because packages are linked via a special form of library, a package import library, and as far as auto-linking is concerned a library is a library.) If you open a VCL header, you will see an auto-linking pragma in each file, causing a link to the package.

More fun fact: the new Win64 toolchain lets you directly link to a DLL without generating an import library first. Wow! See below…

Notes

In other words: remove library files from the Projects view; add in the #pragma comment(lib, “…”) statement in your source instead. I’d recommend putting it in a header you certainly use, or some other file you know for sure is linked in so that the linker will see the records this pragma emits. (You don’t want whereever this is located not to be used or regarded as requied by the compiler and thus not seen by the linker)

Avoid giving your libraries names with a three-letter extension, like ‘MyLibrary.abc’. It will see the ‘.abc’ and conclude it’s intended to be the file extension, and so will not test for similar names by adding ‘.lib’ etc.

You can also use #pragma link to link to object files. Usually you want a whole library.

Finally, don’t forget the documentation! Like many other pages it was updated for the new Win64 and explains the behaviour of auto-linking in full.

Bonus Magic: Linking Directly to DLLs!

Something very cool, and a completely new feature in this toolchain: it’s now much easier to link to DLLs.

In the past, for the entire lifetime of C++Builder, you ensured your app linked to a DLL by using a DLL import library. That’s a little miniature library that contains info about the methods in the DLL. It’s how it has always been done on Windows and is just ‘normal’ for many Windows developers.

Here’s the magic: now you can just link to the DLL itself.

• Make sure there’s a copy of the DLL on the Library search path
• Use either -lmydll or #pragma comment(lib, “mydll”)

That’s it. It will find the DLL and do all the magic of ensuring the methods in the DLL are required by your app without you needing to use an import library.