PortingWorkflow [FreeBSD WIKI]

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
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 =====
  - Get a [[/GitHub|GitHub]] account
  - Create a ports repo in your [[/GitHub|GitHub]]
  - Clone your [[/GitHub|GitHub]] ports repo on your local system to %%<%%ghports>
  - add ''%%.svn%%'' and ''%%work%%'' to ''%%<ghports>/.gitignore%%''
  - alias ''%%svn%%'' to ''%%svnlite%%'' if you're not installing ''%%devel/subversion%%'' for full svn support
  - Install and configure ''%%ports-mgmt/[[#poudriere|poudriere]]%%'' 

====== Workflow ======
A way to get from patching a port to submitting it
===== Hack a port =====
  - Create the category dir in ''%%<ghports>%%''
  - In the category dir using svn  ''%%svn co https://svn.FreeBSD.org/ports/head/<category>/<port>%%''\\  Check [[https://www.freebsd.org/doc/en/books/handbook/svn.html|Using Subversion]] for your closest mirror, at first call you need to match and accept the SSL fingerprint
  - In ''%%<ghports>%%'' run ''%%git add .%%''
  - Modify your port
    - whatever needs to change, see next sections
  - In ''%%<ghports>/<category>/<port>%%'' update local svn
    - ''%%svn add/move/copy/remove <file>%%''
    - ''%%svn status%%'' to check your work
    - ''%%svn update%%'' to update your local svn tree
  - in ''%%<ghports>%%'' run ''%%svn diff <category>/<port> > ../patch-<category>-<port>-<version>-<shortdesc>%%''
  - Build your modified port using poudriere testport
===== Quality checks =====
  - ''%%portlint -C%%''
  - ''%%make check-plist%%''
  - ''%%make -V CPE_STR%%''
===== Submit a Bug Report =====
  - 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%%''%%%%
  - Describe what's changed, refer to link if you submitted it upstream as well
  - Attach the svn diff(s) relative to the ''%%${PORTSDIR}%%'' root
    - Set ''%%maintainer-approval%%'' to ''%%+%%'' if you're the maintainer of the port
  - Attach the poudriere testport log
    - As plain text when < 1MB
    - Gzipped when > 1MB
====== Tips-'n-tricks ======
===== make makepatch =====
''%%make makepatch%%'' is your friend
  - make a backup of the files dir...
  - run ''%%make do-patch%%'' to extract and patch the port (but not run pre- nor post-patch)
  - cd into the ${WRKSRC}
  - Copy the file you want to modify to ''%%<file>.orig%%''

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

  - Edit ''%%path/to/file-to-patch%%'' using your favourite editor
  - cd into the port-dir (i.e. ''%%cd ../..%%'') run ''%%make makepatch%%'' to update all patches in the ''%%files%%'' dir
  - 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 ======
[[https://www.freebsd.org/doc/en/books/porters-handbook/|Porter's Handbook]]\\ 
[[https://www.freebsd.org/doc/en/articles/committers-guide/ports.html|Committer's Guide - Ports]]