= General Purpose Packaging =

<<TableOfContents()>>

== Overview ==
From time to time, you may find it necessary to create a general purpose package, which installs files to arbitrary places on disk. For instance, if you have a piece of software that can be licensed with the addition of a licence file to the file system, then you would create a recipe to pkg the file and make it require the parent software (so that the parent software is always installed first). Then when both are added to a manifest, the software will install and then become licensed. These types of pkgs will not be added to the autobuild, and should only be built if the contents need to change.

== Requirements ==
 * You should have set up your build system in accordance with the page on [[https://docs.orchard.ox.ac.uk/AutoPkg/Contributing|Contributing to Orchard autopkg]] and be familiar with writing autopkg recipes for Orchard as outlined therein.
 * You should also familiarise yourself with the use of autopkg as a general purpose packaging tool on [[https://managingosx.wordpress.com/2015/07/30/using-autopkg-for-general-purpose-packaging/|Greg Neagle's blog]] and corresponding [[https://github.com/gregneagle/autopkg-packaging-demo|Github repo]].
 * You must be allowed to contribute to the [[https://github.com/ox-it/orchard-recipes-private|private Orchard recipe repo]]. If you are not, contact the Orchard team with your request.

== Guidelines ==
 * Fork the [[https://github.com/ox-it/orchard-recipes-private|private Orchard repo]] to your own account and clone it to your test build device/vm.
 * You probably don't need a `build` dir like Greg mentions. This is because all of our pkgs will be imported into munki and we can just use the regular autopkg cache dir as our build directory.
 * Create a pkg structure in the payload directory of your recipe. For instance if your file needed to go into `/Applications/Amazing_Widgets.app/Contents/licence.lic` you would create `payload/Applications/Amazing Widgets/Contents` and then place your licence file in the `Contents` dir. Munki will always install pkgs to `/`
 * You may do this for as many locations/files as you need.
 * Write a .pkg and a .munki recipe to pkg your files
  * You don't have to set overridable inputs if you don't want to
  * The pkg's id sent to `PkgCreator` should be something like `uk.ox.ac.orchard.NAMEOFYOURPKG` - N.B. macOS does not like underscores in pkg id's.
  * The version should start at 1.0 and be bumped incrementally each time there is a minor/major change.
  * Make sure you are careful about setting permissions and modes throughout the process, see the [[https://github.com/autopkg/autopkg/wiki|autopkg wiki]] for more information about the `PkgRootCreator` and `PkgCreator` processors if you are not familiar with them
  * Remember you could add a scripts dir with pre/postinstall scripts in it, and send this directory to `PkgCreator` if necessary.
  * Don't forget any `requires`/`update_for` that needs specifying in the munki recipe.
 * Now run and test the pkg recipe to check it creates the pkg you want. [[Software/SuspiciousPackageQLP|Suspicious Package (available in the Orchard Software Centre)]]  can be a very useful tool for examining this. Check on your build environment that it installs the correct files to the correct places with the correct permissions.
 * Check the munki recipe can import it as usual
 * Submit your PR to the repo as normal with any information the Orchard team will need.

== Updating ==
If you need to update a general purpose pkg recipe, remember to bump the version number in your fork/PR and then ask the Orchard team to rebuild and import it into munki.