A pgxman buildkit is a configuration file in YAML format that pgxman uses to specify how a PostgreSQL extension should be built and packaged. Buildkits are added to the buildkit repository.

Below is an example buildkit configuration including all the fields:

# API version of the buildkit specification. Only v1 is supported.
apiVersion: v1
# Name of the extension.
name: my-extension
# Version of the extension. Must be in semantic versioning v2 format.
version: "0.4.4"
# URL of the extension's homepage.
homepage: https://github.com/org/repo
# URL of the extension's repository.
repository: https://github.com/org/repo
# URL of the extension's source code. Only `tar.gz` files are supported.
source: https://github.com/org/repo/archive/refs/tags/v0.4.4.tar.gz
# Description of the extension.
description: Extension description
# License of the extension. Must be a valid SPDX license identifier.
license: PostgreSQL
# Keywords relevant to the extension.
keywords:
  - keyword1
  - keyword2
# Supported architectures.
arch:
  - amd64
  - arm64
# Maintainers of the buildkit.
maintainers:
  - name: Owen Ou
    email: o@hydra.so
# Supported PostgreSQL versions.
pgVersions:
  - "13"
  - "14"
  - "15"
  - "16"
# Build scripts for the extension.
build:
  # Steps to be executed before the main build process.
  pre:
    - name: Install dependencies
      run: |
        # Do something
  # Steps to be executed for the main build process.
  main:
    - name: Build pgvector
      run: |
        # Do something
  # Steps to be executed after the main build process.
  post:
    - name: Cleanup
      run: |
        # Do something
# Build dependencies of the extension.
buildDependencies:
  - dep1
  - dep2
  - pgxman/extension
# Run dependencies of the extension.
runDependencies:
  - dep3
  - dep4
  - pgxman/extension
# Overrides the default builders to be used.
builders:
  # Overrides the debian:bookworm builder.
  debian:bookworm:
    # Overrides the global build dependencies for this builder.
    buildDependencies:
      - dep1
      - dpe2
    # Overrides the global run dependencies for this builder.
    runDependencies:
      - dep3
      - dep4
    # Extra APT repositories to add.
    aptRepositories:
      - id: repo1
        types:
          - deb
          - deb-src
        uris:
          - http://repo1.com
        suites:
          - suite1
        components:
          - comp1
        signedKey:
          - uri: http://repo1.com/key
            format: gpg
  # Overrides the ubuntu:jammy builder.
  ubuntu:jammy:
    # Overrides the global build dependencies for this builder.
    buildDependencies:
      - dep1
      - dpe2
    # Overrides the global run dependencies for this builder.
    runDependencies:
      - dep3
      - dep4
    # Extra APT repositories to add.
    aptRepositories:
      - id: repo1
        types:
          - deb
          - deb-src
        uris:
          - http://repo1.com
        suites:
          - suite1
        components:
          - comp1
        signedKey:
          - uri: http://repo1.com/key
            format: gpg
overrides:
  pgVersions:
    # overrides fields for pg 13
    "13":
      version: "1.2.3"
      homepage: https://github.com/org/repo2
      repository: https://github.com/org/repo2
      source: https://github.com/org/repo/archive/refs/tags/v1.2.3.tar.gz
    # overrides fields for pg 14
    "14":
      version: "2.3.4"
      homepage: https://github.com/org/repo3
      repository: https://github.com/org/repo3
      source: https://github.com/org/repo/archive/refs/tags/v2.3.4.tar.gz

​
apiVersion

  • Description: Defines the API version to which the buildkit conforms, ensuring its compatibility.
  • Type: String
  • Required: Yes
  • Supported Values: Currently, only v1 is supported.

​
name

  • Description: Identifies the name of the extension.
  • Type: String
  • Required: Yes

​
maintainers

  • Description: Lists the individuals or organizations responsible for maintaining the buildkit.
  • Type: List of objects
  • Required: Yes
  • Fields:
    • name:
      • Description: The maintainer’s full name.
      • Type: String
      • Required: Yes
    • email:
      • Description: The maintainer’s contact email.
      • Type: String
      • Required: Yes

​
source

  • Description: Specifies the URI for the extension’s source code. The URI can be a HTTP/HTTPS URL or a local file path. If the URI is a HTTP/HTTPS URL, it must end with .tar.gz.
  • Type: String
  • Required: Yes

