Packaging Tutorial

Any easy way to begin producing your own software packages for Shedbuilt is to start from the build recipes shared by the Beyond Linux from Scratch project. In this tutorial, we'll package the alpine e-mail client and prepare it for distribution to other Shedbuilt users.

Step 0: Update User Permissions

When using shedmake to create packages you should be logged into a normal user account (i.e. not root) that is a member of the shedmake group.

# sudo usermod -g shedmake myusername

Step 1: Locate Software and Build Instructions

First things first, you'll need to find where the source code for the software you want to package resides and read through its build instructions. Traditionally, build instructions are placed in a text file called INSTALL at the root of the source folder. You'll want to check for any dependencies your chosen software has on other bits of software as they'll need to be packaged before proceeding. In the case of our example package, alpine, the Beyond Linux from Scratch developers have kindly aggregated the source code download, build instructions and dependency information we need.

Step 2: Create a Package Repository on GitHub

Because we intend to share our package with others in the Shedbuilt community, we're going to set up a git repository to host and distribute it. With this approach we'll even be able to provide other users with updates to the package with minimal effort. Head over to GitHub or your favorite git hosting service and create a new, empty repository. Forego automatic creation of a README or other document to prevent the initial commit from taking place.

Step 3: Create a New Shedbuilt Package

From your Shedbuilt device, use shedmake's create action to initialize a new package using the included template, passing the SSH version of the repository URL provided by GitHub. This can be done from any directory:

# shedmake create alpine --origin git@github.com:myaccount/alpine.git

We're using the SSH version of the git URL to simplify authentication. This requires that you establish SSH keys for your GitHub account and use ssh-agent to load them on your Shedbuilt device.

Step 4: Populate Packaging Files

If you cd into the newly created alpine folder you'll find the template versions of the standard package.txt, build.sh and LICENSE files waiting to be fleshed out. Let's start by editing the package metadata file, package.txt, in vim:

# vim package.txt

Now we'll need to copy over information about the package as provided by Beyond Linux from Scratch:

NAME=alpine
VERSION=2.21
REVISION=1
LICENSE=Apache-2.0
SRC=http://anduin.linuxfromscratch.org/BLFS/alpine/alpine-2.21.tar.xz
SRCMD5=02dad85c1be80ce020206f222ecf5ac8
PURGE=yes
BUILDDEPS=openssl
INSTALLDEPS=openssl

We're going to compile alpine with support for OpenSSL so we list it in the BUILDDEPS and INSTALLDEPS section. This isn't strictly required as OpenSSL is part of the standard Shedbuilt System but doing this ensure that updates to OpenSSL will be installed first and prevent issues if the base configuration changes.

Next we'll fill out build.sh with the required compilation commands, modifying them slightly to work with shedmake's build environment:

#!/bin/bash
LIBS+="-lcrypto" ./configure --prefix=/usr       \
                             --sysconfdir=/etc   \
                             --without-ldap      \
                             --without-krb5      \
                             --without-pam       \
                             --without-tcl       \
                             --with-ssl-dir=/usr \
                             --with-passfile=.pine-passfile &&
make -j $SHED_NUM_JOBS &&
make DESTDIR="$SHED_FAKE_ROOT" install

To facilitate binary archive creation and prevent failed builds from literring your system with files, shedmake builds packages in a temporary folder descending from the TMP_DIR specified in /etc/shedmake.conf. For GNU autotools-based builds (i.e. those using make) we pass $SHED_FAKEROOT as the DESTDIR when installing to ensure files end up in the right place. We also pass $SHED_NUMJOBS to make to allow it to build in multiple files in parallel on device configured to do so in /etc/shedmake.conf. Most Shedbuilt devices have four or more cores so this speeds up compilation significantly.

Finally, hop into the LICENSE file and update the copyright info. We encourage you to select a license for your packaging that respects upstream licensing and enables your friends to use, inspect, modify and share it.

Step 5: Perform a Test Build

Now that the required files are in place, we can cd .. out of the folder and try building the package, optionally storing the compiled binary in an archive:

# sudo shedmake build alpine --verbose --cache-binary

We're using sudo here to perform the build as root to ensure the binaries it creates will have proper ownership if you go on to install the package as demonstrated below.

If all goes well, shedmake will indicate success and a binary archive for alpine will be sitting in the package's binary folder. You can now install it with root permissions using:

# sudo shedmake install alpine

Step 6: Share with the Community

Now that your package is building, let push it up to that git repository you created and share it with the community. You can perform the initial commit like so:

# shedmake push alpine --verbose

Once that's done you and your friends can add your package to the default, managed local repository using shedmake's add action and the HTTPS clone URL for the git repo:

# shedmake add https://github.com/myaccount/alpine.git default

The package can then be installed from any directory like so:

# sudo shedmake install alpine