DPortsContributions
There are many ways to contribute to DPorts.
Details about DPorts
Some explanations are required first, in order to understand how FreeBSD ports, DeltaPorts and DPorts are organized together.
Repositories
- FreeBSD Ports: This is the FreeBSD Ports collection git repository which is generated from the SVN repository.
- DeltaPorts: This is an overlay which, when applied on top of the FreeBSD Ports collection with the correct scripts, creates the DPorts collection.
- DPorts: This is the DragonFly BSD Ports collection which is just a modified version of FreeBSD Ports.
Steps of every sync with FreeBSD Ports
- Around the 15th of each month a monthly branch is created in a local clone of the freebsd ports repository. This is taken as the base for the sync between freebsd ports and dports.
- The transformation scripts are applied on each freebsd ports' port and a temporary dports tree (called potential tree) is generated.
- In the staged build box (right now it's ironman) a full build of the potential tree is built. Every package that builds will go to ports/staged branch and will also leave a trace of the build outcome in deltaports master branch.
- Once that build is done, a snapshot of the current failures is taken snap-failures and the port build fixing process starts.
How to help
Test dports and report bugs
The easiest thing you can do is to try to use the ports yourself and reports any issues, either by opening a Github issue, or through our bugtracker, where there's a specific DPorts category.
Keep the documentation up-to-date
The way we do things around DPorts evolve with time, so documentation has to be maintainted, and that requires time. Feel free to propose changes if things are obsolete.
This apply to this page and DPorts Usage but also to the DPorts(7) manpage.
On the bugtracker
Sort the tickets
It's helpful to check open tickets, and try to answer them.
On Github
Test DeltaPorts PRs
Sometimes people notice that a built port has a broken behaviour and open a PR on Github in order to fix that. One can check what's the PR is doing, try to reproduce the initial issue and comment on the PR if that works as intended.
Check open PRs
It can happen that the PRs are not open properly, not in the right repo, trying to update the version of a port when we follow FreeBSD's ports rhythm, etc. So checking which are open and filtering them is a good help to DPorts maintainers.
Fix DPorts failures yourself
That's when you want to step in and help us.
Setup the environment
In this guide the base directory will be /build/chroot.
Create a vanilla chroot installation in /build/chroot , that is from a DragonFly BSD source tree without modifications. If you need to build for RELEASE, use the release branch then.
# export BASEDIR=/build/chroot
# cd /usr/src
# make buildworld
# make installworld DESTDIR=$BASEDIR
# cd etc && make distribution DESTDIR=$BASEDIR
Clone the repos for freebsd ports, deltaports and dports. This 3 repositories should not be modified except for updates and such.
# git clone https://github.com/freebsd/freebsd-ports.git $BASEDIR/root/s/freebsd-ports
# git clone https://github.com/DragonFlyBSD/DPorts.git $BASEDIR/root/s/DPorts
# git clone https://github.com/DragonFlyBSD/DeltaPorts.git $BASEDIR/root/s/DeltaPorts
Copy /etc/resolv.conf to $BASEDIR/etc so that the chroot can have internet access.
Clone the DPorts repo in $BASEDIR/usr/dports and switch to staged branch. The port fixes will be done here:
# chroot $BASEDIR
# cd /usr && make dports create
# cd dports
# git checkout -b staged origin/staged
Install your favourite editor and other utils in the chroot. You only have to run 'make pkg-bootstrap' the first time.
# chroot $BASEDIR
# cd /usr && make pkg-bootstrap
# pkg install -y vim
# pkg install -y genpatch
Setup dsynth according your computer parameters (cpu, mem, disk) and needs.
For helping with the dports, one has to setup dsynth to use OpenSSL and not LibreSSL. For reference the following is the configuration used on sting.dragonflybsd.org.
DPORTS_BUILDER= yes
DISABLE_LICENSES= yes
DEFAULT_VERSIONS= ssl=openssl
FORCE_PACKAGE= yes
DEVELOPER= yes
Save the adapted dports configuration in $BASEDIR/usr/local/etc/dports.conf, it will be used by the sync scripts.Example contents:
FPORTS=/build/chroot/root/s/freebsd-ports
MERGED=/tmp/dports
DPORTS=/build/chroot/root/s/DPorts
DELTA=/build/chroot/root/s/DeltaPorts
POTENTIAL=/build/chroot/root/s/potential
INDEX=${FPORTS}/INDEX-3
COMQUEUE=/tmp/crondports
Create script $BASEDIR/root/bin/getdport.sh
#!/bin/sh
. /usr/local/etc/dports.conf
if [ -z "$1" ]; then
echo category/port to handle
exit 1
fi
[ -d /root/s/freebsd-ports/$1 ] || (echo $1 does not exist in ports && exit 1)
${DELTA}/scripts/generator/sync1.sh $1
[ -d /usr/dports/$1 ] && rm -fr /usr/dports/$1
cp -r ${POTENTIAL}/$1 /usr/dports/$1
cd /usr/dports/$1
Check latest failures
Latest failures can be checked in here:
https://ironman.dragonflybsd.org/dports/snap-failures/Report/
Normally you would sort the report data by Skip. Skip means the number of ports that were skipped during the build because of that port.
Fixing port failures
Please note all the commands here are run while chrooted.
Make sure FPORTS is at commit of the current sync. See the timestamp and commitid in this document: https://github.com/DragonFlyBSD/DeltaPorts/blob/master/docs/synclog.json
For this guide we're going to pick www/node12 which currently shows 7 skips. All actions will take place inside the chroot. If you have enough RAM+swap, you can probably mount tmpfs in /usr/obj within the chroot.
# chroot $BASEDIR tcsh
# mount_tmpfs tmpfs /usr/obj
# /root/bin/getdport.sh www/node12
# cd /usr/dports/www/node12
At this point you might want to verify that the changes from the getport.sh script were done correctly, for example with 'git diff .' where you should see changes already but only when the freebsd ports version and the dports/staged version differ.
www/node12 failed in the patch phase, here's the failure text so you want to get to that point, locally.
# make -DBATCH -DDEVELOPER patch
[...]
===> Patching for node12-12.18.0
===> Applying ports patches for node12-12.18.0 from /xports/www/node12/files
===> Applying dragonfly patches for node12-12.18.0 from /xports/www/node12/dragonfly
2 out of 2 hunks failed--saving rejects to deps/uv/src/unix/udp.c.rej
===> FAILED Applying dragonfly patch-deps_uv_src_unix_udp.c
===> FAILED to apply cleanly dragonfly patch(es) patch-deps_uv_src_unix_udp.c
*** Error code 1
Stop.
make[1]: stopped in /xports/www/node12
*** Error code 1
Stop.
make: stopped in /xports/www/node12
The source directory is specified in the WRKSRC make variable, you can easily print it:
# make -V WRKSRC
/usr/obj/dports/www/node12/node-v12.18.0
In the work source directory you will usually find the .rej files that were generated as a result of the patch phase failure:
# cd /usr/obj/dports/www/node12/node-v12.18.0
sting-chroot# find . -iname "*.rej"
./deps/uv/src/unix/udp.c.rej
Fix the patch and regenerate it again. In this case you move it to the dragonfly directory overwriting the previous patch, which failed to apply
# $EDITOR deps/uv/src/unix/udp.c
# genpatch deps/uv/src/unix/udp.c
generated patch-deps_uv_src_unix_udp.c
# mv patch-deps_uv_src_unix_udp.c /usr/dports/www/node12/dragonfly/
The patch phase should now successfully complete:
# make -DBATCH -DDEVELOPER clean
===> Cleaning for node12-12.18.0
# make -DBATCH -DDEVELOPER patch
[...]
===> Patching for node12-12.18.0
===> Applying ports patches for node12-12.18.0 from /usr/dports/www/node12/files
===> Applying dragonfly patches for node12-12.18.0 from /usr/dports/www/node12/dragonfly
More problems will likely arise, you have to keep adding fixes until the port fully builds and packages:
# make -DBATCH -DDEVELOPER package |& tee /tmp/node12.log
[...]
===> Building package for node12-12.18.0
Make sure it passes a 'dsynth test www/node12', this may take a while.
# dsynth test www/node12
Processing 1 ports
100.00%
Total 2
Resolving dependencies...done
Total Returned 54
Scanning 1345 packages
100.00%
Total 1345
all done
Check Template: Good
[000] START www/node12 idep=137 depi=00/00 dep=0.23G
[000] SUCCESS www/node12 00:07:23
Initial queue size: 1
packages built: 1
ignored: 0
skipped: 0
failed: 0
missing: 0
Duration: 00:07:23
Now it should be ready for submit.
Submitting your work
Layout
See below the key elements that might need to be included in the PR. Many examples exists already in the DeltaPorts repository, you can get most of the things you'll need to do from there.
Makefile.DragonFly
This is evaluated for every port build. As much stuff as possible should be included here, like variable override or modification, sed commands, etc.
diffs/*.diff
A way of patching directly the files within the port directory. For example, diffs/Makefile.diff will be applied to the port Makefile.
diffs/TOREMOVE
File which contains the file to be removed from the port, one file per line.
dragonfly/
This directory holds the Dragonfly specific patches. Same rules as for FreeBSD files apply, i.e. just one patch per file, etc.
How to submit
Create a PR with the appropriate changes here: https://github.com/DragonFlyBSD/DeltaPorts/pulls
Local repository for the chroot
There are some packages that will have quite some dependencies and since you are going to be building with dsynth a lot, it is a good practice to keep a local binary repository in the chroot. That way you can quickly install need packages for a specific build. You can just add the repository as a local in the pkg repos configuration.
# fgrep -i packages= /etc/dsynth/dsynth.ini
Directory_packages= /build/dsynth/live_packages
# cat /usr/local/etc/pkg/repos/00_synth.conf
# Automatically generated.
Synth: {
url : file:///build/dsynth/live_packages
priority : 0,
enabled : yes,
}