​
repository

  • Description: Specifies the URL for the extension’s repository, where users can view the source code in more detail.
  • Type: String
  • Required: Yes

​
version

  • Description: Specifies the version of the extension buildkit. The versioning must adhere to the Semantic Versioning 2.0.0 format.
  • Type: String
  • Required: Yes

​
pgVersions

  • Description: Lists the PostgreSQL versions compatible with the extension. If unspecified, the extension is assumed to be compatible with all versions.
  • Type: List of strings
  • Required: No
  • Supported Values: "13", "14", "15", "16"
  • Default Values: "13", "14", "15", "16"

​
license

  • Description: Specifies the license under which the extension is distributed. The license must be a valid SPDX license identifier.
  • Type: String
  • Required: No

​
build

  • Description: Contains Bash scripts that automates the extension’s build process. Some environment variables are set during the execution of these scripts. The built extension must be placed in the $DESTDIR directory.
  • Type: Object
  • Required: Yes
  • Fields:
    • pre:
      • Description: A list of steps before the main build process.
      • Type: List of objects
      • Required: No
      • Fields:
        • name:
          • Description: Name of the build step.
          • Type: String
          • Required: Yes
        • run:
          • Description: Bash command for the build step.
          • Type: String
          • Required: Yes
    • main:
      • Description: A list of steps to be executed during main build process.
      • Type: List of objects
      • Required: Yes
      • Fields:
        • name:
          • Description: Name of the build step.
          • Type: String
          • Required: Yes
        • run:
          • Description: Bash command for the build step.
          • Type: String
          • Required: Yes
      • Environment Variables:
        • DESTDIR: Indicates the directory where the built extension should be placed.
        • WORKDIR: The working directory that contains the source code and the script.
        • PG_CONFIG: Identifies the path to the pg_config executable.
        • USE_PGXS: Always set to 1.
        • PG_VERSION: The PostgreSQL version that the script is building against.
    • post:
      • Description: A list of steps after the main build process.
      • Type: List of objects
      • Required: No
      • Fields:
        • name:
          • Description: Name of the build step.
          • Type: String
          • Required: Yes
        • run:
          • Description: Bash command for the build step.
          • Type: String
          • Required: Yes

The following is an example:

build: |
  make
  DESTDIR=${DESTDIR} make install

​
runDependencies

  • Description: Lists the packages needed for the extension to function properly at runtime. pgxman extensions can be specified as dependencies using the format pgxman/EXTENSION.
  • Type: List of strings
  • Required: No

​
buildDependencies

  • Description: Lists the packages necessary for building the extension. pgxman extensions can be specified as dependencies using the format pgxman/EXTENSION.
  • Type: List of strings
  • Required: No

​
arch

  • Description: Lists the architectures that the extension supports. If unspecified, all architectures are assumed to be supported.
  • Type: List of strings
  • Required: No
  • Supported Values: amd64, arm64
  • Default Values: amd64, arm64

​
formats

  • Description: Lists the formats in which the built extension can be packaged. Currently, only Debian packages (deb) are supported.
  • Type: List of strings
  • Required: No
  • Supported Values: deb
  • Default Values: deb

​
description

  • Description: Provides a succinct overview of the extension.
  • Type: String
  • Required: No

​
homepage

  • Description: Specifies the URL of the extension’s homepage, where users can find additional information about the extension.
  • Type: String
  • Required: No

​
keywords

  • Description: Lists keywords relevant to the extension, aiding its discovery in pgxman tool searches.
  • Type: List of strings
  • Required: No

​
readme

  • Description: Specifies the README content for the extension. The content may include directions for installing, configuring, and using the extension, as well as any other information a user may find helpful. The README will be shown on the registry page. If this field is unspecified, pgxman tries to detect a README file at the root of extension source.
  • Type: String
  • Required: No

