pkgdev:setup

Contents

1. Introduction
2. OS setup
3. SmartOS
4. Mac OS X
5. Ubuntu Linux
6. RedHat Linux
7. Fetch Repositories
8. Create Sandbox

## Introduction

In order to get started with package development it is recommended that you use the pkgbuild infrastructure. This provides scripts and configuration files used by Joyent to produce the official binary packages, and helps to ensure your environment is similar.

## OS setup

Follow the instructions below for your target OS.

### SmartOS

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

Use the image version which matches the package set you want to build. For example, to build packages for 16.4.x/2016Q4 images use the 16.4.x pkgbuild image. If you want to develop against pkgsrc trunk, then use whatever the most recent release available is.

$ imgadm update
$ imgadm avail | awk '/pkgbuild.*16.4/ {print}'
880c4958-d651-11e6-a654-dfde57efd4bf pkgbuild 16.4.0 smartos zone-dataset 2017-01-09
$ imgadm import 880c4958-d651-11e6-a654-dfde57efd4bf

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": "880c4958-d651-11e6-a654-dfde57efd4bf",
  "alias": "pkgbuild-16-4",
  "max_physical_memory": 8192,
  "quota": 16384,
  "resolvers": [
    "8.8.8.8"
  ],
  "dns_domain": "local",
  "nics": [
    {
      "nic_tag": "admin",
      "ip": "dhcp"
    }
  ]
}

$ vmadm create -f pkgbuild.json

### Mac OS X

XXX: write up based on clean VM

### Ubuntu Linux

Perform a full upgrade.

$ apt-get update
$ apt-get dist-upgrade
$ apt-get autoremove

Install required packages. git is part of build-essential on 16.04 or later.

$ apt-get install build-essential git mailutils postfix

If using the Joyent Ubuntu image rename the /mnt mount to provide /data.

: Switch /mnt to /data if required
$ sed -ie 's,/mnt,/data,' /etc/fstab

Create the pbulk user, used for unprivileged builds.

$ useradd -U -m -s /bin/bash -c "pbulk user" pbulk

Set hostname if required

$ vi /etc/hostname
pkgsrc-pbulk.local

$ reboot

### RedHat Linux

Perform a full upgrade.

$ yum update

Install required packages.

$ yum install bzip2 ed gcc gcc-c++ git screen

Create the pbulk user, used for unprivileged builds.

$ useradd -U -m -s /bin/bash -c "pbulk user" pbulk

Set hostname if required.

: EL 6.x
$ vi /etc/sysconfig/network
HOSTNAME=pkgsrc-pbulk.local

: EL 7.x
$ hostnamectl set-hostname pkgsrc-pbulk.local

$ reboot

### Fetch repositories

Fetch both the pkgsrc and pkgbuild repositories. If you are using the SmartOS pkgbuild image these repositories will have already been cloned, so you may just want to do a git pull instead.

The /data prefix is somewhat hardcoded at this point, though with some work you can use a different prefix if necessary. This is however currently undocumented).

: For OSX/Linux
$ mkdir -p /data
$ cd /data
$ git clone https://github.com/joyent/pkgsrc.git
$ git clone https://github.com/joyent/pkgbuild.git

: For SmartOS
$ (cd /data/pkgbuild; git pull)
$ (cd /data/pkgsrc; git pull)

Add the pkgbuild/scripts directory to your path.

: For OSX/Linux.  SmartOS 'pkgbuild' already has this by default.
$ PATH=$PATH:/data/pkgbuild/scripts

For OS X you will want to track the joyent/osx/trunk branch, i.e.:

$ cd /data/pkgsrc
$ git checkout joyent/osx/trunk
$ git submodule init
$ git submodule update

While for Linux you don't need to do anything and can use the default trunk.

## Create Sandbox

The pkgbuild repository aims to recreate the same environment that produces the official Joyent binaries. 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 /data/pkgbuild/conf.

Some examples:

run-sandbox 2016Q4-x86_64       # Create a 64-bit SmartOS sandbox for 16.4.x
run-sandbox 2016Q4-i386         # Create a 32-bit SmartOS sandbox for 16.4.x
run-sandbox osx-trunk-x86_64    # Create a 64-bit OS X sandbox
run-sandbox linux-trunk-i386    # Create a 32-bit Linux sandbox

Once you have successfully created a sandbox you can move onto any of the other package development documents.