Initial VCPkg integration

CHANGES.txt

@@ -25,6 +25,8 @@ RELEASE  VERSION/DATE TO BE FILLED IN LATER
     - Added -fsanitize support to ParseFlags().  This will propagate to CCFLAGS and LINKFLAGS.
 
   From Ryan Saunders:
+    - Added VCPkg() builder, enabling cross-platform acquisition and building of 3rd party C/C++
+      libraries.
     - Fixed runtest.py failure on Windows caused by excessive escaping of the path to python.exe.
 
 RELEASE 4.4.0 -  Sat, 30 Jul 2022 14:08:29 -0700

SCons/Tool/__init__.py

@@ -809,6 +809,8 @@ def tool_list(platform, env):
         'tar', 'zip',
         # File builders (text)
         'textfile',
+        # Package management
+        'vcpkg',
     ], env)
 
     tools = [

SCons/Tool/default.xml

@@ -55,7 +55,7 @@ are selected if their respective conditions are met:
 &t-link-jar;, &t-link-javac;, &t-link-javah;, &t-link-rmic;,
 &t-link-dvipdf;, &t-link-dvips;, &t-link-gs;,
 &t-link-tex;, &t-link-latex;, &t-link-pdflatex;, &t-link-pdftex;,
-&t-link-tar;, &t-link-zip;, &t-link-textfile;.
+&t-link-tar;, &t-link-zip;, &t-link-textfile; &t-link-vcpkg;.
 </para>
 
 <para>

SCons/Tool/vcpkg.xml

@@ -0,0 +1,97 @@
+<?xml version="1.0"?>
+<!--
+__COPYRIGHT__
+
+This file is processed by the bin/SConsDoc.py module.
+See its __doc__ string for a discussion of the format.
+-->
+
+<!DOCTYPE sconsdoc [
+        <!ENTITY % scons SYSTEM '../../doc/scons.mod'>
+        %scons;
+        <!ENTITY % builders-mod SYSTEM '../../doc/generated/builders.mod'>
+        %builders-mod;
+        <!ENTITY % functions-mod SYSTEM '../../doc/generated/functions.mod'>
+        %functions-mod;
+        <!ENTITY % tools-mod SYSTEM '../../doc/generated/tools.mod'>
+        %tools-mod;
+        <!ENTITY % variables-mod SYSTEM '../../doc/generated/variables.mod'>
+        %variables-mod;
+        ]>
+
+<sconsdoc xmlns="http://www.scons.org/dbxsd/v1.0"
+          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+          xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0 http://www.scons.org/dbxsd/v1.0/scons.xsd">
+
+    <tool name="vcpkg">
+        <summary>
+            <para>
+                Sets construction variables for the &vcpkg; package manager
+            </para>
+        </summary>
+        <uses>
+            <item>VCPKGROOT</item>
+            <item>VCPKGDEBUG</item>
+        </uses>
+    </tool>
+
+    <builder name="VCPkg">
+        <summary>
+            <para>
+                Downloads and builds one or more software packages (plus any dependencies of those packages) via the
+                &vcpkg; package manager, making the built artifcats available for other builders.
+            </para>
+
+            <example_commands>
+# Install FreeImage, plus any of its dependencies
+env.VCPkg('freeimage')
+            </example_commands>
+
+            <para>
+                &vcpkg; is distributed as a Git repository, containing the &vcpkg; executable (or a script to build it)
+                and a "snapshot" of the current versions of all available packages. A typical usage pattern is for your
+                project to incorporate &vcpkg; as a Git submodule underneath your project (run 'git submodule --help'),
+                though system-wide installation is also supported.
+            </para>
+
+            <para>
+                Packages built with &vcpkg; may produce header files, static libraries and shared libraries
+                (<filename>.dll</filename>/<filename>.so</filename> files). The &vcpkg;-internal directores
+                containing these built artifacts are added to &cv-link-CPPPATH; and &cv-link-LIBPATH; and
+                &cv-link-PATH;, respectively.
+            </para>
+
+        </summary>
+    </builder>
+
+    <cvar name="VCPKGROOT">
+        <summary>
+            <para>
+                Specifies the path to the root directory of the &vcpkg; installation. This must be set in the
+                SConstruct/SConscript file, and must point to an existing &vcpkg; installation. Often, this directory
+                will be a Git sub-module of your project, in which case VCPKGROOT will be specified relative to the
+                project root.
+            </para>
+
+            <example_commands>
+# vcpkg is a submodule located in the 'vcpkg' directory underneath the project root
+env['VCPKGROOT'] = '#/vcpkg'
+            </example_commands>
+        </summary>
+    </cvar>
+
+    <cvar name="VCPKGDEBUG">
+        <summary>
+            <para>
+                Specifies whether &vcpkg; should build debug or optimized versions of packages. If True, then "debug"
+                packages will be built, with full debugging information and most optimizations disabled. If False (or
+                unset), then packages will be built using optimized settings.
+            </para>
+            <para>
+                Note that, while you may choose to set this to match the optimization settings of your project's build,
+                this is not required: it's perfectly fine to use optimized packages with a "debug" build of your project.
+            </para>
+        </summary>
+    </cvar>
+
+</sconsdoc>

bin/files

@@ -99,6 +99,7 @@
 ./SCons/Tool/tar.py
 ./SCons/Tool/tex.py
 ./SCons/Tool/tlib.py
+./SCons/Tool/vcpkg.py
 ./SCons/Tool/yacc.py
 ./SCons/Util.py
 ./SCons/Warnings.py

doc/generated/tools.mod

@@ -104,6 +104,7 @@ THIS IS AN AUTOMATICALLY-GENERATED FILE.  DO NOT EDIT.
 <!ENTITY t-tex "<literal xmlns='http://www.scons.org/dbxsd/v1.0'>tex</literal>">
 <!ENTITY t-textfile "<literal xmlns='http://www.scons.org/dbxsd/v1.0'>textfile</literal>">
 <!ENTITY t-tlib "<literal xmlns='http://www.scons.org/dbxsd/v1.0'>tlib</literal>">
+<!ENTITY t-vcpkg "<literal xmlns='http://www.scons.org/dbxsd/v1.0'>vcpkg</literal>">
 <!ENTITY t-xgettext "<literal xmlns='http://www.scons.org/dbxsd/v1.0'>xgettext</literal>">
 <!ENTITY t-yacc "<literal xmlns='http://www.scons.org/dbxsd/v1.0'>yacc</literal>">
 <!ENTITY t-zip "<literal xmlns='http://www.scons.org/dbxsd/v1.0'>zip</literal>">
@@ -210,6 +211,7 @@ THIS IS AN AUTOMATICALLY-GENERATED FILE.  DO NOT EDIT.
 <!ENTITY t-link-tex "<link linkend='t-tex' xmlns='http://www.scons.org/dbxsd/v1.0'><literal>tex</literal></link>">
 <!ENTITY t-link-textfile "<link linkend='t-textfile' xmlns='http://www.scons.org/dbxsd/v1.0'><literal>textfile</literal></link>">
 <!ENTITY t-link-tlib "<link linkend='t-tlib' xmlns='http://www.scons.org/dbxsd/v1.0'><literal>tlib</literal></link>">
+<!ENTITY t-link-vcpkg "<link linkend='t-vcpkg' xmlns='http://www.scons.org/dbxsd/v1.0'><literal>vcpkg</literal></link>">
 <!ENTITY t-link-xgettext "<link linkend='t-xgettext' xmlns='http://www.scons.org/dbxsd/v1.0'><literal>xgettext</literal></link>">
 <!ENTITY t-link-yacc "<link linkend='t-yacc' xmlns='http://www.scons.org/dbxsd/v1.0'><literal>yacc</literal></link>">
 <!ENTITY t-link-zip "<link linkend='t-zip' xmlns='http://www.scons.org/dbxsd/v1.0'><literal>zip</literal></link>">