Merge branch 'master' into dev/jack/4167

8 files changed, 352 insertions, 111 deletions

diff --git a/docs/examples/overlay-triplets-linux-dynamic.md b/docs/examples/overlay-triplets-linux-dynamic.md
index 6168d85e6..b2868e2fd 100644
--- a/docs/examples/overlay-triplets-linux-dynamic.md
+++ b/docs/examples/overlay-triplets-linux-dynamic.md
@@ -1,66 +1,41 @@
-# Overlay triplets example: build dynamic libraries on Linux

+# Overlay triplets example

 

-Using **vcpkg** you can build libraries for the following triplets:

+## Building dynamic libraries on Linux

 

-<div>

-    <ul style="columns: 3;">

-        <li> arm-uwp</li>

-        <li> arm-windows</li>

-        <li> arm64-uwp</li>

-        <li> arm64-windows</li>

-        <li> x86-uwp</li>

-        <li> x86-windows</li>

-        <li> x86-windows-static</li>

-        <li> x64-uwp</li>

-        <li> x64-linux</li>

-        <li> x64-osx</li>

-        <li> x64-windows</li>

-        <li> x64-windows-static</li>

-    </ul>

-</div>

+Using **vcpkg** you can build libraries for many configurations out of the box. However, this doesn't currently include shared libraries on Linux and Mac OS.

 

+This doesn't mean that you cannot use **vcpkg** to build your dynamic libraries on these platforms! This document will guide you through creating your own custom triplets with `--overlay-triplets` to easily build dynamic libraries on Linux.

 

-

-By design **vcpkg** builds only static libraries for Linux and Mac OS.

-However, this doesn't mean that you cannot use **vcpkg** to build your dynamic libraries on these platforms.

-

-This document will guide you through creating your own custom triplets to build dynamic libraries on Linux using **vcpkg**.

-

-### Step 1: Create a folder to contain your custom triplets

-

-```

-~/vcpkg$ mkdir ../custom-triplets

-```

-

-### Step 2: Create the custom triplet files

+### Step 1: Create the custom triplet files

 

 To save time, copy the existing `x64-linux.cmake` triplet file.

 

-```

-~/vcpkg$ cp ./triplets/x64-linux.cmake ../custom-triplets/x64-linux-dynamic.cmake

+```sh

+~/git$ mkdir custom-triplets

+~/git$ cp vcpkg/triplets/x64-linux.cmake custom-triplets/x64-linux-dynamic.cmake

 ```

 

 And modify `custom-triplets/x64-linux-dynamic.cmake` to match the contents below:

-```

+```cmake

+# ~/git/custom-triplets/x64-linux-dynamic.cmake

 set(VCPKG_TARGET_ARCHITECTURE x64)

 set(VCPKG_CRT_LINKAGE dynamic)

-# Change VCPKG_LIBRARY_LINKAGE from static to dynamic

-set(VCPKG_LIBRARY_LINKAGE dynamic)

+set(VCPKG_LIBRARY_LINKAGE dynamic) # This changed from static to dynamic

 

 set(VCPKG_CMAKE_SYSTEM_NAME Linux)

 ```

 

-### Step 3: Use `--overlay-triplets` to build dynamic libraries

+### Step 2: Use `--overlay-triplets` to build dynamic libraries

 

 Use the `--overlay-triplets` option to include the triplets in the `custom-triplets` directory. 

 

 ```

-./vcpkg install sqlite3:x64-linux-dynamic --overlay-triplets=../custom-triplets

+~/git$ vcpkg/vcpkg install sqlite3:x64-linux-dynamic --overlay-triplets=custom-triplets

 The following packages will be built and installed:

-    sqlite3[core]:x64-linux

+    sqlite3[core]:x64-linux-dynamic

 Starting package 1/1: sqlite3:x64-linux-dynamic

 Building package sqlite3[core]:x64-linux-dynamic...

--- Loading triplet configuration from: /home/custom-triplets/x64-linux-dynamic.cmake

+-- Loading triplet configuration from: /home/victor/git/custom-triplets/x64-linux-dynamic.cmake

 -- Downloading https://sqlite.org/2019/sqlite-amalgamation-3280000.zip...

 -- Extracting source /home/victor/git/vcpkg/downloads/sqlite-amalgamation-3280000.zip

 -- Applying patch fix-arm-uwp.patch

@@ -84,7 +59,7 @@ The package sqlite3:x64-linux-dynamic provides CMake targets:
     target_link_libraries(main PRIVATE sqlite3)

 ```

 

