Repository navigation
documentation: tell users to link with -Wl,--gc-sections - #616
Merged
Merged
Conversation
Since #615 each backend archive is compiled with one section per procedure, but the docs never told users to link with --gc-sections. Without it a program that calls one rocBLAS routine links every rocBLAS wrapper, and a hipFORT newer than the installed ROCm fails every link of a library as soon as one wrapper names a routine that ROCm does not export. Explain this in using-hipfort, with the CMake form, the -Wl, spelling, and the shared-library case, and point to it from install, the README and the ROCm version of the interfaces.
…ipFORT's archive --exclude-libs,ALL hid the symbols of every static archive the shared library links, not only hipFORT's, and the note did not say that the wrappers stay in the library and keep working, only unexported. Name libhipfort-amdgcn.a and explain both.
amontoison
changed the title
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Since #615 each backend archive is compiled with one section per procedure, but nothing outside the CHANGELOG told users to link with
-Wl,--gc-sections. Each module compiles to one object and a linker takes whole objects from an archive, so without it:develop, derived from ROCm 10.1.0, built against an older 10.x) fails every link of a library as soon as one wrapper names a routine that ROCm does not export, whether or not the program calls it.Changes:
docs/how-to/using-hipfort.rst: new subsection "Linking only the routines you call", with the CMake form (target_link_options(... -Wl,--gc-sections)on non-Apple, non-Windows), why to spell it-Wl,rather thanLINKER:(CMake 3.27 passes the latter toamdflangbare), the command-line form, and, for a shared library,-Wl,--exclude-libs,libhipfort-amdgcn.a: the wrappers stay in the library and keep working, but are no longer exported, so--gc-sectionscan remove the unused ones. The "derived from ROCm 10.1.0" sentence now points to it.docs/install/install.rstandREADME.md: a short pointer in "Linking against hipFORT", and in the README's supported-API section.The option is documented, not added to the exported
hipfort::*targets: it would change the user's whole link, and does nothing for a shared library without--exclude-libs.Test plan
docs/how-toanddocs/install: no warning, and the:ref:frominstall.rstresolves to the new subsection.--gc-sectionsalone the link fails; with-Wl,--exclude-libs,<archive>it links, the used wrapper is called, and another archive's symbols stay exported; several archives separated by:also work.