1/**************************************************************************** 2** 3** Copyright (C) 2016 The Qt Company Ltd. 4** Contact: https://www.qt.io/licensing/ 5** 6** This file is part of the documentation of the Qt Toolkit. 7** 8** $QT_BEGIN_LICENSE:FDL$ 9** Commercial License Usage 10** Licensees holding valid commercial Qt licenses may use this file in 11** accordance with the commercial license agreement provided with the 12** Software or, alternatively, in accordance with the terms contained in 13** a written agreement between you and The Qt Company. For licensing terms 14** and conditions see https://www.qt.io/terms-conditions. For further 15** information use the contact form at https://www.qt.io/contact-us. 16** 17** GNU Free Documentation License Usage 18** Alternatively, this file may be used under the terms of the GNU Free 19** Documentation License version 1.3 as published by the Free Software 20** Foundation and appearing in the file included in the packaging of 21** this file. Please review the following information to ensure 22** the GNU Free Documentation License version 1.3 requirements 23** will be met: https://www.gnu.org/licenses/fdl-1.3.html. 24** $QT_END_LICENSE$ 25** 26****************************************************************************/ 27/*! 28 \page qdoc-guide.html 29 \title Getting Started with QDoc 30 \nextpage Installing Clang for QDoc 31 32 Qt uses QDoc to generate its documentation set into HTML and DITA XML 33 formats. QDoc uses a set of configuration files to generate documentation 34 from QDoc comments. The comments have types called 35 \l{writing-topic-commands}{topics} that determine whether a comment is a 36 class documentation or a property documentation. A comment may also have 37 \l{writing-markup}{mark up} to enhance the layout and formatting of the 38 final output. 39 40 There are three essential materials for generating documentation with QDoc: 41 \list 42 \li \c QDoc binary 43 \li \c qdocconf configuration files 44 \li \c Documentation in \c C++, \c QML, and \c .qdoc files 45 \endlist 46 47 \note From Qt 5.11, \l{QDoc Manual}{QDoc} requires \l{http://clang.llvm.org}{Clang} 48 for parsing C++ header and source files, and for parsing the function 49 signatures in \l {fn-command} {\\fn} commands. See \l {Installing Clang for QDoc} 50 for details. 51 52 This section intends to cover the basic necessities for creating a 53 documentation set. Additionally, the guide presents special considerations 54 and options to documenting non-C++ API documentation as well as QML 55 documentation. Finally, the guide will provide a sample project 56 documentation and an example of a QML type documentation. 57 58 For specific QDoc information, consult the 59 \l{QDoc Manual}. 60 \section1 Chapters 61 62 \list 1 63 \li \l{Installing Clang for QDoc} 64 \li \l{Creating QDoc Configuration Files} 65 \li \l{Writing Documentation} 66 \li \l{Categories of Documentation} 67 \list 68 \li \l{C++ Documentation Style} 69 \li \l{QML Documentation Style} 70 \endlist 71 \endlist 72 73*/ 74 75/*! 76 \page qdoc-guide-conf.html 77 \title Creating QDoc Configuration Files 78 \previouspage Installing Clang for QDoc 79 \nextpage Writing Documentation 80 To generate documentation, QDoc uses configuration files, with the 81 \c qdocconf extension, to store configuration settings. 82 83 The \l{The QDoc Configuration File} article covers the various configuration 84 variables in greater detail. 85 86 \section1 QDoc Configuration Files 87 QDoc's configuration settings can reside in a single \e qdocconf file, but 88 can also be in other qdocconf files. The \c {include(<filepath>)} command 89 allows configuration files to include other configuration files. 90 91 QDoc has two outputs, HTML documentation and documentation in DITA XML 92 format. The main distinction between the two outputs is that HTML 93 documentation needs to have its HTML styling information in the 94 configuration files. DITA XML documentation does not, and a separate process 95 can style the documentation in DITA at a later time. DITA XML is therefore 96 more flexible in allowing different styles to apply to the same information. 97 98 To run QDoc, the project configuration file is supplied as an argument. 99 \code 100 qdoc project.qdocconf 101 \endcode 102 103 The project configuration contains information that QDoc uses to create the 104 documentation. 105 106 \section2 Project Information 107 108 QDoc uses the \c project information to generate the documentation. 109 \code 110 project = QDoc Project 111 description = Sample QDoc project 112 \endcode 113 114 \target qdoc-input-output-dir 115 \section2 Input and Output Directories 116 117 Specifying the path to the source directories allow QDoc to find sources and 118 generate documentation. 119 120 \badcode 121 sourcedirs = <path to source code> 122 exampledirs = <path to examples directory> 123 imagedirs = <path to image directory> 124 125 sources.fileextensions = "*.cpp *.qdoc *.mm *.qml" 126 headers.fileextensions = "*.h *.ch *.h++ *.hh *.hpp *.hxx" 127 examples.fileextensions = "*.cpp *.h *.js *.xq *.svg *.xml *.ui *.qhp *.qhcp *.qml" 128 examples.imageextensions = "*.png *.jpeg *.jpg *.gif *.mng" 129 \endcode 130 131 QDoc will process headers and sources from the ones specified in the 132 \c fileextensions variable. 133 134 Likewise, QDoc needs the path to the output directory. The \c outputformats 135 variable determines the type of documentation. These variables should be 136 in separate configuration files to modularize the documentation build. 137 \badcode 138 outputdir = $SAMPLE_PROJECT/doc/html 139 outputformats = HTML 140 \endcode 141 142 QDoc can resolve the paths relative to the qdocconf file as well as 143 environment variables. 144 145 \note During each QDoc run, the output directory is deleted. 146 \section2 Extra Files 147 148 QDoc will output generated documentation into the directory specified in 149 the \l{Input and Output Directories}{output} directory. It is also possible 150 to specify extra files that QDoc should export. 151 152 \badcode 153 HTML.extraimages = extraImage.png \ 154 extraImage2.png 155 \endcode 156 157 The \c extraImage.png and the \c extraImage2.png files will be copied to the 158 HTML output directory. 159 160 \section2 Qt Help Framework Configuration 161 162 QDoc will also export a \e {Qt Help Project} file, in a \c qhp file. 163 The qhp file is then used by the \c qhelpgenerator to package the 164 documentation into a \c qch file. Qt Creator and Qt Assistant reads the qch 165 file to display the documentation. 166 167 The \l {Creating Help Project Files} article covers the configuration 168 options. 169 170 \section2 HTML Configuration 171 172 QDoc has an HTML generator that will export a set of documentation into 173 HTML files using various configuration settings. QDoc will place the 174 generated documentation into the directory specified by the \c outputdir 175 variable. 176 177 \badcode 178 outputformats = HTML 179 outputdir = <path to output directory> 180 \endcode 181 182 QDoc needs to know where the styles and templates for generating HTML 183 are located. Typically, the templates directory contains a \c scripts, 184 \c images, and a \c style directory, containing scripts and CSS files. 185 186 The main configuration variables are: 187 \badcode 188 HTML.postheader 189 HTML.postpostheader 190 HTML.postheader 191 HTML.footer 192 193 HTML.headerstyles 194 HTML.stylesheets = template/style/style.css \ 195 template/style/style1.css 196 197 HTML.scripts = template/scripts/script.js 198 \endcode 199 200 The \c{HTML.headerstyles} variable inserts the style information into the 201 HTML file and the \c{HTML.stylesheets} specifies which files QDoc should 202 copy into the output directory. As well, QDoc will embed the string 203 in the \c postheader, \c footer, and related variables into each HTML file. 204 205 The \l {Format-specific Configuration Variables} article outlines the usage 206 of each variable. 207 208 \section2 QDoc Index Files 209 210 Documentation projects can link to targets in other projects by specifying 211 a set of dependencies, or a set of direct paths to to index file(s) this 212 project depends on. When QDoc generates documentation for a project, 213 it will also generate an \c .index file containing URLs to each linkable 214 entity in the project. Other projects can then define a dependency to the 215 index file in order to link to the documentation within that project. 216 217 \b {See also}: \l {depends-variable}{depends} and 218 \l {indexes-variable}{indexes}. 219 220 \section1 Macros and Other Configurations 221 222 Macros for substituting HTML characters exist and are helpful for generating 223 specific HTML-valid characters. 224 225 \badcode 226 macro.pi.HTML = "Π" 227 \endcode 228 The snippet code will replace any instances of \c{\\pi} with \c Π in the 229 HTML file, which will appear as the Greek \pi symbol when viewed in 230 browsers. 231 232 \b {See also:} \l {macro-variable}{macro}. 233 234 \section2 QML Additions 235 236 QDoc is able to parse QML files for QDoc comments. QDoc will parse files 237 with the QML extension, \c{.qml}, if the extension type is included in the 238 \l{Input and Output Directories}{fileextensions} variable. 239 240 Also, the generated HTML files can have a prefix and a suffix following the 241 QML module name, specified in the QDoc configuration file. 242 \badcode 243 outputprefixes = QML 244 outputprefixes.QML = uicomponents- 245 outputsuffixes = QML 246 outputsuffixes.QML = -tp 247 \endcode 248 249 \b {See also}: \l {outputprefixes-variable}{outputprefixes}, 250 \l {outputsuffixes-variable}{outputsuffixes}. 251 252*/ 253 254/*! 255 \page qdoc-guide-writing.html 256 \title Writing Documentation 257 \previouspage Creating QDoc Configuration Files 258 \nextpage Categories of Documentation 259 260 \section1 QDoc Comments 261 262 Documentation is contained within QDoc \e comments, delimited by 263 \beginqdoc and \endqdoc comments. Note that these are valid comments 264 in C++, QML, and JavaScript. 265 266 Within a QDoc comment, \c {//!} is used as a single-line documentation 267 comment; the comment itself and anything after it, until a newline, 268 is omitted from the generated output. 269 270 QDoc will parse C++ and QML files to look for QDoc comments. To explicitly 271 omit a certain file type, omit it from the 272 \l{Input and Output Directories}{configuration} file. 273 274 \section1 QDoc Commands 275 276 QDoc uses \e commands to retrieve information about the documentation. \c 277 Topic commands determine the type of documentation element, the \c context 278 commands provide hints and information about a topic, and \c markup commands 279 provide information on how QDoc should format a piece of documentation. 280 281 \target writing-topic-commands 282 \section2 QDoc Topics 283 Each QDoc comment must have a \e topic type. A topic distinguishes it from 284 other topics. To specify a topic type, use one of the several 285 \l{Topic Commands}{topic commands}. 286 287 QDoc will collect similar topics and create a page for each one. For 288 example, all the enumerations, properties, functions, and class description 289 of a particular C++ class will reside in one page. A generic page is 290 specified using the \l{page-command}{\\page} command and the filename is the 291 argument. 292 293 Example of topic commands: 294 \list 295 \li \l{enum-command}{\\enum} - for enumeration documentation 296 \li \l{class-command}{\\class} - for C++ class documentation 297 \li \l{qmltype-command}{\\qmltype} - for QML type documentation 298 \li \l{page-command}{\\page} - for creating a page. 299 \endlist 300 301 The \l{page-command}{\\page} command is for creating articles that are not 302 part of source documentation. The command can also accept two arguments: the 303 file name of the article and the documentation type. The possible types are: 304 \list 305 \li \c howto 306 \li \c overview 307 \li \c tutorial 308 \li \c faq 309 \li \c article - \e default when there is no type 310 \endlist 311 312 \snippet examples/samples.qdocinc sample-faq 313 314 The \l{Topic Commands} page has information on all of the available topic 315 commands. 316 317 \target writing-context 318 \section2 Topic Contexts 319 320 Context commands give QDoc a hint about the \e context of the topic. For 321 example, if a C++ function is obsolete, then it should be marked obsolete 322 with the \l{obsolete-command}{\\obsolete} command. Likewise, 323 \l{nextpage-command}{page navigation} and \l{title-command}{page title} 324 give extra page information to QDoc. 325 326 QDoc will create additional links or pages for these contexts. For example, 327 a group is created using the \l{group-command}{\\group} command and the 328 members have the \l{ingroup-command}{\\ingroup} command. The group name is 329 supplied as an argument. 330 331 The \l{Context Commands} page has a listing of all the available context 332 commands. 333 334 \target writing-markup 335 \section2 Documentation Markup 336 337 QDoc can do \e markup of text similar to other markup or 338 documentation tools. QDoc can mark a section of text in \b{bold}, 339 when the text is marked up with the \l{b-command}{\\b} command. 340 341 \code 342 \b{This} text will be in \b{bold}. 343 \endcode 344 345 The \l{Markup Commands} page has a full listing of the available markup 346 commands. 347 348 \section1 Anatomy of Documentation 349 350 Essentially, for QDoc to create a page, there must be some essential 351 ingredients present. 352 353 \list 354 \li Assign a topic to a QDoc comment - A comment could be a page, a 355 property documentation, a class documentation, or any of the available 356 \l{Topic Commands}{topic commands}. 357 358 \li Give the topic a context - QDoc can associate certain topics to other 359 pages such as associating obsolete functions when the documentation is 360 marked with \l{obsolete-command}{\\obsolete}. 361 362 \li Mark sections of the document with 363 \l{Markup Commands}{markup commands} - QDoc can create layouts and 364 format the documentation for the documentation. 365 \endlist 366 367 In Qt, the \l{QVector3D} class was documented with the following QDoc 368 comment: 369 \snippet examples/samples.qdocinc qvector3d-class 370 371 It has a constructor, \l{QVector3D::QVector3D()}, which was documented with 372 the following QDoc comment: 373 \snippet examples/samples.qdocinc qvector3d-function 374 375 The different comments may reside in different files and QDoc will collect 376 them depending on their topic and their context. The resulting documentation 377 from the snippets are generated into the \l{QVector3D} class documentation. 378 379 Note that if the documentation immediately precedes the function or class 380 in the source code, then it does not need to have a topic. QDoc will assume 381 that the documentation above the code is the documentation for that code. 382 383 An article is created using \l{page-command}{\\page} command. The first 384 argument is the HTML file that QDoc will create. The topic is supplemented 385 with context commands, the \l{title-command}{\\title} and 386 \l{nextpage-command}{\\nextpage} commands. There are several other 387 QDoc commands such as the \l{list-command}{\\list} command. 388 \snippet examples/samples.qdocinc sample-page 389 390 The section on \l{QDoc Topics}{topic commands} gives an overview on several 391 other topic types. 392 393 394*/ 395 396/*! 397 \page qdoc-categories.html 398 \title Categories of Documentation 399 \previouspage Writing Documentation 400 \brief Describes the different types such as How-To's, Tutorials, Overviews, 401 Examples, and Class Documentation. 402 403 There are several types of predefined documentation \e categories or 404 \e types: 405 \list 406 \li How-To's 407 \li Tutorial 408 \li Overview 409 \li Article 410 \li FAQ (Frequently Asked Questions) 411 \li C++ API Documentation 412 \li QML Type Documentation 413 \li Code Example 414 \endlist 415 416 QDoc has the ability to format a page depending on the type. Further, 417 stylesheets can provide additional control on the display of each category. 418 419 \section1 API Documentation 420 QDoc excels in the creation of API documentation given a set of source code 421 and documentation in QDoc comments. Specifically, QDoc is aware of Qt's 422 architecture and can validate the existence of Qt C++ class, function, or 423 property documentation. QDoc gives warnings and errors if it cannot 424 associate a documentation with a code entity or if a code entity does not 425 have documentation. 426 427 In general, every Qt code entity such as properties, classes, methods, 428 signals, and enumerations have a corresponding 429 \l{qdoc-topics}{topic command}. QDoc will associate the documentation to the 430 source using C++ naming rules. 431 432 QDoc will parse the header files (typically \c .h files) to build a tree of 433 the class structures. Then QDoc will parse the source files and 434 documentation files to attach documentation to the class structure. 435 Afterwards, QDoc will generate a page for the class. 436 437 \note QDoc uses the header files to inform itself about the class and will 438 not properly process QDoc comments in header files. 439 440 \section2 Language Styles 441 442 To produce quality API documentation, the Qt API references follow a 443 particular language guidelines. While the contents of this page demonstrates 444 how to create API documentation, the style guidelines demonstrate how 445 the reference materials follow a consistent use of language. 446 447 \list 448 \li \l{C++ Documentation Style} 449 \li \l{QML Documentation Style} 450 \endlist 451 452 \keyword qml-documentation 453 \section2 Documenting QML Types 454 455 In the world of \l{Qt Quick}{QML}, there are additional entities we need to 456 document such as QML signals, attached properties, and QML methods. 457 Internally, they use Qt technologies, however, QML API documentation 458 requires different layout and naming conventions from the Qt C++ API 459 documentation. 460 461 A list of QML related QDoc commands: 462 \list 463 \li \l{qmlattachedproperty-command}{\\qmlattachedproperty} 464 \li \l{qmlattachedsignal-command}{\\qmlattachedsignal} 465 \li \l{qmlbasictype-command}{\\qmlbasictype} 466 \li \l{qmltype-command}{\\qmltype} - creates a QML type documentation 467 \li \l{qmlmethod-command}{\\qmlmethod} 468 \li \l{qmlproperty-command}{\\qmlproperty} 469 \li \l{qmlsignal-command}{\\qmlsignal} 470 \li \l{inherits-command}{\\inherits} 471 \li \l{qmlmodule-command}{\\qmlmodule} 472 \li \l{inqmlmodule-command}{\\inqmlmodule} 473 \li \l{instantiates-command}{\\instantiates} 474 475 \endlist 476 477 \note Remember to enable QML parsing by including the \c{*.qml} filetype in 478 the \l{qdoc-input-output-dir}{fileextension} variable. 479 480 To document a QML type, start by creating a QDoc comment that uses the 481 \l{qmltype-command} {\\qmltype} command as its topic command. 482 483 \section3 QML Parser 484 485 If your QML type is defined in a \e qml file, document it there. 486 If your QML type is represented by a C++ class, document it in the 487 \e cpp file for that C++ class and include an 488 \l{instantiates-command}{\\instantiates} command to specify the 489 name of the C++ class. Don't document a QML type in a \e{cpp} file 490 if the QML type is defined in a \e{qml} file. 491 492 When documenting a QML type in a \e{qml} file, place each QDoc 493 comment directly above the entity to which the comment applies. 494 For example, place the QDoc comment containing the \e{\\qmltype} 495 command (the topic comment) directly above the outer QML type in 496 the \e{qml} file. Place the comment for documenting a QML property 497 directly above the property declaration, and so on for QML signal 498 handlers and QML methods. Note that when documenting QML 499 properties in a \e{qml} file, you don't normally include the 500 \e{\\qmlproperty} command as a topic command (which you must do 501 when documenting QML types in \e{cpp} files), because the QML 502 parser automatically associates each QDoc comment with the next 503 QML declaration it parses. The same is true for QML signal handler 504 and QML method comments. But it is sometimes useful to include one 505 or more \e{\\qmlproperty} commands in the comment, e.g. when the 506 property type is another QML type and you want the user to only 507 use certain properties within that other QML type, but not all of 508 them. But when documenting a property that has an alias, place the 509 QDoc comment for it directly above the alias declaration. In these 510 cases, the QDoc comment \e must contain a \e{\\qmlproperty} 511 command, because that is the only way QDoc can know the type of 512 the aliased property. 513 514 When documenting a QML type in the \e cpp file of its 515 corresponding C++ class (if it has one), you normally place each 516 QDoc comment directly above the entity it documents. However, QDoc 517 does not use the QML parser to parse these files (the C++ parser 518 is used), so these QML QDoc comments can appear anywhere in the 519 \e{cpp} file. Note that QML QDoc comments in \e cpp files \e must 520 use the QML topic commands. i.e., the \l{qmltype-command} 521 {\\qmltype} command \e must appear in the QDoc comment for the 522 QML type, and a \l{qmlproperty-command} {\\qmlproperty} command \e 523 must appear in each QML property QDoc comment. 524 525 \section3 QML Modules 526 527 A QML type belongs to a \e module. The module 528 may include all the related types for a platform or contain a certain 529 version of \l{Qt Quick}. For example, the Qt Quick 2 QML types belong 530 to the Qt Quick 2 module while there is also a Qt Quick 1 module for the older 531 types introduced in Qt 4. 532 533 QML modules allow grouping QML types. The \l{qmltype-command} 534 {\\qmltype} topic command must have an \l{inqmlmodule-command} 535 {\\inqmlmodule} context command to relate the type to a QML 536 module. Similarly, a \l{qmlmodule-command}{\\qmlmodule} topic 537 command must exist in a separate \c{.qdoc} file to create the 538 overview page for the module. The overview page will list the 539 QML types of the QML module. 540 541 The links to the QML types must therefore also contain the module name. 542 For example, if a type called \c TabWidget is in the \c UIComponents 543 module, it must be linked as \c {UIComponents::TabWidget}. 544 545 \section3 Read-only and Internal QML Properties 546 547 QDoc detects QML properties that are marked as \c readonly. Note that the 548 property must be initialized with a value. 549 550 \badcode 551 readonly property int sampleReadOnlyProperty: 0 552 \endcode 553 554 Properties and signals that are not meant for the public interface may 555 be marked with the \l{internal-command}{\\internal} command. QDoc will not 556 publish the documentation in the generated outputs. 557 558 \section1 Articles & Overviews 559 560 Articles and overviews are a style of writing best used for providing 561 summary detail on a topic or concept. It may introduce a technology or 562 discuss how a concept may be applied, but without discussing exact steps 563 in too much detail. However, this type of content could provide the entry 564 point for readers to find instructional and reference materials that do, 565 such as tutorials, examples and class documentation. An example of an 566 overview might be a product page, such as a top level discussion of 567 Qt Quick, individual modules, design principles, or tools. 568 569 To signify that a document is an article, you append the article keyword 570 to the \\page command: 571 572 \snippet examples/samples.qdocinc sample-overview 573 574 The \l{writing-topic-commands}{writing topic commands} section has a listing 575 of the available \\page command arguments. 576 577 \section1 Tutorials, How-To's, FAQ's 578 579 Tutorials, How-To's, and FAQ's are all instructional material, in that they 580 instruct or prescribe to the reader. Tutorials are content designed to guide 581 the reader along a progressive learning path for a concept or technology. 582 How-To's and FAQ's (\e{Frequently Asked Questions}) provide guidance by 583 presenting material in the form of answers to commonly asked topics. 584 How-To's and FAQ's are designed for easy reference and are not necessarily 585 presented in a linear progression. 586 587 To create these types, mark the pages by providing a \c type argument to the 588 \l{page-command}{\\page} command. The \c type argument is the second 589 argument, with the file name being the first. 590 \snippet examples/samples.qdocinc sample-faq 591 592 The \l{writing-topic-commands}{writing topic commands} section has a listing 593 of the available \\page command arguments. 594 595 \section1 Code Examples 596 Examples are an effective way to demonstrate practical usage of a given 597 technology or concept. When it comes to middleware this is usually in the 598 form of an application using simple code and clear explanations of what the 599 code is doing. Any module, API, project, pattern etc. should have at least 600 one good example. 601 602 An example may have an accompanying tutorial. The tutorial instructs and 603 describes the code, while the code example is the code content that users 604 may study. Code examples may have accompanying text that are not in the 605 tutorial. 606 607 QDoc will create a page containing the example code with a description 608 using the \l{example-command}{\\example} command. 609 610 \snippet examples/samples.qdocinc sample-example 611 612 QDoc will use the directory specified in the input 613 \l{Input and Output Directories}{exampledirs} variable to find the Qt 614 Project (\c .pro) file to generate the example files. The generated HTML 615 will have the filename, \c {declarative-ui-components-tabwidget.html}. QDoc 616 will also list all of the example code. 617 618 \note The example's project file must be the same as the 619 directory name. 620*/ 621 622 623/*! 624 \page qdoc-guide-clang.html 625 \title Installing Clang for QDoc 626 \previouspage Getting Started with QDoc 627 \nextpage Creating QDoc Configuration Files 628 629 QDoc uses Clang when parsing C++ files as well as function signatures in 630 \l {fn-command} {\\fn} commands. Clang is part of 631 \l {https://llvm.org/}{the LLVM Compiler Infrastructure Project}. 632 Therefore, if you are going to build QDoc from source, you need to install 633 \l{http://clang.llvm.org}{LLVM 6.0} or greater first. You can find the 634 required pre-built binaries 635 \l {http://releases.llvm.org/download.html}{here}. 636 637 To build QDoc on Debian-based Linux distributions, it is sufficient to 638 install the \c libclang-dev package and its dependencies. For running QDoc, 639 the \c libclang package is required. 640 641 \note On Windows, after installing the pre-built LLVM you must restart your 642 build shell to ensure that LLVM's binary directory is added to the PATH 643 variable. This is needed to be able to run qdoc. 644 645 \section1 Set Clang location automatically 646 647 The Qt build system uses the tool \c llvm-config to discover the location 648 of LLVM on your system, and relies on the path to llvm-config being in 649 the \c PATH environment variable to do so. \c llvm-config is commonly 650 installed with LLVM and Clang on Linux systems, and also on macOS if 651 LLVM is installed using Brew. 652 653 On Windows, the installation binaries provided by LLVM do not include 654 \c llvm-config. You may still have it on your system, if you have built 655 LLVM yourself from source. If that is the case, and you want to let the 656 build system find Clang automatically, add the path to \c llvm-config 657 to your \c PATH environment variable. For example: 658 659 \badcode 660 C:\> set PATH=%PATH%;C:\[build directory]\bin\Release" 661 \endcode 662 663 Make sure to set the path to your LLVM build directory. The \c llvm-config 664 executable is located in \c {bin\Release} or \c {bin\Debug}, reflecting the 665 build version. 666 667 \section1 Specify Clang location manually 668 669 If \c llvm-config is not in your \c PATH environment variable, or not 670 installed on your system, you can still build QDoc, by manually setting the 671 environment variable \c LLVM_INSTALL_DIR to point to the directory where 672 the Clang libraries are installed. This directory should be the top level 673 directory. For example, on a Linux or macOS system with LLVM installed to 674 \c /usr/llvm: 675 676 \badcode 677 $ export LLVM_INSTALL_DIR=/usr/llvm 678 \endcode 679 680 Debian-based Linux distributions usually offer multiple versions of the 681 \c libclang packages, such as \c libclang-<VERSION>. In this case, 682 \c LLVM_INSTALL_DIR should contain \c /usr/lib/clang/<VERSION> . 683 684 On a Windows system with LLVM installed to \c {C:\Program Files\LLVM}: 685 686 \badcode 687 C:\> set LLVM_INSTALL_DIR=C:\Program Files\LLVM 688 \endcode 689*/ 690