forked from OSchip/llvm-project
1d16515fb4
This patch implements a limited form of autolinking primarily designed to allow either the --dependent-library compiler option, or "comment lib" pragmas ( https://docs.microsoft.com/en-us/cpp/preprocessor/comment-c-cpp?view=vs-2017) in C/C++ e.g. #pragma comment(lib, "foo"), to cause an ELF linker to automatically add the specified library to the link when processing the input file generated by the compiler. Currently this extension is unique to LLVM and LLD. However, care has been taken to design this feature so that it could be supported by other ELF linkers. The design goals were to provide: - A simple linking model for developers to reason about. - The ability to to override autolinking from the linker command line. - Source code compatibility, where possible, with "comment lib" pragmas in other environments (MSVC in particular). Dependent library support is implemented differently for ELF platforms than on the other platforms. Primarily this difference is that on ELF we pass the dependent library specifiers directly to the linker without manipulating them. This is in contrast to other platforms where they are mapped to a specific linker option by the compiler. This difference is a result of the greater variety of ELF linkers and the fact that ELF linkers tend to handle libraries in a more complicated fashion than on other platforms. This forces us to defer handling the specifiers to the linker. In order to achieve a level of source code compatibility with other platforms we have restricted this feature to work with libraries that meet the following "reasonable" requirements: 1. There are no competing defined symbols in a given set of libraries, or if they exist, the program owner doesn't care which is linked to their program. 2. There may be circular dependencies between libraries. The binary representation is a mergeable string section (SHF_MERGE, SHF_STRINGS), called .deplibs, with custom type SHT_LLVM_DEPENDENT_LIBRARIES (0x6fff4c04). The compiler forms this section by concatenating the arguments of the "comment lib" pragmas and --dependent-library options in the order they are encountered. Partial (-r, -Ur) links are handled by concatenating .deplibs sections with the normal mergeable string section rules. As an example, #pragma comment(lib, "foo") would result in: .section ".deplibs","MS",@llvm_dependent_libraries,1 .asciz "foo" For LTO, equivalent information to the contents of a the .deplibs section can be retrieved by the LLD for bitcode input files. LLD processes the dependent library specifiers in the following way: 1. Dependent libraries which are found from the specifiers in .deplibs sections of relocatable object files are added when the linker decides to include that file (which could itself be in a library) in the link. Dependent libraries behave as if they were appended to the command line after all other options. As a consequence the set of dependent libraries are searched last to resolve symbols. 2. It is an error if a file cannot be found for a given specifier. 3. Any command line options in effect at the end of the command line parsing apply to the dependent libraries, e.g. --whole-archive. 4. The linker tries to add a library or relocatable object file from each of the strings in a .deplibs section by; first, handling the string as if it was specified on the command line; second, by looking for the string in each of the library search paths in turn; third, by looking for a lib<string>.a or lib<string>.so (depending on the current mode of the linker) in each of the library search paths. 5. A new command line option --no-dependent-libraries tells LLD to ignore the dependent libraries. Rationale for the above points: 1. Adding the dependent libraries last makes the process simple to understand from a developers perspective. All linkers are able to implement this scheme. 2. Error-ing for libraries that are not found seems like better behavior than failing the link during symbol resolution. 3. It seems useful for the user to be able to apply command line options which will affect all of the dependent libraries. There is a potential problem of surprise for developers, who might not realize that these options would apply to these "invisible" input files; however, despite the potential for surprise, this is easy for developers to reason about and gives developers the control that they may require. 4. This algorithm takes into account all of the different ways that ELF linkers find input files. The different search methods are tried by the linker in most obvious to least obvious order. 5. I considered adding finer grained control over which dependent libraries were ignored (e.g. MSVC has /nodefaultlib:<library>); however, I concluded that this is not necessary: if finer control is required developers can fall back to using the command line directly. RFC thread: http://lists.llvm.org/pipermail/llvm-dev/2019-March/131004.html. Differential Revision: https://reviews.llvm.org/D60274 llvm-svn: 360984 |
||
|---|---|---|
| .. | ||
| AMDGPU | ||
| CommandGuide | ||
| Frontend | ||
| HistoricalNotes | ||
| PDB | ||
| Proposals | ||
| TableGen | ||
| _ocamldoc | ||
| _static | ||
| _templates | ||
| _themes/llvm-theme | ||
| tutorial | ||
| AMDGPUInstructionNotation.rst | ||
| AMDGPUInstructionSyntax.rst | ||
| AMDGPUModifierSyntax.rst | ||
| AMDGPUOperandSyntax.rst | ||
| AMDGPUUsage.rst | ||
| ARM-BE-bitcastfail.png | ||
| ARM-BE-bitcastsuccess.png | ||
| ARM-BE-ld1.png | ||
| ARM-BE-ldr.png | ||
| AddingConstrainedIntrinsics.rst | ||
| AdvancedBuilds.rst | ||
| AliasAnalysis.rst | ||
| Atomics.rst | ||
| Benchmarking.rst | ||
| BigEndianNEON.rst | ||
| BitCodeFormat.rst | ||
| BlockFrequencyTerminology.rst | ||
| BranchWeightMetadata.rst | ||
| BugLifeCycle.rst | ||
| Bugpoint.rst | ||
| CFIVerify.rst | ||
| CMake.rst | ||
| CMakeLists.txt | ||
| CMakePrimer.rst | ||
| CodeGenerator.rst | ||
| CodeOfConduct.rst | ||
| CodingStandards.rst | ||
| CommandLine.rst | ||
| CompileCudaWithLLVM.rst | ||
| CompilerWriterInfo.rst | ||
| Contributing.rst | ||
| Coroutines.rst | ||
| CoverageMappingFormat.rst | ||
| DebuggingJITedCode.rst | ||
| DeveloperPolicy.rst | ||
| Docker.rst | ||
| ExceptionHandling.rst | ||
| ExtendedIntegerResults.txt | ||
| ExtendingLLVM.rst | ||
| Extensions.rst | ||
| FAQ.rst | ||
| FaultMaps.rst | ||
| FuzzingLLVM.rst | ||
| GarbageCollection.rst | ||
| GetElementPtr.rst | ||
| GettingStarted.rst | ||
| GettingStartedVS.rst | ||
| GlobalISel.rst | ||
| GoldPlugin.rst | ||
| HowToAddABuilder.rst | ||
| HowToBuildOnARM.rst | ||
| HowToBuildWithPGO.rst | ||
| HowToCrossCompileBuiltinsOnArm.rst | ||
| HowToCrossCompileLLVM.rst | ||
| HowToReleaseLLVM.rst | ||
| HowToSetUpLLVMStyleRTTI.rst | ||
| HowToSubmitABug.rst | ||
| HowToUseAttributes.rst | ||
| HowToUseInstrMappings.rst | ||
| InAlloca.rst | ||
| LLVMBuild.rst | ||
| LLVMBuild.txt | ||
| LangRef.rst | ||
| Lexicon.rst | ||
| LibFuzzer.rst | ||
| LinkTimeOptimization.rst | ||
| MCJIT-creation.png | ||
| MCJIT-dyld-load.png | ||
| MCJIT-engine-builder.png | ||
| MCJIT-load-object.png | ||
| MCJIT-load.png | ||
| MCJIT-resolve-relocations.png | ||
| MCJITDesignAndImplementation.rst | ||
| MIRLangRef.rst | ||
| Makefile.sphinx | ||
| MarkdownQuickstartTemplate.md | ||
| MarkedUpDisassembly.rst | ||
| MeetupGuidelines.rst | ||
| MemorySSA.rst | ||
| MergeFunctions.rst | ||
| NVPTXUsage.rst | ||
| OptBisect.rst | ||
| Packaging.rst | ||
| Passes.rst | ||
| Phabricator.rst | ||
| ProgrammersManual.rst | ||
| Projects.rst | ||
| README.txt | ||
| ReleaseNotes.rst | ||
| ReleaseProcess.rst | ||
| ReportingGuide.rst | ||
| ScudoHardenedAllocator.rst | ||
| SegmentedStacks.rst | ||
| SourceLevelDebugging.rst | ||
| SpeculativeLoadHardening.md | ||
| SphinxQuickstartTemplate.rst | ||
| StackMaps.rst | ||
| StackSafetyAnalysis.rst | ||
| Statepoints.rst | ||
| SupportLibrary.rst | ||
| SystemLibrary.rst | ||
| TableGenFundamentals.rst | ||
| TestSuiteGuide.md | ||
| TestSuiteMakefileGuide.rst | ||
| TestingGuide.rst | ||
| TransformMetadata.rst | ||
| TypeMetadata.rst | ||
| Vectorizers.rst | ||
| WritingAnLLVMBackend.rst | ||
| WritingAnLLVMPass.rst | ||
| XRay.rst | ||
| XRayExample.rst | ||
| XRayFDRFormat.rst | ||
| YamlIO.rst | ||
| conf.py | ||
| doxygen-mainpage.dox | ||
| doxygen.cfg.in | ||
| gcc-loops.png | ||
| index.rst | ||
| linpack-pc.png | ||
| llvm-objdump.1 | ||
| make.bat | ||
| re_format.7 | ||
| speculative_load_hardening_microbenchmarks.png | ||
| yaml2obj.rst | ||
README.txt
LLVM Documentation
==================
LLVM's documentation is written in reStructuredText, a lightweight
plaintext markup language (file extension `.rst`). While the
reStructuredText documentation should be quite readable in source form, it
is mostly meant to be processed by the Sphinx documentation generation
system to create HTML pages which are hosted on <http://llvm.org/docs/> and
updated after every commit. Manpage output is also supported, see below.
If you instead would like to generate and view the HTML locally, install
Sphinx <http://sphinx-doc.org/> and then do:
cd <build-dir>
cmake -DLLVM_ENABLE_SPHINX=true -DSPHINX_OUTPUT_HTML=true <src-dir>
make -j3 docs-llvm-html
$BROWSER <build-dir>/docs//html/index.html
The mapping between reStructuredText files and generated documentation is
`docs/Foo.rst` <-> `<build-dir>/docs//html/Foo.html` <-> `http://llvm.org/docs/Foo.html`.
If you are interested in writing new documentation, you will want to read
`SphinxQuickstartTemplate.rst` which will get you writing documentation
very fast and includes examples of the most important reStructuredText
markup syntax.
Manpage Output
===============
Building the manpages is similar to building the HTML documentation. The
primary difference is to use the `man` makefile target, instead of the
default (which is `html`). Sphinx then produces the man pages in the
directory `<build-dir>/docs/man/`.
cd <build-dir>
cmake -DLLVM_ENABLE_SPHINX=true -DSPHINX_OUTPUT_MAN=true <src-dir>
make -j3 docs-llvm-man
man -l >build-dir>/docs/man/FileCheck.1
The correspondence between .rst files and man pages is
`docs/CommandGuide/Foo.rst` <-> `<build-dir>/docs//man/Foo.1`.
These .rst files are also included during HTML generation so they are also
viewable online (as noted above) at e.g.
`http://llvm.org/docs/CommandGuide/Foo.html`.
Checking links
==============
The reachability of external links in the documentation can be checked by
running:
cd docs/
make -f Makefile.sphinx linkcheck
Doxygen page Output
==============
Install doxygen <http://www.stack.nl/~dimitri/doxygen/download.html> and dot2tex <https://dot2tex.readthedocs.io/en/latest>.
cd <build-dir>
cmake -DLLVM_ENABLE_DOXYGEN=On <llvm-top-src-dir>
make doxygen-llvm # for LLVM docs
make doxygen-clang # for clang docs
It will generate html in
<build-dir>/docs/doxygen/html # for LLVM docs
<build-dir>/tools/clang/docs/doxygen/html # for clang docs