Buildkit

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:

      Copy

      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