From 43b545f0f3744b27ba9bf511ff0c923f31cbf47a Mon Sep 17 00:00:00 2001 From: Mats Wichmann Date: Tue, 7 Nov 2023 10:28:17 -0700 Subject: Update documentation of PCH builder Notes added on inclusion of PCH source file and object file. Note that PCH is not just MSVC-only, but also C++-only. Signed-off-by: Mats Wichmann --- CHANGES.txt | 1 + RELEASE.txt | 1 + SCons/Tool/msvc.xml | 67 +++++++++++++++++++++++++++++++++++++++++------------ 3 files changed, 54 insertions(+), 15 deletions(-) diff --git a/CHANGES.txt b/CHANGES.txt index b87d81f..87611ed 100644 --- a/CHANGES.txt +++ b/CHANGES.txt @@ -213,6 +213,7 @@ RELEASE VERSION/DATE TO BE FILLED IN LATER - Add a LIBLITERALPREFIX variable which can be set to the linker's prefix for considering a library argument unmodified (e.g. for the GNU linker, the ':' in '-l:libfoo.a'). Fixes Github issue #3951. + - Update PCH builder docs with some usage notes. From Jonathon Reinhart: - Fix another instance of `int main()` in CheckLib() causing failures diff --git a/RELEASE.txt b/RELEASE.txt index 546bba7..232d61f 100644 --- a/RELEASE.txt +++ b/RELEASE.txt @@ -158,6 +158,7 @@ DOCUMENTATION - Updated the first two chapters on building with SCons in the User Guide. - Clarify that exported variables are shared - if mutable, changes made in an SConscript are visible everywhere that takes a refereence to that object. +- Update PCH builder docs with some usage notes. DEVELOPMENT ----------- diff --git a/SCons/Tool/msvc.xml b/SCons/Tool/msvc.xml index bf2e267..ab0828e 100644 --- a/SCons/Tool/msvc.xml +++ b/SCons/Tool/msvc.xml @@ -94,10 +94,9 @@ Sets &consvars; for the Microsoft Visual C/C++ compiler. Builds a Microsoft Visual C++ precompiled header. Calling this builder -returns a list of two targets: the PCH as the first element, and the object -file as the second element. Normally the object file is ignored. -This builder is only -provided when Microsoft Visual C++ is being used as the compiler. +returns a list of two target nodes: the PCH as the first element, +and the object file as the second element. +Normally the object file is ignored. The &b-PCH; builder is generally used in conjunction with the &cv-link-PCH; &consvar; to force object files to use the precompiled header: @@ -106,6 +105,42 @@ the precompiled header: env['PCH'] = env.PCH('StdAfx.cpp')[0] + + + +This builder is specific to the PCH implementation +in Microsoft Visual C++. +Other compiler chains also implement precompiled header support, +but &b-PCH; does not work with them at this time. +As a result, the builder is only generated into the +construction environment when +Microsoft Visual C++ is being used as the compiler. + + +The builder only works correctly in a C++ project. +The Microsoft implementation distinguishes between +precompiled headers from C and C++. +Use of the builder will cause the PCH generation to happen with a flag +that tells cl.exe all of the +files are C++ files; if that PCH file is then supplied when +compiling a C source file, +cl.exe will fail the build with +a compatibility violation. + + +If possible, arrange the project so that a +C++ source file passed to the &b-PCH; builder +is not also included in the list of sources +to be otherwise compiled in the project. +&SCons; will correctly track that file in the dependency tree +as a result of the &b-PCH; call, +and (for MSVC 11.0 and greater) automatically add the +corresponding object file to the link line. +If the source list is automatically generated, +for example using the &f-link-Glob; function, +it may be necessary to remove that file from the list. + + @@ -154,7 +189,7 @@ when the &cv-link-PDB; &consvar; is set. -The Visual C++ compiler option that SCons uses by default +The Visual C++ compiler option that &SCons; uses by default to generate PDB information is . This works correctly with parallel () builds because it embeds the debug information in the intermediate object files, @@ -192,12 +227,12 @@ env['CCPDBFLAGS'] = '/Zi /Fd${TARGET}.pdb' When set to any true value, -specifies that SCons should batch +specifies that &SCons; should batch compilation of object files when calling the Microsoft Visual C/C++ compiler. All compilations of source files from the same source directory that generate target files in a same output directory -and were configured in SCons using the same &consenv; +and were configured in &SCons; using the same &consenv; will be built in a single call to the compiler. Only source files that have changed since their object files were built will be passed to each compiler invocation @@ -213,17 +248,19 @@ will be compiled separately. -The Microsoft Visual C++ precompiled header that will be used when compiling -object files. This variable is ignored by tools other than Microsoft Visual C++. +A node for the Microsoft Visual C++ precompiled header that will be +used when compiling object files. +This variable is ignored by tools other than Microsoft Visual C++. When this variable is -defined SCons will add options to the compiler command line to +defined, &SCons; will add options to the compiler command line to cause it to use the precompiled header, and will also set up the dependencies for the PCH file. -Example: +Examples: env['PCH'] = File('StdAfx.pch') +env['PCH'] = env.PCH('pch.cc')[0] @@ -242,7 +279,7 @@ builder to generated a precompiled header. The string displayed when generating a precompiled header. -If this is not set, then &cv-link-PCHCOM; (the command line) is displayed. +If not set, then &cv-link-PCHCOM; (the command line) is displayed. @@ -356,7 +393,7 @@ when the &cv-link-RCINCFLAGS; variable is expanded. Sets the preferred version of Microsoft Visual C/C++ to use. If the specified version is unavailable (not installed, or not discoverable), tool initialization will fail. -If &cv-MSVC_VERSION; is not set, SCons will (by default) select the +If &cv-MSVC_VERSION; is not set, &SCons; will (by default) select the latest version of Visual C/C++ installed on your system. @@ -796,10 +833,10 @@ Specify the location of vswhere.exe. It provides full information about installations of 2017 and later editions. With the argument, vswhere.exe can detect installations of the 2010 through 2015 editions with limited data returned. -If VSWHERE is set, SCons will use that location. +If VSWHERE is set, &SCons; will use that location. - Otherwise SCons will look in the following locations and set VSWHERE to the path of the first vswhere.exe + Otherwise &SCons; will look in the following locations and set VSWHERE to the path of the first vswhere.exe located. -- cgit v0.12