1.. _makefile_guide: 2 3=================== 4LLVM Makefile Guide 5=================== 6 7.. contents:: 8 :local: 9 10Introduction 11============ 12 13This document provides *usage* information about the LLVM makefile system. While 14loosely patterned after the BSD makefile system, LLVM has taken a departure from 15BSD in order to implement additional features needed by LLVM. Although makefile 16systems, such as ``automake``, were attempted at one point, it has become clear 17that the features needed by LLVM and the ``Makefile`` norm are too great to use 18a more limited tool. Consequently, LLVM requires simply GNU Make 3.79, a widely 19portable makefile processor. LLVM unabashedly makes heavy use of the features of 20GNU Make so the dependency on GNU Make is firm. If you're not familiar with 21``make``, it is recommended that you read the `GNU Makefile Manual 22<http://www.gnu.org/software/make/manual/make.html>`_. 23 24While this document is rightly part of the `LLVM Programmer's 25Manual <ProgrammersManual.html>`_, it is treated separately here because of the 26volume of content and because it is often an early source of bewilderment for 27new developers. 28 29General Concepts 30================ 31 32The LLVM Makefile System is the component of LLVM that is responsible for 33building the software, testing it, generating distributions, checking those 34distributions, installing and uninstalling, etc. It consists of a several files 35throughout the source tree. These files and other general concepts are described 36in this section. 37 38Projects 39-------- 40 41The LLVM Makefile System is quite generous. It not only builds its own software, 42but it can build yours too. Built into the system is knowledge of the 43``llvm/projects`` directory. Any directory under ``projects`` that has both a 44``configure`` script and a ``Makefile`` is assumed to be a project that uses the 45LLVM Makefile system. Building software that uses LLVM does not require the 46LLVM Makefile System nor even placement in the ``llvm/projects`` 47directory. However, doing so will allow your project to get up and running 48quickly by utilizing the built-in features that are used to compile LLVM. LLVM 49compiles itself using the same features of the makefile system as used for 50projects. 51 52For complete details on setting up your projects configuration, simply mimic the 53``llvm/projects/sample`` project. Or for further details, consult the 54`Projects <Projects.html>`_ page. 55 56Variable Values 57--------------- 58 59To use the makefile system, you simply create a file named ``Makefile`` in your 60directory and declare values for certain variables. The variables and values 61that you select determine what the makefile system will do. These variables 62enable rules and processing in the makefile system that automatically Do The 63Right Thing™. 64 65Including Makefiles 66------------------- 67 68Setting variables alone is not enough. You must include into your Makefile 69additional files that provide the rules of the LLVM Makefile system. The various 70files involved are described in the sections that follow. 71 72``Makefile`` 73^^^^^^^^^^^^ 74 75Each directory to participate in the build needs to have a file named 76``Makefile``. This is the file first read by ``make``. It has three 77sections: 78 79#. Settable Variables --- Required that must be set first. 80#. ``include $(LEVEL)/Makefile.common`` --- include the LLVM Makefile system. 81#. Override Variables --- Override variables set by the LLVM Makefile system. 82 83.. _$(LEVEL)/Makefile.common: 84 85``Makefile.common`` 86^^^^^^^^^^^^^^^^^^^ 87 88Every project must have a ``Makefile.common`` file at its top source 89directory. This file serves three purposes: 90 91#. It includes the project's configuration makefile to obtain values determined 92 by the ``configure`` script. This is done by including the 93 `$(LEVEL)/Makefile.config`_ file. 94 95#. It specifies any other (static) values that are needed throughout the 96 project. Only values that are used in all or a large proportion of the 97 project's directories should be placed here. 98 99#. It includes the standard rules for the LLVM Makefile system, 100 `$(LLVM_SRC_ROOT)/Makefile.rules`_. This file is the *guts* of the LLVM 101 ``Makefile`` system. 102 103.. _$(LEVEL)/Makefile.config: 104 105``Makefile.config`` 106^^^^^^^^^^^^^^^^^^^ 107 108Every project must have a ``Makefile.config`` at the top of its *build* 109directory. This file is **generated** by the ``configure`` script from the 110pattern provided by the ``Makefile.config.in`` file located at the top of the 111project's *source* directory. The contents of this file depend largely on what 112configuration items the project uses, however most projects can get what they 113need by just relying on LLVM's configuration found in 114``$(LLVM_OBJ_ROOT)/Makefile.config``. 115 116.. _$(LLVM_SRC_ROOT)/Makefile.rules: 117 118``Makefile.rules`` 119^^^^^^^^^^^^^^^^^^ 120 121This file, located at ``$(LLVM_SRC_ROOT)/Makefile.rules`` is the heart of the 122LLVM Makefile System. It provides all the logic, dependencies, and rules for 123building the targets supported by the system. What it does largely depends on 124the values of ``make`` `variables`_ that have been set *before* 125``Makefile.rules`` is included. 126 127Comments 128^^^^^^^^ 129 130User ``Makefile``\s need not have comments in them unless the construction is 131unusual or it does not strictly follow the rules and patterns of the LLVM 132makefile system. Makefile comments are invoked with the pound (``#``) character. 133The ``#`` character and any text following it, to the end of the line, are 134ignored by ``make``. 135 136Tutorial 137======== 138 139This section provides some examples of the different kinds of modules you can 140build with the LLVM makefile system. In general, each directory you provide will 141build a single object although that object may be composed of additionally 142compiled components. 143 144Libraries 145--------- 146 147Only a few variable definitions are needed to build a regular library. 148Normally, the makefile system will build all the software into a single 149``libname.o`` (pre-linked) object. This means the library is not searchable and 150that the distinction between compilation units has been dissolved. Optionally, 151you can ask for a shared library (.so) or archive library (.a) built. Archive 152libraries are the default. For example: 153 154.. code-block:: makefile 155 156 LIBRARYNAME = mylib 157 SHARED_LIBRARY = 1 158 ARCHIVE_LIBRARY = 1 159 160says to build a library named ``mylib`` with both a shared library 161(``mylib.so``) and an archive library (``mylib.a``) version. The contents of all 162the libraries produced will be the same, they are just constructed differently. 163Note that you normally do not need to specify the sources involved. The LLVM 164Makefile system will infer the source files from the contents of the source 165directory. 166 167The ``LOADABLE_MODULE=1`` directive can be used in conjunction with 168``SHARED_LIBRARY=1`` to indicate that the resulting shared library should be 169openable with the ``dlopen`` function and searchable with the ``dlsym`` function 170(or your operating system's equivalents). While this isn't strictly necessary on 171Linux and a few other platforms, it is required on systems like HP-UX and 172Darwin. You should use ``LOADABLE_MODULE`` for any shared library that you 173intend to be loaded into an tool via the ``-load`` option. See the 174`WritingAnLLVMPass.html <WritingAnLLVMPass.html#makefile>`_ document for an 175example of why you might want to do this. 176 177Bitcode Modules 178^^^^^^^^^^^^^^^ 179 180In some situations, it is desirable to build a single bitcode module from a 181variety of sources, instead of an archive, shared library, or bitcode 182library. Bitcode modules can be specified in addition to any of the other types 183of libraries by defining the `MODULE_NAME`_ variable. For example: 184 185.. code-block:: makefile 186 187 LIBRARYNAME = mylib 188 BYTECODE_LIBRARY = 1 189 MODULE_NAME = mymod 190 191will build a module named ``mymod.bc`` from the sources in the directory. This 192module will be an aggregation of all the bitcode modules derived from the 193sources. The example will also build a bitcode archive containing a bitcode 194module for each compiled source file. The difference is subtle, but important 195depending on how the module or library is to be linked. 196 197Loadable Modules 198^^^^^^^^^^^^^^^^ 199 200In some situations, you need to create a loadable module. Loadable modules can 201be loaded into programs like ``opt`` or ``llc`` to specify additional passes to 202run or targets to support. Loadable modules are also useful for debugging a 203pass or providing a pass with another package if that pass can't be included in 204LLVM. 205 206LLVM provides complete support for building such a module. All you need to do is 207use the ``LOADABLE_MODULE`` variable in your ``Makefile``. For example, to build 208a loadable module named ``MyMod`` that uses the LLVM libraries ``LLVMSupport.a`` 209and ``LLVMSystem.a``, you would specify: 210 211.. code-block:: makefile 212 213 LIBRARYNAME := MyMod 214 LOADABLE_MODULE := 1 215 LINK_COMPONENTS := support system 216 217Use of the ``LOADABLE_MODULE`` facility implies several things: 218 219#. There will be no "``lib``" prefix on the module. This differentiates it from 220 a standard shared library of the same name. 221 222#. The `SHARED_LIBRARY`_ variable is turned on. 223 224#. The `LINK_LIBS_IN_SHARED`_ variable is turned on. 225 226A loadable module is loaded by LLVM via the facilities of libtool's libltdl 227library which is part of ``lib/System`` implementation. 228 229Tools 230----- 231 232For building executable programs (tools), you must provide the name of the tool 233and the names of the libraries you wish to link with the tool. For example: 234 235.. code-block:: makefile 236 237 TOOLNAME = mytool 238 USEDLIBS = mylib 239 LINK_COMPONENTS = support system 240 241says that we are to build a tool name ``mytool`` and that it requires three 242libraries: ``mylib``, ``LLVMSupport.a`` and ``LLVMSystem.a``. 243 244Note that two different variables are use to indicate which libraries are 245linked: ``USEDLIBS`` and ``LLVMLIBS``. This distinction is necessary to support 246projects. ``LLVMLIBS`` refers to the LLVM libraries found in the LLVM object 247directory. ``USEDLIBS`` refers to the libraries built by your project. In the 248case of building LLVM tools, ``USEDLIBS`` and ``LLVMLIBS`` can be used 249interchangeably since the "project" is LLVM itself and ``USEDLIBS`` refers to 250the same place as ``LLVMLIBS``. 251 252Also note that there are two different ways of specifying a library: with a 253``.a`` suffix and without. Without the suffix, the entry refers to the re-linked 254(.o) file which will include *all* symbols of the library. This is 255useful, for example, to include all passes from a library of passes. If the 256``.a`` suffix is used then the library is linked as a searchable library (with 257the ``-l`` option). In this case, only the symbols that are unresolved *at 258that point* will be resolved from the library, if they exist. Other 259(unreferenced) symbols will not be included when the ``.a`` syntax is used. Note 260that in order to use the ``.a`` suffix, the library in question must have been 261built with the ``ARCHIVE_LIBRARY`` option set. 262 263JIT Tools 264^^^^^^^^^ 265 266Many tools will want to use the JIT features of LLVM. To do this, you simply 267specify that you want an execution 'engine', and the makefiles will 268automatically link in the appropriate JIT for the host or an interpreter if none 269is available: 270 271.. code-block:: makefile 272 273 TOOLNAME = my_jit_tool 274 USEDLIBS = mylib 275 LINK_COMPONENTS = engine 276 277Of course, any additional libraries may be listed as other components. To get a 278full understanding of how this changes the linker command, it is recommended 279that you: 280 281.. code-block:: bash 282 283 % cd examples/Fibonacci 284 % make VERBOSE=1 285 286Targets Supported 287================= 288 289This section describes each of the targets that can be built using the LLVM 290Makefile system. Any target can be invoked from any directory but not all are 291applicable to a given directory (e.g. "check", "dist" and "install" will always 292operate as if invoked from the top level directory). 293 294================= =============== ================== 295Target Name Implied Targets Target Description 296================= =============== ================== 297``all`` \ Compile the software recursively. Default target. 298``all-local`` \ Compile the software in the local directory only. 299``check`` \ Change to the ``test`` directory in a project and run the test suite there. 300``check-local`` \ Run a local test suite. Generally this is only defined in the ``Makefile`` of the project's ``test`` directory. 301``clean`` \ Remove built objects recursively. 302``clean-local`` \ Remove built objects from the local directory only. 303``dist`` ``all`` Prepare a source distribution tarball. 304``dist-check`` ``all`` Prepare a source distribution tarball and check that it builds. 305``dist-clean`` ``clean`` Clean source distribution tarball temporary files. 306``install`` ``all`` Copy built objects to installation directory. 307``preconditions`` ``all`` Check to make sure configuration and makefiles are up to date. 308``printvars`` ``all`` Prints variables defined by the makefile system (for debugging). 309``tags`` \ Make C and C++ tags files for emacs and vi. 310``uninstall`` \ Remove built objects from installation directory. 311================= =============== ================== 312 313.. _all: 314 315``all`` (default) 316----------------- 317 318When you invoke ``make`` with no arguments, you are implicitly instructing it to 319seek the ``all`` target (goal). This target is used for building the software 320recursively and will do different things in different directories. For example, 321in a ``lib`` directory, the ``all`` target will compile source files and 322generate libraries. But, in a ``tools`` directory, it will link libraries and 323generate executables. 324 325``all-local`` 326------------- 327 328This target is the same as `all`_ but it operates only on the current directory 329instead of recursively. 330 331``check`` 332--------- 333 334This target can be invoked from anywhere within a project's directories but 335always invokes the `check-local`_ target in the project's ``test`` directory, if 336it exists and has a ``Makefile``. A warning is produced otherwise. If 337`TESTSUITE`_ is defined on the ``make`` command line, it will be passed down to 338the invocation of ``make check-local`` in the ``test`` directory. The intended 339usage for this is to assist in running specific suites of tests. If 340``TESTSUITE`` is not set, the implementation of ``check-local`` should run all 341normal tests. It is up to the project to define what different values for 342``TESTSUTE`` will do. See the `Testing Guide <TestingGuide.html>`_ for further 343details. 344 345``check-local`` 346--------------- 347 348This target should be implemented by the ``Makefile`` in the project's ``test`` 349directory. It is invoked by the ``check`` target elsewhere. Each project is 350free to define the actions of ``check-local`` as appropriate for that 351project. The LLVM project itself uses dejagnu to run a suite of feature and 352regresson tests. Other projects may choose to use dejagnu or any other testing 353mechanism. 354 355``clean`` 356--------- 357 358This target cleans the build directory, recursively removing all things that the 359Makefile builds. The cleaning rules have been made guarded so they shouldn't go 360awry (via ``rm -f $(UNSET_VARIABLE)/*`` which will attempt to erase the entire 361directory structure. 362 363``clean-local`` 364--------------- 365 366This target does the same thing as ``clean`` but only for the current (local) 367directory. 368 369``dist`` 370-------- 371 372This target builds a distribution tarball. It first builds the entire project 373using the ``all`` target and then tars up the necessary files and compresses 374it. The generated tarball is sufficient for a casual source distribution, but 375probably not for a release (see ``dist-check``). 376 377``dist-check`` 378-------------- 379 380This target does the same thing as the ``dist`` target but also checks the 381distribution tarball. The check is made by unpacking the tarball to a new 382directory, configuring it, building it, installing it, and then verifying that 383the installation results are correct (by comparing to the original build). This 384target can take a long time to run but should be done before a release goes out 385to make sure that the distributed tarball can actually be built into a working 386release. 387 388``dist-clean`` 389-------------- 390 391This is a special form of the ``clean`` clean target. It performs a normal 392``clean`` but also removes things pertaining to building the distribution. 393 394``install`` 395----------- 396 397This target finalizes shared objects and executables and copies all libraries, 398headers, executables and documentation to the directory given with the 399``--prefix`` option to ``configure``. When completed, the prefix directory will 400have everything needed to **use** LLVM. 401 402The LLVM makefiles can generate complete **internal** documentation for all the 403classes by using ``doxygen``. By default, this feature is **not** enabled 404because it takes a long time and generates a massive amount of data (>100MB). If 405you want this feature, you must configure LLVM with the --enable-doxygen switch 406and ensure that a modern version of doxygen (1.3.7 or later) is available in 407your ``PATH``. You can download doxygen from `here 408<http://www.stack.nl/~dimitri/doxygen/download.html#latestsrc>`_. 409 410``preconditions`` 411----------------- 412 413This utility target checks to see if the ``Makefile`` in the object directory is 414older than the ``Makefile`` in the source directory and copies it if so. It also 415reruns the ``configure`` script if that needs to be done and rebuilds the 416``Makefile.config`` file similarly. Users may overload this target to ensure 417that sanity checks are run *before* any building of targets as all the targets 418depend on ``preconditions``. 419 420``printvars`` 421------------- 422 423This utility target just causes the LLVM makefiles to print out some of the 424makefile variables so that you can double check how things are set. 425 426``reconfigure`` 427--------------- 428 429This utility target will force a reconfigure of LLVM or your project. It simply 430runs ``$(PROJ_OBJ_ROOT)/config.status --recheck`` to rerun the configuration 431tests and rebuild the configured files. This isn't generally useful as the 432makefiles will reconfigure themselves whenever its necessary. 433 434``spotless`` 435------------ 436 437.. warning:: 438 439 Use with caution! 440 441This utility target, only available when ``$(PROJ_OBJ_ROOT)`` is not the same as 442``$(PROJ_SRC_ROOT)``, will completely clean the ``$(PROJ_OBJ_ROOT)`` directory 443by removing its content entirely and reconfiguring the directory. This returns 444the ``$(PROJ_OBJ_ROOT)`` directory to a completely fresh state. All content in 445the directory except configured files and top-level makefiles will be lost. 446 447``tags`` 448-------- 449 450This target will generate a ``TAGS`` file in the top-level source directory. It 451is meant for use with emacs, XEmacs, or ViM. The TAGS file provides an index of 452symbol definitions so that the editor can jump you to the definition 453quickly. 454 455``uninstall`` 456------------- 457 458This target is the opposite of the ``install`` target. It removes the header, 459library and executable files from the installation directories. Note that the 460directories themselves are not removed because it is not guaranteed that LLVM is 461the only thing installing there (e.g. ``--prefix=/usr``). 462 463.. _variables: 464 465Variables 466========= 467 468Variables are used to tell the LLVM Makefile System what to do and to obtain 469information from it. Variables are also used internally by the LLVM Makefile 470System. Variable names that contain only the upper case alphabetic letters and 471underscore are intended for use by the end user. All other variables are 472internal to the LLVM Makefile System and should not be relied upon nor 473modified. The sections below describe how to use the LLVM Makefile 474variables. 475 476Control Variables 477----------------- 478 479Variables listed in the table below should be set *before* the inclusion of 480`$(LEVEL)/Makefile.common`_. These variables provide input to the LLVM make 481system that tell it what to do for the current directory. 482 483``BUILD_ARCHIVE`` 484 If set to any value, causes an archive (.a) library to be built. 485 486``BUILT_SOURCES`` 487 Specifies a set of source files that are generated from other source 488 files. These sources will be built before any other target processing to 489 ensure they are present. 490 491``BYTECODE_LIBRARY`` 492 If set to any value, causes a bitcode library (.bc) to be built. 493 494``CONFIG_FILES`` 495 Specifies a set of configuration files to be installed. 496 497``DEBUG_SYMBOLS`` 498 If set to any value, causes the build to include debugging symbols even in 499 optimized objects, libraries and executables. This alters the flags 500 specified to the compilers and linkers. Debugging isn't fun in an optimized 501 build, but it is possible. 502 503``DIRS`` 504 Specifies a set of directories, usually children of the current directory, 505 that should also be made using the same goal. These directories will be 506 built serially. 507 508``DISABLE_AUTO_DEPENDENCIES`` 509 If set to any value, causes the makefiles to **not** automatically generate 510 dependencies when running the compiler. Use of this feature is discouraged 511 and it may be removed at a later date. 512 513``ENABLE_OPTIMIZED`` 514 If set to 1, causes the build to generate optimized objects, libraries and 515 executables. This alters the flags specified to the compilers and 516 linkers. Generally debugging won't be a fun experience with an optimized 517 build. 518 519``ENABLE_PROFILING`` 520 If set to 1, causes the build to generate both optimized and profiled 521 objects, libraries and executables. This alters the flags specified to the 522 compilers and linkers to ensure that profile data can be collected from the 523 tools built. Use the ``gprof`` tool to analyze the output from the profiled 524 tools (``gmon.out``). 525 526``DISABLE_ASSERTIONS`` 527 If set to 1, causes the build to disable assertions, even if building a 528 debug or profile build. This will exclude all assertion check code from the 529 build. LLVM will execute faster, but with little help when things go 530 wrong. 531 532``EXPERIMENTAL_DIRS`` 533 Specify a set of directories that should be built, but if they fail, it 534 should not cause the build to fail. Note that this should only be used 535 temporarily while code is being written. 536 537``EXPORTED_SYMBOL_FILE`` 538 Specifies the name of a single file that contains a list of the symbols to 539 be exported by the linker. One symbol per line. 540 541``EXPORTED_SYMBOL_LIST`` 542 Specifies a set of symbols to be exported by the linker. 543 544``EXTRA_DIST`` 545 Specifies additional files that should be distributed with LLVM. All source 546 files, all built sources, all Makefiles, and most documentation files will 547 be automatically distributed. Use this variable to distribute any files that 548 are not automatically distributed. 549 550``KEEP_SYMBOLS`` 551 If set to any value, specifies that when linking executables the makefiles 552 should retain debug symbols in the executable. Normally, symbols are 553 stripped from the executable. 554 555``LEVEL`` (required) 556 Specify the level of nesting from the top level. This variable must be set 557 in each makefile as it is used to find the top level and thus the other 558 makefiles. 559 560``LIBRARYNAME`` 561 Specify the name of the library to be built. (Required For Libraries) 562 563``LINK_COMPONENTS`` 564 When specified for building a tool, the value of this variable will be 565 passed to the ``llvm-config`` tool to generate a link line for the 566 tool. Unlike ``USEDLIBS`` and ``LLVMLIBS``, not all libraries need to be 567 specified. The ``llvm-config`` tool will figure out the library dependencies 568 and add any libraries that are needed. The ``USEDLIBS`` variable can still 569 be used in conjunction with ``LINK_COMPONENTS`` so that additional 570 project-specific libraries can be linked with the LLVM libraries specified 571 by ``LINK_COMPONENTS``. 572 573.. _LINK_LIBS_IN_SHARED: 574 575``LINK_LIBS_IN_SHARED`` 576 By default, shared library linking will ignore any libraries specified with 577 the `LLVMLIBS`_ or `USEDLIBS`_. This prevents shared libs from including 578 things that will be in the LLVM tool the shared library will be loaded 579 into. However, sometimes it is useful to link certain libraries into your 580 shared library and this option enables that feature. 581 582.. _LLVMLIBS: 583 584``LLVMLIBS`` 585 Specifies the set of libraries from the LLVM ``$(ObjDir)`` that will be 586 linked into the tool or library. 587 588``LOADABLE_MODULE`` 589 If set to any value, causes the shared library being built to also be a 590 loadable module. Loadable modules can be opened with the dlopen() function 591 and searched with dlsym (or the operating system's equivalent). Note that 592 setting this variable without also setting ``SHARED_LIBRARY`` will have no 593 effect. 594 595.. _MODULE_NAME: 596 597``MODULE_NAME`` 598 Specifies the name of a bitcode module to be created. A bitcode module can 599 be specified in conjunction with other kinds of library builds or by 600 itself. It constructs from the sources a single linked bitcode file. 601 602``NO_INSTALL`` 603 Specifies that the build products of the directory should not be installed 604 but should be built even if the ``install`` target is given. This is handy 605 for directories that build libraries or tools that are only used as part of 606 the build process, such as code generators (e.g. ``tblgen``). 607 608``OPTIONAL_DIRS`` 609 Specify a set of directories that may be built, if they exist, but its not 610 an error for them not to exist. 611 612``PARALLEL_DIRS`` 613 Specify a set of directories to build recursively and in parallel if the 614 ``-j`` option was used with ``make``. 615 616.. _SHARED_LIBRARY: 617 618``SHARED_LIBRARY`` 619 If set to any value, causes a shared library (``.so``) to be built in 620 addition to any other kinds of libraries. Note that this option will cause 621 all source files to be built twice: once with options for position 622 independent code and once without. Use it only where you really need a 623 shared library. 624 625``SOURCES`` (optional) 626 Specifies the list of source files in the current directory to be 627 built. Source files of any type may be specified (programs, documentation, 628 config files, etc.). If not specified, the makefile system will infer the 629 set of source files from the files present in the current directory. 630 631``SUFFIXES`` 632 Specifies a set of filename suffixes that occur in suffix match rules. Only 633 set this if your local ``Makefile`` specifies additional suffix match 634 rules. 635 636``TARGET`` 637 Specifies the name of the LLVM code generation target that the current 638 directory builds. Setting this variable enables additional rules to build 639 ``.inc`` files from ``.td`` files. 640 641.. _TESTSUITE: 642 643``TESTSUITE`` 644 Specifies the directory of tests to run in ``llvm/test``. 645 646``TOOLNAME`` 647 Specifies the name of the tool that the current directory should build. 648 649``TOOL_VERBOSE`` 650 Implies ``VERBOSE`` and also tells each tool invoked to be verbose. This is 651 handy when you're trying to see the sub-tools invoked by each tool invoked 652 by the makefile. For example, this will pass ``-v`` to the GCC compilers 653 which causes it to print out the command lines it uses to invoke sub-tools 654 (compiler, assembler, linker). 655 656.. _USEDLIBS: 657 658``USEDLIBS`` 659 Specifies the list of project libraries that will be linked into the tool or 660 library. 661 662``VERBOSE`` 663 Tells the Makefile system to produce detailed output of what it is doing 664 instead of just summary comments. This will generate a LOT of output. 665 666Override Variables 667------------------ 668 669Override variables can be used to override the default values provided by the 670LLVM makefile system. These variables can be set in several ways: 671 672* In the environment (e.g. setenv, export) --- not recommended. 673* On the ``make`` command line --- recommended. 674* On the ``configure`` command line. 675* In the Makefile (only *after* the inclusion of `$(LEVEL)/Makefile.common`_). 676 677The override variables are given below: 678 679``AR`` (defaulted) 680 Specifies the path to the ``ar`` tool. 681 682``PROJ_OBJ_DIR`` 683 The directory into which the products of build rules will be placed. This 684 might be the same as `PROJ_SRC_DIR`_ but typically is not. 685 686.. _PROJ_SRC_DIR: 687 688``PROJ_SRC_DIR`` 689 The directory which contains the source files to be built. 690 691``BUILD_EXAMPLES`` 692 If set to 1, build examples in ``examples`` and (if building Clang) 693 ``tools/clang/examples`` directories. 694 695``BZIP2`` (configured) 696 The path to the ``bzip2`` tool. 697 698``CC`` (configured) 699 The path to the 'C' compiler. 700 701``CFLAGS`` 702 Additional flags to be passed to the 'C' compiler. 703 704``CXX`` 705 Specifies the path to the C++ compiler. 706 707``CXXFLAGS`` 708 Additional flags to be passed to the C++ compiler. 709 710``DATE`` (configured) 711 Specifies the path to the ``date`` program or any program that can generate 712 the current date and time on its standard output. 713 714``DOT`` (configured) 715 Specifies the path to the ``dot`` tool or ``false`` if there isn't one. 716 717``ECHO`` (configured) 718 Specifies the path to the ``echo`` tool for printing output. 719 720``EXEEXT`` (configured) 721 Provides the extension to be used on executables built by the makefiles. 722 The value may be empty on platforms that do not use file extensions for 723 executables (e.g. Unix). 724 725``INSTALL`` (configured) 726 Specifies the path to the ``install`` tool. 727 728``LDFLAGS`` (configured) 729 Allows users to specify additional flags to pass to the linker. 730 731``LIBS`` (configured) 732 The list of libraries that should be linked with each tool. 733 734``LIBTOOL`` (configured) 735 Specifies the path to the ``libtool`` tool. This tool is renamed ``mklib`` 736 by the ``configure`` script. 737 738``LLVMAS`` (defaulted) 739 Specifies the path to the ``llvm-as`` tool. 740 741``LLVMCC`` 742 Specifies the path to the LLVM capable compiler. 743 744``LLVMCXX`` 745 Specifies the path to the LLVM C++ capable compiler. 746 747``LLVMGCC`` (defaulted) 748 Specifies the path to the LLVM version of the GCC 'C' Compiler. 749 750``LLVMGXX`` (defaulted) 751 Specifies the path to the LLVM version of the GCC C++ Compiler. 752 753``LLVMLD`` (defaulted) 754 Specifies the path to the LLVM bitcode linker tool 755 756``LLVM_OBJ_ROOT`` (configured) 757 Specifies the top directory into which the output of the build is placed. 758 759``LLVM_SRC_ROOT`` (configured) 760 Specifies the top directory in which the sources are found. 761 762``LLVM_TARBALL_NAME`` (configured) 763 Specifies the name of the distribution tarball to create. This is configured 764 from the name of the project and its version number. 765 766``MKDIR`` (defaulted) 767 Specifies the path to the ``mkdir`` tool that creates directories. 768 769``ONLY_TOOLS`` 770 If set, specifies the list of tools to build. 771 772``PLATFORMSTRIPOPTS`` 773 The options to provide to the linker to specify that a stripped (no symbols) 774 executable should be built. 775 776``RANLIB`` (defaulted) 777 Specifies the path to the ``ranlib`` tool. 778 779``RM`` (defaulted) 780 Specifies the path to the ``rm`` tool. 781 782``SED`` (defaulted) 783 Specifies the path to the ``sed`` tool. 784 785``SHLIBEXT`` (configured) 786 Provides the filename extension to use for shared libraries. 787 788``TBLGEN`` (defaulted) 789 Specifies the path to the ``tblgen`` tool. 790 791``TAR`` (defaulted) 792 Specifies the path to the ``tar`` tool. 793 794``ZIP`` (defaulted) 795 Specifies the path to the ``zip`` tool. 796 797Readable Variables 798------------------ 799 800Variables listed in the table below can be used by the user's Makefile but 801should not be changed. Changing the value will generally cause the build to go 802wrong, so don't do it. 803 804``bindir`` 805 The directory into which executables will ultimately be installed. This 806 value is derived from the ``--prefix`` option given to ``configure``. 807 808``BuildMode`` 809 The name of the type of build being performed: Debug, Release, or 810 Profile. 811 812``bytecode_libdir`` 813 The directory into which bitcode libraries will ultimately be installed. 814 This value is derived from the ``--prefix`` option given to ``configure``. 815 816``ConfigureScriptFLAGS`` 817 Additional flags given to the ``configure`` script when reconfiguring. 818 819``DistDir`` 820 The *current* directory for which a distribution copy is being made. 821 822.. _Echo: 823 824``Echo`` 825 The LLVM Makefile System output command. This provides the ``llvm[n]`` 826 prefix and starts with ``@`` so the command itself is not printed by 827 ``make``. 828 829``EchoCmd`` 830 Same as `Echo`_ but without the leading ``@``. 831 832``includedir`` 833 The directory into which include files will ultimately be installed. This 834 value is derived from the ``--prefix`` option given to ``configure``. 835 836``libdir`` 837 The directory into which native libraries will ultimately be installed. 838 This value is derived from the ``--prefix`` option given to 839 ``configure``. 840 841``LibDir`` 842 The configuration specific directory into which libraries are placed before 843 installation. 844 845``MakefileConfig`` 846 Full path of the ``Makefile.config`` file. 847 848``MakefileConfigIn`` 849 Full path of the ``Makefile.config.in`` file. 850 851``ObjDir`` 852 The configuration and directory specific directory where build objects 853 (compilation results) are placed. 854 855``SubDirs`` 856 The complete list of sub-directories of the current directory as 857 specified by other variables. 858 859``Sources`` 860 The complete list of source files. 861 862``sysconfdir`` 863 The directory into which configuration files will ultimately be 864 installed. This value is derived from the ``--prefix`` option given to 865 ``configure``. 866 867``ToolDir`` 868 The configuration specific directory into which executables are placed 869 before they are installed. 870 871``TopDistDir`` 872 The top most directory into which the distribution files are copied. 873 874``Verb`` 875 Use this as the first thing on your build script lines to enable or disable 876 verbose mode. It expands to either an ``@`` (quiet mode) or nothing (verbose 877 mode). 878 879Internal Variables 880------------------ 881 882Variables listed below are used by the LLVM Makefile System and considered 883internal. You should not use these variables under any circumstances. 884 885.. code-block:: makefile 886 887 Archive 888 AR.Flags 889 BaseNameSources 890 BCCompile.C 891 BCCompile.CXX 892 BCLinkLib 893 C.Flags 894 Compile.C 895 CompileCommonOpts 896 Compile.CXX 897 ConfigStatusScript 898 ConfigureScript 899 CPP.Flags 900 CPP.Flags 901 CXX.Flags 902 DependFiles 903 DestArchiveLib 904 DestBitcodeLib 905 DestModule 906 DestSharedLib 907 DestTool 908 DistAlways 909 DistCheckDir 910 DistCheckTop 911 DistFiles 912 DistName 913 DistOther 914 DistSources 915 DistSubDirs 916 DistTarBZ2 917 DistTarGZip 918 DistZip 919 ExtraLibs 920 FakeSources 921 INCFiles 922 InternalTargets 923 LD.Flags 924 LibName.A 925 LibName.BC 926 LibName.LA 927 LibName.O 928 LibTool.Flags 929 Link 930 LinkModule 931 LLVMLibDir 932 LLVMLibsOptions 933 LLVMLibsPaths 934 LLVMToolDir 935 LLVMUsedLibs 936 LocalTargets 937 Module 938 ObjectsBC 939 ObjectsLO 940 ObjectsO 941 ObjMakefiles 942 ParallelTargets 943 PreConditions 944 ProjLibsOptions 945 ProjLibsPaths 946 ProjUsedLibs 947 Ranlib 948 RecursiveTargets 949 SrcMakefiles 950 Strip 951 StripWarnMsg 952 TableGen 953 TDFiles 954 ToolBuildPath 955 TopLevelTargets 956 UserTargets 957