Mercurial > hg > CbC > CbC_llvm

comparison docs/CMake.rst @ 95:afa8332a0e37 LLVM3.8

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
LLVM 3.8
author Kaito Tokumori <e105711@ie.u-ryukyu.ac.jp>
date Tue, 13 Oct 2015 17:48:58 +0900
parents 60c9769439b8
children 7d135dc70f03
comparison
equal deleted inserted replaced
84:f3e34b893a5f 95:afa8332a0e37
8 Introduction 8 Introduction
9 ============ 9 ============
10 10
11 `CMake <http://www.cmake.org/>`_ is a cross-platform build-generator tool. CMake 11 `CMake <http://www.cmake.org/>`_ is a cross-platform build-generator tool. CMake
12 does not build the project, it generates the files needed by your build tool 12 does not build the project, it generates the files needed by your build tool
13 (GNU make, Visual Studio, etc) for building LLVM. 13 (GNU make, Visual Studio, etc.) for building LLVM.
14 14
15 If you are really anxious about getting a functional LLVM build, go to the 15 If you are really anxious about getting a functional LLVM build, go to the
16 `Quick start`_ section. If you are a CMake novice, start on `Basic CMake usage`_ 16 `Quick start`_ section. If you are a CMake novice, start with `Basic CMake usage`_
17 and then go back to the `Quick start`_ once you know what you are doing. The 17 and then go back to the `Quick start`_ section once you know what you are doing. The
18 `Options and variables`_ section is a reference for customizing your build. If 18 `Options and variables`_ section is a reference for customizing your build. If
19 you already have experience with CMake, this is the recommended starting point. 19 you already have experience with CMake, this is the recommended starting point.
20 20
21 .. _Quick start: 21 .. _Quick start:
22 22
29 CMake. Version 2.8.8 is the minimum required. 29 CMake. Version 2.8.8 is the minimum required.
30 30
31 #. Open a shell. Your development tools must be reachable from this shell 31 #. Open a shell. Your development tools must be reachable from this shell
32 through the PATH environment variable. 32 through the PATH environment variable.
33 33
34 #. Create a directory for containing the build. It is not supported to build 34 #. Create a build directory. Building LLVM in the source
35 LLVM on the source directory. cd to this directory: 35 directory is not supported. cd to this directory:
36 36
37 .. code-block:: console 37 .. code-block:: console
38 38
39 $ mkdir mybuilddir 39 $ mkdir mybuilddir
40 $ cd mybuilddir 40 $ cd mybuilddir
41 41
42 #. Execute this command on the shell replacing `path/to/llvm/source/root` with 42 #. Execute this command in the shell replacing `path/to/llvm/source/root` with
43 the path to the root of your LLVM source tree: 43 the path to the root of your LLVM source tree:
44 44
45 .. code-block:: console 45 .. code-block:: console
46 46
47 $ cmake path/to/llvm/source/root 47 $ cmake path/to/llvm/source/root
48 48
49 CMake will detect your development environment, perform a series of test and 49 CMake will detect your development environment, perform a series of tests, and
50 generate the files required for building LLVM. CMake will use default values 50 generate the files required for building LLVM. CMake will use default values
51 for all build parameters. See the `Options and variables`_ section for 51 for all build parameters. See the `Options and variables`_ section for
52 fine-tuning your build 52 a list of build parameters that you can modify.
53 53
54 This can fail if CMake can't detect your toolset, or if it thinks that the 54 This can fail if CMake can't detect your toolset, or if it thinks that the
55 environment is not sane enough. On this case make sure that the toolset that 55 environment is not sane enough. In this case, make sure that the toolset that
56 you intend to use is the only one reachable from the shell and that the shell 56 you intend to use is the only one reachable from the shell, and that the shell
57 itself is the correct one for you development environment. CMake will refuse 57 itself is the correct one for your development environment. CMake will refuse
58 to build MinGW makefiles if you have a POSIX shell reachable through the PATH 58 to build MinGW makefiles if you have a POSIX shell reachable through the PATH
59 environment variable, for instance. You can force CMake to use a given build 59 environment variable, for instance. You can force CMake to use a given build
60 tool, see the `Usage`_ section. 60 tool; for instructions, see the `Usage`_ section, below.
61 61
62 #. After CMake has finished running, proceed to use IDE project files or start 62 #. After CMake has finished running, proceed to use IDE project files, or start
63 the build from the build directory: 63 the build from the build directory:
64 64
65 .. code-block:: console 65 .. code-block:: console
66 66
67 $ cmake --build . 67 $ cmake --build .
68 68
69 The ``--build`` option tells ``cmake`` to invoke the underlying build 69 The ``--build`` option tells ``cmake`` to invoke the underlying build
70 tool (``make``, ``ninja``, ``xcodebuild``, ``msbuild``, etc). 70 tool (``make``, ``ninja``, ``xcodebuild``, ``msbuild``, etc.)
71 71
72 The underlying build tool can be invoked directly either of course, but 72 The underlying build tool can be invoked directly, of course, but
73 the ``--build`` option is portable. 73 the ``--build`` option is portable.
74 74
75 #. After LLVM has finished building, install it from the build directory: 75 #. After LLVM has finished building, install it from the build directory:
76 76
77 .. code-block:: console 77 .. code-block:: console
93 .. _Usage: 93 .. _Usage:
94 94
95 Basic CMake usage 95 Basic CMake usage
96 ================= 96 =================
97 97
98 This section explains basic aspects of CMake, mostly for explaining those 98 This section explains basic aspects of CMake
99 options which you may need on your day-to-day usage. 99 which you may need in your day-to-day usage.
100 100
101 CMake comes with extensive documentation in the form of html files and on the 101 CMake comes with extensive documentation, in the form of html files, and as
102 cmake executable itself. Execute ``cmake --help`` for further help options. 102 online help accessible via the ``cmake`` executable itself. Execute ``cmake
103 103 --help`` for further help options.
104 CMake requires to know for which build tool it shall generate files (GNU make, 104
105 Visual Studio, Xcode, etc). If not specified on the command line, it tries to 105 CMake allows you to specify a build tool (e.g., GNU make, Visual Studio,
106 guess it based on you environment. Once identified the build tool, CMake uses 106 or Xcode). If not specified on the command line, CMake tries to guess which
107 the corresponding *Generator* for creating files for your build tool. You can 107 build tool to use, based on your environment. Once it has identified your
108 build tool, CMake uses the corresponding *Generator* to create files for your
109 build tool (e.g., Makefiles or Visual Studio or Xcode project files). You can
108 explicitly specify the generator with the command line option ``-G "Name of the 110 explicitly specify the generator with the command line option ``-G "Name of the
109 generator"``. For knowing the available generators on your platform, execute 111 generator"``. To see a list of the available generators on your system, execute
110 112
111 .. code-block:: console 113 .. code-block:: console
112 114
113 $ cmake --help 115 $ cmake --help
114 116
115 This will list the generator's names at the end of the help text. Generator's 117 This will list the generator names at the end of the help text.
116 names are case-sensitive. Example: 118
119 Generators' names are case-sensitive, and may contain spaces. For this reason,
120 you should enter them exactly as they are listed in the ``cmake --help``
121 output, in quotes. For example, to generate project files specifically for
122 Visual Studio 12, you can execute:
117 123
118 .. code-block:: console 124 .. code-block:: console
119 125
120 $ cmake -G "Visual Studio 11" path/to/llvm/source/root 126 $ cmake -G "Visual Studio 12" path/to/llvm/source/root
121 127
122 For a given development platform there can be more than one adequate 128 For a given development platform there can be more than one adequate
123 generator. If you use Visual Studio "NMake Makefiles" is a generator you can use 129 generator. If you use Visual Studio, "NMake Makefiles" is a generator you can use
124 for building with NMake. By default, CMake chooses the more specific generator 130 for building with NMake. By default, CMake chooses the most specific generator
125 supported by your development environment. If you want an alternative generator, 131 supported by your development environment. If you want an alternative generator,
126 you must tell this to CMake with the ``-G`` option. 132 you must tell this to CMake with the ``-G`` option.
127 133
128 .. todo:: 134 .. todo::
129 135
140 146
141 .. code-block:: console 147 .. code-block:: console
142 148
143 $ cmake -DVARIABLE=value path/to/llvm/source 149 $ cmake -DVARIABLE=value path/to/llvm/source
144 150
145 You can set a variable after the initial CMake invocation for changing its 151 You can set a variable after the initial CMake invocation to change its
146 value. You can also undefine a variable: 152 value. You can also undefine a variable:
147 153
148 .. code-block:: console 154 .. code-block:: console
149 155
150 $ cmake -UVARIABLE path/to/llvm/source 156 $ cmake -UVARIABLE path/to/llvm/source
151 157
152 Variables are stored on the CMake cache. This is a file named ``CMakeCache.txt`` 158 Variables are stored in the CMake cache. This is a file named ``CMakeCache.txt``
153 on the root of the build directory. Do not hand-edit it. 159 stored at the root of your build directory that is generated by ``cmake``.
154 160 Editing it yourself is not recommended.
155 Variables are listed here appending its type after a colon. It is correct to 161
156 write the variable and the type on the CMake command line: 162 Variables are listed in the CMake cache and later in this document with
163 the variable name and type separated by a colon. You can also specify the
164 variable and type on the CMake command line:
157 165
158 .. code-block:: console 166 .. code-block:: console
159 167
160 $ cmake -DVARIABLE:TYPE=value path/to/llvm/source 168 $ cmake -DVARIABLE:TYPE=value path/to/llvm/source
161 169
162 Frequently-used CMake variables 170 Frequently-used CMake variables
163 ------------------------------- 171 -------------------------------
164 172
165 Here are some of the CMake variables that are used often, along with a 173 Here are some of the CMake variables that are used often, along with a
166 brief explanation and LLVM-specific notes. For full documentation, check the 174 brief explanation and LLVM-specific notes. For full documentation, consult the
167 CMake docs or execute ``cmake --help-variable VARIABLE_NAME``. 175 CMake manual, or execute ``cmake --help-variable VARIABLE_NAME``.
168 176
169 **CMAKE_BUILD_TYPE**:STRING 177 **CMAKE_BUILD_TYPE**:STRING
170 Sets the build type for ``make`` based generators. Possible values are 178 Sets the build type for ``make``-based generators. Possible values are
171 Release, Debug, RelWithDebInfo and MinSizeRel. On systems like Visual Studio 179 Release, Debug, RelWithDebInfo and MinSizeRel. If you are using an IDE such as
172 the user sets the build type with the IDE settings. 180 Visual Studio, you should use the IDE settings to set the build type.
173 181
174 **CMAKE_INSTALL_PREFIX**:PATH 182 **CMAKE_INSTALL_PREFIX**:PATH
175 Path where LLVM will be installed if "make install" is invoked or the 183 Path where LLVM will be installed if "make install" is invoked or the
176 "INSTALL" target is built. 184 "install" target is built.
177 185
178 **LLVM_LIBDIR_SUFFIX**:STRING 186 **LLVM_LIBDIR_SUFFIX**:STRING
179 Extra suffix to append to the directory where libraries are to be 187 Extra suffix to append to the directory where libraries are to be
180 installed. On a 64-bit architecture, one could use ``-DLLVM_LIBDIR_SUFFIX=64`` 188 installed. On a 64-bit architecture, one could use ``-DLLVM_LIBDIR_SUFFIX=64``
181 to install libraries to ``/usr/lib64``. 189 to install libraries to ``/usr/lib64``.
186 **CMAKE_CXX_FLAGS**:STRING 194 **CMAKE_CXX_FLAGS**:STRING
187 Extra flags to use when compiling C++ source files. 195 Extra flags to use when compiling C++ source files.
188 196
189 **BUILD_SHARED_LIBS**:BOOL 197 **BUILD_SHARED_LIBS**:BOOL
190 Flag indicating if shared libraries will be built. Its default value is 198 Flag indicating if shared libraries will be built. Its default value is
191 OFF. Shared libraries are not supported on Windows and not recommended on the 199 OFF. This option is only recommended for use by LLVM developers.
192 other OSes. 200 On Windows, shared libraries may be used when building with MinGW, including
201 mingw-w64, but not when building with the Microsoft toolchain.
193 202
194 .. _LLVM-specific variables: 203 .. _LLVM-specific variables:
195 204
196 LLVM-specific variables 205 LLVM-specific variables
197 ----------------------- 206 -----------------------
201 targets. Case-sensitive. Defaults to *all*. Example: 210 targets. Case-sensitive. Defaults to *all*. Example:
202 ``-DLLVM_TARGETS_TO_BUILD="X86;PowerPC"``. 211 ``-DLLVM_TARGETS_TO_BUILD="X86;PowerPC"``.
203 212
204 **LLVM_BUILD_TOOLS**:BOOL 213 **LLVM_BUILD_TOOLS**:BOOL
205 Build LLVM tools. Defaults to ON. Targets for building each tool are generated 214 Build LLVM tools. Defaults to ON. Targets for building each tool are generated
206 in any case. You can build an tool separately by invoking its target. For 215 in any case. You can build a tool separately by invoking its target. For
207 example, you can build *llvm-as* with a makefile-based system executing *make 216 example, you can build *llvm-as* with a Makefile-based system by executing *make
208 llvm-as* on the root of your build directory. 217 llvm-as* at the root of your build directory.
209 218
210 **LLVM_INCLUDE_TOOLS**:BOOL 219 **LLVM_INCLUDE_TOOLS**:BOOL
211 Generate build targets for the LLVM tools. Defaults to ON. You can use that 220 Generate build targets for the LLVM tools. Defaults to ON. You can use this
212 option for disabling the generation of build targets for the LLVM tools. 221 option to disable the generation of build targets for the LLVM tools.
213 222
214 **LLVM_BUILD_EXAMPLES**:BOOL 223 **LLVM_BUILD_EXAMPLES**:BOOL
215 Build LLVM examples. Defaults to OFF. Targets for building each example are 224 Build LLVM examples. Defaults to OFF. Targets for building each example are
216 generated in any case. See documentation for *LLVM_BUILD_TOOLS* above for more 225 generated in any case. See documentation for *LLVM_BUILD_TOOLS* above for more
217 details. 226 details.
218 227
219 **LLVM_INCLUDE_EXAMPLES**:BOOL 228 **LLVM_INCLUDE_EXAMPLES**:BOOL
220 Generate build targets for the LLVM examples. Defaults to ON. You can use that 229 Generate build targets for the LLVM examples. Defaults to ON. You can use this
221 option for disabling the generation of build targets for the LLVM examples. 230 option to disable the generation of build targets for the LLVM examples.
222 231
223 **LLVM_BUILD_TESTS**:BOOL 232 **LLVM_BUILD_TESTS**:BOOL
224 Build LLVM unit tests. Defaults to OFF. Targets for building each unit test 233 Build LLVM unit tests. Defaults to OFF. Targets for building each unit test
225 are generated in any case. You can build a specific unit test with the target 234 are generated in any case. You can build a specific unit test using the
226 *UnitTestNameTests* (where at this time *UnitTestName* can be ADT, Analysis, 235 targets defined under *unittests*, such as ADTTests, IRTests, SupportTests,
227 ExecutionEngine, JIT, Support, Transform, VMCore; see the subdirectories of 236 etc. (Search for ``add_llvm_unittest`` in the subdirectories of *unittests*
228 *unittests* for an updated list.) It is possible to build all unit tests with 237 for a complete list of unit tests.) It is possible to build all unit tests
229 the target *UnitTests*. 238 with the target *UnitTests*.
230 239
231 **LLVM_INCLUDE_TESTS**:BOOL 240 **LLVM_INCLUDE_TESTS**:BOOL
232 Generate build targets for the LLVM unit tests. Defaults to ON. You can use 241 Generate build targets for the LLVM unit tests. Defaults to ON. You can use
233 that option for disabling the generation of build targets for the LLVM unit 242 this option to disable the generation of build targets for the LLVM unit
234 tests. 243 tests.
235 244
236 **LLVM_APPEND_VC_REV**:BOOL 245 **LLVM_APPEND_VC_REV**:BOOL
237 Append version control revision info (svn revision number or Git revision id) 246 Append version control revision info (svn revision number or Git revision id)
238 to LLVM version string (stored in the PACKAGE_VERSION macro). For this to work 247 to LLVM version string (stored in the PACKAGE_VERSION macro). For this to work
247 **LLVM_ENABLE_ASSERTIONS**:BOOL 256 **LLVM_ENABLE_ASSERTIONS**:BOOL
248 Enables code assertions. Defaults to ON if and only if ``CMAKE_BUILD_TYPE`` 257 Enables code assertions. Defaults to ON if and only if ``CMAKE_BUILD_TYPE``
249 is *Debug*. 258 is *Debug*.
250 259
251 **LLVM_ENABLE_EH**:BOOL 260 **LLVM_ENABLE_EH**:BOOL
252 Build LLVM with exception handling support. This is necessary if you wish to 261 Build LLVM with exception-handling support. This is necessary if you wish to
253 link against LLVM libraries and make use of C++ exceptions in your own code 262 link against LLVM libraries and make use of C++ exceptions in your own code
254 that need to propagate through LLVM code. Defaults to OFF. 263 that need to propagate through LLVM code. Defaults to OFF.
255 264
256 **LLVM_ENABLE_PIC**:BOOL 265 **LLVM_ENABLE_PIC**:BOOL
257 Add the ``-fPIC`` flag for the compiler command-line, if the compiler supports 266 Add the ``-fPIC`` flag to the compiler command-line, if the compiler supports
258 this flag. Some systems, like Windows, do not need this flag. Defaults to ON. 267 this flag. Some systems, like Windows, do not need this flag. Defaults to ON.
259 268
260 **LLVM_ENABLE_RTTI**:BOOL 269 **LLVM_ENABLE_RTTI**:BOOL
261 Build LLVM with run time type information. Defaults to OFF. 270 Build LLVM with run-time type information. Defaults to OFF.
262 271
263 **LLVM_ENABLE_WARNINGS**:BOOL 272 **LLVM_ENABLE_WARNINGS**:BOOL
264 Enable all compiler warnings. Defaults to ON. 273 Enable all compiler warnings. Defaults to ON.
265 274
266 **LLVM_ENABLE_PEDANTIC**:BOOL 275 **LLVM_ENABLE_PEDANTIC**:BOOL
267 Enable pedantic mode. This disables compiler specific extensions, if 276 Enable pedantic mode. This disables compiler-specific extensions, if
268 possible. Defaults to ON. 277 possible. Defaults to ON.
269 278
270 **LLVM_ENABLE_WERROR**:BOOL 279 **LLVM_ENABLE_WERROR**:BOOL
271 Stop and fail build, if a compiler warning is triggered. Defaults to OFF. 280 Stop and fail the build, if a compiler warning is triggered. Defaults to OFF.
281
282 **LLVM_ABI_BREAKING_CHECKS**:STRING
283 Used to decide if LLVM should be built with ABI breaking checks or
284 not. Allowed values are `WITH_ASSERTS` (default), `FORCE_ON` and
285 `FORCE_OFF`. `WITH_ASSERTS` turns on ABI breaking checks in an
286 assertion enabled build. `FORCE_ON` (`FORCE_OFF`) turns them on
287 (off) irrespective of whether normal (`NDEBUG`-based) assertions are
288 enabled or not. A version of LLVM built with ABI breaking checks
289 is not ABI compatible with a version built without it.
272 290
273 **LLVM_BUILD_32_BITS**:BOOL 291 **LLVM_BUILD_32_BITS**:BOOL
274 Build 32-bits executables and libraries on 64-bits systems. This option is 292 Build 32-bit executables and libraries on 64-bit systems. This option is
275 available only on some 64-bits unix systems. Defaults to OFF. 293 available only on some 64-bit Unix systems. Defaults to OFF.
276 294
277 **LLVM_TARGET_ARCH**:STRING 295 **LLVM_TARGET_ARCH**:STRING
278 LLVM target to use for native code generation. This is required for JIT 296 LLVM target to use for native code generation. This is required for JIT
279 generation. It defaults to "host", meaning that it shall pick the architecture 297 generation. It defaults to "host", meaning that it shall pick the architecture
280 of the machine where LLVM is being built. If you are cross-compiling, set it 298 of the machine where LLVM is being built. If you are cross-compiling, set it
281 to the target architecture name. 299 to the target architecture name.
282 300
283 **LLVM_TABLEGEN**:STRING 301 **LLVM_TABLEGEN**:STRING
284 Full path to a native TableGen executable (usually named ``tblgen``). This is 302 Full path to a native TableGen executable (usually named ``llvm-tblgen``). This is
285 intended for cross-compiling: if the user sets this variable, no native 303 intended for cross-compiling: if the user sets this variable, no native
286 TableGen will be created. 304 TableGen will be created.
287 305
288 **LLVM_LIT_ARGS**:STRING 306 **LLVM_LIT_ARGS**:STRING
289 Arguments given to lit. ``make check`` and ``make clang-test`` are affected. 307 Arguments given to lit. ``make check`` and ``make clang-test`` are affected.
290 By default, ``'-sv --no-progress-bar'`` on Visual C++ and Xcode, ``'-sv'`` on 308 By default, ``'-sv --no-progress-bar'`` on Visual C++ and Xcode, ``'-sv'`` on
291 others. 309 others.
292 310
293 **LLVM_LIT_TOOLS_DIR**:PATH 311 **LLVM_LIT_TOOLS_DIR**:PATH
294 The path to GnuWin32 tools for tests. Valid on Windows host. Defaults to "", 312 The path to GnuWin32 tools for tests. Valid on Windows host. Defaults to
295 then Lit seeks tools according to %PATH%. Lit can find tools(eg. grep, sort, 313 the empty string, in which case lit will look for tools needed for tests
296 &c) on LLVM_LIT_TOOLS_DIR at first, without specifying GnuWin32 to %PATH%. 314 (e.g. ``grep``, ``sort``, etc.) in your %PATH%. If GnuWin32 is not in your
315 %PATH%, then you can set this variable to the GnuWin32 directory so that
316 lit can find tools needed for tests in that directory.
297 317
298 **LLVM_ENABLE_FFI**:BOOL 318 **LLVM_ENABLE_FFI**:BOOL
299 Indicates whether LLVM Interpreter will be linked with Foreign Function 319 Indicates whether the LLVM Interpreter will be linked with the Foreign Function
300 Interface library. If the library or its headers are installed on a custom 320 Interface library (libffi) in order to enable calling external functions.
301 location, you can set the variables FFI_INCLUDE_DIR and 321 If the library or its headers are installed in a custom
302 FFI_LIBRARY_DIR. Defaults to OFF. 322 location, you can also set the variables FFI_INCLUDE_DIR and
323 FFI_LIBRARY_DIR to the directories where ffi.h and libffi.so can be found,
324 respectively. Defaults to OFF.
303 325
304 **LLVM_EXTERNAL_{CLANG,LLD,POLLY}_SOURCE_DIR**:PATH 326 **LLVM_EXTERNAL_{CLANG,LLD,POLLY}_SOURCE_DIR**:PATH
305 Path to ``{Clang,lld,Polly}``\'s source directory. Defaults to 327 These variables specify the path to the source directory for the external
306 ``tools/{clang,lld,polly}``. ``{Clang,lld,Polly}`` will not be built when it 328 LLVM projects Clang, lld, and Polly, respectively, relative to the top-level
307 is empty or it does not point to a valid path. 329 source directory. If the in-tree subdirectory for an external project
330 exists (e.g., llvm/tools/clang for Clang), then the corresponding variable
331 will not be used. If the variable for an external project does not point
332 to a valid path, then that project will not be built.
308 333
309 **LLVM_USE_OPROFILE**:BOOL 334 **LLVM_USE_OPROFILE**:BOOL
310 Enable building OProfile JIT support. Defaults to OFF 335 Enable building OProfile JIT support. Defaults to OFF.
336
337 **LLVM_PROFDATA_FILE**:PATH
338 Path to a profdata file to pass into clang's -fprofile-instr-use flag. This
339 can only be specified if you're building with clang.
311 340
312 **LLVM_USE_INTEL_JITEVENTS**:BOOL 341 **LLVM_USE_INTEL_JITEVENTS**:BOOL
313 Enable building support for Intel JIT Events API. Defaults to OFF 342 Enable building support for Intel JIT Events API. Defaults to OFF.
314 343
315 **LLVM_ENABLE_ZLIB**:BOOL 344 **LLVM_ENABLE_ZLIB**:BOOL
316 Build with zlib to support compression/uncompression in LLVM tools. 345 Enable building with zlib to support compression/uncompression in LLVM tools.
317 Defaults to ON. 346 Defaults to ON.
318 347
319 **LLVM_USE_SANITIZER**:STRING 348 **LLVM_USE_SANITIZER**:STRING
320 Define the sanitizer used to build LLVM binaries and tests. Possible values 349 Define the sanitizer used to build LLVM binaries and tests. Possible values
321 are ``Address``, ``Memory``, ``MemoryWithOrigins`` and ``Undefined``. 350 are ``Address``, ``Memory``, ``MemoryWithOrigins``, ``Undefined``, ``Thread``,
322 Defaults to empty string. 351 and ``Address;Undefined``. Defaults to empty string.
323 352
324 **LLVM_PARALLEL_COMPILE_JOBS**:STRING 353 **LLVM_PARALLEL_COMPILE_JOBS**:STRING
325 Define the maximum number of concurrent compilation jobs. 354 Define the maximum number of concurrent compilation jobs.
326 355
327 **LLVM_PARALLEL_LINK_JOBS**:STRING 356 **LLVM_PARALLEL_LINK_JOBS**:STRING
350 ``-DLLVM_ENABLE_DOXYGEN=ON`` and 379 ``-DLLVM_ENABLE_DOXYGEN=ON`` and
351 ``-DLLVM_ENABLE_DOXYGEN_QT_HELP=ON`` are given. Defaults to 380 ``-DLLVM_ENABLE_DOXYGEN_QT_HELP=ON`` are given. Defaults to
352 ``org.llvm.qch``. 381 ``org.llvm.qch``.
353 This option is only useful in combination with 382 This option is only useful in combination with
354 ``-DLLVM_ENABLE_DOXYGEN_QT_HELP=ON``; 383 ``-DLLVM_ENABLE_DOXYGEN_QT_HELP=ON``;
355 otherwise this has no effect. 384 otherwise it has no effect.
356 385
357 **LLVM_DOXYGEN_QHP_NAMESPACE**:STRING 386 **LLVM_DOXYGEN_QHP_NAMESPACE**:STRING
358 Namespace under which the intermediate Qt Help Project file lives. See `Qt 387 Namespace under which the intermediate Qt Help Project file lives. See `Qt
359 Help Project`_ 388 Help Project`_
360 for more information. Defaults to "org.llvm". This option is only useful in 389 for more information. Defaults to "org.llvm". This option is only useful in
361 combination with ``-DLLVM_ENABLE_DOXYGEN_QT_HELP=ON``; otherwise 390 combination with ``-DLLVM_ENABLE_DOXYGEN_QT_HELP=ON``; otherwise
362 this has no effect. 391 it has no effect.
363 392
364 **LLVM_DOXYGEN_QHP_CUST_FILTER_NAME**:STRING 393 **LLVM_DOXYGEN_QHP_CUST_FILTER_NAME**:STRING
365 See `Qt Help Project`_ for 394 See `Qt Help Project`_ for
366 more information. Defaults to the CMake variable ``${PACKAGE_STRING}`` which 395 more information. Defaults to the CMake variable ``${PACKAGE_STRING}`` which
367 is a combination of the package name and version string. This filter can then 396 is a combination of the package name and version string. This filter can then
368 be used in Qt Creator to select only documentation from LLVM when browsing 397 be used in Qt Creator to select only documentation from LLVM when browsing
369 through all the help files that you might have loaded. This option is only 398 through all the help files that you might have loaded. This option is only
370 useful in combination with ``-DLLVM_ENABLE_DOXYGEN_QT_HELP=ON``; 399 useful in combination with ``-DLLVM_ENABLE_DOXYGEN_QT_HELP=ON``;
371 otherwise this has no effect. 400 otherwise it has no effect.
372 401
373 .. _Qt Help Project: http://qt-project.org/doc/qt-4.8/qthelpproject.html#custom-filters 402 .. _Qt Help Project: http://qt-project.org/doc/qt-4.8/qthelpproject.html#custom-filters
374 403
375 **LLVM_DOXYGEN_QHELPGENERATOR_PATH**:STRING 404 **LLVM_DOXYGEN_QHELPGENERATOR_PATH**:STRING
376 The path to the ``qhelpgenerator`` executable. Defaults to whatever CMake's 405 The path to the ``qhelpgenerator`` executable. Defaults to whatever CMake's
377 ``find_program()`` can find. This option is only useful in combination with 406 ``find_program()`` can find. This option is only useful in combination with
378 ``-DLLVM_ENABLE_DOXYGEN_QT_HELP=ON``; otherwise this has no 407 ``-DLLVM_ENABLE_DOXYGEN_QT_HELP=ON``; otherwise it has no
379 effect. 408 effect.
409
410 **LLVM_DOXYGEN_SVG**:BOOL
411 Uses .svg files instead of .png files for graphs in the Doxygen output.
412 Defaults to OFF.
380 413
381 **LLVM_ENABLE_SPHINX**:BOOL 414 **LLVM_ENABLE_SPHINX**:BOOL
382 If enabled CMake will search for the ``sphinx-build`` executable and will make 415 If enabled CMake will search for the ``sphinx-build`` executable and will make
383 the ``SPHINX_OUTPUT_HTML`` and ``SPHINX_OUTPUT_MAN`` CMake options available. 416 the ``SPHINX_OUTPUT_HTML`` and ``SPHINX_OUTPUT_MAN`` CMake options available.
384 Defaults to OFF. 417 Defaults to OFF.
404 errors. Defaults to ON. 437 errors. Defaults to ON.
405 438
406 Executing the test suite 439 Executing the test suite
407 ======================== 440 ========================
408 441
409 Testing is performed when the *check* target is built. For instance, if you are 442 Testing is performed when the *check-all* target is built. For instance, if you are
410 using makefiles, execute this command while on the top level of your build 443 using Makefiles, execute this command in the root of your build directory:
411 directory:
412 444
413 .. code-block:: console 445 .. code-block:: console
414 446
415 $ make check 447 $ make check-all
416 448
417 On Visual Studio, you may run tests to build the project "check". 449 On Visual Studio, you may run tests by building the project "check-all".
450 For more information about testing, see the :doc:`TestingGuide`.
418 451
419 Cross compiling 452 Cross compiling
420 =============== 453 ===============
421 454
422 See `this wiki page <http://www.vtk.org/Wiki/CMake_Cross_Compiling>`_ for 455 See `this wiki page <http://www.vtk.org/Wiki/CMake_Cross_Compiling>`_ for
432 Embedding LLVM in your project 465 Embedding LLVM in your project
433 ============================== 466 ==============================
434 467
435 From LLVM 3.5 onwards both the CMake and autoconf/Makefile build systems export 468 From LLVM 3.5 onwards both the CMake and autoconf/Makefile build systems export
436 LLVM libraries as importable CMake targets. This means that clients of LLVM can 469 LLVM libraries as importable CMake targets. This means that clients of LLVM can
437 now reliably use CMake to develop their own LLVM based projects against an 470 now reliably use CMake to develop their own LLVM-based projects against an
438 installed version of LLVM regardless of how it was built. 471 installed version of LLVM regardless of how it was built.
439 472
440 Here is a simple example of CMakeLists.txt file that imports the LLVM libraries 473 Here is a simple example of a CMakeLists.txt file that imports the LLVM libraries
441 and uses them to build a simple application ``simple-tool``. 474 and uses them to build a simple application ``simple-tool``.
442 475
443 .. code-block:: cmake 476 .. code-block:: cmake
444 477
445 cmake_minimum_required(VERSION 2.8.8) 478 cmake_minimum_required(VERSION 2.8.8)
480 * ``<INSTALL_PREFIX>/share/llvm/cmake/LLVMConfig.cmake`` where 513 * ``<INSTALL_PREFIX>/share/llvm/cmake/LLVMConfig.cmake`` where
481 ``<INSTALL_PREFIX>`` is the install prefix of an installed version of LLVM. 514 ``<INSTALL_PREFIX>`` is the install prefix of an installed version of LLVM.
482 On Linux typically this is ``/usr/share/llvm/cmake/LLVMConfig.cmake``. 515 On Linux typically this is ``/usr/share/llvm/cmake/LLVMConfig.cmake``.
483 516
484 * ``<LLVM_BUILD_ROOT>/share/llvm/cmake/LLVMConfig.cmake`` where 517 * ``<LLVM_BUILD_ROOT>/share/llvm/cmake/LLVMConfig.cmake`` where
485 ``<LLVM_BUILD_ROOT>`` is the root of the LLVM build tree. **Note this only 518 ``<LLVM_BUILD_ROOT>`` is the root of the LLVM build tree. **Note: this is only
486 available when building LLVM with CMake** 519 available when building LLVM with CMake.**
487 520
488 If LLVM is installed in your operating system's normal installation prefix (e.g. 521 If LLVM is installed in your operating system's normal installation prefix (e.g.
489 on Linux this is usually ``/usr/``) ``find_package(LLVM ...)`` will 522 on Linux this is usually ``/usr/``) ``find_package(LLVM ...)`` will
490 automatically find LLVM if it is installed correctly. If LLVM is not installed 523 automatically find LLVM if it is installed correctly. If LLVM is not installed
491 or you wish to build directly against the LLVM build tree you can use 524 or you wish to build directly against the LLVM build tree you can use
514 547
515 ``LLVM_INCLUDE_DIRS`` 548 ``LLVM_INCLUDE_DIRS``
516 A list of include paths to directories containing LLVM header files. 549 A list of include paths to directories containing LLVM header files.
517 550
518 ``LLVM_PACKAGE_VERSION`` 551 ``LLVM_PACKAGE_VERSION``
519 The LLVM version. This string can be used with CMake conditionals. E.g. ``if 552 The LLVM version. This string can be used with CMake conditionals, e.g., ``if
520 (${LLVM_PACKAGE_VERSION} VERSION_LESS "3.5")``. 553 (${LLVM_PACKAGE_VERSION} VERSION_LESS "3.5")``.
521 554
522 ``LLVM_TOOLS_BINARY_DIR`` 555 ``LLVM_TOOLS_BINARY_DIR``
523 The path to the directory containing the LLVM tools (e.g. ``llvm-as``). 556 The path to the directory containing the LLVM tools (e.g. ``llvm-as``).
524 557
567 600
568 add_library(LLVMPassname MODULE Pass.cpp) 601 add_library(LLVMPassname MODULE Pass.cpp)
569 602
570 Note if you intend for this pass to be merged into the LLVM source tree at some 603 Note if you intend for this pass to be merged into the LLVM source tree at some
571 point in the future it might make more sense to use LLVM's internal 604 point in the future it might make more sense to use LLVM's internal
572 add_llvm_loadable_module function instead by... 605 ``add_llvm_loadable_module`` function instead by...
573 606
574 607
575 Adding the following to ``<project dir>/CMakeLists.txt`` (after 608 Adding the following to ``<project dir>/CMakeLists.txt`` (after
576 ``find_package(LLVM ...)``) 609 ``find_package(LLVM ...)``)
577 610
587 add_llvm_loadable_module(LLVMPassname 620 add_llvm_loadable_module(LLVMPassname
588 Pass.cpp 621 Pass.cpp
589 ) 622 )
590 623
591 When you are done developing your pass, you may wish to integrate it 624 When you are done developing your pass, you may wish to integrate it
592 into LLVM source tree. You can achieve it in two easy steps: 625 into the LLVM source tree. You can achieve it in two easy steps:
593 626
594 #. Copying ``<pass name>`` folder into ``<LLVM root>/lib/Transform`` directory. 627 #. Copying ``<pass name>`` folder into ``<LLVM root>/lib/Transform`` directory.
595 628
596 #. Adding ``add_subdirectory(<pass name>)`` line into 629 #. Adding ``add_subdirectory(<pass name>)`` line into
597 ``<LLVM root>/lib/Transform/CMakeLists.txt``. 630 ``<LLVM root>/lib/Transform/CMakeLists.txt``.
603 636
604 Microsoft Visual C++ 637 Microsoft Visual C++
605 -------------------- 638 --------------------
606 639
607 **LLVM_COMPILER_JOBS**:STRING 640 **LLVM_COMPILER_JOBS**:STRING
608 Specifies the maximum number of parallell compiler jobs to use per project 641 Specifies the maximum number of parallel compiler jobs to use per project
609 when building with msbuild or Visual Studio. Only supported for the Visual 642 when building with msbuild or Visual Studio. Only supported for the Visual
610 Studio 2010 CMake generator. 0 means use all processors. Default is 0. 643 Studio 2010 CMake generator. 0 means use all processors. Default is 0.