INSTALL                                                            ETCUTILS
===========================================================================


Introduction
------------

etcutils uses the GNU Automake and GNU Autoconf utilities as its build
system.  As such, its configuration and installation resembles that of most
other utilities.

This document is only intended to users willing to build etcutils from
sources.  If your operating system provides a pre-packaged version of
etcutils, you do not need to read this document: installing the package
will do the right thing.

For the impatient:

$ ./configure --sysconfdir=/etc
$ make
$ sudo make install
$ make installcheck


Dependencies
------------

Building etcutils from sources requires the following:

* A POSIX shell interpreter.

* A make(1) utility.

* Optionally, if you want to build the tests, the Automated Testing
  Framework (ATF).

Additionally, if you are building etcutils from the source code repository,
you will also need:

* GNU autoconf 2.65

* GNU automake 1.11.1


Regenerating the build system
-----------------------------

If you are building etcutils from code checked out from the repository, you
must first regenerate the files used by the build system.  Do this with:

$ autoreconf -is

This is not needed if you are building from a formal release distribution
file.


General build procedure
-----------------------

1) Configure the sources.  This step allows you to specify where to install
   the utilities and which configuration files they have to use.
   Generally, the following is enough:

   $ ./configure --prefix /usr/local --sysconfdir=/etc

   For details on available configuration flags, see below.

2) Build the sources by running:

   $ make

3) Install the utilities.  You may need superuser powers to do this:

   # make install

4) If you built the tests, run them to ensure everything is working fine.
   You can do this either from the source tree:

   $ make installcheck

   Or from the installed tools:

   $ cd /usr/local/tests/etcutils
   $ atf-run | atf-report


Configuration flags
-------------------

The configure script provides many flags to tune its behavior.  The
following are the most useful ones for this package:

* --help

  Shows usage information.

* --prefix=directory
  Possible values: any path
  Default: /usr/local

  Specifies where all the files will be installed.

* --sysconfdir=directory
  Possible values: any path
  Default: ${prefix}/etc

  Specifies the location of the configuration files.  Note that the default
  value is almost-always WRONG.  You must pass --sysconfdir=/etc to the
  script if you want to be able to make the utilities use the system-wide
  databases by default.  The configure script will warn you if you do not
  do so.

* --with-atf=yes|no|auto
  Possible values: yes, no, auto
  Default: auto

  Whether to use the Automated Testing Framework to build and install the
  test programs.

* SERVICES_FILE=path
  Possible values: any path
  Default: ${sysconfdir}/services

  Absolute path to the services(5) file to use by default.

* SHELLS_FILE=path
  Possible values: any path
  Default: ${sysconfdir}/shells

  Absolute path to the shells(5) file to use by default.


===========================================================================
EOF
