This is a set of guidelines for how sipXecs projects should choose filesystem names and layouts in the installed files and within the development tree. Deviating from these guidelines is not automatically a bug - there may be good reasons for doing so, but if possible they should be followed, and when not followed the reasons should be clear and the differences well documented..

These recommendations are based, at least roughly, on the Filesystem Hierarchy Standard. The intent is that the evolution of these conventions be toward closer conformance to that standard (and for the actual layout of files in the sipXecs project to evolve toward these conventions).

Installation Tree

This section describes the layout conventions used for sipXecs projects at installation time on a user system. This does not include everything used by a system being used for development (see Development Tree).

${prefix}

The sipXecs build system uses the GNU autotools; as such, many of the conventions here can be modified at build time by the various options available in that framework. The most commonly used of these is the variable prefix, normally passed to the 'configure' script. Depending on how the configure script is invoked, the paths given here may be relative to the value of ${prefix}. When building from source (from tar files or subversion), the default ${prefix} value is '/usr/local/sipx'. In RPM releases there is no common prefix.

Install Directories

The following is a list of directories where sipXecs components are installed. These can be controlled in a variety of ways; see the table of directory controls below.

bin/

Executables intended for use directly by users or as system daemons; may include both scripts and binaries.

bin/ssl-cert/

Utility scripts to generate and install SSL/TLS certificates and keys.

etc/init.d/

Startup scripts intended to be run under a sysV-style system (such as the 'chkconfig/service' system used by Red Hat).

etc/sipxpbx/

Configuration files that may be modified by the user, but will not be modified by the system itself at run time.

Some of these files are installed as templates (with a '.in' suffix). These files are processed at startup time to produce the functional file to incorporate configuration information from the config.defs file. The processing is done by the bin/configpp utility, which is invoked at startup time.

include/

(included only in developer installs)
Interface definition files.

lib/

Shared and static libraries.

lib/sipviewer/

Java .jar files for the sipviewer utility (used by the wrapper script 'bin/sipviewer').

share/sipxpbx/

Architecture-independent data files that should not be modified by the user.
Note: no files are to be installed in 'share/' other than under 'share/sipxpbx' or another appropriate subdirectory.

var/

Files that are modified by the system at run time. They should not include files that the user modifies.
Note: no files are to be installed in 'var/' other than under the appropriate subdirectory (see below).

var/log/sipxpbx

Log files - written only, never read by the system. The 'logrotate' mechanism or other safeguards should be applied to ensure that these do not grow without bound.

var/run/sipxpbx

Marker files used to detect that a process is running (typically '.pid' files containing a process id). These should be created by the process when it starts, and destroyed when it stops (either by the process itself or by the means used to stop it).

var/sipxdata/

Persistent data used (and potentially modified) by the system.
Note: it could be argued that everything we have put here actually belongs elsewhere.

var/spool/

Spool data - variable size objects created and destroyed by the system (examples would include such things as voice mail messages, but right now they are under var/sipxdata - see note above).

var/tmp/

Purely temporary files - created by the system when running that can be safely deleted whenever it is not running.

www/

Modifications to the apache web server for the benefit of sipXecs. Note: it could be argued that everything we have put here actually belongs elsewhere.

Directory Variables

In makefiles or RPM spec files, the autoconf variable names for directories should be used. The machinery to make these names available is in sipXportLib/config/sipXcommon.mak.in. In code, these names can be made available as strings through C macros, but each such substitution has to be added to the appropriate lib*_la_CXXFLAGS variable.  The default values are listed below and are set by the sipXlib.m4 macro SFAC_INIT_FLAGS. When building from source, each of the ${...} variables listed below has the default value shown in the table. These default values can be overridden by the corresponding argument to ./configure. ${prefix} defaults to /usr/local/sipx and can be overridden by the --prefix argument to ./configure.

Development Tree

Each of the headings below represents a directory that may be found in a sipXecs project; each is followed by a description of the contents to be found in that directory (and in some cases, specific files that may be present). Not all projects will need all of the subdirectories (for example, a project with no metadata would not need a meta/ subdirectory), but if the project has the content described as being found in one of these directories, then it should have the directory and use it in this way.