pkgdev:setup

Contents

1. Introduction
2. OS setup
   1. SmartOS / illumos
   2. macOS
3. Fetch Repositories
4. Create Sandbox

Introduction

Our goal is that our binary packages fulfill all of our users' needs. This isn't always possible, however - users may want packages we do not yet provide, or build with different options. Some users may also want to explore package development.

To satisfy those demands, it should instead be reasonably straight-forward for users to build or develop their own packages, and this guide hopefully provides all the information for them to do just that.

OS setup

Follow the instructions below for your target OS.

SmartOS / illumos

For SmartOS users we provide a pkgbuild image. This contains everything you need to get going quickly.

You can either use the LTS pkgbuild image specific to your release:

$ imgadm avail name=pkgbuild-lts version=~23.4
UUID                                  NAME          VERSION  OS       TYPE          PUB
ceeb6d4e-acab-11ee-8483-00151714048c  pkgbuild-lts  23.4.0   smartos  zone-dataset  2024-01-06

or you can also use the latest trunk image which supports building either trunk or any recent LTS:

$ imgadm avail name=pkgbuild-trunk version=~2024
UUID                                  NAME            VERSION   OS       TYPE          PUB
7223b551-4106-46f0-9eb9-3ebe8369ce97  pkgbuild-trunk  20240116  smartos  zone-dataset  2024-01-16

Create a zone using the chosen image uuid, giving it plenty of RAM and quota if you are planning to build large packages. For example:

{
  "brand": "joyent",
  "image_uuid": "7223b551-4106-46f0-9eb9-3ebe8369ce97",
  "alias": "pkgbuild-trunk",
  "max_physical_memory": 8192,
  "quota": 16,
  "resolvers": [
    "1.1.1.1"
  ],
  "dns_domain": "local",
  "nics": [
    {
      "nic_tag": "admin",
      "ip": "dhcp"
    }
  ]
}

$ vmadm create -f pkgbuild.json

macOS

If your main file system is not case-sensitive we recommend creating an APFS volume that is. We try to avoid case-insensitive issues in pkgsrc but there's always a chance that something is missed, so this avoids potential problems.

$ diskutil apfs addVolume disk1 "Case-sensitive APFS" data

Fetch repositories

On SmartOS with pkgbuild there will already be a clone of pkgsrc at /data/pkgsrc. You may want to git pull to update it, and if you are building a different branch compared to the version the pkgbuild image is targetting then checkout the correct branch:

$ cd /data/pkgsrc
$ git pull
$ git checkout release/trunk   # release/2023Q4, release/2022Q4, etc.
$ git submodule update

On macOS:

$ cd /Volumes/data   # if you created an APFS file system above
$ git clone https://github.com/TritonDataCenter/pkgsrc.git
$ cd pkgsrc
$ git checkout release/macos
$ git submodule init
$ git submodule update

Create Sandbox

On SmartOS, the pkgbuild repository aims to recreate the same environment that produces our official binary package sets. The run-sandbox script prepares a chroot environment with everything set up ready to build packages. It takes a single argument which is the pkgbuild configuration to use, based on one of the directories under pkgbuild/conf.

Some examples:

$ run-sandbox trunk-x86_64    # Create a trunk sandbox
$ run-sandbox 2023Q4-x86_64   # Create a 23.4.x sandbox
$ run-sandbox 2023Q4-tools    # Create a 23.4.x GZ "tools" sandbox

On macOS there used to be instructions for creating a sandbox, but the amount of setup is considerable and changes over time. At the current time it's simpler to just build as a regular user with no special setup.

You can now move onto building packages, or choose one of the other links in the "Package Development" section of the sidebar at the top of this page.