[llvm] r245911 - [docs] Improvements to CMake.rst
Sean Silva via llvm-commits
llvm-commits at lists.llvm.org
Mon Aug 24 22:41:38 PDT 2015
Thanks Vedant and Brian!
On Mon, Aug 24, 2015 at 5:09 PM, Vedant Kumar via llvm-commits <
llvm-commits at lists.llvm.org> wrote:
> Author: vedantk
> Date: Mon Aug 24 19:09:47 2015
> New Revision: 245911
>
> URL: http://llvm.org/viewvc/llvm-project?rev=245911&view=rev
> Log:
> [docs] Improvements to CMake.rst
>
> - Fix some grammatical and typographical errors.
> - Try to improve upon some awkward/nonstandard phrasings.
> - Expand slightly the treatment of how you specify arguments to cmake.
> - Update the list of possible LLVM_BUILD_TESTS and state where to find the
> definitive list.
> - Correct the name of llvm-tblgen.
> - Expand slightly the treatment of several build options, including
> LLVM_LIT_TOOLS_DIR, LLVM_ENABLE_FFI, and
> LLVM_EXTERNAL_project_SOURCE_DIR.
>
> Patch by Brian R. Gaeke!
>
> Differential Revision: http://reviews.llvm.org/D11862
>
> Modified:
> llvm/trunk/docs/CMake.rst
>
> Modified: llvm/trunk/docs/CMake.rst
> URL:
> http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/CMake.rst?rev=245911&r1=245910&r2=245911&view=diff
>
> ==============================================================================
> --- llvm/trunk/docs/CMake.rst (original)
> +++ llvm/trunk/docs/CMake.rst Mon Aug 24 19:09:47 2015
> @@ -10,11 +10,11 @@ Introduction
>
> `CMake <http://www.cmake.org/>`_ is a cross-platform build-generator
> tool. CMake
> does not build the project, it generates the files needed by your build
> tool
> -(GNU make, Visual Studio, etc) for building LLVM.
> +(GNU make, Visual Studio, etc.) for building LLVM.
>
> If you are really anxious about getting a functional LLVM build, go to the
> -`Quick start`_ section. If you are a CMake novice, start on `Basic CMake
> usage`_
> -and then go back to the `Quick start`_ once you know what you are doing.
> The
> +`Quick start`_ section. If you are a CMake novice, start with `Basic
> CMake usage`_
> +and then go back to the `Quick start`_ section once you know what you are
> doing. The
> `Options and variables`_ section is a reference for customizing your
> build. If
> you already have experience with CMake, this is the recommended starting
> point.
>
> @@ -31,35 +31,35 @@ We use here the command-line, non-intera
> #. Open a shell. Your development tools must be reachable from this shell
> through the PATH environment variable.
>
> -#. Create a directory for containing the build. It is not supported to
> build
> - LLVM on the source directory. cd to this directory:
> +#. Create a build directory. Building LLVM in the source
> + directory is not supported. cd to this directory:
>
> .. code-block:: console
>
> $ mkdir mybuilddir
> $ cd mybuilddir
>
> -#. Execute this command on the shell replacing `path/to/llvm/source/root`
> with
> +#. Execute this command in the shell replacing `path/to/llvm/source/root`
> with
> the path to the root of your LLVM source tree:
>
> .. code-block:: console
>
> $ cmake path/to/llvm/source/root
>
> - CMake will detect your development environment, perform a series of
> test and
> + CMake will detect your development environment, perform a series of
> tests, and
> generate the files required for building LLVM. CMake will use default
> values
> for all build parameters. See the `Options and variables`_ section for
> - fine-tuning your build
> + a list of build parameters that you can modify.
>
> This can fail if CMake can't detect your toolset, or if it thinks that
> the
> - environment is not sane enough. On this case make sure that the
> toolset that
> - you intend to use is the only one reachable from the shell and that
> the shell
> - itself is the correct one for you development environment. CMake will
> refuse
> + environment is not sane enough. In this case, make sure that the
> toolset that
> + you intend to use is the only one reachable from the shell, and that
> the shell
> + itself is the correct one for your development environment. CMake will
> refuse
> to build MinGW makefiles if you have a POSIX shell reachable through
> the PATH
> environment variable, for instance. You can force CMake to use a given
> build
> - tool, see the `Usage`_ section.
> + tool; for instructions, see the `Usage`_ section, below.
>
> -#. After CMake has finished running, proceed to use IDE project files or
> start
> +#. After CMake has finished running, proceed to use IDE project files, or
> start
> the build from the build directory:
>
> .. code-block:: console
> @@ -67,9 +67,9 @@ We use here the command-line, non-intera
> $ cmake --build .
>
> The ``--build`` option tells ``cmake`` to invoke the underlying build
> - tool (``make``, ``ninja``, ``xcodebuild``, ``msbuild``, etc).
> + tool (``make``, ``ninja``, ``xcodebuild``, ``msbuild``, etc.)
>
> - The underlying build tool can be invoked directly either of course, but
> + The underlying build tool can be invoked directly, of course, but
> the ``--build`` option is portable.
>
> #. After LLVM has finished building, install it from the build directory:
> @@ -95,33 +95,39 @@ We use here the command-line, non-intera
> Basic CMake usage
> =================
>
> -This section explains basic aspects of CMake, mostly for explaining those
> -options which you may need on your day-to-day usage.
> +This section explains basic aspects of CMake
> +which you may need in your day-to-day usage.
>
> -CMake comes with extensive documentation in the form of html files and on
> the
> -cmake executable itself. Execute ``cmake --help`` for further help
> options.
> -
> -CMake requires to know for which build tool it shall generate files (GNU
> make,
> -Visual Studio, Xcode, etc). If not specified on the command line, it
> tries to
> -guess it based on you environment. Once identified the build tool, CMake
> uses
> -the corresponding *Generator* for creating files for your build tool. You
> can
> +CMake comes with extensive documentation, in the form of html files, and
> as
> +online help accessible via the ``cmake`` executable itself. Execute
> ``cmake
> +--help`` for further help options.
> +
> +CMake allows you to specify a build tool (e.g., GNU make, Visual Studio,
> +or Xcode). If not specified on the command line, CMake tries to guess
> which
> +build tool to use, based on your environment. Once it has identified your
> +build tool, CMake uses the corresponding *Generator* to create files for
> your
> +build tool (e.g., Makefiles or Visual Studio or Xcode project files). You
> can
> explicitly specify the generator with the command line option ``-G "Name
> of the
> -generator"``. For knowing the available generators on your platform,
> execute
> +generator"``. To see a list of the available generators on your system,
> execute
>
> .. code-block:: console
>
> $ cmake --help
>
> -This will list the generator's names at the end of the help text.
> Generator's
> -names are case-sensitive. Example:
> +This will list the generator names at the end of the help text.
> +
> +Generators' names are case-sensitive, and may contain spaces. For this
> reason,
> +you should enter them exactly as they are listed in the ``cmake --help``
> +output, in quotes. For example, to generate project files specifically for
> +Visual Studio 12, you can execute:
>
> .. code-block:: console
>
> - $ cmake -G "Visual Studio 11" path/to/llvm/source/root
> + $ cmake -G "Visual Studio 12" path/to/llvm/source/root
>
> For a given development platform there can be more than one adequate
> -generator. If you use Visual Studio "NMake Makefiles" is a generator you
> can use
> -for building with NMake. By default, CMake chooses the more specific
> generator
> +generator. If you use Visual Studio, "NMake Makefiles" is a generator you
> can use
> +for building with NMake. By default, CMake chooses the most specific
> generator
> supported by your development environment. If you want an alternative
> generator,
> you must tell this to CMake with the ``-G`` option.
>
> @@ -142,18 +148,20 @@ CMake command line like this:
>
> $ cmake -DVARIABLE=value path/to/llvm/source
>
> -You can set a variable after the initial CMake invocation for changing its
> +You can set a variable after the initial CMake invocation to change its
> value. You can also undefine a variable:
>
> .. code-block:: console
>
> $ cmake -UVARIABLE path/to/llvm/source
>
> -Variables are stored on the CMake cache. This is a file named
> ``CMakeCache.txt``
> -on the root of the build directory. Do not hand-edit it.
> -
> -Variables are listed here appending its type after a colon. It is correct
> to
> -write the variable and the type on the CMake command line:
> +Variables are stored in the CMake cache. This is a file named
> ``CMakeCache.txt``
> +stored at the root of your build directory that is generated by ``cmake``.
> +Editing it yourself is not recommended.
> +
> +Variables are listed in the CMake cache and later in this document with
> +the variable name and type separated by a colon. You can also specify the
> +variable and type on the CMake command line:
>
> .. code-block:: console
>
> @@ -163,17 +171,17 @@ Frequently-used CMake variables
> -------------------------------
>
> Here are some of the CMake variables that are used often, along with a
> -brief explanation and LLVM-specific notes. For full documentation, check
> the
> -CMake docs or execute ``cmake --help-variable VARIABLE_NAME``.
> +brief explanation and LLVM-specific notes. For full documentation,
> consult the
> +CMake manual, or execute ``cmake --help-variable VARIABLE_NAME``.
>
> **CMAKE_BUILD_TYPE**:STRING
> - Sets the build type for ``make`` based generators. Possible values are
> - Release, Debug, RelWithDebInfo and MinSizeRel. On systems like Visual
> Studio
> - the user sets the build type with the IDE settings.
> + Sets the build type for ``make``-based generators. Possible values are
> + Release, Debug, RelWithDebInfo and MinSizeRel. If you are using an IDE
> such as
> + Visual Studio, you should use the IDE settings to set the build type.
>
> **CMAKE_INSTALL_PREFIX**:PATH
> Path where LLVM will be installed if "make install" is invoked or the
> - "INSTALL" target is built.
> + "install" target is built.
>
> **LLVM_LIBDIR_SUFFIX**:STRING
> Extra suffix to append to the directory where libraries are to be
> @@ -188,8 +196,9 @@ CMake docs or execute ``cmake --help-var
>
> **BUILD_SHARED_LIBS**:BOOL
> Flag indicating if shared libraries will be built. Its default value is
> - OFF. Shared libraries are not supported on Windows and not recommended
> on the
> - other OSes.
> + OFF. This option is only recommended for use by LLVM developers.
> + On Windows, shared libraries may be used when building with MinGW,
> including
> + mingw-w64, but not when building with the Microsoft toolchain.
>
> .. _LLVM-specific variables:
>
> @@ -203,13 +212,13 @@ LLVM-specific variables
>
> **LLVM_BUILD_TOOLS**:BOOL
> Build LLVM tools. Defaults to ON. Targets for building each tool are
> generated
> - in any case. You can build an tool separately by invoking its target.
> For
> - example, you can build *llvm-as* with a makefile-based system executing
> *make
> - llvm-as* on the root of your build directory.
> + in any case. You can build a tool separately by invoking its target. For
> + example, you can build *llvm-as* with a Makefile-based system by
> executing *make
> + llvm-as* at the root of your build directory.
>
> **LLVM_INCLUDE_TOOLS**:BOOL
> - Generate build targets for the LLVM tools. Defaults to ON. You can use
> that
> - option for disabling the generation of build targets for the LLVM tools.
> + Generate build targets for the LLVM tools. Defaults to ON. You can use
> this
> + option to disable the generation of build targets for the LLVM tools.
>
> **LLVM_BUILD_EXAMPLES**:BOOL
> Build LLVM examples. Defaults to OFF. Targets for building each example
> are
> @@ -217,20 +226,20 @@ LLVM-specific variables
> details.
>
> **LLVM_INCLUDE_EXAMPLES**:BOOL
> - Generate build targets for the LLVM examples. Defaults to ON. You can
> use that
> - option for disabling the generation of build targets for the LLVM
> examples.
> + Generate build targets for the LLVM examples. Defaults to ON. You can
> use this
> + option to disable the generation of build targets for the LLVM examples.
>
> **LLVM_BUILD_TESTS**:BOOL
> Build LLVM unit tests. Defaults to OFF. Targets for building each unit
> test
> - are generated in any case. You can build a specific unit test with the
> target
> - *UnitTestNameTests* (where at this time *UnitTestName* can be ADT,
> Analysis,
> - ExecutionEngine, JIT, Support, Transform, VMCore; see the
> subdirectories of
> - *unittests* for an updated list.) It is possible to build all unit
> tests with
> - the target *UnitTests*.
> + are generated in any case. You can build a specific unit test using the
> + targets defined under *unittests*, such as ADTTests, IRTests,
> SupportTests,
> + etc. (Search for ``add_llvm_unittest`` in the subdirectories of
> *unittests*
> + for a complete list of unit tests.) It is possible to build all unit
> tests
> + with the target *UnitTests*.
>
> **LLVM_INCLUDE_TESTS**:BOOL
> Generate build targets for the LLVM unit tests. Defaults to ON. You can
> use
> - that option for disabling the generation of build targets for the LLVM
> unit
> + this option to disable the generation of build targets for the LLVM unit
> tests.
>
> **LLVM_APPEND_VC_REV**:BOOL
> @@ -249,39 +258,39 @@ LLVM-specific variables
> is *Debug*.
>
> **LLVM_ENABLE_EH**:BOOL
> - Build LLVM with exception handling support. This is necessary if you
> wish to
> + Build LLVM with exception-handling support. This is necessary if you
> wish to
> link against LLVM libraries and make use of C++ exceptions in your own
> code
> that need to propagate through LLVM code. Defaults to OFF.
>
> **LLVM_ENABLE_PIC**:BOOL
> - Add the ``-fPIC`` flag for the compiler command-line, if the compiler
> supports
> + Add the ``-fPIC`` flag to the compiler command-line, if the compiler
> supports
> this flag. Some systems, like Windows, do not need this flag. Defaults
> to ON.
>
> **LLVM_ENABLE_RTTI**:BOOL
> - Build LLVM with run time type information. Defaults to OFF.
> + Build LLVM with run-time type information. Defaults to OFF.
>
> **LLVM_ENABLE_WARNINGS**:BOOL
> Enable all compiler warnings. Defaults to ON.
>
> **LLVM_ENABLE_PEDANTIC**:BOOL
> - Enable pedantic mode. This disables compiler specific extensions, if
> + Enable pedantic mode. This disables compiler-specific extensions, if
> possible. Defaults to ON.
>
> **LLVM_ENABLE_WERROR**:BOOL
> - Stop and fail build, if a compiler warning is triggered. Defaults to
> OFF.
> + Stop and fail the build, if a compiler warning is triggered. Defaults
> to OFF.
>
> **LLVM_ABI_BREAKING_CHECKS**:STRING
> Used to decide if LLVM should be built with ABI breaking checks or
> not. Allowed values are `WITH_ASSERTS` (default), `FORCE_ON` and
> `FORCE_OFF`. `WITH_ASSERTS` turns on ABI breaking checks in an
> assertion enabled build. `FORCE_ON` (`FORCE_OFF`) turns them on
> - (off) irrespective of whether normal (`NDEBUG` based) assertions are
> + (off) irrespective of whether normal (`NDEBUG`-based) assertions are
> enabled or not. A version of LLVM built with ABI breaking checks
> is not ABI compatible with a version built without it.
>
> **LLVM_BUILD_32_BITS**:BOOL
> - Build 32-bits executables and libraries on 64-bits systems. This option
> is
> - available only on some 64-bits unix systems. Defaults to OFF.
> + Build 32-bit executables and libraries on 64-bit systems. This option is
> + available only on some 64-bit Unix systems. Defaults to OFF.
>
> **LLVM_TARGET_ARCH**:STRING
> LLVM target to use for native code generation. This is required for JIT
> @@ -290,7 +299,7 @@ LLVM-specific variables
> to the target architecture name.
>
> **LLVM_TABLEGEN**:STRING
> - Full path to a native TableGen executable (usually named ``tblgen``).
> This is
> + Full path to a native TableGen executable (usually named
> ``llvm-tblgen``). This is
> intended for cross-compiling: if the user sets this variable, no native
> TableGen will be created.
>
> @@ -300,29 +309,36 @@ LLVM-specific variables
> others.
>
> **LLVM_LIT_TOOLS_DIR**:PATH
> - The path to GnuWin32 tools for tests. Valid on Windows host. Defaults
> to "",
> - then Lit seeks tools according to %PATH%. Lit can find tools(eg. grep,
> sort,
> - &c) on LLVM_LIT_TOOLS_DIR at first, without specifying GnuWin32 to
> %PATH%.
> + The path to GnuWin32 tools for tests. Valid on Windows host. Defaults
> to
> + the empty string, in which case lit will look for tools needed for tests
> + (e.g. ``grep``, ``sort``, etc.) in your %PATH%. If GnuWin32 is not in
> your
> + %PATH%, then you can set this variable to the GnuWin32 directory so that
> + lit can find tools needed for tests in that directory.
>
> **LLVM_ENABLE_FFI**:BOOL
> - Indicates whether LLVM Interpreter will be linked with Foreign Function
> - Interface library. If the library or its headers are installed on a
> custom
> - location, you can set the variables FFI_INCLUDE_DIR and
> - FFI_LIBRARY_DIR. Defaults to OFF.
> + Indicates whether the LLVM Interpreter will be linked with the Foreign
> Function
> + Interface library (libffi) in order to enable calling external
> functions.
> + If the library or its headers are installed in a custom
> + location, you can also set the variables FFI_INCLUDE_DIR and
> + FFI_LIBRARY_DIR to the directories where ffi.h and libffi.so can be
> found,
> + respectively. Defaults to OFF.
>
> **LLVM_EXTERNAL_{CLANG,LLD,POLLY}_SOURCE_DIR**:PATH
> - Path to ``{Clang,lld,Polly}``\'s source directory. Defaults to
> - ``tools/{clang,lld,polly}``. ``{Clang,lld,Polly}`` will not be built
> when it
> - is empty or it does not point to a valid path.
> + These variables specify the path to the source directory for the
> external
> + LLVM projects Clang, lld, and Polly, respectively, relative to the
> top-level
> + source directory. If the in-tree subdirectory for an external project
> + exists (e.g., llvm/tools/clang for Clang), then the corresponding
> variable
> + will not be used. If the variable for an external project does not
> point
> + to a valid path, then that project will not be built.
>
> **LLVM_USE_OPROFILE**:BOOL
> - Enable building OProfile JIT support. Defaults to OFF
> + Enable building OProfile JIT support. Defaults to OFF.
>
> **LLVM_USE_INTEL_JITEVENTS**:BOOL
> - Enable building support for Intel JIT Events API. Defaults to OFF
> + Enable building support for Intel JIT Events API. Defaults to OFF.
>
> **LLVM_ENABLE_ZLIB**:BOOL
> - Build with zlib to support compression/uncompression in LLVM tools.
> + Enable building with zlib to support compression/uncompression in LLVM
> tools.
> Defaults to ON.
>
> **LLVM_USE_SANITIZER**:STRING
> @@ -361,14 +377,14 @@ LLVM-specific variables
> ``org.llvm.qch``.
> This option is only useful in combination with
> ``-DLLVM_ENABLE_DOXYGEN_QT_HELP=ON``;
> - otherwise this has no effect.
> + otherwise it has no effect.
>
> **LLVM_DOXYGEN_QHP_NAMESPACE**:STRING
> Namespace under which the intermediate Qt Help Project file lives. See
> `Qt
> Help Project`_
> for more information. Defaults to "org.llvm". This option is only
> useful in
> combination with ``-DLLVM_ENABLE_DOXYGEN_QT_HELP=ON``; otherwise
> - this has no effect.
> + it has no effect.
>
> **LLVM_DOXYGEN_QHP_CUST_FILTER_NAME**:STRING
> See `Qt Help Project`_ for
> @@ -377,14 +393,14 @@ LLVM-specific variables
> be used in Qt Creator to select only documentation from LLVM when
> browsing
> through all the help files that you might have loaded. This option is
> only
> useful in combination with ``-DLLVM_ENABLE_DOXYGEN_QT_HELP=ON``;
> - otherwise this has no effect.
> + otherwise it has no effect.
>
> .. _Qt Help Project:
> http://qt-project.org/doc/qt-4.8/qthelpproject.html#custom-filters
>
> **LLVM_DOXYGEN_QHELPGENERATOR_PATH**:STRING
> The path to the ``qhelpgenerator`` executable. Defaults to whatever
> CMake's
> ``find_program()`` can find. This option is only useful in combination
> with
> - ``-DLLVM_ENABLE_DOXYGEN_QT_HELP=ON``; otherwise this has no
> + ``-DLLVM_ENABLE_DOXYGEN_QT_HELP=ON``; otherwise it has no
> effect.
>
> **LLVM_DOXYGEN_SVG**:BOOL
> @@ -419,15 +435,15 @@ LLVM-specific variables
> Executing the test suite
> ========================
>
> -Testing is performed when the *check* target is built. For instance, if
> you are
> -using makefiles, execute this command while on the top level of your build
> -directory:
> +Testing is performed when the *check-all* target is built. For instance,
> if you are
> +using Makefiles, execute this command in the root of your build directory:
>
> .. code-block:: console
>
> - $ make check
> + $ make check-all
>
> -On Visual Studio, you may run tests to build the project "check".
> +On Visual Studio, you may run tests by building the project "check-all".
> +For more information about testing, see the :doc:`TestingGuide`.
>
> Cross compiling
> ===============
> @@ -447,10 +463,10 @@ Embedding LLVM in your project
>
> From LLVM 3.5 onwards both the CMake and autoconf/Makefile build systems
> export
> LLVM libraries as importable CMake targets. This means that clients of
> LLVM can
> -now reliably use CMake to develop their own LLVM based projects against an
> +now reliably use CMake to develop their own LLVM-based projects against an
> installed version of LLVM regardless of how it was built.
>
> -Here is a simple example of CMakeLists.txt file that imports the LLVM
> libraries
> +Here is a simple example of a CMakeLists.txt file that imports the LLVM
> libraries
> and uses them to build a simple application ``simple-tool``.
>
> .. code-block:: cmake
> @@ -495,8 +511,8 @@ This file is available in two different
> On Linux typically this is ``/usr/share/llvm/cmake/LLVMConfig.cmake``.
>
> * ``<LLVM_BUILD_ROOT>/share/llvm/cmake/LLVMConfig.cmake`` where
> - ``<LLVM_BUILD_ROOT>`` is the root of the LLVM build tree. **Note this
> only
> - available when building LLVM with CMake**
> + ``<LLVM_BUILD_ROOT>`` is the root of the LLVM build tree. **Note: this
> is only
> + available when building LLVM with CMake.**
>
> If LLVM is installed in your operating system's normal installation
> prefix (e.g.
> on Linux this is usually ``/usr/``) ``find_package(LLVM ...)`` will
> @@ -529,7 +545,7 @@ include
> A list of include paths to directories containing LLVM header files.
>
> ``LLVM_PACKAGE_VERSION``
> - The LLVM version. This string can be used with CMake conditionals. E.g.
> ``if
> + The LLVM version. This string can be used with CMake conditionals,
> e.g., ``if
> (${LLVM_PACKAGE_VERSION} VERSION_LESS "3.5")``.
>
> ``LLVM_TOOLS_BINARY_DIR``
> @@ -582,7 +598,7 @@ Contents of ``<project dir>/<pass name>/
>
> Note if you intend for this pass to be merged into the LLVM source tree
> at some
> point in the future it might make more sense to use LLVM's internal
> -add_llvm_loadable_module function instead by...
> +``add_llvm_loadable_module`` function instead by...
>
>
> Adding the following to ``<project dir>/CMakeLists.txt`` (after
> @@ -602,7 +618,7 @@ And then changing ``<project dir>/<pass
> )
>
> When you are done developing your pass, you may wish to integrate it
> -into LLVM source tree. You can achieve it in two easy steps:
> +into the LLVM source tree. You can achieve it in two easy steps:
>
> #. Copying ``<pass name>`` folder into ``<LLVM root>/lib/Transform``
> directory.
>
> @@ -618,6 +634,6 @@ Microsoft Visual C++
> --------------------
>
> **LLVM_COMPILER_JOBS**:STRING
> - Specifies the maximum number of parallell compiler jobs to use per
> project
> + Specifies the maximum number of parallel compiler jobs to use per
> project
> when building with msbuild or Visual Studio. Only supported for the
> Visual
> Studio 2010 CMake generator. 0 means use all processors. Default is 0.
>
>
> _______________________________________________
> llvm-commits mailing list
> llvm-commits at lists.llvm.org
> http://lists.llvm.org/cgi-bin/mailman/listinfo/llvm-commits
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.llvm.org/pipermail/llvm-commits/attachments/20150824/13f786a6/attachment-0001.html>
More information about the llvm-commits
mailing list