README: add one and tweaks; closes opnsense#891

Author: fichtner

Makefile

@@ -184,14 +184,22 @@ plist: force
 	@${MAKE} -C ${.CURDIR}/lang plist
 	@${MAKE} -C ${.CURDIR}/src plist
 
+package-keywords: force
+	@if [ ! -f /usr/ports/Keywords/sample.ucl ]; then \
+		mkdir -p /usr/ports/Keywords; \
+		cd /usr/ports/Keywords; \
+		fetch https://raw.githubusercontent.com/opnsense/ports/master/Keywords/sample.ucl; \
+	fi
+	@echo ">>> Installed /usr/ports/Keywords/sample.ucl"
+
 package: force
 	@if [ -f ${WRKDIR}/.mount_done ]; then \
-	    echo "Cannot continue with live mount"; exit 1; \
+		echo ">>> Cannot continue with live mount.  Please run 'make umount'." >&2; \
+		exit 1; \
 	fi
 	@if [ ! -f /usr/ports/Keywords/sample.ucl ]; then \
-	    mkdir -p /usr/ports/Keywords; \
-	    cd /usr/ports/Keywords; \
-	    fetch -q https://raw.githubusercontent.com/opnsense/ports/master/Keywords/sample.ucl; \
+		echo ">>> Missing required file(s).  Please run 'make package-keywords'" >&2; \
+		exit 1; \
 	fi
 	@${PKG} info gettext-tools > /dev/null
 	@${PKG} info git > /dev/null

README.md

@@ -5,13 +5,9 @@ The OPNsense project invites developers to start contributing to
 the code base.  For your own purpose or even better to join us in
 creating the best open source firewall available.
 
-The build process has been designed to make it truly straightforward
-and easy for anyone to build and code.  Being able to get the sources
-and build it yourself is one of the key factors of open source software.
-
-Although a lot of the code is still in flux, we try to publish the
-direction we're taking on our wiki page.  The main outline of the new
-codebase is available at:
+The build process has been designed to make it easy for anyone to
+build and write code.  The main outline of the new codebase is
+available at:
 
 https://wiki.opnsense.org/index.php/Develop:Architecture
 
@@ -23,7 +19,6 @@ Build tools
 
 To create working software like OPNsense you need the sources and the
 tools to build it.  The build tools for OPNsense are freely available.
-No strings attached.
 
 Notes on how to build OPNsense can be found in the tools repository:
 
@@ -46,3 +41,70 @@ http://opensource.org/licenses/BSD-2-Clause
 Every contribution made to the project must be licensed under the
 same conditions in order to keep OPNsense truly free and accessible
 for everybody.
+
+Makefile targets
+================
+
+The repository offers a couple of targets that either tie into
+tools.git build processes or are aimed at fast development.
+
+make package
+------------
+
+A package of the current state of the repository can be created using
+this target.  It may require several packages to be installed.  The
+target will try to assist in case of failure, e.g. when a missing file
+needs to be fetched from an external location.
+
+Several OPTIONS exist to customise the package:
+
+* CORE_DEPENDS: a list of required dependencies for the package
+* CORE_ORIGIN: sets a FreeBSD compatible package/ports origin
+* FLAVOUR: can be set to "OpenSSL" (default) or "LibreSSL"
+* CORE_COMMENT: a short description of the package
+* CORE_MAINTAINER: email of the package maintainer
+* CORE_WWW: web url of the package
+* CORE_NAME: sets a package name
+
+Options are passed in the following form:
+
+    # make package CORE_NAME=my_new_name
+
+make upgrade
+------------
+
+Upgrade will run the package build and attempt to replace the currently
+installed package in the system.  Safety measures may prevent the target
+from succeeding.  The following rules apply:
+
+In order to install from the master branch of this repository, the
+opnsense-devel package must be installed:
+
+    # pkg install opnsense-devel
+
+In order to install from the stable branches of this repository, the
+opnsense-stable package must be installed:
+
+    # pkg install opnsense-stable
+
+make mount
+----------
+
+Live-mount the package into the current system.  This will overlay
+the repository over /usr/local and will instantly change the GUI
+accordingly.  In this mode changes can be quickly tested.
+
+Note that live-mount will not be persistent after reboot and causes
+trouble when used while upgrading firmware as packages get installed
+into the repository as oppsed to the system.  Use with care.
+
+make umount
+-----------
+
+Disable the live-mount feature.
+
+make lint
+---------
+
+Run serveral syntax checks on the repository.  This is recommended
+before issuing a pull request on GitHub.