This document covers the build and execution instructions for Plaid on Windows.
Plaid has the following library dependencies:
- OpenSSL (or another libcurl supported TLS library)
- xerces 3.1+
Pre-built binaries for these libraries are provided in a file called install.zip. The files can be downloaded from here: https://app.box.com/s/gnkmook0tl95r4qvunprlacphtc9tlan.
Extract the install directory from
install.zip and move
Instructions for building the 3rd party libraries are in section Build Third Party Dependencies. Its far easier to use the pre-built binaries, but instructions are provided for situations where the build settings chosen for the pre-built binaries don't match the target system (run 32 bit instead of 64 bit for example).
Plaid uses cmake and Visual Studio 2015 to build. CMake Windows binaries can be installed from here: https://cmake.org/download/. Visual Studio 2015 is available from Microsoft. Newer versions of Visual Studio should work but will need to set the platform toolset to Visual Studio 2015 (v140).
The Windows build creates two components built in separate steps:
- plaidven.exe: executable
- plaidven-notifierhttp-plugin.dll: sample plugin
plaidven.exe uses CMake to generate a Visual Studio project and is built from the command line. To aid in building and debugging the plugin, a hand built Visual Studio project is provided for building the sample plugin plaidven-notifierhttp-plugin.dll.
The following commands must be run from a Visual Studio developer command prompt. Start a prompt in the Plaid source root directory.
To build Plaid in release mode, run the following commands in a Visual Studio 2015 command prompt from the root of the Plaid source:
mkdir build\release && cd build\release cmake -G "Visual Studio 14 2015 Win64" -DCMAKE_BUILD_TYPE=Release ..\.. cmake --build . --config Release
After building the plugin (see below) and Plaid In release mode, everything needed to run Plaid is copied to
To build plaid in debug mode, run the following commands in a Visual Studio 2015 command prompt from the root of the Plaid source:
mkdir build\debug && cd build\debug cmake -G "Visual Studio 14 2015 Win64" -DCMAKE_BUILD_TYPE=Debug ..\.. cmake --build . --config Debug
The executable built in debug can be used to debug the plugin. The plugin build (covered below) will copy the debug Plaid build along with all binaries need to run Plaid into the plugin output directory.
Sample Plugin Build
A pre-built Visual Studio project is provided for the sample plugin in
pluginimpl\plaidven-notifierhttp-plugin.sln. Prior to building the plugin, follow the instructions above to build Plaid for debug or release.
Plaid and the plugin require a config file. Before starting the plugin build, rename the following files:
- config.json.sample in
- plugin_config.json.sample in
The Visual Studio debug build contains a post-build step to copy config.json and plugin plugin_config.json and all binaries needed to debug the plugin to the plugin output directory.
Next, Open the Visual Studio project file found in
Change the build type to Debug or Release to match the corresponding build type selected for Plaid: the Plaid build type and plugin build type must match.
Start the build by selecting Build -> Build Solution from the menu.
The final step of the build will copy files to the plugin debug output directory when in debug mode or to deploy in the Plaid source root directory when in release mode. The deploy directory contains everything needed to run Plaid in release mode. The plugin debug output directory contains everything needed to debug the plugin from Visual Studio.
Debugging the plugin
When built in debug mode, the plugin can be debugged from the Visual Studio solution. Executing the debugger will launch a debug build of Plaid. Breakpoints set in the IDE will be hit when Plaid calls the callbacks in the plugin. The image blow shows a breakpoint triggered in the
The project is pre-configure to run plaidven from the plugin output directory. Files involved with running Plaid are highlighted below for reference:
Plaid is executed from the command line and takes two parameters: a path to a json formatted schema file (which describes the Plaid config), and the path to a config file. See the sample file
In a release build, the outputs of the build are copied to
<rootdir>\deploy\plaid. To run Plaid using the default plugin and default Plaid config, execute the following command from
.\plaidven schema.json config.json
Build Third Party Dependencies
Binaries of the third party dependencies used by Plaid should be downloaded from this public github project: https://github.com/gridfabric/plaid-deps/releases/tag/v1.0.1. The following instructs building these binaries from source.
We use the installer from Shining Light: https://slproweb.com/products/Win32OpenSSL.html. Plaid expects the binaries to be located at
<rootdir>\install\openssl. Note the openssl installer will try to append another directory past
<rootdir>\install\openssl, so be sure to remove this directory from the installer path.
If installed correctly, the
<rootdir>\install\openssl directory will have
The source for curl is provided in
deps\curl. To build curl, run the following
commands from the root directory:
cd deps\curl .\buildconf.bat cd winbuild nmake /f Makefile.vc VC=14 MACHINE=X64 mode=dll ENABLE_WINSSL=no DEBUG=no WITH_SSL=dll WITH_DEVEL=..\..\..\install\openssl
This creates a directory that will be named similarly to
<rootdir>\deps\curl\builds\libcurl-vc14-X64-release-dll-ipv6-sspi-winssl that contains
lib directories. Copy the
lib directories to
Note that the WITH_DEVEL option tells curl where to find openssl, so be sure to install openssl as outlined in this document prior to building curl.
To create a release build, change
DEBUG=yes and copy the files to
<rootdir>\install\debug\curl\ when the build completes.
Xerces is built using Visual Studio. The procedures outlined below are for a release build. Replace "release" with "debug" for a debug build.
<rootdir>\deps\xerces-c\projects\Win32\VC14\xerces-all\XercesLib\XercesLib.vcxprojwith Visual Studio 2015
- Change the build to Release and x64 using the combo boxes under the menu
- Build XercesLib by right clicking and selecting Build.