* node_package
** Release 3.0.0 - Release notes

Please see [[RELEASE-NOTES.md][RELEASE-NOTES.md]] for important changes in the 3.0.0 release of `node_package`

** Overview

`node_package` is a set of RPM/Debian/Solaris templates and scripts, suitable for
packaging embedded Erlang nodes.

*** Supported Operating Systems

Currently supported operating systems / distros
 - Redhat / Fedora and variants
 - Debian / Ubuntu and variants
 - FreeBSD
 - OSX
 - SmartOS
 - Solaris

** Use

*** Makefile Variables

**** Required Variables

The following variables need to be exported for node_package to work correctly.

 - =PKG_VERSION= - The version of your application (ex: 1.2.0)
 - =PKG_ID= - The full name of the package, typically
   ={{package_name}}-PKG_VERSION= (ex: riak-1.2.0)

**** Defaulted Variables

The following variables will have a default, but can be overriden in your
application.

 - =PKG_BUILD= - (Default: 1) Sets the "release" version of the build
   (ex: app-5.4-1 <- the '1')
 - =ERLANG_BIN= - (Default: `which erl`) Sets the path of the current erlang
   binary
 - =DEPS_DIR= - (Default: deps) Sets the deps directory of the project, most
   projects uses 'deps'.  Change this if something different is used.

** Package and Script Variables

*** Package Variables
The following variables describe a package and should be put in the
=pkg.vars.config= file.

**** Required Variables
 - =package_name= - The name of the package
 - =package_install_name= - The name used in the install directories
    eg: /usr/lib/{{package_install_name}}. Usually the same as package_name.
 - =package_shortdesc= - A short (< one line) description of the package
 - =package_install_user= - The user to create and run the daemon from
 - =package_install_group= - The group to create and add the above user to
 - =copyright= - The copyright holder (ex: 2011 Basho Technologies, Inc)
 - =license_type= - The short desciption of what license the app is under
 - =vendor_name= - The name of the person or company who is releasing this
    package
 - =vendor_url= - The website of the person or company who is releasing this
    package
 - =vendor_contact_name= - The name of the maintainer (ex: Basho Packaging)
 - =vendor_contact_email= - The email address of the maintainer
     (ex: packages@basho.com)
 - =solaris_pkgname= - Package names for Solaris follow a naming convention of
    MAINTapp (ex: BASHOriak)
 - =runner_wait_process= - The erlang process to wait for to determine if your
   app started or not. (ex: `riak_core_node_watcher` in riak's case)


**** Optional Variables
 - =license_full_text= - If the full text of a license needs to be included, use
    this variable
 - =deb_depends= - Dependencies you require on deb sytems.  This should be a
    comma separated list.
 - =package_desc= - A long description of the package
 - =solaris_depends= - (not supported yet) Dependencies specific to the solaris
    package
 - =package_install_user_desc= - The description of the user created for the app
 - =bin_or_sbin= - Tells where to put the binaries, in */bin or */sbin
   (default: bin)
 - =freebsd_package_category= - The subsection the package is filed under in FreeBSD
   (ex: in this line, "ORIGIN: db/riak" 'db' would be the package_category)
   This defaults to 'db' if not specified for lack of a better default.
 - =debuild_extra_options= - This is added to pass extra flags to debuild
 - =cuttlefish_conf= - If your app uses cuttlefish for configuration, this
   is the filename you are using for configuration (ex: "riak.conf")

*** Script Variables
The following variables are used in the =env.sh= and =runner= scripts which can
be used by reltool for =rel= and =devrel= builds.  They should be set in
your application's =vars.config=.

**** Optional Variables
 - =runner_ulimit_warn= - The runner script will warn if `ulimit -n` is less than
   this value.  This defaults to 4096 in all packages.
 - =package_patch_dir= - Directory to include in erlang's load path to allow for
   patches to be hotloaded.  By default this will be in the =platform_lib_dir=
   (ex: "basho-patches")
 - =runner_user= - The username to run the application as
 - =runner_wait_process= - Registered process to wait for to consider start a
   success
 - =cuttlefish_conf= - This is a rare case of a repeated variable since it is
   used in packaging and the main runner scripts, you should have this set
   in both the vars.config and pkg.vars.config (sadly this was the cleanest
   solution).

*** Templating Order
There are several templating steps done in node_package:

- pkg.vars.config from the application is used to template
  <osname>.template from
  deps/node_package/priv/templates/<osname>/<osname>.template
- For all the files in <osname>.template, those files are copied and
  templated according to the values from <osname>.template and
  pkg.vars.config, with pkg.vars.config trumping values from
  <osname>.template. This includes vars.config, which will be used in
  the next templating step.
- Finally, as part of the rebar generate phase, the values from the
  package's rel/vars.config and node_package's vars.config are used to
  template any overlay files marked as a template in
  rel/reltool.config. Values from node_package's vars.config trump the
  ones from rel/vars.config.

So, if you want to have a variable persist all the way through to the
final reltool step, the variable needs to be set in pkg.vars.config
(or defaulted in <osname>.template) AND be present in the vars.config,
so it can be applied to the reltool templates.

*** Example App

The easiest app that uses =node_package= is [[https://github.com/basho/stanchion][stanchion]] a small application that Basho uses along side Riak CS.

In particular, see:

 -  [[https://github.com/basho/stanchion/blob/develop/pkg.vars.config][pkg.vars.config]]
 -  [[https://github.com/basho/stanchion/blob/develop/Makefile#L73][makefile]]
 -  [[https://github.com/basho/stanchion/blob/develop/rel/reltool.config#L46][reltool.config]]  

It also has custom settings in its [[https://github.com/basho/stanchion/blob/develop/rel/vars.config#L31][vars.config]] for adjusting settings in the =bin/stanchion= that comes from node_package's =runner= script.