Gnu bintools - llvm bintools migration guide

Hi,

is there a doc/migration guide from GNU bintools to llvm bintools?
which features is supported/not supported/changed etc?
also in regarud for linker script file foramt printing of disasm and more.
I have found this link ( LLVM Command Guide — LLVM 15.0.0git documentation ) that maps llvm tool to gcc tool but I wondered if there is a guide that help users with the migration.

Thanks,
David

I am not aware of such guide. But it seems like something that might be good to have - so if it’s something you want to start, I’ll be happy to review and help out with comments.

1 Like

There was a distinct effort some years ago to get the llvm bintools to accept the GNU options, @jh7370 might remember the details more clearly. I agree that a doc would be helpful to users, if we can manage to keep it up-to-date as things change.

For the most part, if an option is present in the GNU binutils, the equivalent LLVM tool should also have that option, and in general, it should do the same thing. There are a few cases where we’ve chosen to diverge (e.g. llvm-readelf has a --wide option, but it is silently ignored, because llvm-readelf always prints in “wide” format), but we still try to remain command-line compatible. Whilst a lot of work has gone into adding options that are present in GNU to the LLVM tools, there are likely some that are missing, and could be added by an interested developer. I can’t give a complete list of those options, as it’s a bit of a moving target (GNU add options which we may not yet have added, or we might have added options since the last time I checked).

My above paragraph is about the “small” tools that form most of the binutils. It specifically does not talk about the linker. LLD (the LLVM linker) is intended to be a drop-in replacement for GNU ld.bfd, but I don’t know exactly how compatible it is in various ways. @MaskRay would be better placed to explain any known differences (see also https://lld.llvm.org/ and its referenced pages for a wider discussion of LLD).

I’d be happy to review any new documentation, but I don’t have the time to write it from scratch myself.

When testing out switching to the LLVM tools, there was one noticeable difference. The tools themselves worked basically the same, but the one difference was when it came to handling symlinks. NOTE: File was already stripped so the time but not size changes.

    16 Jun 15 18:32 libzstd.so.1 -> libzstd.so.1.5.2
710832 Jun 15 18:32 libzstd.so.1.5.2

strip --strip-unneeded libzstd.so.1 would follow the symlink to libzstd.so.1.5.2, strip the file and output it to libzstd.so.1.5.2.

    16 Jun 15 18:32 libzstd.so.1 -> libzstd.so.1.5.2
710832 Jun 15 18:34 libzstd.so.1.5.2

llvm-strip --strip-unneeded libzstd.so.1 would follow the symlink to libzstd.so.1.5.2, strip the file BUT output it to libzstd.so.1. Here you would essentially duplicate the file and overwrite the symlink.

710832 Jun 15 18:43 libzstd.so.1
710832 Jun 15 18:32 libzstd.so.1.5.2

This is quite an important difference. So only run the LLVM tools on the actual files and not the symlinks! Have no preference to either behaviour as proper tooling shouldn’t attempt to run it on symlinks.

My feeling is that there isn’t a strong enough need to have a migration guide from GNU binutils to LLVM binary utilities. LLVM Command Guide has good enough description on implemented options. Their behaviors are very similar to GNU binutils’. GNU binutils has some options we don’t/haven’t implement. We can add options as needed but it doesn’t seem necessary to list what we don’t have.

llvm-objdump’s disassembly has quite a bit noticeable format difference from GNU objdump, but I don’t know whether it’s something worth documenting.


For GNU ld vs ld.lld, I have a post LLD and GNU linker incompatibilities | MaskRay . It gives me freedom to update it and I occasionally add items as I notice new differences:) It’s quite discoverable (“lld BFD difference” “lld GNU ld difference” on Google search will find it). If it is a doc in the llvm-project repository, I’d feel bad if I push a commit just to adjust some minor things.