Skip to main content

Configure Polywrap build pipeline

In this section, we'll explore the Polywrap's build pipeline and how to configure it. This article will help you understand the follow concepts:

  • Polywrap's build pipeline
  • Customizing the Build Manifest file
  • Customizing the Dockerfile

Build pipeline#

The build process begins by running the build command from the polywrap CLI. The command will first search for the Polywrap Manifest, find the wrapper schema and implementation, and move these files into a Docker image.

Within the docker image, the wrapper schema is parsed and its contents are extracted into an ABI. The ABI is used to generate binding code for the wrapper. The wrapper is then compiled into a Wasm module. The ABI and the Polywrap Manifest are merged into a Wrap Manifest file called wrap.info.

While the default build settings work well for many projects, the toolchain offers a highly configurable build pipeline for those who need more customization.

Build Manifest#

The Build Manifest polywrap.build.yaml file is the entry point to build pipeline configuration.

Declaration#

The location of the Build Manifest must be declared in your Polywrap Manifest with a field labeled build. If a custom build manifest is not declared, the default build configuration will be used.

build: ./polywrap.build.yaml

Content#

format: # Polywrap YAML Format version
docker: # (Optional) Custom Docker configuration
name: # (Optional) Docker image name
dockerfile: # (Optional) Docker image file name
buildx: # (Optional) Configuration options for Docker Buildx, set to true for default value.
cache: # (Optional) Path to cache directory, set to true for default value, set to false to disable caching
remove builder: # (Optional) Remove the builder instance
removeImage: # (Optional) Remove the image
config: # (Optional) Custom build image configurations
node_version: # (Optional) Node version
include: # (Optional) Files to include in build
linked_packages: # (Optional) Array of locally linked packages into docker build image
- name: # Package name
path: # Path to linked package directory
filter: # (Optional) Ignore files matching this regex in linked package directory

Customizing the Dockerfile#

Those who need to fully customize the Docker image build steps can customize the Dockerfile. The Dockerfile is a text file containing instructions for Docker to build images. You can learn more about it at Docker's Dockerfile documentation.

To begin, either copy the default Dockerfile from the .polywrap/wasm/build/image folder or create your own.

Then, in the polywrap.build.yaml file, add a key called dockerfile with the path of the newly created Dockerfile as the value. That's it! Now, you can customize the Dockerfile to your heart's content.

format: 0.1.0
docker:
name: build-env
dockerfile: ./Dockerfile

Mustache support#

Mustache is a logic-less template system that can be used for HTML, config files, and more. You can learn more about writing Mustache templates here.

To enable Mustache capabilities for your Dockerfile, name your custom Dockerfile with a .mustache file extension:

dockerfile: ./Dockerfile.mustache

With Mustache, your Dockerfile will be able to recognize variable tags set within the config field of the Build Manifest. For example, in your Build Manifest file, you could have a key such as foo with the value hey like so:

format: 0.1.0
docker:
name: build-env
dockerfile: ./Dockerfile.mustache
config:
foo: hey

To use this variable in your Mustache-enabled Dockerfile, simply reference the variable with curly braces like so:

{{ foo }}