How to generate an LLVM docset for Dash

llvm-docset.md

How to generate an LLVM docset for Dash

Prerequisites

brew install swiftdocorg/formulae/docsetutil
sudo ln -s /usr/local/bin/docsetutil /Library/Developer/CommandLineTools/usr/bin/docsetutil
brew install doxygen graphviz

LLVM Build

Assuming that we've already checked out LLVM from the git repo into a directory named e. g. llvm-project, we're gonna need to run the CMake configuration.

Inside the llvm-project directory let's create the build folder, and then run CMake from that folder:

$ cd llvm-project
$ mkdir build
$ cmake ../llvm \
-DLLVM_ENABLE_PROJECTS="clang;llvm" \
-DLLVM_BUILD_DOC=ON \
-DLLVM_ENABLE_DOXYGEN=ON \
-DLLVM_DOXYGEN_SVG=ON

The latter one (LLVM_DOXYGEN_SVG=ON) is optional and is needed only if you want the class diagrams to be saved as SVGs instead of PNGs. You'll need the dot tool for that. This tool is part of Graphviz.

After executing these commands a Makefile and a doxygen.cfg will be generated in the build/docs folder.

We need to change some variables in doxygen.cfg to have the following values:

GENERATE_DOCSET = YES
DISABLE_INDEX = YES
SEARCHENGINE = NO
GENERATE_TREEVIEW = NO
DOCSET_BUNDLE_ID = org.doxygen.LLVM.docs
DOCSET_PUBLISHER_ID = org.doxygen.LLVM

If you've decided to generate diagrams in SVG format, make sure to also set these:

HAVE_DOT = YES
DOT_IMAGE_FORMAT = svg
INTERACTIVE_SVG = YES
DOT_PATH = /usr/local/bin/dot
DOT_TRANSPARENT = YES

Run the Makefile in the build/docs directory:

$ cd docs
$ make doxygen-llvm

The HTML documentation will be generated, but we're not done yet.

Run Docsetutil

Now you need to get the docsetutil tool. It used to be a part of Xcode until Xcode 9.3. See this comment on GitHub.

Assuming that you've downloaded docsetutil from the link above into a directory DocSetUtil (that directory must contains subdirectories Developer, SharedFrameworks and Frameworks), go to the build/docs/doxygen/html directory and run:

$ cd doxygen/html
$ make XCODE_INSTALL=DocSetUtil/Developer all

The docset will be generated. This will take quite some time and disk space (~13 GB).

When the docset is ready, the .docset file will be generated in the html directory.

Optional

Add a docset icon:

curl https://llvm.org/favicon.ico -o ~/Downloads/favicon.ico
cp ~/Downloads/favicon.ico org.doxygen.LLVM.docs.docset/icon@2x.png

Let's support online redirection:

Set the DashDocSetFallbackURL key in the docset's Info.plist to a URL containing the official LLVM HTML docset (see here). This example shows the URL for LLVM 10).

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN"
"http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
     <key>CFBundleName</key>
     <string>LLVM</string>
     <key>CFBundleIdentifier</key>
     <string>org.doxygen.Project</string>
     <key>CFBundleVersion</key>
     <string>10.0.0</string>
     <key>DocSetFeedName</key>
     <string>Doxygen generated docs</string>
     <key>DocSetFeedUrl</key>
     <string>FeedUrl</string>
     <key>DocSetPublisherIdentifier</key>
     <string>org.doxygen.Publisher</string>
     <key>DocSetPublisherName</key>
     <string>Publisher</string>
     <key>DashDocSetFamily</key>
     <string>doxy</string>
     <key>DocSetPlatformFamily</key>
     <string>doxygen</string>
     <key>DashDocSetFallbackURL</key>
     <string>https://releases.llvm.org/10.0.0/docs</string>
</dict>
</plist>