FreeBSD/Setup/Area51
Area 51 repository
Area 51 is used for development of KDE and Qt ports that are maintained by the KDE on FreeBSD team. Right now, that is for Plasma 5 and the latest (KF5-based) KDE Applications.
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.
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.
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.
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:
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