salt/doc/topics/conventions/packaging.rst

=========================
SaltStack Packaging Guide
=========================

Since Salt privides a powerful toolkit for system maangement and automation,
the package can be spit into a number of sub-tools. While packaging Salt as
a single package containing all components is perfectly acceptable, the split
packages should follow this convention.

Source Files
============

Release packages should always be built from the source tarball distributed via
pypi. Release packages should *NEVER* use a git checkout as the source for
distribution.

Singe Package
=============

Shipping Salt as a single package, where the minion, master and all tools are
together is perfectly acceptable and practiced by distributions such as
FreeBSD.

Split Package
=============

Salt Should always be split in a standard way, with standard deps, this lowers
cross distribution confusion about what components are going to be shipped with
specific packages. These packages can be defined from the Salt Source as of
Salt 0.17.0:

Salt Common
-----------

The `salt-common` or `salt` package should contain the files provided by the
salt python package, or all files distributed from the ``salt/`` directory in
the source distribution packages. The documentation contained under the
``doc/`` directory can be a part of this package but spliting out a doc
package is prefered.

Name
~~~~

- `salt` OR `salt-common`

Files
~~~~~

- `salt/*`
- `man/salt.7`
- `tests/*`

Depends
~~~~~~~

- `Python 2.6-2.7`
- `PyYAML`
- `Jinja2`

Salt Master
-----------

The `salt-master` package contains the aplicable scripts, related man
pages and init information for the given platform.

Name
~~~~

- `salt-master`

Files
~~~~~

- `scripts/salt-master`
- `scripts/salt`
- `scripts/salt-run`
- `scripts/salt-key`
- `scripts/salt-cp`
- `pkg/<master init data>`
- `man/salt.1`
- `man/salt-master.1`
- `man/salt-run.1`
- `man/salt-key.1`
- `man/salt-cp.1`
- `conf/master`

Depends
~~~~~~~

- `Salt Common`
- `ZeroMQ` >= 3.2
- `PyZMQ` >= 2.10
- `PyCrypto`
- `M2Crypto`
- `Python MessagePack` (Messagepack C lib, or msgpack-pure)

Salt Syndic
-----------

The Salt Syndic package can be rolled completely into the Salt Master package.
Platforms which start servies as part of the package deployment need to
maintain a seperate `salt-syndic` package(primarily Debian based platforms).

The Syndic may optionally not dep the anything more than the Salt Master since
the master will bring in all needed deps, but fall back to the platform
specific packaging guidelines.

Name
~~~~

- `salt-syndic`

Files
~~~~~

- `scripts/salt-syndic`
- `pkg/<syndic init data>`
- `man/salt-syndic.1`

Depends
~~~~~~~

- `Salt Common`
- `Salt Master`
- `ZeroMQ` >= 3.2
- `PyZMQ` >= 2.10
- `PyCrypto`
- `M2Crypto`
- `Python MessagePack` (Messagepack C lib, or msgpack-pure)

Salt Minion
-----------

The Minion Is a standalone package and should not be split beyond the
`salt-minion` and `salt-common` packages.

Name
~~~~

- `salt-minion`

Files
~~~~~

- `scripts/salt-minion`
- `pkg/<minion init data>`
- `man/salt-minion.1`
- `conf/minion`

Depends
~~~~~~~

- `Salt Common`
- `ZeroMQ` >= 3.2
- `PyZMQ` >= 2.10
- `PyCrypto`
- `M2Crypto`
- `Python MessagePack` (Messagepack C lib, or msgpack-pure)

Salt SSH
--------

Since Salt SSH does not require the same deps as the minion and master, it
should be split out.

Name
~~~~

- `salt-ssh`

Files
~~~~~

- `scripts/salt-minion`
- `man/salt-ssh.1`

Depends
~~~~~~~

- `Salt Common`
- `sshpass`

Salt Doc
--------

The documentation package is very distribution optional. A completly split
package will split out the documentation, but some platform conventions do not
prefer this.
If the documentation is not split out, it should be included with the
`Salt Common` package.

Name
----

- `salt-doc`

Files
~~~~~

- `doc/*`

Optional Depends
~~~~~~~~~~~~~~~~

- `Salt Common`
- `Python Sphinx`
- `Make`