This document covers the build and execution instructions for Plaid on Linux.
As a general rule, Plaid will require >1GB of memory for the build stage and up to 2GB to be safe. Once it is built, it will run on far less. Some errors may occur if you are building Plaid in an environment with too little memory.
Plaid ships as a source bundle which includes some dependencies but expects other dependencies to be installed prior to build. Refer to your operating system documentation to install the dependencies.
Third Party Dependencies
Plaid has the following build tool dependencies:
- gcc 4.9+ / g++
Plaid has the following library dependencies:
- OpenSSL (or another libcurl supported TLS library)
- xerces 3.1+
Make sure you have these libraries installed before building Plaid.
When building, these libraries will likely require a core package plus a development package. For example, on Ubuntu 16.04 the xerces packages are libxerces-c-dev and libxerces-c3.1.
For Ubuntu 16.04, you can install all of them with the following command:
sudo apt-get install cmake make g++ libcurl3 libcurl4-openssl-dev libxerces-c-dev
Make sure that apt-get is up to date with
sudo apt-get update.
Additional dependencies are included in the deps directory and will be built automatically.
Plaid uses cmake and make to build. To build Plaid, run the following commands from the root directory:
mkdir -p build/debug && cd build/debug cmake -DCMAKE_BUILD_TYPE=Debug ../../ cmake --build . # To use multiple cores/processes to speed the build, use this instead: # cmake --build . ** -- -j <number of of cores + 1> # (replacing the placeholder with the appropriate # of cores +1)
To create a release build, run the following commands from the root directory:
mkdir -p build/release && cd build/release cmake -DCMAKE_BUILD_TYPE=Release ../../ cmake --build .
Running make will build Plaid and all of the included dependencies. The
oadr communication library takes a significant amount of time to build depending on the resources available on the build machine. Expect 10-20 minutes.
Once the build is complete, the following files should be available:
nova/nova: Core executable
nova/libnova.so: Core library
nova/libnova-notifierhttp-plugin.so: Sample HTTP plugin. This plugin communicates to vendor systems through HTTP posts. Your plugin can use this sample as a starting point or as a model to create a plugin from scratch. See Creating a Plugin for instructions to create a plugin from scratch.
liboadrsd.so: Serialize and deserialize OADR XML messages
liboadr.so: Core OADR communication library
libhttp.so: An http library for posting messages to the VTN
All of the libraries must be installed correctly to run Plaid. When building with cmake, these libraries will automatically be available to Plaid when run from the build directory.
Installing to a production system can be done by generating a package for your operating system.
The binary can be executed from an arbitrary directory as long as the libraries can be found. One option is to place all binaries in a single directory and execute the following export command before running Plaid:
Plaid is executed from the command line and takes two parameters:
- A path to a json formatted schema file (which describes the config)
- And the path to a Plaid config file. See the sample file
To run Plaid using the default plugin and default Plaid config, execute the following command from the build directory:
./nova/nova ../../nova/nova/config/schema.json ../../nova/nova/config/config.json.sample
sample if you are following the quickstart guide and have already updated the configuration.
Using the default config files, Plaid won't be configured to connect to a VTN, and the http plugin won't have endpoints configured to post to. Read the instructions in Connecting to a VTN to configure Plaid to connect to a VTN. Refer to the Plugin Reference section for instructions to configure the plugin.