[RFC] LLD Deprecation policy

Hello everyone,

LLD is used by many projects, both upstream and downstream. Removing functionality, such as in ⚙ D119108 [ELF] Remove obscure -dp and GNU ld incompatible --[no-]define-common, ignore -d/-dc “Remove obscure -dp and GNU ld incompatible --[no-]define-common” has a non-zero risk of breaking projects. Whilst many open-source projects can be searched for use of options, there will be projects that are missed, including all downstream ones. Sometimes we get lucky and no-one is affected, in other cases there are projects that see their project fail to build when they take the next numbered release.

One possible way to handle this case is to adopt a deprecation policy for removed functionality. This policy would set out the actions that the LLD developers should take to inform the community and the user base about removal of functionality. Users would know what to expect from LLD, and the development team would not need to handle each removal request on an ad-hoc basis.

The LLD developers would like to get feedback from the community on what sort of deprecation policy LLD should have, if any? I volunteer to write up the consensus in the LLD documentation.

For what it is worth, my personal preference is:

  • Raise a github issue to advertise the change as more people will be monitoring than the code reviews.
  • Post on the llvm discourse linking the github issue.
  • Put an entry in the release notes advertising the deprecation and intent to remove.
  • Put a silenceable deprecated warning on use of the feature for the next numbered release, stating that the option will be removed in the next release.
  • Remove the feature in numbered release after next. For example deprecate in LLVM 15.0, remove in LLVM 16.0
  • When removing, if the functionality is not required for a correct link, for example it is an optimization, then set the option to silent ignore.

I think this should give enough notice to developers and users. What to do with the resulting feedback is another question which is much harder to put into a policy.

Peter

4 Likes

@MaskRay

Yeah, I tend to think having some amount of deprecation for command line compatibility’s reasonable (though, admittedly, I’ve taken a fairly relaxed stance to that for things like Clang warning flag names in the not-so-distant past, so I’m hardly entirely consistent in holding to that value) - probably reasonable for Clang and lld to have similar guarantees.

Thanks for raising the topic. I think the steps are great for some options, including -d, -dc (legacy, difficult to cause different observable behavior, used somewhere; we warned in release/14.x and ignored/removed in the main branch), and will likely include --warn-shared-textrel if we can remove the usage from projects.

I’ve taken a relaxed stance on (legacy&&likely unused || experimental) options when a silent ignore works and thought it’d be great we can still make changes without going through the process, e.g.

Some judgement call can be made.

  • When removing, if the functionality is not required for a correct link, for example it is an optimization, then set the option to silent ignore.

This is what I decide to do for .strtab deduplication (currently takes ~3% time without saving much space). The best I think I can do is to document that the optimization may go away in a future release ⚙ D119318 ReleaseNotes: add lld/ELF notes . It’s infeasible for a warning, though…