Key Concepts

Plywood's workflow is based on the following concepts:

Workspaces

A Plywood workspace is the root folder of the Plywood repository. This folder is located wherever you ran the git clone command in Quick Start. This folder contains the plytool (or plytool.exe on Windows) executable which is used to manage most of the workspace contents. For more information about the directory structure of the workspace, see Directory Structure.

Repos

The workspace root folder contains a repos directory, and each directory under repos is considered a repo folder. When you first install Plywood, there will be a single repo folder named plywood. All of the built-in Plywood modules are located here.

It's also possible, and encouraged, to create other repo folders. Typically, each repo folder comes from a different Git repository. Organizing your work into separate repos lets you distribute them independently.

You can share modules between repos by setting one repo as a child of another. A parent repo is allowed to reference any module or extern in its child repos. The relationship is transitive, so a parent can reference any module in its children's child repos, too.

Modules

Each repo folder contains a collection of modules. A Plywood module is a self-contained group of C++ source files that can depend on other modules or externs. To view a list of all available modules in your workspace, run the command:

$ plytool module list

Modules are defined by *.modules.cpp files scattered throughout each repo folder. Modules are allowed to depend on other modules in the same repo or in any child repo.

Modules can be instantiated as targets within a build folder.

Currently, all Plywood modules are built from source in every build folder that uses them. In the future, it may be possible to share targets between build folders instead.

Plywood modules should not be confused with C++20 modules. Unless otherwise indicated, any mention of the word "module" throughout the Plywood documentation is meant to refer to Plywood modules and not C++20 modules.

Build Folders

Each directory under plywood/data/build that contains an info.pylon file is considered a build folder. Each build folder is meant to contain a single build system along with any autogenerated source code needed by the build system. Files inside the build folder are maintained by PlyTool and are typically not edited manually. The info.pylon file contains information about the build folder, such as:

  • A set of root targets that ultimately get built to produce a library or executable.
  • A choice of CMake generator to use to create the build system.
  • A set of extern provider choices for the build system to use.

To create a new build folder, run

$ plytool folder create <name>

To view a list of existing build folders, run

$ plytool folder list

Targets

A target corresponds to a library or executable to build inside a build folder. Each target is instantiated from a module inside a repo. If that module depends on other modules, targets will be instantiated for its dependencies, too.

Each build folder contains a set of root targets. To add a root target to the current build folder, run:

$ plytool target add <module-name>

To view the list of existing root targets for the current build folder, run:

$ plytool target list

Externs

An extern is any third-party library or package that Plywood knows how to download and integrate into a build system. For example, the plywood repo comes with built-in knowledge of four third-party libraries: Cairo, libavcodec, libpng and LibSass. You can view known externs by running plytool extern list:

$ plytool extern list
Externs defined by repo 'plywood':
    cairo
    libavcodec
    libpng
    libsass

Modules can depend on externs just like they can depend on other modules. Whenever an extern is required by a build folder, you must specify which extern provider to use.

Extern Providers

An extern can come from multiple locations. Sometimes you want to install the extern through a system package manager such as apt, MacPorts or Conan. Sometimes you want to download prebuilt libraries to a local folder. Sometimes you want to build the extern from source to improve your debugging experience.

For each extern defined by a repo, a set of extern providers is also defined. Each extern provider offers a different way to install that extern. To view the set of providers for an extern, run plytool extern info:

$ plytool extern info libsass
Found 3 providers for extern 'libsass':
    libsass.macports (not supported on host system)
    libsass.apt (not supported on host system)
    libsass.prebuilt (installed)

If an extern is required in a build folder, you must select an extern provider for that folder. Providers can be selected using plytool extern select. If the provider is not yet installed, you can install it at the same time by including the --install flag.

$ plytool extern select --install cairo.prebuilt

Build Systems

Each build folder holds exactly one build system.

After defining a set of root targets for a build folder, you can generate the build system by running:

$ plytool generate