llvm-project/llvm/docs
Fangrui Song 45ae553109 [llvm-objcopy] Remove support for legacy .zdebug sections
clang 14 removed -gz=zlib-gnu support and ld.lld removed linker input support
for zlib-gnu in D126793. Now let's remove zlib-gnu from llvm-objcopy.

* .zdebug* sections are no longer recognized as debug sections. --strip* don't remove them.
  They are copied like other opaque sections
* --decompress-debug-sections does not uncompress .zdebug* sections
* --compress-debug-sections=zlib-gnu is not supported

It is very rare but in case a user has object files using .zdebug . They can use
llvm-objcopy<15 or GNU objcopy for uncompression.
--compress-debug-sections=zlib-gnu is unlikely ever used by anyone, so I do not
add a custom diagnostic.

Differential Revision: https://reviews.llvm.org/D128688
2022-06-29 10:42:55 -07:00
..
AMDGPU [AMDGPU][GFX90a][DOC][NFC] Update assembler syntax description 2022-06-29 13:31:09 +03:00
AMDGPUDwarfExtensionAllowLocationDescriptionOnTheDwarfExpressionStack [AMDGPU][NFC] Update DWARF extension allowing locations on stack 2021-12-28 17:12:20 +00:00
CommandGuide [llvm-ar] Add --output to specify output directory 2022-06-29 10:00:43 -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] Add G_IS_FPCLASS 2022-05-27 13:49:47 +07:00
HistoricalNotes Doc: Links should use https 2020-03-22 22:49:33 +01:00
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 [docs] Fix Kaleidoscope code example 2022-04-06 10:41:10 +01:00
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] Restore documentation of .amdhsa_shared_vgpr_count 2022-06-10 17:06:08 +01:00
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 [AArch64] Out-of-line atomics (-moutline-atomics) implementation. 2020-11-20 13:30:12 +00:00
Benchmarking.rst
BigEndianNEON.rst [NFC] Trim trailing whitespace in *.rst 2021-11-15 09:17:08 +08:00
BitCodeFormat.rst [SanitizerBounds] Add support for NoSanitizeBounds function 2022-03-01 18:47:02 +01:00
BlockFrequencyTerminology.rst
BranchWeightMetadata.rst Add support of __builtin_expect_with_probability 2020-06-22 10:21:28 -07:00
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 [docs] Improve documentation around CMAKE_BUILD_TYPE 2022-05-04 11:23:45 +02:00
CMakeLists.txt
CMakePrimer.rst [CMake] Bump CMake minimum version to 3.13.4 2020-07-22 14:25:07 -04:00
CodeGenerator.rst [docs] Adding table of object file formats 2022-06-17 13:37:52 -05: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 [Docs] Clarify the guideline on omitting braces 2022-05-31 23:35:30 -07: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] Update the label name for new contributors 2022-05-28 23:14:31 +09:00
Coroutines.rst [Coroutines] Convert coroutine.presplit to enum attr 2022-06-14 14:23:46 +08:00
CoverageMappingFormat.rst [Coverage] Store compilation dir separately in coverage mapping 2021-02-18 14:34:39 -08:00
CycleTerminology.rst Reapply CycleInfo: Introduce cycles as a generalization of loops 2021-12-10 14:36:43 +05:30
DebuggingJITedCode.rst [NFC] Trim trailing whitespace in *.rst 2021-11-15 09:17:08 +08:00
DeveloperPolicy.rst [DeveloperPolicy] Add invitation link for commit access. 2022-04-21 12:44:59 -07: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 [docs] Fix typos 2020-08-09 19:31:49 -07:00
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 [Propeller] Encode address offsets of basic blocks relative to the end of the previous basic blocks. 2022-06-28 07:42:54 -07: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
GettingInvolved.rst [docs] Document and publish LLVM community calendar 2022-06-23 13:29:41 +02:00
GettingStarted.rst [CMake] Make omitting CMAKE_BUILD_TYPE an error 2022-05-04 14:01:33 +02: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
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 HowToReleaseLLVM: Add description of the bug triage process 2022-06-21 22:18:35 -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 Remove references to the 4.0 release as a major breaking (NFC) 2020-06-25 23:49:07 +00:00
HowToUseInstrMappings.rst [llvm] NFC: Fix trivial typo in rst and td files 2020-04-23 14:26:32 +09:00
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 Fix sphinx docs build 2022-06-27 12:22:04 -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] improve introductory sentence 2022-03-15 17:19:20 -07:00
LinkTimeOptimization.rst [LTO][Legacy] Add new API to query Mach-O CPU (sub)type 2020-02-28 12:56:05 -08:00
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 Fix MemTagSanitizer docs to point at Armv8.5-A MTE 2020-03-05 17:23:58 +00:00
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 update of the llvm doc: we moved to git 2020-03-22 22:36:21 +01:00
Passes.rst Reland "Lower `@llvm.global_dtors` using `__cxa_atexit` on MachO" 2022-03-23 18:36:55 -07:00
Phabricator.rst Correct a minor point with the Phabricator docs 2022-03-28 07:15:09 -04: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 the ProgrammersManual explanation for ilist and iplist 2022-06-07 22:50:04 -04:00
Projects.rst [NFC][llvm] Inclusive language: replace master in llvm docs 2021-11-25 13:36:51 -06: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 [llvm-objcopy] Remove support for legacy .zdebug sections 2022-06-29 10:42:55 -07:00
ReleaseProcess.rst Doc: Links should use https 2020-03-22 22:49:33 +01:00
Remarks.rst [Remarks] Extend the RemarkStreamer to support other emitters 2020-02-04 17:16:02 -08:00
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 [STACKMAPS] Document+test UINT64_MAX stack size. 2022-06-27 11:57:07 +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 [Symbolize] Add log markup --filter to llvm-symbolizer. 2022-06-27 10:44:15 -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 Insert missing bracket in docs. 2020-09-08 15:20:39 -07:00
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 [NFC] Trim trailing whitespace in *.rst 2021-11-15 09:17:08 +08:00
WritingAnLLVMNewPMPass.rst [docs] Add documentation on using the new pass manager 2021-02-26 15:28:19 -08:00
WritingAnLLVMPass.rst [NFC] Trim trailing whitespace in *.rst 2021-11-15 09:17:08 +08:00
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] Implement --prefix-strip option 2021-03-24 13:22:35 +00:00
loop-guard.svg [docs] Revise loop terminology reference. 2020-10-05 10:28:04 -05:00
loop-irreducible.svg [docs] Revise loop terminology reference. 2020-10-05 10:28:04 -05:00
loop-merge.svg [docs] Revise loop terminology reference. 2020-10-05 10:28:04 -05:00
loop-nested.svg [docs] Revise loop terminology reference. 2020-10-05 10:28:04 -05:00
loop-nonmaximal.svg [docs] Revise loop terminology reference. 2020-10-05 10:28:04 -05:00
loop-separate.svg [docs] Revise loop terminology reference. 2020-10-05 10:28:04 -05:00
loop-single.svg [docs] Revise loop terminology reference. 2020-10-05 10:28:04 -05:00
loop-terminology-guarded-loop.png [LoopTerminology] Rotated Loops images 2020-03-17 01:02:19 +02:00
loop-terminology-initial-loop.png [LoopTerminology] Rotated Loops images 2020-03-17 01:02:19 +02:00
loop-terminology-rotated-loop.png [LoopTerminology] Rotated Loops images 2020-03-17 01:02:19 +02:00
loop-terminology.svg [docs] Revise loop terminology reference. 2020-10-05 10:28:04 -05:00
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