From bee60d9c8a803de07db9b1cc5a2a7fb581a63da9 Mon Sep 17 00:00:00 2001 From: DeForest Richards Date: Sun, 6 Oct 2019 15:36:37 +0000 Subject: [PATCH] [Docs] Adds new Getting Started/Tutorials page Adds a new page for Getting Started/Tutorials topics. Also updates existing topic categories on the User Guides and Reference pages. git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@373854 91177308-0d34-0410-b5e6-96231b3b80d8 --- docs/GettingStartedTutorials.rst | 29 ++++++++++ docs/ProgrammingDocumentation.rst | 23 +------- docs/Reference.rst | 91 ++++++++++++++++++++++------- docs/SubsystemDocumentation.rst | 46 +-------------- docs/UserGuides.rst | 95 +++++++++++++++++-------------- docs/index.rst | 31 ++-------- 6 files changed, 160 insertions(+), 155 deletions(-) create mode 100644 docs/GettingStartedTutorials.rst diff --git a/docs/GettingStartedTutorials.rst b/docs/GettingStartedTutorials.rst new file mode 100644 index 00000000000..60a5ddf7c06 --- /dev/null +++ b/docs/GettingStartedTutorials.rst @@ -0,0 +1,29 @@ +Getting Started/Tutorials +========================= + +For those new to the LLVM system. + +.. toctree:: + :hidden: + + GettingStarted + GettingStartedVS + Frontend/PerformanceTips + tutorial/index + +:doc:`GettingStarted` + Discusses how to get up and running quickly with the LLVM infrastructure. + Everything from unpacking and compilation of the distribution to execution + of some tools. + +:doc:`tutorial/index` + Tutorials about using LLVM. Includes a tutorial about making a custom + language with LLVM. + +:doc:`GettingStartedVS` + An addendum to the main Getting Started guide for those using Visual Studio + on Windows. + +:doc:`Frontend/PerformanceTips` + A collection of tips for frontend authors on how to generate IR + which LLVM is able to effectively optimize. \ No newline at end of file diff --git a/docs/ProgrammingDocumentation.rst b/docs/ProgrammingDocumentation.rst index 6a4d7aa25ba..a36127a87dd 100644 --- a/docs/ProgrammingDocumentation.rst +++ b/docs/ProgrammingDocumentation.rst @@ -8,13 +8,10 @@ For developers of applications which use LLVM as a library. Atomics CommandLine - CommandGuide/index ExtendingLLVM HowToSetUpLLVMStyleRTTI ProgrammersManual Extensions - LibFuzzer - FuzzingLLVM ScudoHardenedAllocator OptBisect GwpAsan @@ -42,26 +39,8 @@ For developers of applications which use LLVM as a library. :doc:`GwpAsan` A sampled heap memory error detection toolkit designed for production use. -============ -Command Line -============ - :doc:`CommandLine` Provides information on using the command line parsing library. :doc:`OptBisect` - A command line option for debugging optimization-induced failures. - -:doc:`LLVM Command Guide ` - A reference manual for the LLVM command line utilities ("man" pages for LLVM - tools). - -========= -LibFuzzer -========= - -:doc:`LibFuzzer` - A library for writing in-process guided fuzzers. - -:doc:`FuzzingLLVM` - Information on writing and using Fuzzers to find bugs in LLVM. \ No newline at end of file + A command line option for debugging optimization-induced failures. \ No newline at end of file diff --git a/docs/Reference.rst b/docs/Reference.rst index 49ff6b6e0e2..9346d4d7608 100644 --- a/docs/Reference.rst +++ b/docs/Reference.rst @@ -3,27 +3,41 @@ Reference LLVM and API reference documentation. +.. contents:: + :local: + .. toctree:: :hidden: - LangRef - TestingGuide + Bugpoint + CommandGuide/index CompilerWriterInfo + FuzzingLLVM + GarbageCollection + GetElementPtr + LangRef + LibFuzzer MIRLangRef - NVPTXUsage - AMDGPUUsage + PDB/index + Statepoints + TestingGuide + YamlIO + +API Reference +------------- + +`Doxygen generated documentation `_ + (`classes `_) + +`Documentation for Go bindings `_ -============== LLVM Reference -============== +-------------- :doc:`LLVM Language Reference Manual ` Defines the LLVM intermediate representation and the assembly form of the different nodes. -:doc:`LLVM Testing Infrastructure Guide ` - A reference manual for using the LLVM testing infrastructure. - :doc:`CompilerWriterInfo` A list of helpful links for compiler writers. @@ -31,17 +45,56 @@ LLVM Reference A reference manual for the MIR serialization format, which is used to test LLVM's code generation passes. -:doc:`NVPTXUsage` - This document describes using the NVPTX backend to compile GPU kernels. +:doc:`YamlIO` + A reference guide for using LLVM's YAML I/O library. -:doc:`AMDGPUUsage` - This document describes using the AMDGPU backend to compile GPU kernels. +:doc:`GetElementPtr` + Answers to some very frequent questions about LLVM's most frequently + misunderstood instruction. -============= -API Reference -============= +====================== +Command Line Utilities +====================== -`Doxygen generated documentation `_ - (`classes `_) +:doc:`LLVM Command Guide ` + A reference manual for the LLVM command line utilities ("man" pages for LLVM + tools). -`Documentation for Go bindings `_ +:doc:`Bugpoint` + Automatic bug finder and test-case reducer description and usage + information. + +:doc:`The Microsoft PDB File Format ` + A detailed description of the Microsoft PDB (Program Database) file format. + +================== +Garbage Collection +================== + +:doc:`GarbageCollection` + The interfaces source-language compilers should use for compiling GC'd + programs. + +:doc:`Statepoints` + This describes a set of experimental extensions for garbage + collection support. + +========= +LibFuzzer +========= + +:doc:`LibFuzzer` + A library for writing in-process guided fuzzers. + +:doc:`FuzzingLLVM` + Information on writing and using Fuzzers to find bugs in LLVM. + +======= +Testing +======= + +:doc:`LLVM Testing Infrastructure Guide ` + A reference manual for using the LLVM testing infrastructure. + +:doc:`TestSuiteGuide` + Describes how to compile and run the test-suite benchmarks. \ No newline at end of file diff --git a/docs/SubsystemDocumentation.rst b/docs/SubsystemDocumentation.rst index 69764cbd282..81feb43f2ee 100644 --- a/docs/SubsystemDocumentation.rst +++ b/docs/SubsystemDocumentation.rst @@ -13,14 +13,12 @@ For API clients and LLVM developers. BitCodeFormat BlockFrequencyTerminology BranchWeightMetadata - Bugpoint CodeGenerator ExceptionHandling AddingConstrainedIntrinsics LinkTimeOptimization SegmentedStacks TableGenFundamentals - TableGen/index DebuggingJITedCode GoldPlugin MarkedUpDisassembly @@ -28,15 +26,11 @@ For API clients and LLVM developers. SupportLibrary SourceLevelDebugging Vectorizers - WritingAnLLVMBackend - GarbageCollection - WritingAnLLVMPass HowToUseAttributes StackMaps InAlloca BigEndianNEON CoverageMappingFormat - Statepoints MergeFunctions TypeMetadata TransformMetadata @@ -46,28 +40,12 @@ For API clients and LLVM developers. XRay XRayExample XRayFDRFormat - PDB/index CFIVerify SpeculativeLoadHardening StackSafetyAnalysis LoopTerminology DependenceGraphs/index -:doc:`WritingAnLLVMPass` - Information on how to write LLVM transformations and analyses. - -:doc:`WritingAnLLVMBackend` - Information on how to write LLVM backends for machine targets. - -:doc:`CodeGenerator` - The design and implementation of the LLVM code generator. Useful if you are - working on retargetting LLVM to a new architecture, designing a new codegen - pass, or enhancing existing components. - -:doc:`TableGen ` - Describes the TableGen tool, which is used heavily by the LLVM code - generator. - :doc:`AliasAnalysis` Information on how to write a new alias analysis implementation or how to use existing analyses. @@ -90,10 +68,6 @@ For API clients and LLVM developers. Gives the steps necessary when adding a new constrained math intrinsic to LLVM. -:doc:`Bugpoint` - Automatic bug finder and test-case reducer description and usage - information. - :doc:`BitCodeFormat` This describes the file format and encoding used for LLVM "bc" files. @@ -169,9 +143,6 @@ For API clients and LLVM developers. :doc:`XRayExample` An example of how to debug an application with XRay. -:doc:`The Microsoft PDB File Format ` - A detailed description of the Microsoft PDB (Program Database) file format. - :doc:`CFIVerify` A description of the verification tool for Control Flow Integrity. @@ -182,21 +153,6 @@ For API clients and LLVM developers. This document describes the design of the stack safety analysis of local variables. -:doc:`LoopTerminology` - A document describing Loops and associated terms as used in LLVM. - :doc:`Dependence Graphs ` A description of the design of the various dependence graphs such as - the DDG (Data Dependence Graph). - -================== -Garbage Collection -================== - -:doc:`GarbageCollection` - The interfaces source-language compilers should use for compiling GC'd - programs. - -:doc:`Statepoints` - This describes a set of experimental extensions for garbage - collection support. + the DDG (Data Dependence Graph). \ No newline at end of file diff --git a/docs/UserGuides.rst b/docs/UserGuides.rst index d75769a7938..7016a52380e 100644 --- a/docs/UserGuides.rst +++ b/docs/UserGuides.rst @@ -1,13 +1,14 @@ User Guides =========== -For those new to the LLVM system. - NOTE: If you are a user who is only interested in using an LLVM-based compiler, you should look into `Clang `_ instead. The documentation here is intended for users who have a need to work with the intermediate LLVM representation. +.. contents:: + :local: + .. toctree:: :hidden: @@ -22,9 +23,6 @@ intermediate LLVM representation. MarkdownQuickstartTemplate Phabricator Passes - YamlIO - GetElementPtr - Frontend/PerformanceTips MCJITDesignAndImplementation ORCv2 CodeOfConduct @@ -34,27 +32,14 @@ intermediate LLVM representation. Docker BuildingADistribution Remarks + WritingAnLLVMPass + WritingAnLLVMBackend + TableGen/index + NVPTXUsage + AMDGPUUsage -Building, Packaging, and Distributing LLVM ------------------------------------------- - -How to build, package, and distribute LLVM. - -===== -CMake -===== - -:doc:`BuildingADistribution` - A best-practices guide for using LLVM's CMake build system to package and - distribute LLVM-based tools. - -:doc:`CMake` - An addendum to the main Getting Started guide for those using the `CMake - build system `_. - -===== Clang -===== +----- :doc:`HowToBuildOnARM` Notes on building and testing LLVM/Clang on ARM. @@ -70,36 +55,58 @@ Clang .. __: http://clang.llvm.org/get_started.html -====== -Docker -====== +LLVM Builds and Distributions +----------------------------- + +:doc:`BuildingADistribution` + A best-practices guide for using LLVM's CMake build system to package and + distribute LLVM-based tools. + +:doc:`CMake` + An addendum to the main Getting Started guide for those using the `CMake + build system `_. :doc:`Docker` A reference for using Dockerfiles provided with LLVM. -================= -Additional Topics -================= +Optimizations +------------- -:doc:`HowToCrossCompileBuiltinsOnArm` - Notes on cross-building and testing the compiler-rt builtins for Arm. +:doc:`WritingAnLLVMPass` + Information on how to write LLVM transformations and analyses. :doc:`Passes` A list of optimizations and analyses implemented in LLVM. -:doc:`TestSuiteGuide` - Describes how to compile and run the test-suite benchmarks. +:doc:`LoopTerminology` + A document describing Loops and associated terms as used in LLVM. -:doc:`YamlIO` - A reference guide for using LLVM's YAML I/O library. +:doc:`Remarks` + A reference on the implementation of remarks in LLVM. -:doc:`GetElementPtr` - Answers to some very frequent questions about LLVM's most frequently - misunderstood instruction. +Code Generation +--------------- -:doc:`Frontend/PerformanceTips` - A collection of tips for frontend authors on how to generate IR - which LLVM is able to effectively optimize. +:doc:`WritingAnLLVMBackend` + Information on how to write LLVM backends for machine targets. -:doc:`Remarks` - A reference on the implementation of remarks in LLVM. \ No newline at end of file +:doc:`CodeGenerator` + The design and implementation of the LLVM code generator. Useful if you are + working on retargetting LLVM to a new architecture, designing a new codegen + pass, or enhancing existing components. + +:doc:`TableGen ` + Describes the TableGen tool, which is used heavily by the LLVM code + generator. + +Additional Topics +----------------- + +:doc:`HowToCrossCompileBuiltinsOnArm` + Notes on cross-building and testing the compiler-rt builtins for Arm. + +:doc:`NVPTXUsage` + This document describes using the NVPTX backend to compile GPU kernels. + +:doc:`AMDGPUUsage` + This document describes using the AMDGPU backend to compile GPU kernels. \ No newline at end of file diff --git a/docs/index.rst b/docs/index.rst index 17a0706a196..f64979ea44a 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -53,14 +53,18 @@ Getting Started, How-tos, Developer Guides, and Tutorials. .. toctree:: :hidden: - UserGuides + GettingStartedTutorials ProgrammingDocumentation Reference SubsystemDocumentation + UserGuides -:doc:`UserGuides` +:doc:`GettingStartedTutorials` For those new to the LLVM system. +:doc:`UserGuides` + User guides and How-tos. + :doc:`ProgrammingDocumentation` For developers of applications which use LLVM as a library. @@ -70,29 +74,6 @@ Getting Started, How-tos, Developer Guides, and Tutorials. :doc:`Reference` LLVM and API reference documentation. -Getting Started/Tutorials -------------------------- - -.. toctree:: - :hidden: - - GettingStarted - tutorial/index - GettingStartedVS - -:doc:`GettingStarted` - Discusses how to get up and running quickly with the LLVM infrastructure. - Everything from unpacking and compilation of the distribution to execution - of some tools. - -:doc:`tutorial/index` - Tutorials about using LLVM. Includes a tutorial about making a custom - language with LLVM. - -:doc:`GettingStartedVS` - An addendum to the main Getting Started guide for those using Visual Studio - on Windows. - Community ========= -- 2.40.0