llvm-project/llvm/docs
Martin Storsjö c5b3de6745 [COFF] Emit embedded -exclude-symbols: directives for hidden visibility for MinGW
This works with the automatic export of all symbols; in MinGW mode,
when a DLL has no explicit dllexports, it exports all symbols (except
for some that are hardcoded to be excluded, including some toolchain
libraries).

By hooking up the hidden visibility to the -exclude-symbols: directive,
the automatic export of all symbols can be controlled in an easier
way (with a mechanism that doesn't require strict annotation of every
single symbol, but which allows gradually marking more unnecessary
symbols as hidden).

The primary use case is dylib builds of LLVM/Clang. These can be done
in MinGW mode but not in MSVC mode, as MinGW builds can export all
symbols (and the calling code can use APIs without corresponding
dllimport directives). However, as all symbols are exported, it can
easily overflow the max number of exported symbols in a DLL (65536).

In the llvm-mingw distribution, only the X86, ARM and AArch64 backends
are enabled; for the LLVM 13.0.0 release, libLLVM-13.dll ended up with
58112 exported symbols. For LLVM 14.0.0, it was 62015 symbols. Current
builds of the 15.x branch end up at around 64650 symbols - i.e. extremely
close to the limit.

The msys2 packages of LLVM have had to progressively disable more
of their backends in their builds, to be able to keep building with a
dylib.

This allows improving the current mingw dylib situation significantly,
by using the same hidden visibility options and attributes as on Unix.
With those in place, a current build of LLVM git main ends up at 35142
symbols instead of 64650.

For code using hidden visibility, this now requires linking with either
a current git lld or ld.bfd. (Older lld error out on the unknown
directives, older ld.bfd will successfully link, but will print huge
amounts of warnings.)

