• BernardSpil
• PortingWorkflow

AKA Hack-a-port

Documenting the workflow I've established to hack ports

WORK IN PROGRESS - INCOMPLETE - YMMV

Setup

Setting up your porting environment

Tools required

• devel/git            : Minimized depedencies CONTRIB=off CVS=off GUI=off NLS=off P4=off

• svn(lite)            : in base is sufficient (or devel/subversion from ports)

• ports-mgmt/portlint  : Sanity checks

• ports-mgmt/poudriere : To generate logs that reviewers like

One-time setup

1. Get a GitHub account

2. Create a ports repo in your GitHub

3. Clone your GitHub ports repo on your local system to <ghports>

4. add .svn and work to <ghports>/.gitignore

5. alias svn to svnlite if you're not installing devel/subversion for full svn support

6. Install and configure ports-mgmt/[[#poudriere|poudriere]]

Workflow

A way to get from patching a port to submitting it

Hack a port

1. Create the category dir in <ghports>

2. In the category dir using svn

   svn co https://svn.FreeBSD.org/ports/head/<category>/<port>
   Check Using Subversion for your closest mirror, at first call you need to match and accept the SSL fingerprint

3. In <ghports> run git add .

4. Modify your port
   1. whatever needs to change, see next sections

5. In <ghports>/<category>/<port> update local svn

   1. svn add/move/copy/remove <file>

   2. svn status to check your work

   3. svn update to update your local svn tree

6. in <ghports> run svn diff <category>/<port> > ../patch-<category>-<port>-<version>-<shortdesc>

7. Build your modified port using poudriere testport

Quality checks

1. portlint -C

2. make check-plist

3. make -V CPE_STR

Submit a Bug Report

1. If you're the maintainer of the port, prefix the Summary with [MAINTAINER] otherwise prefix with [PATCH]

   • e.g. [PATCH] category/port: Fix this and that

2. Describe what's changed, refer to link if you submitted it upstream as well

3. Attach the svn diff(s) relative to the ${PORTSDIR} root

   1. Set maintainer-approval to + if you're the maintainer of the port

4. Attach the poudriere testport log

   1. As plain text when < 1MB

   2. Gzipped when > 1MB

Tips-'n-tricks

make makepatch

make makepatch is your friend

1. make a backup of the files dir...

2. run make do-patch to extract and patch the port (but not run pre- nor post-patch)

3. cd into the ${WRKSRC}

4. Copy the file you want to modify to <file>.orig

cd `make -V WRKSRC`
cp -p path/to/file-to-patch{,.orig}

5. Edit path/to/file-to-patch using your favourite editor

6. cd into the port-dir (i.e. cd ../..) run make makepatch to update all patches in the files dir

7. NB. There can also be PATCH commands in the Makefile and extra-patches...

Verbose builds

Not all builds are equally verbose. Options to enable more verbose builds

• make V=1 (generic)

• make VERBOSE=1 (cmake)

poudriere

TODO

TODO

Poudriere usage

References/Links

Porter's Handbook
Committer's Guide - Ports