diff options
Diffstat (limited to 'doc/manual.cli')
| -rw-r--r-- | doc/manual.cli | 166 |
1 files changed, 163 insertions, 3 deletions
diff --git a/doc/manual.cli b/doc/manual.cli index 76c82dd..2ce1ef3 100644 --- a/doc/manual.cli +++ b/doc/manual.cli @@ -206,13 +206,13 @@ $ b config.cxx=clang++ version and build for the \c{x86_64} target (\c{x64} in the Microsoft's terminology). You can, however, override these defaults by either running from a suitable Visual Studio development command prompt or by specifying an -absolute path to \c{cl.exe} that you wish to use. For example: +absolute path to \c{cl} that you wish to use. For example: \ -> b \"config.cxx=...\VC\Tools\MSVC\14.23.28105\bin\Hostx64\x86\cl.exe\" +> b \"config.cxx=...\VC\Tools\MSVC\14.23.28105\bin\Hostx64\x86\cl\" \ -| +See \l{#cc-msvc MSVC Compiler Toolchain} for details.| Similarly, for additional compile options, such as debug information or optimization level, there is \c{config.cxx.coptions}. For example: @@ -5089,6 +5089,17 @@ common compilation and linking support for C-family languages. \h#cc-config|C-Common Configuration Variables| \ +config.c +config.cxx + cc.id + + c.target + c.target.cpu + c.target.vendor + c.target.system + c.target.version + c.target.class + config.cc.poptions cc.poptions @@ -5118,6 +5129,155 @@ $ b config.cxx=\"g++ -m32\" $ b config.cxx=\"clang++ -stdlib=libc++\" \ +\h#cc-gcc|GCC Compiler Toolchain| + +The GCC compiler id is \c{gcc}. + + +\h#cc-clang|Clang Compiler Toolchain| + +The vanilla Clang compiler id is \c{clang} (including when targeting the MSVC +runtime), Apple Clang compiler id is \c{clang-apple}, and Clang's \c{cl} +compatibility driver (\c{clang-cl}) id is \c{msvc-clang}. + +\h2#cc-clang-msvc|Clang Targeting MSVC| + +There are two common ways to obtain Clang on Windows: bundled with the MSVC +installation or as a separate installation. If you are using the separate +installation, then the Clang compiler is most likely already in the \c{PATH} +environment variable. Otherwise, if you are using Clang that is bundled with +MSVC, the \c{cc} module will attempt various search strategies described +below. Note, however, that in both cases once the Clang compiler binary +located, the mode (32 or 64-bit) and the rest of the environment (locations of +binary utilities as well as the system headers and libraries) are obtained +by querying Clang. + +\N|Normally, if Clang is invoked from one of the Visual Studio command +prompts, then it will use the corresponding Visual Studio version and +environment (it is, however, still up to you to match the mode with the +\c{-m32}/\c{-m64} options, if necessary). Otherwise, Clang will try to locate +the latest version of Visual Studio and Platform SDK and use that (in this +case it matches the environment to the \c{-m32}/\c{-m64} options). Refer to +Clang documentation for details.| + +If you specify the compiler as just \c{config.c=clang} or +\c{config.cxx=clang++} and it is found in the \c{PATH} environment variable or +if you specify it as an absolute path, then the \c{cc} module will use that. + +Otherwise, if you are building from one of the Visual Studio development +command prompts, the \c{cc} module will look for the corresponding bundled +Clang (\c{%VCINSTALLDIR%\\Tools\\Llvm\\bin}). + +Finally, the \c{cc} module will attempt to locate the latest installed version +of Visual Studio and look for a bundled Clang in there. + +The default mode (32 or 64-bit) depends on the Clang configuration and can +be overridden with the \c{-m32}/\c{-m64} options. For example: + +\ +> b \"config.cxx=clang++ -m64\" +\ + +The default MSVC runtime selected by the \c{cc} module is multi-threaded +shared (the \c{/MD} option in \c{cl}). Unfortunately, the Clang driver does +not yet provide anything equivalent to the \c{cl} \c{/M*} options (see +\l{https://bugs.llvm.org/show_bug.cgi?id=33273 Clang bug #33273}) and +selection of an alternative runtime has to be performed manually: + +\ +> rem /MD - multi-threaded shared (default) +> rem +> b \"config.cxx=clang++ -nostdlib -D_MT -D_DLL\" ^ + config.cc.libs=/DEFAULTLIB:msvcrt + +> rem /MDd - multi-threaded debug shared +> rem +> b \"config.cxx=clang++ -nostdlib -D_MT -D_DLL -D_DEBUG\" ^ + config.cc.libs=/DEFAULTLIB:msvcrtd + +> rem /MT - multi-threaded static +> rem +> b \"config.cxx=clang++ -nostdlib -D_MT\" ^ + config.cc.libs=/DEFAULTLIB:libcmt + +> rem /MTd - multi-threaded debug static +> rem +> b \"config.cxx=clang++ -nostdlib -D_MT -D_DEBUG\" ^ + config.cc.libs=/DEFAULTLIB:libcmtd +\ + +By default the MSVC's binary utilities (\c{link} and \c{lib}) are used when +compiling with Clang. It is, however, possible to use LLVM's versions instead, +for example: + +\ +> b config.cxx=clang++ ^ + config.bin.ld=lld-link ^ + config.bin.ar=llvm-lib +\ + +In particular, one benefit of using \c{llvm-lib} is support for thin archives +which, if available, is automatically enabled for utility libraries. + +\N|While there is basic support for Clang's \c{cl} compatibility driver +(\c{clang-cl}), its use is not recommended. This driver is a very thin wrapper +over the standard Clang interface that does not always recreate the \c{cl}'s +semantics exactly. Specifically, its diagnostics in the \c{/showIncludes} mode +does not match that of \c{cl} in the presence of missing headers. As a result, +\c{clang-cl}'s use, if any, should be limited to projects that do not have +auto-generated headers. + +If you need to link with other projects that use \c{clang-cl}, then the +recommended approach is to discover any additional \c{cc1} options passed by +\c{clang-cl} by comparing the \c{-v} output of a test compilation with +\c{clang-cl} and \c{clang}/\c{clang++} and then passing them explicitly +to \c{clang}/\c{clang++} prefixed with \c{-Xclang}. For example: + +\ +b \"config.cxx=clang++ -Xclang -fms-volatile ...\" +\ + +| + + +\h#cc-msvc|MSVC Compiler Toolchain| + +The Microsoft VC (MSVC) compiler id is \c{msvc}. + +There are several ways to specify the desired MSVC compiler and mode (32 or +64-bit) as well as the corresponding environment (locations of binary +utilities as well as the system headers and libraries). + +\N|Unlike other compilers, MSVC compiler (\c{cl}) binaries are +target-specific, that is, there are no \c{-m32}/\c{-m64} options nor something +like the \c{/MACHINE} option available in \c{link}.| + +If the compiler is specified as just \c{cl} in \c{config.{c,cxx}} and it is +found in the \c{PATH} environment variable, then the \c{cc} module assumes the +build is performed from one of the Visual Studio development command prompts +and expects the environment (the \c{PATH}, \c{INCLUDE}, and \c{LIB} +environment variables) to already be setup. + +If, however, \c{cl} is not found in \c{PATH}, then the \c{cc} module will +attempt to locate the latest installed version of Visual Studio and Platform +SDK and use that in the 64-bit mode. + +Finally, if the compiler is specified as an absolute path to \c{cl}, then the +\c{cc} module will attempt to locate the corresponding Visual Studio +installation as well as the latest Platform SDK and use that in the mode +corresponding to the specified \c{cl} executable. + +Note that the latter two methods are only available for Visual Studio 15 (2017) +and later and for earlier versions the development command prompt must be +used. + +The default MSVC runtime selected by the \c{cc} module is multi-threaded +shared (the \c{/MD} \c{cl} option). An alternative runtime can be selected +by passing one of the \c{cl} \c{/M*} options, for example: + +\ +> b \"config.cxx=cl /MT\" +\ \h1#module-c|\c{c} Module| |