Nanobox pkgsrc-base

This repo contains the package definitions for build and runtime assets that a Nanobox engine may require and download during the build phase.

Overview

This project will create a re-usable build environment using vagrant with the following assumptions and advantages:

Package definition occurs directly on the developer's workstation, in the prefered native editor and environment.
Package definitions are live-mounted into the vm.
Package build occurs entirely within the vagrant vm, and within an isolated sandbox (chroot).
Final package will be uploaded to the public server for consumption.
All sensitive secrets will be sourced and available as environment variables when the vagrant environment is setup.

Installation

Workstation setup

Ensure that the following environment variables are exported in your bashrc, bash_profile, or zshrc:

# Nanobox secrets
export NANOBOX_USER="nanobox"
export NANOBOX_BASE_PROJECT="base"
export NANOBOX_BASE_SECRET="INSERT_SECRET_HERE"
# optionally set the default vagrant plugin to vmware if the plugin is installed
# export NANOBOX_BUILD_VAGRANT_PROVIDER="vmware_fusion"

Initialize the vagrant environment
```
$ vagrant up
```

Environment setup

Each package should be built inside a sandbox (chroot). This ensures that there is no dependency leaking and no overlap between packages. A 'sandbox' utility exists within the vagrant vm to facilitate such isolation.

The following subcommands are available to manage sandboxes: create, enter, rm, list, resume.

Package Creation

pkgsrc

Nanobox uses pkgsrc exclusively as the build system. pkgsrc is chosen primarily for it's correctness and portability.

For an in-depth understanding of how pkgsrc works and a comprehensive guide on defining and building packages, please refer to the pkgsrc developer's guide

The following guide defined here will serve as a quick overview only.

defining a package

Required files for a package definition:

Makefile - Contains instruction on how to fetch and build sources
DESCR - Contains long description of package
PLIST - List of files contained in package
distinfo - List of sources and checksums

Optional files for a package definition:

MESSAGE - Contains a message that is shown when package is installed
INSTALL - Shell script segment that gets injected into the install process
DEINSTALL - Shell script segment that gets injected into the uninstall process

Styleguide

Each Makefile MUST contain the following modelines declaration at the top of the file:

# $NetBSD$
# -*- mode: makefile; tab-width: 8; indent-tabs-mode: 1 -*-
# vim: ts=8 sw=8 ft=make noet

Your editor MUST understand and obey the modelines declared at the top. Adjust your editor accordingly.

All variables MUST be aligned vertically. Consider this example and follow exactly.

build

create a sandbox
```
$ sandbox up [name]
```
Enter the sandbox
```
$ sandbox enter [name]
```

Navigate to the package directory

$ cd /content/pkgsrc/base/[package_name]

Build distinfo file

Note: This step generates a checksum of the downloaded source. This step is required on a new package and when the source changes, perhaps on a new version.
```
$ bmake distinfo
```
Pre-fetch dependencies that already exist on the remote server

WARNING: omitting this step may lead to unecessarily long build times
```
$ bmake fetch-depends
```
Attempt compilation
```
$ bmake
```

Generate patches if necessary

Navigate to the build folder

$ cd /var/tmp/pkgsrc-build-data/base/[package_name]/work/[package_source_dir]

Use pkgvi to edit the source
```
$ pkgvi [path/to/src/file]
```

Create a patch

$ mkdir /content/pkgsrc/base/[package_name]/patches
$ pkgdiff [path/to/src/file] > /content/pkgsrc/base/[package_name]/patches/patch-path_to_src_file

Return to the pkgsrc folder and add patch into the distinfo file
```
$ cd /content/pkgsrc/base/[package_name]
$ bmake mps
```

Clean and build again
```
$ bmake clean
$ bmake
```
Generate a PLIST file

WARNING: A PLIST contains a list of files for the package. Omitting this step will generate an empty package.
```
$ bmake stage-install
$ bmake print-PLIST > PLIST
```
Create the final package
```
$ bmake install-clean
$ bmake package
```
Publish the package
```
$ bmake publish
```
Exit and remove the sandbox
```
$ exit
$ sandbox rm [name]
```

Package modification

Versioning

When a new version of the software is available, the VERSION variable in the Makefile should be updated to match the software version.

If the software version has not changed, but a new patchset has been applied, then PKGREVISION variable should be incremented.

Iteration

Create a sandbox
```
$ sandbox create [name]
```
Enter the sandbox
```
$ sandbox enter [name]
```