-Overlay triplets will add your custom triplet files when using `vcpkg install`, `vcpkg update`, `vcpkg upgrade`, and `vcpkg remove`.

+Overlay triplets enables your custom triplet files when using `vcpkg install`, `vcpkg update`, `vcpkg upgrade`, and `vcpkg remove`.

 

 When using the `--overlay-triplets` option, a message like the following lets you know that a custom triplet is being used: 

 

@@ -94,40 +69,33 @@ When using the `--overlay-triplets` option, a message like the following lets yo
 

 ## Overriding default triplets

 

-As you may have noticed, the default triplets for Windows (`x86-windows` and `x64-windows`) install dynamic libraries, while a suffix (`-static`) is needed for static libraries. This is inconsistent with Linux and Mac OS where only static libraries are built.

+As you may have noticed, the default triplets for Windows (`x86-windows` and `x64-windows`) install dynamic libraries, while a suffix (`-static`) is needed for static libraries. This is different with Linux and Mac OS where static libraries are built by `x64-linux` and `x64-osx`.

 

 Using `--overlay-ports` it is possible to override the default triplets to accomplish the same behavior on Linux:

 

 * `x64-linux`: Builds dynamic libraries,

 * `x64-linux-static`: Builds static libraries.

 

-### Step 1: Create the overriden triplet

-

-Using the custom triplet created in the previous example, rename `custom-triplets/x64-linux-dynamic.cmake` to `custom-triplets/x64-linux.cmake`.

-

-```

-~/vcpkg$ mv ../custom-triplets/x64-linux-dynamic.cmake ../custom-triplets/x64-linux.cmake

-```

+### Step 1: Create the overlay triplets

 

-### Step 2: Copy and rename the default triplet

+Using the custom triplet created in the previous example, rename `custom-triplets/x64-linux-dynamic.cmake` to `custom-triplets/x64-linux.cmake`. Then, copy the default `x64-linux` triplet (which builds static libraries) in your `custom-triplets` folder and rename it to `x64-linux-static.cmake`.

 

-Then, copy the default `x64-linux` triplet (which builds static libraries) in your `/custom-triplets` folder and rename it to `x64-linux-static.cmake`.

-

-```

-~/vcpkg$ cp ./triplets/x64-linux.cmake ../custom-triplets/x64-linux-static.cmake

+```sh

+~/git$ mv custom-triplets/x64-linux-dynamic.cmake custom-triplets/x64-linux.cmake

+~/git$ cp vcpkg/triplets/x64-linux.cmake custom-triplets/x64-linux-static.cmake

 ```

 

-### Step 3: Use `--overlay-ports` to override default triplets

+### Step 2: Use `--overlay-ports` to override default triplets

 

 Use the `--overlay-triplets` option to include the triplets in the `custom-triplets` directory.

 

 ```

-./vcpkg install sqlite3:x64-linux --overlay-triplets=../custom-triplets

+~/git$ vcpkg/vcpkg install sqlite3:x64-linux --overlay-triplets=custom-triplets

 The following packages will be built and installed:

     sqlite3[core]:x64-linux

 Starting package 1/1: sqlite3:x64-linux

 Building package sqlite3[core]:x64-linux...

--- Loading triplet configuration from: /home/custom-triplets/x64-linux.cmake

+-- Loading triplet configuration from: /home/victor/git/custom-triplets/x64-linux.cmake

 -- Downloading https://sqlite.org/2019/sqlite-amalgamation-3280000.zip...

 -- Extracting source /home/victor/git/vcpkg/downloads/sqlite-amalgamation-3280000.zip

 -- Applying patch fix-arm-uwp.patch

@@ -154,5 +122,5 @@ The package sqlite3:x64-linux provides CMake targets:
 Note that the default triplet is masked by your custom triplet:

 

 ```

--- Loading triplet configuration from: /home/custom-triplets/x64-linux.cmake

+-- Loading triplet configuration from: /home/victor/git/custom-triplets/x64-linux.cmake

 ```

