FreeBSD/Setup/Area51

Area 51 repository

In the KDE 3 days, around FreeBSD 5, the repository where KDE ports were developed was called Area 51 – the famous place where aliens land. Although 'area51' no longer appears in the host name or repository name, we still call it Area 51.

Area 51 is used for development of KDE and Qt ports that are maintained by the KDE on FreeBSD team. These ports are not always in a stable state, so users are encouraged to test and report problems, especially during call for testing (CFT) periods. Area 51 is hosted on GitHub.

New versions and changes to ports are always committed here first and only later hit the FreeBSD ports tree. The history of commits is recorded in the KDE on FreeBSD e-mail list. Workflow is similar to the graphics stack ports development workflow, or GNOME ports: a complete Git clone of the ports tree is kept, branches work on specific updates, and that work gets merged to FreeBSD ports master when things are ready.

---

HIC SUNT LEONES

Source organization

The Area 51 ports tree is an official git fork of the official FreeBSD ports tree; it is hosted on GitHub alongside the XOrg and GNOME ports trees. This section talks about the procedures used to keep the ports tree up-to-date. This is for *maintainers* of the ports tree, not *users* of the ports tree.

Most important for maintainers: *never* push to master except when synchronizing with upstream.

Initial Clone

This assumes you have a GitHub account and permissions for the KDE-FreeBSD ports tree:

git clone https://github.com/freebsd/freebsd-ports-kde.git
git remote set-url --push origin [email protected]:freebsd/freebsd-ports-kde.git
git remote add upstream https://github.com/freebsd/freebsd-ports.git

}

Synchronizing with upstream

Do this at least every weekend:

git checkout master
git fetch -p upstream
git merge --ff-only upstream/master
git push

Working on a port

Use a topic branch. Topic branches are local, but you can also push them to the origin for collaboration. Topic branches are cleaned up once they are merged, and there is no need to hang on to them or references to them.

To get started:

git checkout master
git checkout -b my-feature

Then modify ports, add commits of the changes you make. Since the working copy of the tree is exactly what you are modifying, you can use poudriere to build your changes quite easily.

Do not ever commit directly to master

You may push a topic branch to origin; this can be useful for collaboration and for testing purposes.

To sync with master (do this before making a PR), first synchronize with upstream, and then merge master into your feature branch; this will show you if anything has changed "out from under you".

git checkout my-feature
git merge master
# Resolve any issues here
git push # If you want to publish

To create a diff for PR purposes, first sync with master and resolve any problems, and then diff between master and your feature branch:

git diff master..my-feature > /tmp/pr.diff

To clean up: once the PR is landed by a commit to the official FreeBSD SVN ports tree (e.g. by a ports committer), the upstream git mirror will update as well. This may take up to two hours. Then the content of the PR commit is available in the git tree.

Do not ever merge branches to master.

You can synchronize with upstream to check that the PR contents have landed properly -- to test, you can checkout master and then use poudriere to build against that tree. The remaining branches can be pruned, unless you really want to keep development history for them.

git checkout master
git branch -D my-feature  # Force delete of topic branch
git push origin --delete my-feature # If you published it

Packages and build status

The current status of some of the branches of Area 51 can be seen in the FreeBSD continuous integration (CI) system, which is a Jenkins instance kindly hosted by one of the team members:

• https://jenkins.mouf.net/view/kde/

Builds are done on both STABLE and 12.0-CURRENT.

Packages may be obtained from the unofficial repository that is created by the Jenkins CI system. To do this, add a configuration file /usr/local/etc/pkg/repos/area51.conf as follows:

FreeBSD: { enabled: false }
area51: {
  url: "http://meatwad.mouf.net/rubick/poudriere/packages/110-amd64-kde/"
  priority: 2
  enabled: true
}

The first line disables the official FreeBSD package repository. This avoids mixing packages from multiple sources, and is is strongly advised when using unofficial packages.

Poudriere

We strongly recommend using poudriere for building packages from Area 51. These packages can then easily be used with pkg(8). First things first, install poudriere:

   # pkg install poudriere

it is recommended to modify `/usr/local/etc/poudriere.conf` to use ZFS.

Setting up the ports tree

(Note that this can be done more easily with poudriere-devel.)

With poudriere installed, you must create one or more ports trees (to build from) and one or more jails (to build in). We'll start with the ports tree. Create a tree, but don't populate it; we'll call this ports tree freebsd-ports-kde.

   # poudriere ports -c -F -m git -p freebsd-ports-kde

Next, clone the ports tree from Area 51. This needs to go into the just-created directory for the ports tree, which could be anywhere on your system depending on how poudriere is configured. The default is under `/usr/local/poudriere/ports`. Depending on how you want to access Area 51, you may need to use a different user or credentials – this example just does an anonymous clone.

   # cd /usr/local/poudriere/ports
   # git clone https://github.com/freebsd/freebsd-ports-kde

With this setup, you can git pull and otherwise update the Git repository as you see fit: it is the working directory that will be used for the ports tree (so you can switch branches inside the clone, too).

Picking the right branch

The ports tree which has been cloned, above, has checked out the master branch. Master always follows the official FreeBSD ports tree, so it is not very interesting compared to the other branches in the Area 51 repository. Note, too, that master may lag behind the official ports: the KDE-FreeBSD team synchronizes master with the official ports tree at least every weekend.

Use git branch -a to see which branches are available. As of mid-june, 2017, there are the following branches:

• plasma5, which contains the complete KDE Frameworks, Plasma Workspace, and KDE Applications. This is probably the branch you want.
• kdevelop-5, kdenlive-17.04, which are branches updating only a single application or collection of related ports to the KDE Frameworks-based version of that application.
• cmake-3.9, which contains preparations for the release of CMake 3.9.

Use git checkout plasma5 to switch to the plasma5 branch, which is the one most likely to be useful at this point (mid-june 2017).

Setting up the build jail

Create a jail to build in; this is essentially a whole new FreeBSD installation inside your existing one. It can also be an older FreeBSD version (newer than the host system is not recommended and may not work at all). This command creates a new 11.0 jail, calling it 110amd64, and installs the jail over FTP:

   # poudriere jail -c -j 110amd64 -v 11.0-STABLE -m ftp

Running a build

Poudriere can bulk-build ports, given a jail and a ports tree to work with. It will generally rebuild all that is needed; assuming you are most interested in all the latest KDE software, the metaport x11/kde is the one to rebuild.

   # poudriere bulk -j 110amd64 -p freebsd-ports-kde x11/kde