Today I will share a simple way to add software to the FreeBSD Ports tree.
In not so distant past I used shar(1) tool that was part of the FreeBSD Base System to generate information needed to either create new port or to update the old one. It was also one of the officially supported ways to do that … but shar(1) tool is no more – it was removed from the FreeBSD Base System and (fortunately) kept as sysutils/freebsd-shar port.
Now sending the diff from git(1) is needed – but as I read the FreeBSD Porters Handbook – Quick Porting chapter … and tried to follow the instructions one by one … I was not able to generate the needed information. Its not that this official guide is written ‘bad’ on purpose – its probably the ‘missing’ steps are so obvious for FreeBSD maintainers/porters/developers that they even forget to mention them at all.
After some time with the problem I found a simple way that works for me – and today I am sharing that as some of you may also find that information useful.
The Table of Contents is below.
- Add Port to FreeBSD Ports
- Create New FreeBSD Port
- Testing Port Before Submitting
- Common Problems
- Checksum Mismatch
- Size Mismatch
- Common Problems
- Submit Proposal to Add New Port
- Updating the FreeBSD Port
- Summary
One may ask WHY I did not submitted the needed changes to the upstream documentation … the reason is disappointment from the past when I tried to fix/update the entire Virtualization chapter of FreeBSD Handbook. 20 years ago I rewrote the chapter and posted it on my (then) place available online. Surprisingly its still available online – FreeBSD Handbook Virtualization – here. I then shared that with people that could update the FreeBSD Handbook with info from there.
To be honest – I did not expected that it would be commited ‘just like that’ as it was – but I at least expected SOME parts of it would be added – as for example the KQEMU part that was missing in the FreeBSD Handbook and as it made QEMU a lot faster it was very valuable … but no. Nothing was added. Nothing was taken from it … like I wasted entire effort … so I keep that FreeBSD Handbook proposal to remind me about it. After I finally succeeded with my 3rd blog attempt I do not care anymore for such things – I just ‘dump’ all the info I have on the blog and if someone wants to add it to the official documentation – like with Jails chapter of FreeBSD Handbook – great – but I am done with official proposals to omit disappointment.
Now to the point.
Create New FreeBSD Port
I will create an example based on my sysutils/lsblk port.
when I proposed to add lsblk(8) as 1.0 version the Makefile and distinfo and pkg-descr files looked like that:
FreeBSD % cat Makefile PORTNAME= lsblk PORTVERSION= 1.0 CATEGORIES= sysutils MASTER_SITES= https://github.com/vermaden/lsblk/raw/master/release/ MAINTAINER= [email protected] COMMENT= Lists information about block devices in the system LICENSE= BSD2CLAUSE NO_BUILD= YES NO_ARCH= YES PLIST_FILES= sbin/${PORTNAME} do-install: ${INSTALL_SCRIPT} ${WRKSRC}/lsblk.sh \ ${STAGEDIR}${PREFIX}/sbin/${PORTNAME} .include FreeBSD % cat distinfo TIMESTAMP = 1570494909 SHA256 (lsblk-1.0.tar.gz) = ec6335ec27fd7ec1c56b2700d073c659c1704b816aa08c0f4d831d417dd2affb SIZE (lsblk-1.0.tar.gz) = 4338 FreeBSD % cat pkg-descr Lists information about block devices in the system in a similar way that util-linux's lsblk(8) does. WWW: https://github.com/vermaden/scripts/blob/master/lsblk.sh
You can even view them in the FreeBSD Ports history here:
To generate the distinfo file you may use my ports-generate-distinfo.sh script.
To make submit a port you will also need lsblk-1.0.tar.gz file placed in the https://github.com/vermaden/lsblk/release/ path – and it contains these contents as shown below.
Just a lsblk-1.0 dir and lsblk.sh in it.
Testing Port Before Submitting
Before you send the ‘BUG’ report to create a port first test the port locally.
FreeBSD # tree /usr/ports/sysutils/lsblk /usr/ports/sysutils/lsblk βββ distinfo βββ Makefile βββ pkg-descr 1 directory, 3 files FreeBSD # cd /usr/ports/sysutils/lsblk FreeBSD # pwd /usr/ports/sysutils/lsblk FreeBSD # make clean distclean ===> Cleaning for lsblk-1.0 ===> Deleting distfiles for lsblk-1.0 FreeBSD # make ===> lsblk-1.0 depends on file: /usr/local/sbin/pkg - found => lsblk-1.0.tar.gz doesn't seem to exist in /usr/ports/distfiles. => Attempting to fetch https://github.com/vermaden/lsblk/raw/master/release/lsblk-1.0.tar.gz lsblk-1.0.tar.gz 4338 B 13 MBps 00s ===> Fetching all distfiles required by lsblk-1.0 for building ===> Extracting for lsblk-1.0 => SHA256 Checksum OK for lsblk-1.0.tar.gz. ===> Patching for lsblk-1.0 ===> Configuring for lsblk-1.0 ===> Staging for lsblk-1.0 ===> Generating temporary packing list install -m 555 /usr/ports/obj/usr/ports/sysutils/lsblk/work/lsblk-1.0/lsblk.sh /usr/ports/obj/usr/ports/sysutils/lsblk/work/stage/usr/local/sbin/lsblk ====> Compressing man pages (compress-man)
Common Problems
Below are common problems that you may encounter while preparing the port.
Checksum Mismatch
More often in the updating then creating first one – but still.
FreeBSD # make ===> lsblk-1.0 depends on file: /usr/local/sbin/pkg - found => lsblk-1.0.tar.gz doesn't seem to exist in /usr/ports/distfiles. => Attempting to fetch https://github.com/vermaden/lsblk/raw/master/release/lsblk-1.0.tar.gz lsblk-1.0.tar.gz 4338 B 26 MBps 00s ===> Fetching all distfiles required by lsblk-1.0 for building ===> Extracting for lsblk-1.0 => SHA256 Checksum mismatch for lsblk-1.0.tar.gz. ===> Refetch for 1 more times files: lsblk-1.0.tar.gz ===> lsblk-1.0 depends on file: /usr/local/sbin/pkg - found => lsblk-1.0.tar.gz doesn't seem to exist in /usr/ports/distfiles. => Attempting to fetch https://github.com/vermaden/lsblk/raw/master/release/lsblk-1.0.tar.gz lsblk-1.0.tar.gz 4338 B 12 MBps 00s ===> Fetching all distfiles required by lsblk-1.0 for building ===> lsblk-1.0 depends on file: /usr/local/sbin/pkg - found ===> Fetching all distfiles required by lsblk-1.0 for building => SHA256 Checksum mismatch for lsblk-1.0.tar.gz. ===> Giving up on fetching files: lsblk-1.0.tar.gz Make sure the Makefile and distinfo file (/usr/ports/sysutils/lsblk/distinfo) are up to date. If you are absolutely sure you want to override this check, type "make NO_CHECKSUM=yes [other args]". *** Error code 1 Stop. make[1]: stopped in /usr/ports/sysutils/lsblk *** Error code 1 Stop. make: stopped in /usr/ports/sysutils/lsblk
Check how to fix that.
FreeBSD # sha256 /usr/ports/distfiles/lsblk-1.0.tar.gz SHA256 (/usr/ports/distfiles/lsblk-1.0.tar.gz) = ec6335ec27fd7ec1c56b2700d073c659c1704b816aa08c0f4d831d417dd2affb FreeBSD # grep SHA /usr/ports/sysutils/lsblk/distinfo SHA256 (lsblk-1.0.tar.gz) = ec6335ec27fd7ec1c56b2700d073c659c1704b816aa08c0f4d831d417dd2affba
As You can see there is additional ‘a’ at the end that makes the checksum different.
Size Mismatch
Also typical error.
FreeBSD # make ===> lsblk-1.0 depends on file: /usr/local/sbin/pkg - found => lsblk-1.0.tar.gz doesn't seem to exist in /usr/ports/distfiles. => Attempting to fetch https://github.com/vermaden/lsblk/raw/master/release/lsblk-1.0.tar.gz fetch: https://github.com/vermaden/lsblk/raw/master/release/lsblk-1.0.tar.gz: size mismatch: expected 4333, actual 4338 => Attempting to fetch http://distcache.FreeBSD.org/ports-distfiles/lsblk-1.0.tar.gz fetch: http://distcache.FreeBSD.org/ports-distfiles/lsblk-1.0.tar.gz: Not Found => Couldn't fetch it - please try to retrieve this => port manually into /usr/ports/distfiles and try again. *** Error code 1 Stop. make: stopped in /usr/ports/sysutils/lsblk
Lets check the size.
FreeBSD # fetch https://github.com/vermaden/lsblk/raw/master/release/lsblk-1.0.tar.gz lsblk-1.0.tar.gz 4338 B 27 MBps 00s FreeBSD # stat -f "%z" lsblk-1.0.tar.gz 4338 FreeBSD # grep SIZE /usr/ports/sysutils/lsblk/distinfo SIZE (lsblk-1.0.tar.gz) = 4333
Yep – wrong size.
Submit Proposal to Add New Port
Now – to add proposal to add a port to FreeBSD Ports you will need to generate git(1) diff for that.
Below are steps needed to get one.
First we need to get the FreeBSD Ports tree.
FreeBSD % git clone https://git.freebsd.org/ports.git freebsd-ports Cloning into 'freebsd-ports'... remote: Enumerating objects: 6635778, done. remote: Counting objects: 100% (995/995), done. remote: Compressing objects: 100% (177/177), done. remote: Total 6635778 (delta 925), reused 816 (delta 816), pack-reused 6634783 (from 1) Receiving objects: 100% (6635778/6635778), 1.45 GiB | 1.89 MiB/s, done. Resolving deltas: 100% (4017143/4017143), done. Updating files: 100% (166471/166471), done. FreeBSD % cd freebsd-ports
Now you need to create new branch – name it as You like it – I will use sysutils-lsblk one without better idea.
FreeBSD % git checkout -b sysutils-lsblk
Switched to a new branch 'sysutils-lsblk'
Now copy your content into that local tree.
FreeBSD % cp -avp ~/misc/git/lsblk/port/sysutils-lsblk sysutils/lsblk
/home/vermaden/misc/git/lsblk/port/sysutils-lsblk -> sysutils/lsblk
/home/vermaden/misc/git/lsblk/port/sysutils-lsblk/distinfo -> sysutils/lsblk/distinfo
/home/vermaden/misc/git/lsblk/port/sysutils-lsblk/Makefile -> sysutils/lsblk/Makefile
/home/vermaden/misc/git/lsblk/port/sysutils-lsblk/pkg-descr -> sysutils/lsblk/pkg-descr
Now add it with git(1) command and create that diff.
FreeBSD % git add sysutils/lsblk FreeBSD % git diff --staged > /home/vermaden/sysutils-lsblk.diff
This is how our git(1) diff looks like.
FreeBSD % cat ~/sysutils-lsblk.diff diff --git a/sysutils/lsblk/Makefile b/sysutils/lsblk/Makefile new file mode 100644 index 000000000000..f59e4af7948b --- /dev/null +++ b/sysutils/lsblk/Makefile @@ -0,0 +1,15 @@ +PORTNAME= lsblk +PORTVERSION= 1.0 +CATEGORIES= sysutils +MASTER_SITES= https://github.com/vermaden/scripts/raw/master/release/ +MAINTAINER= [email protected] +COMMENT= Lists information about block devices in the system +LICENSE= BSD2CLAUSE +NO_BUILD= YES +NO_ARCH= YES +PLIST_FILES= sbin/${PORTNAME} +do-install: + ${INSTALL_SCRIPT} ${WRKSRC}/lsblk.sh \ + ${STAGEDIR}${PREFIX}/sbin/${PORTNAME} +.include + diff --git a/sysutils/lsblk/distinfo b/sysutils/lsblk/distinfo new file mode 100644 index 000000000000..bacd71658c5a --- /dev/null +++ b/sysutils/lsblk/distinfo @@ -0,0 +1,4 @@ +TIMESTAMP = 1570494909 +SHA256 (lsblk-1.0.tar.gz) = ec6335ec27fd7ec1c56b2700d073c659c1704b816aa08c0f4d831d417dd2affb +SIZE (lsblk-1.0.tar.gz) = 4338 + diff --git a/sysutils/lsblk/pkg-descr b/sysutils/lsblk/pkg-descr new file mode 100644 index 000000000000..01e1707486ed --- /dev/null +++ b/sysutils/lsblk/pkg-descr @@ -0,0 +1,4 @@ +Lists information about block devices in the system in a similar way +that util-linux's lsblk(8) does. +WWW: https://github.com/vermaden/scripts/blob/master/lsblk.sh +
… and this sysutils-lsblk.diff we would have to attach to our ‘BUG’ report for new FreeBSD port.
Now go to the https://freebsd.org/send-pr.html page (you will be redirected to https://bugs.freebsd.org/bugzilla/enter_bug.cgi page) and click Ports & Packages type … and fill all the needed information. On the screenshot you have everything that is needed.
Remember to add the sysutils-lsblk.diff with Add an Attachment button below.
If some modifications would be needed – and often are – FreeBSD developers and maintainers will tell you what to do π
Updating the FreeBSD Port
Now … after You already have a FreeBSD port there will be a need to update it.
The procedure is generally the same – you fetch the FreeBSD Ports tree – create new branch – dump your updates to it – create git(1) diff and attach it to the ‘BUG’ report.
Example report could look like that one below.
Summary
Some notes of the current Status Quo and trends.
For some reason instead of just links to where to fetch the code from the FreeBSD implemented additional variables just for GitHub to … make it more simple? Not for me at least … and its just for one vendor. IMHO its pointless to create such ‘per vendor’ settings while we can have just generic things that works for everyone … but that is me.
Example Makefile for sysutils/jmore with these options for GitHub is below.
FreeBSD % cat /usr/ports/*/jmore/Makefile PORTNAME= jmore DISTVERSION= 0.5.20251030 DISTVERSIONSUFFIX= -g${GH_TAGNAME} CATEGORIES= sysutils MAINTAINER= [email protected] COMMENT= FreeBSD Jail listing and managing utility WWW= https://github.com/vermaden/jmore LICENSE= BSD2CLAUSE LICENSE_FILE= ${WRKSRC}/LICENSE USE_GITHUB= yes GH_ACCOUNT= vermaden GH_PROJECT= jmore GH_TAGNAME= 9b72e97 NO_ARCH= YES NO_BUILD= YES PLIST_FILES= sbin/${PORTNAME} do-install: ${INSTALL_SCRIPT} ${WRKSRC}/jmore \ ${STAGEDIR}${PREFIX}/sbin/${PORTNAME} .include
Now nothing is stopping You from adding something to the FreeBSD Ports tree.
ππππππππ 