Differential Revision: https://reviews.llvm.org/D130121
2022-08-11 12:00:08 +03:00
..
AMDGPU [AMDGPU][GFX940][DOC][NFC] Update assembler syntax description 2022-08-01 16:34:45 +03:00
AMDGPUDwarfExtensionAllowLocationDescriptionOnTheDwarfExpressionStack [AMDGPU][NFC] Update DWARF extension allowing locations on stack 2021-12-28 17:12:20 +00:00
CommandGuide [Symbolizer] Implement pc element in symbolizing filter. 2022-08-08 11:08:48 -07:00
DependenceGraphs [NFC] Trim trailing whitespace in *.rst 2021-11-15 09:17:08 +08:00
Frontend [docs] fix typo 2022-02-20 18:43:30 +00:00
GlobalISel GlobalISel: Allow forming atomic/volatile G_ZEXTLOAD 2022-07-08 11:55:08 -04:00
HistoricalNotes
PDB [PDB] Add char8_t type 2022-03-01 13:39:51 -08:00
Proposals Move LLVM Proposal to doc directory, create index 2022-01-29 00:29:31 +00:00
TableGen [TableGen] Add new operator !exists 2022-06-23 11:11:47 +08:00
_ocamldoc
_static [docs] Add Loop Opt WG meeting ics. 2022-04-04 20:07:51 -05:00
_templates
_themes/llvm-theme
tutorial Added warning about outdated feature into Kaleidoscope tutorial text 2022-08-07 14:37:05 +05:30
AMDGPUDwarfExtensionsForHeterogeneousDebugging.rst [AMDGPU][NFC] Correct typo in DWARF Extensions For Heterogeneous Debugging 2022-06-24 11:05:08 +05:30
AMDGPUInstructionNotation.rst [AMDGPU][MC][NFC][DOC] Updated AMD GPU assembler syntax description. 2021-08-27 17:23:20 +03:00
AMDGPUInstructionSyntax.rst [AMDGPU][DOC][NFC] Added GFX1030 assembler syntax description 2022-03-25 18:14:04 +03:00
AMDGPUModifierSyntax.rst [AMDGPU][GFX9][DOC][NFC] Update assembler syntax description 2022-06-27 14:03:58 +03:00
AMDGPUOperandSyntax.rst [AMDGPU][MC][NFC][DOC] Updated description of registers 2021-09-03 13:09:54 +03:00
AMDGPUUsage.rst [AMDGPU] Add the uses_dynamic_stack field to the kernel descriptor and the kernel metadata map 2022-07-18 10:07:13 +05:30
ARM-BE-bitcastfail.png
ARM-BE-bitcastsuccess.png
ARM-BE-ld1.png
ARM-BE-ldr.png
AddingConstrainedIntrinsics.rst
AdvancedBuilds.rst [CMake] Make omitting CMAKE_BUILD_TYPE an error 2022-05-04 14:01:33 +02:00
AliasAnalysis.rst [NFC] Trim trailing whitespace in *.rst 2021-11-15 09:17:08 +08:00
Atomics.rst [RISCV] Add target feature to force-enable atomics 2022-08-09 16:04:46 +02:00
Benchmarking.rst
BigEndianNEON.rst [NFC] Trim trailing whitespace in *.rst 2021-11-15 09:17:08 +08:00
BitCodeFormat.rst [gold] Ignore bitcode from sections inside object files 2022-07-14 14:46:15 -07:00
BlockFrequencyTerminology.rst
BranchWeightMetadata.rst
BugLifeCycle.rst Fix "the the" typo in documentation and user facing strings 2022-05-05 17:52:08 +02:00
Bugpoint.rst
BugpointRedesign.md
BuildingADistribution.rst [cmake] Loosen multi-distribution restrictions 2022-04-13 20:33:28 -07:00
CFIVerify.rst
CMake.rst [llvm][cmake] Follow up to D117973 2022-07-26 14:51:12 +00:00
CMakeLists.txt
CMakePrimer.rst
CodeGenerator.rst [docs] Remove unmaintained target feature matrix 2022-07-18 18:38:23 +01:00
CodeOfConduct.rst Add transparency report. 2022-05-02 16:29:38 -07:00
CodeReview.rst [docs] Set Phabricator as the tool for pre-commit reviews 2021-06-07 11:50:52 -05:00
CodingStandards.rst [LLVM] Update C++ standard to 17 2022-08-06 09:42:10 +02:00
CommandLine.rst Remove unneeded cl::ZeroOrMore for cl::list options 2022-06-04 23:51:13 -07:00
CompileCudaWithLLVM.rst [CUDA] Bump supported CUDA version to 11.5 2021-11-09 08:20:53 +00:00
CompilerWriterInfo.rst [SPIR-V](1/6) Add stub for SPIRV backend 2022-04-20 01:10:25 +02:00
Contributing.rst [docs] Move code contribution from GettingStarted.rst to Contributing.rst 2022-07-07 10:51:20 -07:00
Coroutines.rst Revert "Don't treat readnone call in presplit coroutine as not access memory" 2022-07-20 17:00:58 +08:00
CoverageMappingFormat.rst [Coverage] Store compilation dir separately in coverage mapping 2021-02-18 14:34:39 -08:00
CycleTerminology.rst [Docs] Improve cycle and closed path definitions 2022-08-03 10:28:13 +02:00
DebuggingJITedCode.rst [NFC] Trim trailing whitespace in *.rst 2021-11-15 09:17:08 +08:00
DeveloperPolicy.rst Revise outdated parts of the developer policy. 2022-07-04 07:05:29 +01:00
DirectXUsage.rst [docs] Adding DirectX target usage doc 2022-06-17 13:34:25 -05:00
DiscourseMigrationGuide.md Update status on migration again. Add note about issues with reply by email from emails pre-migration. 2022-02-01 22:25:31 -08:00
Docker.rst [Dockerfile] Upgrade debian base image to version 10 2022-03-23 15:32:15 +00:00
ExceptionHandling.rst
ExtendedIntegerResults.txt
ExtendingLLVM.rst Replace links to archived mailing lists by links to Discourse forums 2022-03-23 10:10:20 -04:00
Extensions.rst [Object] Add ELF section type for offloading objects 2022-07-07 12:20:30 -04:00
FAQ.rst Update references to 'master' branch. 2020-12-21 19:10:34 +00:00
FaultMaps.rst [NFC] Trim trailing whitespace in *.rst 2021-11-15 09:17:08 +08:00
FuzzingLLVM.rst [lldb] Add a fuzzer for target creation 2022-03-25 09:34:00 -07:00
GarbageCollection.rst [MC] De-capitalize SwitchSection. NFC 2022-06-10 22:50:55 -07:00
GetElementPtr.rst [Docs] Update GEP docs for opaque pointers 2022-07-25 09:52:14 +02:00
GettingInvolved.rst [Docs] Added my office hours 2022-08-04 15:20:06 +02:00
GettingStarted.rst [docs] Move code contribution from GettingStarted.rst to Contributing.rst 2022-07-07 10:51:20 -07:00
GettingStartedTutorials.rst [docs] Add a new tutorial that talk about how to make a change to llvm 2021-08-30 07:01:04 +00:00
GettingStartedVS.rst Raise the minimum Visual Studio version to VS2019 2022-01-29 10:56:41 +00:00
GitBisecting.rst [NFC] Trim trailing whitespace in *.rst 2021-11-15 09:17:08 +08:00
GitHub.rst docs: Update instructions for requesting backports to the release branches 2022-03-08 16:28:02 -08:00
GitRepositoryPolicy.md first draft of a written policy around git repos 2021-10-19 08:05:37 +00:00
GoldPlugin.rst [gold] Ignore bitcode from sections inside object files 2022-07-14 14:46:15 -07:00
GwpAsan.rst
HowToAddABuilder.rst [docs] Update new builder instructions to starting on the staging buildmaster 2021-12-22 18:21:17 -08:00
HowToBuildOnARM.rst Remove Python2 fallback and only advertise Python3 in the doc 2020-12-17 15:40:16 +01:00
HowToBuildWindowsItaniumPrograms.rst [NFC] Trim trailing whitespace in *.rst 2021-11-15 09:17:08 +08:00
HowToBuildWithPGO.rst docs: Add pointer to cmake caches for PGO 2020-12-07 15:55:26 -05:00
HowToCrossCompileBuiltinsOnArm.rst [test] Migrate -gcc-toolchain with space separator to --gcc-toolchain= 2021-08-20 15:24:58 -07:00
HowToCrossCompileLLVM.rst [CMake] Make omitting CMAKE_BUILD_TYPE an error 2022-05-04 14:01:33 +02:00
HowToReleaseLLVM.rst Update references to mailing lists that have moved to Discourse. 2022-07-28 16:54:58 -07:00
HowToSetUpLLVMStyleRTTI.rst [docs] Fix style and typo in HowToSetUpLLVMStyleRTTI.rst after D126943 2022-06-06 12:41:21 -07:00
HowToSubmitABug.rst docs: update some bug tracker references (NFC) 2022-01-10 15:59:08 -08:00
HowToUpdateDebugInfo.rst [Debugify] Limit number of processed functions for original mode 2022-04-21 13:58:17 +02:00
HowToUseAttributes.rst
HowToUseInstrMappings.rst
InAlloca.rst
InstrRefDebugInfo.md [DebugInfo][Docs] Improve code formatting in instruction referencing doc 2022-06-07 13:18:12 +02:00
JITLink.rst Fix some typos in the llvm docs 2021-08-31 21:31:20 +02:00
LangRef.rst [InstrProf] Add the skipprofile attribute 2022-08-04 08:45:27 -07:00
Lexicon.rst [docs][Lexicon] Add new explanation for some shortcomings(WPD, CFI) for lexicon 2022-03-28 12:46:28 +08:00
LibFuzzer.rst [libFuzzer] Extend the fuzz target intarface to allow -1 return value. 2022-06-30 13:21:27 -07:00
LinkTimeOptimization.rst
LoopTerminology.rst [docs] Update LoopTerminology. 2022-03-29 23:26:18 -05:00
MCJIT-creation.png
MCJIT-dyld-load.png
MCJIT-engine-builder.png
MCJIT-load-object.png
MCJIT-load.png
MCJIT-resolve-relocations.png
MCJITDesignAndImplementation.rst [NFC] Trim trailing whitespace in *.rst 2021-11-15 09:17:08 +08:00
MIRLangRef.rst [DebugInfo][NFC] Add instr-ref documentation, migration guide 2022-05-20 14:13:46 +01:00
MarkdownQuickstartTemplate.md [doc] added section on generating the html doc 2021-08-09 07:27:56 +00:00
MarkedUpDisassembly.rst
MeetupGuidelines.rst
MemTagSanitizer.rst
MemorySSA.rst [Docs] Fix reference (NFC) 2022-03-21 10:06:27 +01:00
MergeFunctions.rst [llvm] Fix typos in documentation (NFC) 2021-02-27 10:09:23 -08:00
MisExpect.rst [misexpect] Re-implement MisExpect Diagnostics 2022-04-19 21:23:48 +00:00
MyFirstTypoFix.rst [docs] Update outdated mentions of lab.llvm.org:8011. 2021-11-18 10:51:47 +00:00
NVPTXUsage.rst [NFC] Trim trailing whitespace in *.rst 2021-11-15 09:17:08 +08:00
NewPassManager.rst [docs][NewPM] Add more info on why accessing mutable outer analyses is disallowed 2022-06-23 10:05:37 -07:00
ORCv2.rst [docs][ORC] Fix RST error in dfffb7df24. 2022-04-12 16:06:11 -07:00
OpaquePointers.rst [docs] Fix typo 2022-06-17 11:29:07 -07:00
OptBisect.rst
Packaging.rst
Passes.rst Reland "Lower `@llvm.global_dtors` using `__cxa_atexit` on MachO" 2022-03-23 18:36:55 -07:00
Phabricator.rst [llvm][docs] commit phabricator patch 2022-07-11 12:33:57 -07:00
Phabricator_premerge_results.png [doc] added documentation for pre-merge testing 2021-04-27 16:53:16 +02:00
Phabricator_premerge_unit_tests.png [doc] added documentation for pre-merge testing 2021-04-27 16:53:16 +02:00
PointerAuth.md [IR] Define "ptrauth" operand bundle. 2022-02-14 11:27:35 -08:00
ProgrammersManual.rst Update ProgrammersManual STL docs 2022-07-27 10:30:47 +01:00
Projects.rst Update references to mailing lists that have moved to Discourse. 2022-07-28 16:54:58 -07:00
README.txt Replace references to Makefile.sphinx 2021-10-22 15:32:12 +02:00
Reference.rst [Symbolize] Add log markup --filter to llvm-symbolizer. 2022-06-27 10:44:15 -07:00
ReleaseNotes.rst [COFF] Emit embedded -exclude-symbols: directives for hidden visibility for MinGW 2022-08-11 12:00:08 +03:00
ReleaseProcess.rst
Remarks.rst
ReportingGuide.rst Consistently use the same apostrophe in these docs. 2022-04-26 09:29:44 -07:00
ResponseGuide.rst Consistently use the same apostrophe in these docs. 2022-04-26 09:29:44 -07:00
SPIRVUsage.rst [Doc][OpenCL] Misc wording improvements for SPIR-V 2022-05-27 11:13:06 +01:00
ScudoHardenedAllocator.rst [llvm] Fix typos in documentation (NFC) 2021-08-28 06:37:03 -07:00
Security.rst [Security Group] Update representative for Rust. 2022-05-18 14:21:19 +02:00
SecurityTransparencyReports.rst Add security group 2021 transparency report. 2022-01-21 15:43:17 +01:00
SegmentedStacks.rst
SourceLevelDebugging.rst [DebugInfo] Add a TargetFuncName field in DISubprogram for 2022-04-15 16:38:23 -04:00
SpeculativeLoadHardening.md
SphinxQuickstartTemplate.rst [NFC] Trim trailing whitespace in *.rst 2021-11-15 09:17:08 +08:00
StackMaps.rst Migrate llvm.experimental.patchpoint() to ptr. 2022-08-10 13:18:02 +01:00
StackSafetyAnalysis.rst
Statepoints.rst Update references to the mailing lists that have moved to Discourse. 2022-02-21 18:58:48 -08:00
SupportLibrary.rst [NFC] Trim trailing whitespace in *.rst 2021-11-15 09:17:08 +08:00
SupportPolicy.rst Update references to the mailing lists that have moved to Discourse. 2022-02-21 18:58:48 -08:00
SymbolizerMarkupFormat.rst [Symbolizer] Implement pc element in symbolizing filter. 2022-08-08 11:08:48 -07:00
SystemLibrary.rst
TableGenFundamentals.rst
TestSuiteGuide.md [CMake] Make omitting CMAKE_BUILD_TYPE an error 2022-05-04 14:01:33 +02:00
TestSuiteMakefileGuide.rst
TestingGuide.rst [lit] Support %if ... %else syntax for RUN lines 2022-04-27 20:29:08 +03:00
TransformMetadata.rst
TypeMetadata.rst Update references to 'master' branch. 2020-12-21 19:10:34 +00:00
UserGuides.rst [docs] Adding DirectX target usage doc 2022-06-17 13:34:25 -05:00
Vectorizers.rst [NFC] Trim trailing whitespace in *.rst 2021-11-15 09:17:08 +08:00
WritingAnLLVMBackend.rst [SystemZ][z/OS] Introduce CCAssignToRegAndStack to calling convention 2022-07-19 13:55:25 -04:00
WritingAnLLVMNewPMPass.rst [docs] Add documentation on using the new pass manager 2021-02-26 15:28:19 -08:00
WritingAnLLVMPass.rst [llvm][docs] Fix typos to say subclasses need to override virtual methods but not overload 2022-07-11 22:25:14 +05:30
XRay.rst [xray] Fix xray document spelling 2021-03-10 16:03:55 +11:00
XRayExample.rst [NFC] Trim trailing whitespace in *.rst 2021-11-15 09:17:08 +08:00
XRayFDRFormat.rst
YamlIO.rst [yamlio] Allow parsing an entire mapping as an enumeration 2022-03-14 04:41:40 +00:00
buildbot_worker_contact.png added section on CI system 2021-04-21 09:59:41 +02:00
conf.py [docs] Remove hard-coded version numbers from sphinx configs 2022-02-01 23:14:12 -08:00
cycle-1.png Reapply CycleInfo: Introduce cycles as a generalization of loops 2021-12-10 14:36:43 +05:30
cycle-2.png Reapply CycleInfo: Introduce cycles as a generalization of loops 2021-12-10 14:36:43 +05:30
cycle-3.png Reapply CycleInfo: Introduce cycles as a generalization of loops 2021-12-10 14:36:43 +05:30
doxygen-mainpage.dox
doxygen.cfg.in [NFC] Inclusive Language: change master to main for .chm files 2021-11-08 08:23:04 -06:00
epilogue-vectorization-cfg.png [LV] Epilogue Vectorization with Optimal Control Flow (Recommit) 2020-12-02 10:09:56 -05:00
gcc-loops.png
index.rst Update references to the mailing lists that have moved to Discourse. 2022-02-21 18:58:48 -08:00
linpack-pc.png
llvm-objdump.1 [llvm-objdump][docs] Fix documentation for offloading flags 2022-07-11 15:44:48 -04:00
loop-guard.svg
loop-irreducible.svg
loop-merge.svg
loop-nested.svg
loop-nonmaximal.svg
loop-separate.svg
loop-single.svg
loop-terminology-guarded-loop.png
loop-terminology-initial-loop.png
loop-terminology-rotated-loop.png
loop-terminology.svg
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 <https://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` <-> `https://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.
`https://llvm.org/docs/CommandGuide/Foo.html`.

Checking links
==============

The reachability of external links in the documentation can be checked by
running:

    cd llvm/docs/
    sphinx-build -b linkcheck . _build/lintcheck/
    # report will be generated in _build/lintcheck/output.txt

Doxygen page Output
==============

Install doxygen <https://www.doxygen.nl/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