| /**************************************************************************** |
| ** |
| ** Copyright (C) 2016 The Qt Company Ltd. |
| ** Contact: https://www.qt.io/licensing/ |
| ** |
| ** This file is part of the documentation of the Qt Toolkit. |
| ** |
| ** $QT_BEGIN_LICENSE:FDL$ |
| ** Commercial License Usage |
| ** Licensees holding valid commercial Qt licenses may use this file in |
| ** accordance with the commercial license agreement provided with the |
| ** Software or, alternatively, in accordance with the terms contained in |
| ** a written agreement between you and The Qt Company. For licensing terms |
| ** and conditions see https://www.qt.io/terms-conditions. For further |
| ** information use the contact form at https://www.qt.io/contact-us. |
| ** |
| ** GNU Free Documentation License Usage |
| ** Alternatively, this file may be used under the terms of the GNU Free |
| ** Documentation License version 1.3 as published by the Free Software |
| ** Foundation and appearing in the file included in the packaging of |
| ** this file. Please review the following information to ensure |
| ** the GNU Free Documentation License version 1.3 requirements |
| ** will be met: https://www.gnu.org/licenses/fdl-1.3.html. |
| ** $QT_END_LICENSE$ |
| ** |
| ****************************************************************************/ |
| /*! |
| \page qdoc-guide.html |
| \title Getting Started with QDoc |
| \nextpage Installing Clang for QDoc |
| |
| Qt uses QDoc to generate its documentation set into HTML and DITA XML |
| formats. QDoc uses a set of configuration files to generate documentation |
| from QDoc comments. The comments have types called |
| \l{writing-topic-commands}{topics} that determine whether a comment is a |
| class documentation or a property documentation. A comment may also have |
| \l{writing-markup}{mark up} to enhance the layout and formatting of the |
| final output. |
| |
| There are three essential materials for generating documentation with QDoc: |
| \list |
| \li \c QDoc binary |
| \li \c qdocconf configuration files |
| \li \c Documentation in \c C++, \c QML, and \c .qdoc files |
| \endlist |
| |
| \note From Qt 5.11, \l{QDoc Manual}{QDoc} requires \l{http://clang.llvm.org}{Clang} |
| for parsing C++ header and source files, and for parsing the function |
| signatures in \l {fn-command} {\\fn} commands. See \l {Installing Clang for QDoc} |
| for details. |
| |
| This section intends to cover the basic necessities for creating a |
| documentation set. Additionally, the guide presents special considerations |
| and options to documenting non-C++ API documentation as well as QML |
| documentation. Finally, the guide will provide a sample project |
| documentation and an example of a QML type documentation. |
| |
| For specific QDoc information, consult the |
| \l{QDoc Manual}. |
| \section1 Chapters |
| |
| \list 1 |
| \li \l{Installing Clang for QDoc} |
| \li \l{Creating QDoc Configuration Files} |
| \li \l{Writing Documentation} |
| \li \l{Categories of Documentation} |
| \list |
| \li \l{C++ Documentation Style} |
| \li \l{QML Documentation Style} |
| \endlist |
| \endlist |
| |
| */ |
| |
| /*! |
| \page qdoc-guide-conf.html |
| \title Creating QDoc Configuration Files |
| \previouspage Installing Clang for QDoc |
| \nextpage Writing Documentation |
| To generate documentation, QDoc uses configuration files, with the |
| \c qdocconf extension, to store configuration settings. |
| |
| The \l{The QDoc Configuration File} article covers the various configuration |
| variables in greater detail. |
| |
| \section1 QDoc Configuration Files |
| QDoc's configuration settings can reside in a single \e qdocconf file, but |
| can also be in other qdocconf files. The \c {include(<filepath>)} command |
| allows configuration files to include other configuration files. |
| |
| QDoc has two outputs, HTML documentation and documentation in DITA XML |
| format. The main distinction between the two outputs is that HTML |
| documentation needs to have its HTML styling information in the |
| configuration files. DITA XML documentation does not, and a separate process |
| can style the documentation in DITA at a later time. DITA XML is therefore |
| more flexible in allowing different styles to apply to the same information. |
| |
| To run QDoc, the project configuration file is supplied as an argument. |
| \code |
| qdoc project.qdocconf |
| \endcode |
| |
| The project configuration contains information that QDoc uses to create the |
| documentation. |
| |
| \section2 Project Information |
| |
| QDoc uses the \c project information to generate the documentation. |
| \code |
| project = QDoc Project |
| description = Sample QDoc project |
| \endcode |
| |
| \target qdoc-input-output-dir |
| \section2 Input and Output Directories |
| |
| Specifying the path to the source directories allow QDoc to find sources and |
| generate documentation. |
| |
| \badcode |
| sourcedirs = <path to source code> |
| exampledirs = <path to examples directory> |
| imagedirs = <path to image directory> |
| |
| sources.fileextensions = "*.cpp *.qdoc *.mm *.qml" |
| headers.fileextensions = "*.h *.ch *.h++ *.hh *.hpp *.hxx" |
| examples.fileextensions = "*.cpp *.h *.js *.xq *.svg *.xml *.ui *.qhp *.qhcp *.qml" |
| examples.imageextensions = "*.png *.jpeg *.jpg *.gif *.mng" |
| \endcode |
| |
| QDoc will process headers and sources from the ones specified in the |
| \c fileextensions variable. |
| |
| Likewise, QDoc needs the path to the output directory. The \c outputformats |
| variable determines the type of documentation. These variables should be |
| in separate configuration files to modularize the documentation build. |
| \badcode |
| outputdir = $SAMPLE_PROJECT/doc/html |
| outputformats = HTML |
| \endcode |
| |
| QDoc can resolve the paths relative to the qdocconf file as well as |
| environment variables. |
| |
| \note During each QDoc run, the output directory is deleted. |
| \section2 Extra Files |
| |
| QDoc will output generated documentation into the directory specified in |
| the \l{Input and Output Directories}{output} directory. It is also possible |
| to specify extra files that QDoc should export. |
| |
| \badcode |
| HTML.extraimages = extraImage.png \ |
| extraImage2.png |
| \endcode |
| |
| The \c extraImage.png and the \c extraImage2.png files will be copied to the |
| HTML output directory. |
| |
| \section2 Qt Help Framework Configuration |
| |
| QDoc will also export a \e {Qt Help Project} file, in a \c qhp file. |
| The qhp file is then used by the \c qhelpgenerator to package the |
| documentation into a \c qch file. Qt Creator and Qt Assistant reads the qch |
| file to display the documentation. |
| |
| The \l {Creating Help Project Files} article covers the configuration |
| options. |
| |
| \section2 HTML Configuration |
| |
| QDoc has an HTML generator that will export a set of documentation into |
| HTML files using various configuration settings. QDoc will place the |
| generated documentation into the directory specified by the \c outputdir |
| variable. |
| |
| \badcode |
| outputformats = HTML |
| outputdir = <path to output directory> |
| \endcode |
| |
| QDoc needs to know where the styles and templates for generating HTML |
| are located. Typically, the templates directory contains a \c scripts, |
| \c images, and a \c style directory, containing scripts and CSS files. |
| |
| The main configuration variables are: |
| \badcode |
| HTML.postheader |
| HTML.postpostheader |
| HTML.postheader |
| HTML.footer |
| |
| HTML.headerstyles |
| HTML.stylesheets = template/style/style.css \ |
| template/style/style1.css |
| |
| HTML.scripts = template/scripts/script.js |
| \endcode |
| |
| The \c{HTML.headerstyles} variable inserts the style information into the |
| HTML file and the \c{HTML.stylesheets} specifies which files QDoc should |
| copy into the output directory. As well, QDoc will embed the string |
| in the \c postheader, \c footer, and related variables into each HTML file. |
| |
| The \l {Format-specific Configuration Variables} article outlines the usage |
| of each variable. |
| |
| \section2 QDoc Index Files |
| |
| Documentation projects can link to targets in other projects by specifying |
| a set of dependencies, or a set of direct paths to to index file(s) this |
| project depends on. When QDoc generates documentation for a project, |
| it will also generate an \c .index file containing URLs to each linkable |
| entity in the project. Other projects can then define a dependency to the |
| index file in order to link to the documentation within that project. |
| |
| \b {See also}: \l {depends-variable}{depends} and |
| \l {indexes-variable}{indexes}. |
| |
| \section1 Macros and Other Configurations |
| |
| Macros for substituting HTML characters exist and are helpful for generating |
| specific HTML-valid characters. |
| |
| \badcode |
| macro.pi.HTML = "Π" |
| \endcode |
| The snippet code will replace any instances of \c{\\pi} with \c Π in the |
| HTML file, which will appear as the Greek \pi symbol when viewed in |
| browsers. |
| |
| \b {See also:} \l {macro-variable}{macro}. |
| |
| \section2 QML Additions |
| |
| QDoc is able to parse QML files for QDoc comments. QDoc will parse files |
| with the QML extension, \c{.qml}, if the extension type is included in the |
| \l{Input and Output Directories}{fileextensions} variable. |
| |
| Also, the generated HTML files can have a prefix and a suffix following the |
| QML module name, specified in the QDoc configuration file. |
| \badcode |
| outputprefixes = QML |
| outputprefixes.QML = uicomponents- |
| outputsuffixes = QML |
| outputsuffixes.QML = -tp |
| \endcode |
| |
| \b {See also}: \l {outputprefixes-variable}{outputprefixes}, |
| \l {outputsuffixes-variable}{outputsuffixes}. |
| |
| */ |
| |
| /*! |
| \page qdoc-guide-writing.html |
| \title Writing Documentation |
| \previouspage Creating QDoc Configuration Files |
| \nextpage Categories of Documentation |
| |
| \section1 QDoc Comments |
| |
| Documentation is contained within QDoc \e comments, delimited by |
| \beginqdoc and \endqdoc comments. Note that these are valid comments |
| in C++, QML, and JavaScript. |
| |
| Within a QDoc comment, \c {//!} is used as a single-line documentation |
| comment; the comment itself and anything after it, until a newline, |
| is omitted from the generated output. |
| |
| QDoc will parse C++ and QML files to look for QDoc comments. To explicitly |
| omit a certain file type, omit it from the |
| \l{Input and Output Directories}{configuration} file. |
| |
| \section1 QDoc Commands |
| |
| QDoc uses \e commands to retrieve information about the documentation. \c |
| Topic commands determine the type of documentation element, the \c context |
| commands provide hints and information about a topic, and \c markup commands |
| provide information on how QDoc should format a piece of documentation. |
| |
| \target writing-topic-commands |
| \section2 QDoc Topics |
| Each QDoc comment must have a \e topic type. A topic distinguishes it from |
| other topics. To specify a topic type, use one of the several |
| \l{Topic Commands}{topic commands}. |
| |
| QDoc will collect similar topics and create a page for each one. For |
| example, all the enumerations, properties, functions, and class description |
| of a particular C++ class will reside in one page. A generic page is |
| specified using the \l{page-command}{\\page} command and the filename is the |
| argument. |
| |
| Example of topic commands: |
| \list |
| \li \l{enum-command}{\\enum} - for enumeration documentation |
| \li \l{class-command}{\\class} - for C++ class documentation |
| \li \l{qmltype-command}{\\qmltype} - for QML type documentation |
| \li \l{page-command}{\\page} - for creating a page. |
| \endlist |
| |
| The \l{page-command}{\\page} command is for creating articles that are not |
| part of source documentation. The command can also accept two arguments: the |
| file name of the article and the documentation type. The possible types are: |
| \list |
| \li \c howto |
| \li \c overview |
| \li \c tutorial |
| \li \c faq |
| \li \c article - \e default when there is no type |
| \endlist |
| |
| \snippet examples/samples.qdocinc sample-faq |
| |
| The \l{Topic Commands} page has information on all of the available topic |
| commands. |
| |
| \target writing-context |
| \section2 Topic Contexts |
| |
| Context commands give QDoc a hint about the \e context of the topic. For |
| example, if a C++ function is obsolete, then it should be marked obsolete |
| with the \l{obsolete-command}{\\obsolete} command. Likewise, |
| \l{nextpage-command}{page navigation} and \l{title-command}{page title} |
| give extra page information to QDoc. |
| |
| QDoc will create additional links or pages for these contexts. For example, |
| a group is created using the \l{group-command}{\\group} command and the |
| members have the \l{ingroup-command}{\\ingroup} command. The group name is |
| supplied as an argument. |
| |
| The \l{Context Commands} page has a listing of all the available context |
| commands. |
| |
| \target writing-markup |
| \section2 Documentation Markup |
| |
| QDoc can do \e markup of text similar to other markup or |
| documentation tools. QDoc can mark a section of text in \b{bold}, |
| when the text is marked up with the \l{b-command}{\\b} command. |
| |
| \code |
| \b{This} text will be in \b{bold}. |
| \endcode |
| |
| The \l{Markup Commands} page has a full listing of the available markup |
| commands. |
| |
| \section1 Anatomy of Documentation |
| |
| Essentially, for QDoc to create a page, there must be some essential |
| ingredients present. |
| |
| \list |
| \li Assign a topic to a QDoc comment - A comment could be a page, a |
| property documentation, a class documentation, or any of the available |
| \l{Topic Commands}{topic commands}. |
| |
| \li Give the topic a context - QDoc can associate certain topics to other |
| pages such as associating obsolete functions when the documentation is |
| marked with \l{obsolete-command}{\\obsolete}. |
| |
| \li Mark sections of the document with |
| \l{Markup Commands}{markup commands} - QDoc can create layouts and |
| format the documentation for the documentation. |
| \endlist |
| |
| In Qt, the \l{QVector3D} class was documented with the following QDoc |
| comment: |
| \snippet examples/samples.qdocinc qvector3d-class |
| |
| It has a constructor, \l{QVector3D::QVector3D()}, which was documented with |
| the following QDoc comment: |
| \snippet examples/samples.qdocinc qvector3d-function |
| |
| The different comments may reside in different files and QDoc will collect |
| them depending on their topic and their context. The resulting documentation |
| from the snippets are generated into the \l{QVector3D} class documentation. |
| |
| Note that if the documentation immediately precedes the function or class |
| in the source code, then it does not need to have a topic. QDoc will assume |
| that the documentation above the code is the documentation for that code. |
| |
| An article is created using \l{page-command}{\\page} command. The first |
| argument is the HTML file that QDoc will create. The topic is supplemented |
| with context commands, the \l{title-command}{\\title} and |
| \l{nextpage-command}{\\nextpage} commands. There are several other |
| QDoc commands such as the \l{list-command}{\\list} command. |
| \snippet examples/samples.qdocinc sample-page |
| |
| The section on \l{QDoc Topics}{topic commands} gives an overview on several |
| other topic types. |
| |
| |
| */ |
| |
| /*! |
| \page qdoc-categories.html |
| \title Categories of Documentation |
| \previouspage Writing Documentation |
| \brief Describes the different types such as How-To's, Tutorials, Overviews, |
| Examples, and Class Documentation. |
| |
| There are several types of predefined documentation \e categories or |
| \e types: |
| \list |
| \li How-To's |
| \li Tutorial |
| \li Overview |
| \li Article |
| \li FAQ (Frequently Asked Questions) |
| \li C++ API Documentation |
| \li QML Type Documentation |
| \li Code Example |
| \endlist |
| |
| QDoc has the ability to format a page depending on the type. Further, |
| stylesheets can provide additional control on the display of each category. |
| |
| \section1 API Documentation |
| QDoc excels in the creation of API documentation given a set of source code |
| and documentation in QDoc comments. Specifically, QDoc is aware of Qt's |
| architecture and can validate the existence of Qt C++ class, function, or |
| property documentation. QDoc gives warnings and errors if it cannot |
| associate a documentation with a code entity or if a code entity does not |
| have documentation. |
| |
| In general, every Qt code entity such as properties, classes, methods, |
| signals, and enumerations have a corresponding |
| \l{qdoc-topics}{topic command}. QDoc will associate the documentation to the |
| source using C++ naming rules. |
| |
| QDoc will parse the header files (typically \c .h files) to build a tree of |
| the class structures. Then QDoc will parse the source files and |
| documentation files to attach documentation to the class structure. |
| Afterwards, QDoc will generate a page for the class. |
| |
| \note QDoc uses the header files to inform itself about the class and will |
| not properly process QDoc comments in header files. |
| |
| \section2 Language Styles |
| |
| To produce quality API documentation, the Qt API references follow a |
| particular language guidelines. While the contents of this page demonstrates |
| how to create API documentation, the style guidelines demonstrate how |
| the reference materials follow a consistent use of language. |
| |
| \list |
| \li \l{C++ Documentation Style} |
| \li \l{QML Documentation Style} |
| \endlist |
| |
| \keyword qml-documentation |
| \section2 Documenting QML Types |
| |
| In the world of \l{Qt Quick}{QML}, there are additional entities we need to |
| document such as QML signals, attached properties, and QML methods. |
| Internally, they use Qt technologies, however, QML API documentation |
| requires different layout and naming conventions from the Qt C++ API |
| documentation. |
| |
| A list of QML related QDoc commands: |
| \list |
| \li \l{qmlattachedproperty-command}{\\qmlattachedproperty} |
| \li \l{qmlattachedsignal-command}{\\qmlattachedsignal} |
| \li \l{qmlbasictype-command}{\\qmlbasictype} |
| \li \l{qmltype-command}{\\qmltype} - creates a QML type documentation |
| \li \l{qmlmethod-command}{\\qmlmethod} |
| \li \l{qmlproperty-command}{\\qmlproperty} |
| \li \l{qmlsignal-command}{\\qmlsignal} |
| \li \l{inherits-command}{\\inherits} |
| \li \l{qmlmodule-command}{\\qmlmodule} |
| \li \l{inqmlmodule-command}{\\inqmlmodule} |
| \li \l{instantiates-command}{\\instantiates} |
| |
| \endlist |
| |
| \note Remember to enable QML parsing by including the \c{*.qml} filetype in |
| the \l{qdoc-input-output-dir}{fileextension} variable. |
| |
| To document a QML type, start by creating a QDoc comment that uses the |
| \l{qmltype-command} {\\qmltype} command as its topic command. |
| |
| \section3 QML Parser |
| |
| If your QML type is defined in a \e qml file, document it there. |
| If your QML type is represented by a C++ class, document it in the |
| \e cpp file for that C++ class and include an |
| \l{instantiates-command}{\\instantiates} command to specify the |
| name of the C++ class. Don't document a QML type in a \e{cpp} file |
| if the QML type is defined in a \e{qml} file. |
| |
| When documenting a QML type in a \e{qml} file, place each QDoc |
| comment directly above the entity to which the comment applies. |
| For example, place the QDoc comment containing the \e{\\qmltype} |
| command (the topic comment) directly above the outer QML type in |
| the \e{qml} file. Place the comment for documenting a QML property |
| directly above the property declaration, and so on for QML signal |
| handlers and QML methods. Note that when documenting QML |
| properties in a \e{qml} file, you don't normally include the |
| \e{\\qmlproperty} command as a topic command (which you must do |
| when documenting QML types in \e{cpp} files), because the QML |
| parser automatically associates each QDoc comment with the next |
| QML declaration it parses. The same is true for QML signal handler |
| and QML method comments. But it is sometimes useful to include one |
| or more \e{\\qmlproperty} commands in the comment, e.g. when the |
| property type is another QML type and you want the user to only |
| use certain properties within that other QML type, but not all of |
| them. But when documenting a property that has an alias, place the |
| QDoc comment for it directly above the alias declaration. In these |
| cases, the QDoc comment \e must contain a \e{\\qmlproperty} |
| command, because that is the only way QDoc can know the type of |
| the aliased property. |
| |
| When documenting a QML type in the \e cpp file of its |
| corresponding C++ class (if it has one), you normally place each |
| QDoc comment directly above the entity it documents. However, QDoc |
| does not use the QML parser to parse these files (the C++ parser |
| is used), so these QML QDoc comments can appear anywhere in the |
| \e{cpp} file. Note that QML QDoc comments in \e cpp files \e must |
| use the QML topic commands. i.e., the \l{qmltype-command} |
| {\\qmltype} command \e must appear in the QDoc comment for the |
| QML type, and a \l{qmlproperty-command} {\\qmlproperty} command \e |
| must appear in each QML property QDoc comment. |
| |
| \section3 QML Modules |
| |
| A QML type belongs to a \e module. The module |
| may include all the related types for a platform or contain a certain |
| version of \l{Qt Quick}. For example, the Qt Quick 2 QML types belong |
| to the Qt Quick 2 module while there is also a Qt Quick 1 module for the older |
| types introduced in Qt 4. |
| |
| QML modules allow grouping QML types. The \l{qmltype-command} |
| {\\qmltype} topic command must have an \l{inqmlmodule-command} |
| {\\inqmlmodule} context command to relate the type to a QML |
| module. Similarly, a \l{qmlmodule-command}{\\qmlmodule} topic |
| command must exist in a separate \c{.qdoc} file to create the |
| overview page for the module. The overview page will list the |
| QML types of the QML module. |
| |
| The links to the QML types must therefore also contain the module name. |
| For example, if a type called \c TabWidget is in the \c UIComponents |
| module, it must be linked as \c {UIComponents::TabWidget}. |
| |
| \section3 Read-only and Internal QML Properties |
| |
| QDoc detects QML properties that are marked as \c readonly. Note that the |
| property must be initialized with a value. |
| |
| \badcode |
| readonly property int sampleReadOnlyProperty: 0 |
| \endcode |
| |
| Properties and signals that are not meant for the public interface may |
| be marked with the \l{internal-command}{\\internal} command. QDoc will not |
| publish the documentation in the generated outputs. |
| |
| \section1 Articles & Overviews |
| |
| Articles and overviews are a style of writing best used for providing |
| summary detail on a topic or concept. It may introduce a technology or |
| discuss how a concept may be applied, but without discussing exact steps |
| in too much detail. However, this type of content could provide the entry |
| point for readers to find instructional and reference materials that do, |
| such as tutorials, examples and class documentation. An example of an |
| overview might be a product page, such as a top level discussion of |
| Qt Quick, individual modules, design principles, or tools. |
| |
| To signify that a document is an article, you append the article keyword |
| to the \\page command: |
| |
| \snippet examples/samples.qdocinc sample-overview |
| |
| The \l{writing-topic-commands}{writing topic commands} section has a listing |
| of the available \\page command arguments. |
| |
| \section1 Tutorials, How-To's, FAQ's |
| |
| Tutorials, How-To's, and FAQ's are all instructional material, in that they |
| instruct or prescribe to the reader. Tutorials are content designed to guide |
| the reader along a progressive learning path for a concept or technology. |
| How-To's and FAQ's (\e{Frequently Asked Questions}) provide guidance by |
| presenting material in the form of answers to commonly asked topics. |
| How-To's and FAQ's are designed for easy reference and are not necessarily |
| presented in a linear progression. |
| |
| To create these types, mark the pages by providing a \c type argument to the |
| \l{page-command}{\\page} command. The \c type argument is the second |
| argument, with the file name being the first. |
| \snippet examples/samples.qdocinc sample-faq |
| |
| The \l{writing-topic-commands}{writing topic commands} section has a listing |
| of the available \\page command arguments. |
| |
| \section1 Code Examples |
| Examples are an effective way to demonstrate practical usage of a given |
| technology or concept. When it comes to middleware this is usually in the |
| form of an application using simple code and clear explanations of what the |
| code is doing. Any module, API, project, pattern etc. should have at least |
| one good example. |
| |
| An example may have an accompanying tutorial. The tutorial instructs and |
| describes the code, while the code example is the code content that users |
| may study. Code examples may have accompanying text that are not in the |
| tutorial. |
| |
| QDoc will create a page containing the example code with a description |
| using the \l{example-command}{\\example} command. |
| |
| \snippet examples/samples.qdocinc sample-example |
| |
| QDoc will use the directory specified in the input |
| \l{Input and Output Directories}{exampledirs} variable to find the Qt |
| Project (\c .pro) file to generate the example files. The generated HTML |
| will have the filename, \c {declarative-ui-components-tabwidget.html}. QDoc |
| will also list all of the example code. |
| |
| \note The example's project file must be the same as the |
| directory name. |
| */ |
| |
| |
| /*! |
| \page qdoc-guide-clang.html |
| \title Installing Clang for QDoc |
| \previouspage Getting Started with QDoc |
| \nextpage Creating QDoc Configuration Files |
| |
| QDoc uses Clang when parsing C++ files as well as function signatures in |
| \l {fn-command} {\\fn} commands. Clang is part of |
| \l {https://llvm.org/}{the LLVM Compiler Infrastructure Project}. |
| Therefore, if you are going to build QDoc from source, you need to install |
| \l{http://clang.llvm.org}{LLVM 6.0} or greater first. You can find the |
| required pre-built binaries |
| \l {http://releases.llvm.org/download.html}{here}. |
| |
| To build QDoc on Debian-based Linux distributions, it is sufficient to |
| install the \c libclang-dev package and its dependencies. For running QDoc, |
| the \c libclang package is required. |
| |
| \note On Windows, after installing the pre-built LLVM you must restart your |
| build shell to ensure that LLVM's binary directory is added to the PATH |
| variable. This is needed to be able to run qdoc. |
| |
| \section1 Set Clang location automatically |
| |
| The Qt build system uses the tool \c llvm-config to discover the location |
| of LLVM on your system, and relies on the path to llvm-config being in |
| the \c PATH environment variable to do so. \c llvm-config is commonly |
| installed with LLVM and Clang on Linux systems, and also on macOS if |
| LLVM is installed using Brew. |
| |
| On Windows, the installation binaries provided by LLVM do not include |
| \c llvm-config. You may still have it on your system, if you have built |
| LLVM yourself from source. If that is the case, and you want to let the |
| build system find Clang automatically, add the path to \c llvm-config |
| to your \c PATH environment variable. For example: |
| |
| \badcode |
| C:\> set PATH=%PATH%;C:\[build directory]\bin\Release" |
| \endcode |
| |
| Make sure to set the path to your LLVM build directory. The \c llvm-config |
| executable is located in \c {bin\Release} or \c {bin\Debug}, reflecting the |
| build version. |
| |
| \section1 Specify Clang location manually |
| |
| If \c llvm-config is not in your \c PATH environment variable, or not |
| installed on your system, you can still build QDoc, by manually setting the |
| environment variable \c LLVM_INSTALL_DIR to point to the directory where |
| the Clang libraries are installed. This directory should be the top level |
| directory. For example, on a Linux or macOS system with LLVM installed to |
| \c /usr/llvm: |
| |
| \badcode |
| $ export LLVM_INSTALL_DIR=/usr/llvm |
| \endcode |
| |
| Debian-based Linux distributions usually offer multiple versions of the |
| \c libclang packages, such as \c libclang-<VERSION>. In this case, |
| \c LLVM_INSTALL_DIR should contain \c /usr/lib/clang/<VERSION> . |
| |
| On a Windows system with LLVM installed to \c {C:\Program Files\LLVM}: |
| |
| \badcode |
| C:\> set LLVM_INSTALL_DIR=C:\Program Files\LLVM |
| \endcode |
| */ |