= General Purpose Packaging = <> == 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]]. * If your package will contain any sensitive material (such as licence numbers) 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 recipe repo you require 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.