Plywood's workflow is based on the following concepts:
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.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.
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.
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.
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
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
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.
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
$ plytool extern select --install cairo.prebuilt
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