​
builders

  • Description: Specify the builders to be used. If not provided, all supported builders are used.
  • Type: Object
  • Required: No
  • Fields:
    • debian:bookworm:
      • Description: Specifies the Debian Bookworm builder.
      • Type: Object
      • Required: No
      • Fields:
        • buildDependencies:
          • Description: Lists the packages necessary for building for the debian:bookworm builder. This list overrides the global buildDependencies. pgxman extensions can be specified as dependencies using the format pgxman/EXTENSION.
          • Type: List of strings
          • Required: No
        • runDependencies:
          • Description: Lists the packages needed for the extension to function properly at runtime for the debian:bookworm builder. This list overrides the global runDependencies. pgxman extensions can be specified as dependencies using the format pgxman/EXTENSION.
          • Type: List of strings
          • Required: No
        • image:
          • Description Speifies the build image.
          • Type: String
          • Required: No
          • Default Value: ghcr.io/pgxman/builder/debian/bookworm
        • aptRepositories:
          • Description: Lists the APT repositories containing the above Debian packages.
          • Type: List of objects
          • Required: No
          • Fields:
            • id:
              • Description: The repository’s id.
              • Type: String
              • Required: Yes
            • types:
              • Description: The repository’s types.
              • Type: String
              • Required: Yes
              • Supported Values deb, deb-src
            • uris:
              • Description: The repository’s URIs.
              • Type: List of strings
              • Required: Yes
            • suites:
              • Description: The repository’s suites within the APT repository.
              • Type: List of objects
              • Required: Yes
            • components:
              • Description: The components of the APT repository.
              • Type: List of strings
              • Required: Yes
            • signedKey:
              • Description: The GPG signed key of the APT repository.
              • Type: List of objects
              • Required: Yes
              • Fields:
                • uri:
                  • Description: The HTTP URL to download the GPG key.
                  • Type: String
                  • Required: Yes
                • format:
                  • Description: The format of the GPG key.
                  • Type: String
                  • Required: Yes
                  • Supported Values: gpg, asc
    • ubuntu:jammy:
      • Description: Specifies the Ubuntu Jammy builder.
      • Type: Object
      • Required: No
      • Fields:
        • buildDependencies:
          • Description: Lists the packages necessary for building for the ubuntu:jammy builder. This list overrides the global buildDependencies. pgxman extensions can be specified as dependencies using the format pgxman/EXTENSION.
          • Type: List of strings
          • Required: No
        • runDependencies:
          • Description: Lists the packages needed for the extension to function properly at runtime for the ubuntu:jammy builder. This list overrides the global runDependencies. pgxman extensions can be specified as dependencies using the format pgxman/EXTENSION.
          • Type: List of strings
          • Required: No
        • image:
          • Description Speifies the build image.
          • Type: String
          • Required: No
          • Default Value: ghcr.io/pgxman/builder/ubuntu/jammy
        • aptRepositories:
          • Description: Lists the APT repositories containing the above Debian packages.
          • Type: List of objects
          • Required: No
          • Fields:
            • id:
              • Description: The repository’s id.
              • Type: String
              • Required: Yes
            • types:
              • Description: The repository’s types.
              • Type: String
              • Required: Yes
              • Supported Values deb, deb-src
            • uris:
              • Description: The repository’s URIs.
              • Type: List of strings
              • Required: Yes
            • suites:
              • Description: The repository’s suites within the APT repository.
              • Type: List of objects
              • Required: Yes
            • components:
              • Description: The components of the APT repository.
              • Type: List of strings
              • Required: Yes
            • signedKey:
              • Description: The GPG signed key of the APT repository.
              • Type: List of objects
              • Required: Yes
              • Fields:
                • uri:
                  • Description: The HTTP URL to download the GPG key.
                  • Type: String
                  • Required: Yes
                • format:
                  • Description: The format of the GPG key.
                  • Type: String
                  • Required: Yes
                  • Supported Values: gpg, asc

​
overrides

  • Description: This section allows for the customization of buildkit fields based on specific conditions. It’s particularly useful for adapting the build process to different versions of PostgreSQL or varying build environments.
  • Type: Object
  • Required: No
  • Fields:
    • pgVersions:

      • Description: Tailors the buildkit configuration for specific PostgreSQL versions as defined in the pgVersions field.

      • Type: Map

      • Required: No

      • Key: The key should match the PostgreSQL versions listed in pgVersions at the root.

      • Value:

        • Type: Object
        • Fields:
          • source
          • version
          • build
          • builders
          • arch
          • formats
          • readme
          • buildDependencies
          • runDependencies

      • Examples:

        pgVersions:
  - "13"
  - "14"
  - "15"
overrides:
  pgVersions:
    "13":
      version: "1.2.3"
      source: https://github.com/org/repo/archive/refs/tags/v1.2.3.tar.gz
    "14":
      version: "2.3.4"
      source: https://github.com/org/repo/archive/refs/tags/v2.3.4.tar.gz