diff --git a/docs/index.md b/docs/index.md
index 5d83b5804..b2f0a53b2 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -21,6 +21,11 @@ Vcpkg helps you manage C and C++ libraries on Windows, Linux and MacOS. This too
 - [Portfile functions](maintainers/portfile-functions.md)
 - [Maintainer Guidelines](maintainers/maintainer-guide.md)
 
+### Tool Maintainer Help
+
+- [Testing](tool-maintainers/testing.md)
+- [Maintainer Guidelines](maintainers/maintainer-guide.md)
+
 ### Specifications
 
 - [Export](specifications/export-command.md)
diff --git a/docs/maintainers/maintainer-guide.md b/docs/maintainers/maintainer-guide.md
index 0baa45a02..e4938844f 100644
--- a/docs/maintainers/maintainer-guide.md
+++ b/docs/maintainers/maintainer-guide.md
@@ -34,7 +34,7 @@ At this time, the following helpers are deprecated:
 

 ### Avoid excessive comments in portfiles

 

-Ideally, portfiles should be short, simple, and as declarative as possible. Remove any helper comments introduced by the `create` command before submitting a PR.

+Ideally, portfiles should be short, simple, and as declarative as possible. Remove any boiler plate comments introduced by the `create` command before submitting a PR.

 

 ## Build Techniques

 

