From 165907550c8f6ce7506beef591f55cd3f8458d78 Mon Sep 17 00:00:00 2001 From: nicole mazzuca Date: Fri, 2 Aug 2019 09:52:39 -0700 Subject: Update tests, and add documentation! (#7506) This PR does the following: * fix tests -- now, they're always built in the CMake scripts, and they work on VS2015 *add a new flag, BUILD_TESTING, which allows one to turn off testing builds * Add documentation for running tests --- docs/index.md | 5 ++ docs/tool-maintainers/testing.md | 162 +++++++++++++++++++++++++++++++++++++++ 2 files changed, 167 insertions(+) create mode 100644 docs/tool-maintainers/testing.md (limited to 'docs') 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/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 +`` 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 +``` + +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 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 -- cgit v1.2.3 From 4d551ff4b3cea2f387b02ed69486a23b1be2fd73 Mon Sep 17 00:00:00 2001 From: Robert Schumacher Date: Fri, 2 Aug 2019 15:42:17 -0700 Subject: [vcpkg-docs] Reword and reorganize overlay-triplets-linux-dynamic.md (#7502) --- docs/examples/overlay-triplets-linux-dynamic.md | 84 ++++++++----------------- 1 file changed, 26 insertions(+), 58 deletions(-) (limited to 'docs') 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 -
-
    -
  • arm-uwp
    • -
  • arm-windows
    • -
  • arm64-uwp
    • -
  • arm64-windows
    • -
  • x86-uwp
    • -
  • x86-windows
    • -
  • x86-windows-static
    • -
  • x64-uwp
    • -
  • x64-linux
    • -
  • x64-osx
    • -
  • x64-windows
    • -
  • x64-windows-static
    • -
-
+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 ``` -- cgit v1.2.3