Building the Documentation
Building Plywood's documentation is similar to building and running the Hello World sample, except that it involves two steps:
- Build and run the WebCooker, which generates data files needed by the WebServer.
- Build and run the WebServer.
Additionally, building the WebCooker requires choosing an extern provider, which helps demonstrate how Plywood works with third-party libraries.
Before you proceed, make sure you've built PlyTool using the steps described in Quick Start.
1. Build and run the WebCooker
First, open a command shell and run the following command from the workspace root. If you're running on Linux or macOS, replace
./plytool instead. (It doesn't really matter what the current directory is as long as your command shell finds the
$ plytool run --auto WebCooker
You should see output similar to the following:
Created build folder 'WebCooker' with root target 'WebCooker' at: C:\Jeff\plywood\data\build\WebCooker\ Can't generate build system in folder 'WebCooker' because extern 'libsass' is not selected. 1 compatible provider is available: libsass.prebuilt (not installed)
This command created a new build folder
WebCooker and added the root target
WebCooker to that folder. However, it fails after that because we haven't told PlyTool where to get LibSass.
To solve this problem, run the
plytool extern select --install command using the name of the provider suggested in the previous output. On Windows, it will be
libsass.prebuilt; on Debian/Ubuntu Linux, it will be
libsass.apt; and on macOS, where MacPorts is currently needed, it'll be
libsass.macports. New providers can be added in the future to support additional package managers or installation methods.
$ plytool extern select --install libsass.prebuilt
In the future, PlyTool will have a mechanism to automatically select and install appropriate extern providers for your system, so the above step will be performed automatically.
plytool run --auto WebCooker again. It will re-use the existing build folder, and this time it should successfully generate, build and run the WebCooker:
$ plytool run --auto WebCooker Generating build system for 'WebCooker'... Successfully generated build system in folder 'WebCooker'. Building Debug configuration of 'WebCooker'... ... Main.cpp WebCooker.vcxproj -> C:\Jeff\plywood\data\build\WebCooker\build\Debug\WebCooker.exe Running 'C:\Jeff\plywood\data\build\WebCooker\build\Debug\WebCooker.exe'...
Once the WebCooker finishes running, there will be a bunch of data files in the
data/docsite directory relative to your workspace root. These are the data files required by the WebServer.
2. Build and run the WebServer
Next, build and run the WebServer using the following command. Note that this time, we specify
--add instead of
--add option makes PlyTool re-use the same build folder;
WebServer is simply added an additional target. (We could use
--auto here, in which case PlyTool will create a separate build folder, but
--add is quicker because several required modules are already built in the existing folder.)
$ plytool run --add WebServer Added target 'WebServer' to folder 'WebCooker'. Generating build system for 'WebCooker'... Successfully generated build system in folder 'WebCooker'. Building Debug configuration of 'WebServer'... ... WebServer.vcxproj -> C:\Jeff\plywood\data\build\WebCooker\build\Debug\WebServer.exe Running 'C:\Jeff\plywood\data\build\WebCooker\build\Debug\WebServer.exe'... Serving from C:\Jeff\plywood\data\docsite on port 8080
While the WebServer is still running, navigate to the following URL in your web browser: http://127.0.0.1:8080
If everything went well, you'll be greeted with the Plywood documentation running on your local machine!
If you chose Visual Studio or Xcode as your generator in Quick Start, you may now find the generated project files (such as a Visual Studio
.sln or Xcode
.xcodeproj) in the
data/build/WebCooker/build (or similar) relative to the workspace root.
You can also open the project files automatically in your IDE from the PlyTool command line:
$ plytool open