@@ -85,6 +85,15 @@ vcpkg_configure_cmake(
 

 Note that `ZLIB` in the above is case-sensitive. See the [cmake documentation](https://cmake.org/cmake/help/v3.15/variable/CMAKE_DISABLE_FIND_PACKAGE_PackageName.html) for more details.

 

+### Place conflicting libs in a `manual-link` directory

+

+A lib is considered conflicting if it does any of the following:

++ Define `main`

++ Define malloc

++ Define symbols that are also declared in other libraries

+

+Conflicting libs are typically by design and not considered a defect.  Because some build systems link against everything in the lib directory, these should be moved into a subdirectory named `manual-link`.

+

 ## Versioning

 

 ### Follow common conventions for the `Version:` field

@@ -157,7 +166,7 @@ While `portfile.cmake`'s and `CMakeLists.txt`'s share a common syntax and core C
 

 Portfiles have direct access to variables set in the triplet file, but `CMakeLists.txt`s do not (though there is often a translation that happens -- `VCPKG_LIBRARY_LINKAGE` versus `BUILD_SHARED_LIBS`).

 

-Finally, portfiles and CMake builds invoked by portfiles are run in different processes. Conceptually:

+Portfiles and CMake builds invoked by portfiles are run in different processes. Conceptually:

 

 ```no-highlight

 +----------------------------+       +------------------------------------+

diff --git a/docs/maintainers/portfile-functions.md b/docs/maintainers/portfile-functions.md
index b98d89192..eadebf49a 100644
--- a/docs/maintainers/portfile-functions.md
+++ b/docs/maintainers/portfile-functions.md
@@ -24,4 +24,5 @@
 - [vcpkg\_from\_gitlab](vcpkg_from_gitlab.md)

 - [vcpkg\_install\_cmake](vcpkg_install_cmake.md)

 - [vcpkg\_install\_msbuild](vcpkg_install_msbuild.md)

+- [vcpkg\_prettify\_command](vcpkg_prettify_command.md)

 - [vcpkg\_test\_cmake](vcpkg_test_cmake.md)

diff --git a/docs/maintainers/vcpkg_check_features.md b/docs/maintainers/vcpkg_check_features.md
index 46ee9051a..cec01dde2 100644
--- a/docs/maintainers/vcpkg_check_features.md
+++ b/docs/maintainers/vcpkg_check_features.md
@@ -1,71 +1,148 @@
 # vcpkg_check_features
-
-Check if one or more features are a part of the package installation.
+Check if one or more features are a part of a package installation.
 
 ## Usage
 ```cmake
 vcpkg_check_features(
-    <feature1> <output_variable1>
-    [<feature2> <output_variable2>]
-    ...
+  OUT_FEATURE_OPTIONS <FEATURE_OPTIONS>  
+  [FEATURES
+    <cuda> <WITH_CUDA>
+    [<opencv> <WITH_OPENCV>]
+    ...]
+  [INVERTED_FEATURES
+    <cuda> <IGNORE_PACKAGE_CUDA>
+    [<opencv> <IGNORE_PACKAGE_OPENCV>]
+    ...]
 )
 ```
+`vcpkg_check_features()` accepts these parameters: 
 
-`vcpkg_check_features` accepts a list of (feature, output_variable) pairs. If a feature is specified, the corresponding output variable will be set as `ON`, or `OFF` otherwise. The syntax is similar to the `PROPERTIES` argument of `set_target_properties`.
+* `OUT_FEATURE_OPTIONS`:  
+  An output variable, the function will clear the variable passed to `OUT_FEATURE_OPTIONS` 
+  and then set it to contain a list of option definitions (`-D<OPTION_NAME>=ON|OFF`).
+  
+  This should be set to `FEATURE_OPTIONS` by convention.
+  
+* `FEATURES`:  
+  A list of (`FEATURE_NAME`, `OPTION_NAME`) pairs.  
+  For each `FEATURE_NAME` a definition is added to `OUT_FEATURE_OPTIONS` in the form of:   
+    
+    * `-D<OPTION_NAME>=ON`, if a feature is specified for installation,
+    * `-D<OPTION_NAME>=OFF`, otherwise. 
+
+* `INVERTED_FEATURES`:  
+  A list of (`FEATURE_NAME`, `OPTION_NAME`) pairs, uses reversed logic from `FEATURES`.  
+  For each `FEATURE_NAME` a definition is added to `OUT_FEATURE_OPTIONS` in the form of:   
+    
+    * `-D<OPTION_NAME>=OFF`, if a feature is specified for installation,
+    * `-D<OPTION_NAME>=ON`, otherwise. 
 
-`vcpkg_check_features` will create a variable `FEATURE_OPTIONS` in the parent scope, which you can pass as a part of `OPTIONS` argument when calling functions like `vcpkg_config_cmake`:
-```cmake
-vcpkg_config_cmake(
-    SOURCE_PATH ${SOURCE_PATH}
-    PREFER_NINJA
-    OPTIONS
-        -DBUILD_TESTING=ON
-        ${FEATURE_OPTIONS}
-)
-```
 
 ## Notes
+
+The `FEATURES` name parameter can be omitted if no `INVERTED_FEATURES` are used.
+
+At least one (`FEATURE_NAME`, `OPTION_NAME`) pair must be passed to the function call.
+
+Arguments passed to `FEATURES` and `INVERTED_FEATURES` are not validated to prevent duplication.  
+If the same (`FEATURE_NAME`, `OPTION_NAME`) pair is passed to both lists, 
+two conflicting definitions are added to `OUT_FEATURE_OPTIONS`.
+
+
+## Examples
+
+### Example 1: Regular features
+
 ```cmake
-vcpkg_check_features(<feature> <output_variable>)
-```
-can be used as a replacement of:
-```cmake
-if(<feature> IN_LIST FEATURES)
-    set(<output_variable> ON)
-else()
-    set(<output_variable> OFF)
-endif()
+$ ./vcpkg install mimalloc[asm,secure]
+
+# ports/mimalloc/portfile.cmake
+vcpkg_check_features(OUT_FEATURE_OPTIONS FEATURE_OPTIONS
+  # Keyword FEATURES is optional if INVERTED_FEATURES are not used
+    asm       MI_SEE_ASM
+    override  MI_OVERRIDE
+    secure    MI_SECURE
+)
+
+vcpkg_configure_cmake(
+  SOURCE_PATH ${SOURCE_PATH}
+  PREFER_NINJA
+  OPTIONS
+    # Expands to "-DMI_SEE_ASM=ON; -DMI_OVERRIDE=OFF; -DMI_SECURE=ON"
+    ${FEATURE_OPTIONS}
+)
 ```
 
-However, if you have a feature that was checked like this before:
+### Example 2: Inverted features
+
 ```cmake
-if(<feature> IN_LIST FEATURES)
-    set(<output_variable> OFF)
-else()
-    set(<output_variable> ON)
-endif()
+$ ./vcpkg install cpprestsdk[websockets]
+
+# ports/cpprestsdk/portfile.cmake
+vcpkg_check_features(OUT_FEATURE_OPTIONS FEATURE_OPTIONS
+  INVERTED_FEATURES # <- Keyword INVERTED_FEATURES required
+    brotli      CPPREST_EXCLUDE_BROTLI
+    websockets  CPPREST_EXCLUDE_WEBSOCKETS
+)
+
+vcpkg_configure_cmake(
+  SOURCE_PATH ${SOURCE_PATH}
+  PREFER_NINJA
+  OPTIONS
+    # Expands to "-DCPPREST_EXCLUDE_BROTLI=ON; -DCPPREST_EXCLUDE_WEBSOCKETS=OFF"
+    ${FEATURE_OPTIONS}
+)
 ```
-then you should not use `vcpkg_check_features` instead. [```oniguruma```](https://github.com/microsoft/vcpkg/blob/master/ports/oniguruma/portfile.cmake), for example, has a feature named `non-posix` which is checked with:
+
+### Example 3: Set multiple options for same feature
+
 ```cmake
-if("non-posix" IN_LIST FEATURES)
-    set(ENABLE_POSIX_API OFF)
-else()
-    set(ENABLE_POSIX_API ON)
-endif()
-```
-and by replacing these code with:
+$ ./vcpkg install pcl[cuda]
+
+# ports/pcl/portfile.cmake
+vcpkg_check_features(OUT_FEATURE_OPTIONS FEATURE_OPTIONS
+    cuda  WITH_CUDA
+    cuda  BUILD_CUDA
+    cuda  BUILD_GPU
+)
+
+vcpkg_configure_cmake(
+  SOURCE_PATH ${SOURCE_PATH}
+  PREFER_NINJA
+  OPTIONS
+    # Expands to "-DWITH_CUDA=ON; -DBUILD_CUDA=ON; -DBUILD_GPU=ON"
+    ${FEATURE_OPTIONS}
+)
+``` 
+
+### Example 4: Use regular and inverted features
+
 ```cmake
-vcpkg_check_features(non-posix ENABLE_POSIX_API)
-```
-is totally wrong.
+$ ./vcpkg install rocksdb[tbb]
 
-`vcpkg_check_features` is supposed to be called only once. Otherwise, the `FEATURE_OPTIONS` variable set by a previous call will be overwritten.
+# ports/rocksdb/portfile.cmake
+vcpkg_check_features(OUT_FEATURE_OPTIONS FEATURE_OPTIONS
+  FEATURES # <- Keyword FEATURES is required because INVERTED_FEATURES are being used
+    tbb   WITH_TBB
+  INVERTED_FEATURES
+    tbb   ROCKSDB_IGNORE_PACKAGE_TBB
+)
 
-## Examples
+vcpkg_configure_cmake(
+  SOURCE_PATH ${SOURCE_PATH}
+  PREFER_NINJA
+  OPTIONS
+    # Expands to "-DWITH_TBB=ON; -DROCKSDB_IGNORE_PACKAGE_TBB=OFF"
+    ${FEATURE_OPTIONS}
+)
+``` 
+
+## Examples in portfiles
+
+* [cpprestsdk](https://github.com/microsoft/vcpkg/blob/master/ports/cpprestsdk/portfile.cmake)
+* [pcl](https://github.com/microsoft/vcpkg/blob/master/ports/pcl/portfile.cmake)
+* [rocksdb](https://github.com/microsoft/vcpkg/blob/master/ports/rocksdb/portfile.cmake)
 
-* [czmq](https://github.com/microsoft/vcpkg/blob/master/ports/czmq/portfile.cmake)
-* [xsimd](https://github.com/microsoft/vcpkg/blob/master/ports/xsimd/portfile.cmake)
-* [xtensor](https://github.com/microsoft/vcpkg/blob/master/ports/xtensor/portfile.cmake)
 
 ## Source
 [scripts/cmake/vcpkg_check_features.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_check_features.cmake)

diff --git a/docs/maintainers/vcpkg_configure_cmake.md b/docs/maintainers/vcpkg_configure_cmake.md
index b78ef54d9..ebbd92ed1 100644
--- a/docs/maintainers/vcpkg_configure_cmake.md
+++ b/docs/maintainers/vcpkg_configure_cmake.md
@@ -18,14 +18,15 @@ vcpkg_configure_cmake(
 
 ## Parameters
 ### SOURCE_PATH
-Specifies the directory containing the `CMakeLists.txt`. By convention, this is usually set in the portfile as the variable `SOURCE_PATH`.
+Specifies the directory containing the `CMakeLists.txt`.
+By convention, this is usually set in the portfile as the variable `SOURCE_PATH`.
 
 ### PREFER_NINJA
-Indicates that, when available, Vcpkg should use Ninja to perform the build. This should be specified unless the port is known to not work under Ninja.
+Indicates that, when available, Vcpkg should use Ninja to perform the build.
+This should be specified unless the port is known to not work under Ninja.
 
 ### DISABLE_PARALLEL_CONFIGURE
 Disables running the CMake configure step in parallel.
-
 This is needed for libraries which write back into their source directory during configure.
 
 ### NO_CHARSET_FLAG
@@ -36,7 +37,8 @@ This is needed for libraries that set their own source code's character set.
 ### GENERATOR
 Specifies the precise generator to use.
 
-This is useful if some project-specific buildsystem has been wrapped in a cmake script that won't perform an actual build. If used for this purpose, it should be set to "NMake Makefiles".
+This is useful if some project-specific buildsystem has been wrapped in a cmake script that won't perform an actual build.
+If used for this purpose, it should be set to "NMake Makefiles".
 
 ### OPTIONS
 Additional options passed to CMake during the configuration.
diff --git a/docs/maintainers/vcpkg_prettify_command.md b/docs/maintainers/vcpkg_prettify_command.md
new file mode 100644
index 000000000..1856e06b4
--- /dev/null
+++ b/docs/maintainers/vcpkg_prettify_command.md
@@ -0,0 +1,17 @@
+# vcpkg_prettify_command
+
+Turns list of command arguments into a formatted string.
+
+## Usage
+```cmake
+vcpkg_prettify_command()
+```
+
+## Examples
+
+* `scripts/cmake/vcpkg_execute_build_process.cmake`
+* `scripts/cmake/vcpkg_execute_required_process.cmake`
+* `scripts/cmake/vcpkg_execute_required_process_repeat.cmake`
+
+## Source
+[scripts/cmake/vcpkg_prettify_command.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_prettify_command.cmake)

diff --git a/docs/tool-maintainers/testing.md b/docs/tool-maintainers/testing.md
new file mode 100644
index 000000000..28cc9e099
--- /dev/null
+++ b/docs/tool-maintainers/testing.md
@@ -0,0 +1,162 @@
+Testing
+=======
+
+Testing vcpkg is important whenever one makes changes to the tool itself, and
+writing new tests and keeping them up to date is also very important. If one's
+code is subtly broken, we'd rather find it out right away than a few weeks down
+the line when someone complains!
+
+Running Tests
+-------------
+
+Before anything else, we should know whether you can actually run the tests!
+All you should need is a way to build vcpkg -- anything will do! All you have to
+do is follow the guide 😄
+
+With `$VCPKG_DIRECTORY` being the directory where you have cloned vcpkg, create
+a build directory in `$VCPKG_DIRECTORY/toolsrc` (commonly named `out`), and
+`cd` into it. Make sure to clean it out if it already exists!
+
+```sh
+$ cmake .. -DCMAKE_BUILD_TYPE=Debug -G Ninja
+$ cmake --build .
+$ ./vcpkg-test # ./vcpkg-test [$SPECIFIC_TEST] for a specific set of tests
+$ # i.e., ./vcpkg-test [arguments]
+```
+
+If you make any modifications to `vcpkg`, you'll have to do the
+`cmake --build .` step again.
+
+Writing Tests
+-------------
+
+In your journey to write new tests, and to modify existing tests, reading the
+[Catch2 documentation] will be very helpful! Come back after reading those 😀
+
+You'll want to place your tests in one of the existing files, or, if it doesn't
+belong in any of those, in a [new file](#adding-new-test-files).
+
+The layout of these tests is as follows:
+
+```cpp
+// ... includes
+
+TEST_CASE("Name of test", "[filename without the .cpp]") {
+  // setup and the like
+  REQUIRE(some boolean expression);
+}
+
+// etc.
+```
+
+You want to give these test cases good, descriptive, unique names, like
+`SourceParagraph construct minimum` -- it doesn't need to be extremely clear
+english, and shorthand is good, but make sure it's clear what the test is from
+the name. For the latter parameter, known as "tags", you should at least put the
+name of the file which the test case is in -- e.g., in `arguments.cpp`, you'd
+tag all of the test cases with `[arguments]`.
+
+If you wish to add helper functions, make sure to place them in an anonymous
+namespace -- this will ensure that they don't trample over anybody else's
+space. Additionally, there are a few helper functions that live in
+`<vcpkg-test/util.h>` and `src/vcpkg-test/util.cpp` -- make sure to look into
+them so that you're not rewriting functionality.
+
+That should be all you need to know to start writing your own tests!
+Remember to check out the [Catch2 documentation]
+if you'd like to get more advanced with your tests,
+and good luck on your testing journey!
+
+Adding New Test Files
+---------------------
+
+Adding new test files should be easy and straightforward. All it requires is
+creating a new source file in `toolsrc/src/vcpkg-test`, and then rerunning
+`CMake` in order to pick up the glob changes.
+
+### Example
+
+Let's try writing a new test file called `example` (very creative, I know).
+
+First, we should create a file, `example.cpp`, in `toolsrc/src/vcpkg-test`:
+
+```cpp
+// vcpkg-test/example.cpp
+#include <vcpkg-test/catch.h>
+```
+
+This is the minimum file needed for tests; let's rebuild our CMake directory.
+You'll have to clean out the existing `out` directory for CMake to rerun
+globbing.
+
+```sh
+$ cmake .. -DCMAKE_BUILD_TYPE=Debug -G Ninja
+# ...
+-- Build files have been written to: $VCPKG_DIRECTORY/toolsrc/out
+$ cmake --build .
+[80/80] Linking CXX executable vcpkg.exe
+```
+
+Okay, now let's make sure this worked; add a test case to `example.cpp`:
+
+```cpp
+TEST_CASE("Example 1 - fail", "[example]") {
+  REQUIRE(false);
+}
+```
+
+Now build the tests again, and run them:
+
+```sh
+$ cmake --build .
+[2/2] Linking CXX executable vcpkg-test.exe
+$ ./vcpkg-test
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+vcpkg-test.exe is a Catch v2.9.1 host application.
+Run with -? for options
+
+-------------------------------------------------------------------------------
+Example 1 - fail
+-------------------------------------------------------------------------------
+$VCPKG_DIRECTORY/toolsrc/src/vcpkg-test/example.cpp(3)
+...............................................................................
+
+$VCPKG_DIRECTORY/toolsrc/src/vcpkg-test/example.cpp(14): FAILED:
+  REQUIRE( false )
+
+===============================================================================
+test cases:  102 |  101 passed | 1 failed
+assertions: 3611 | 3610 passed | 1 failed
+```
+
+Hopefully, that worked! It should compile correctly, and have one failing test.
+Now let's try a more complex test, after deleting the old one;
+
+```cpp
+// add #include <vcpkg/base/strings.h> to the top of the file
+namespace Strings = vcpkg::Strings;
+
+TEST_CASE("Example 2 - success", "[example]") {
+  std::string hello = "Hello";
+  REQUIRE(Strings::case_insensitive_ascii_equals(hello, "hELLo"));
+  REQUIRE_FALSE(Strings::case_insensitive_ascii_starts_with(hello, "E"));
+}
+```
+
+Now compile and build the tests, and this time let's only run our example tests:
+
+```sh
+$ cmake --build .
+[2/2] Linking CXX executable vcpkg-test.exe
+$ ./vcpkg-test [example]
+Filters: [example]
+===============================================================================
+All tests passed (2 assertions in 1 test case)
+```
+
+Hopefully you have one test running and succeeding! If you have that, you have
+succeeded at adding a new file to vcpkg's tests. Congratulations! Have fun on
+the rest of your journey 🐱‍👤😁
+
+[Catch2 documentation]: https://github.com/catchorg/Catch2/blob/master/docs/tutorial.md#top