Installation Instructions
=========================

This file contains instructions on building and installing the
libraries and utilities in the elftoolchain project's sources.

Supported Operating Systems
---------------------------

The source tree is currently built and tested on the following
operating systems.

  =================   ========   =======================
  Operating System    Version    Supported Architectures
  -----------------   --------   -----------------------
  `DragonFly BSD`_    5.8.1      amd64
  FreeBSD_            12.2       amd64 & i386
  Minix_              3.0.2      i386
  NetBSD_             9.1        amd64
  OpenBSD_            6.5        amd64
  Raspbian_           10         armv7l
  Ubuntu_ GNU/Linux   18.04      x86_64
  =================   ========   =======================

.. _DragonFly BSD: http://www.dragonflybsd.org/
.. _FreeBSD: http://www.freebsd.org/
.. _Minix:   http://www.minix3.org/
.. _NetBSD:  http://www.netbsd.org/
.. _OpenBSD: http://www.openbsd.org/
.. _Raspbian: https://www.raspberrypi.org/software/
.. _Ubuntu:  http://www.ubuntu.com/

Building the Source Tree
========================

The core libraries and utilities that make up the software release are
always built by default.  Builds of the project's test suites (in the
``test/`` subdirectory), and of additional documentation (in the directory
``documentation/``) are optional, and will only be attempted if these
directories are present.

Prerequisites
-------------

:DragonFly BSD 5.8.1:
    - The core libraries and utilities should build out of the box on
      a stock install of DragonFly BSD.

    - To build and run the test suite:

      #. The current release of the `Test Execution Toolkit`_ needs to
         be downloaded and unpacked into the ``test/tet/`` directory.

      #. The ``py37-yaml`` package needs to be installed::

            % sudo pkg install py37-yaml

    - Building additional documentation is not currently supported
      under DragonFly BSD.

:FreeBSD 12.2:
    - The core libraries and utilities should build out of the box on
      a stock install of FreeBSD.

    - To build and run the test suite:

      #. The current release of the `Test Execution Toolkit`_ needs to
         be downloaded and unpacked into the ``test/tet/`` directory::

            % cd <SRCDIR>/test/tet
            % tar -xf /PATH/TO/DOWNLOADED/TET-3.8-SOURCES

      #. The ``py37-yaml`` package needs to be installed::

            % sudo pkg install py37-yaml

    - Building additional documentation is not currently supported under
      FreeBSD 12.2.

:Minix 3.2.0:
    - The following packages are pre-requisites for building the
      sources on Minix 3.2.0:

      ===================     =====================================
      **Package**             **Description**
      ===================     =====================================
      ``gcc44``               The GNU C compiler.
      ===================     =====================================

      The following command line may be used to install the necessary
      pre-requisites::

          # pkgin install gcc44

    - The test suites cannot currently be built under Minix.

    - Building additional documentation is not currently supported
      under Minix.

:OpenBSD 6.5:
    - The following packages are pre-requisites for building the
      sources on OpenBSD 6.5:

      ===================     =====================================
      **Package**             **Description**
      ===================     =====================================
      ``libarchive``          An archive access library.
      ===================     =====================================

      The following command line may be used to install the necessary
      pre-requisites::

          # pkg_add libarchive

    - Building additional documentation is not currently supported
      under OpenBSD.

:NetBSD 9.1:
    - The core libraries and utilities should build out of the box on
      a stock install of NetBSD 9.1.

    - To build and run the test suite:

      #. The current release of the `Test Execution Toolkit`_, needs
         to be downloaded and unpacked into the ``test/tet/``
         directory.

      #. The following additional package needs to be installed, as
         listed in the example command line below ::

            % sudo pkgin install py38-yaml

    - Building additional documentation is not currently supported
      under NetBSD.

:Ubuntu GNU/Linux 18.04:
    - The following packages are pre-requisites for building the
      sources on Ubuntu GNU/Linux 18.04:

      ===================     =====================================
      **Package**             **Description**
      ===================     =====================================
      ``binutils``            Needed for the build.
      ``bison``               Parser generator.
      ``flex``                Lexical analyser.
      ``gcc``                 C compiler.
      ``libarchive-dev``      Archive access library.
      ``libbsd-dev``          BSD headers and libraries.
      ``libc6-dev``           Files for C language development.
      ``libexpat1-dev``       An XML processing library.
      ``m4``                  Macro processor.
      ``bmake``               NetBSD ``make``.
      ``python3-yaml``        A YAML library for Python.
      ``sharutils``           For ``uudecode``.
      ``zlib1g-dev``          Compression library.
      ===================     =====================================

      The following command line may be used to install the necessary
      pre-requisites::

	  % sudo apt install binutils bison flex gcc libarchive-dev \
	    libc6-dev m4 bmake zlib1g-dev

    - To build and run the test suite:

      #. The current release of the `Test Execution Toolkit`_, needs
         to be downloaded and unpacked into the ``test/tet/``
         directory.

      #. The following additional packages need to be installed, as
         listed in the example command line below::

            % sudo apt install libexpat1-dev python3.7 python3-yaml \
              sharutils

    - To build additional documentation, the packages listed in the
      example command line below are needed::

          % sudo apt install html-xml-utils libbsd-dev mandoc \
               texlive-extra-utils texlive-latex-recommended texlive-pictures

:Raspbian 10:
    - The following packages are pre-requisites for building the
      sources on Raspbian 10:

      ===================     =====================================
      **Package**             **Description**
      ===================     =====================================
      ``bison``               Parser generator.
      ``flex``                Lexical analyser.
      ``libarchive-dev``      Archive access library.
      ``m4``                  Macro processor.
      ``bmake``               NetBSD ``make``.
      ===================     =====================================

      The following command line may be used to install the necessary
      pre-requisites::

	  % sudo apt install bison flex libarchive-dev m4 bmake

    - To build and run the test suite:

      #. The current release of the `Test Execution Toolkit`_ needs to
         be downloaded and unpacked into the ``test/tet/`` directory::

            % cd <SRCDIR>/test/tet
            % tar -xf /PATH/TO/DOWNLOADED/TET-3.8-SOURCES

      #. The ``python3-yaml`` package needs to be installed::

            % sudo apt install python3-yaml

    - Building additional documentation is not currently supported
      under Raspbian.

.. _Test Execution Toolkit: http://tetworks.opengroup.org/
.. _OpenGroup: http://www.opengroup.org/


Building the software
---------------------

The software may be built by running **make**.

On `DragonFly BSD`_,  FreeBSD_, Minix_, NetBSD_ and OpenBSD_, use::

  % make

On Ubuntu GNU/Linux with the **bmake** package installed, use::

  % bmake


Testing the software
---------------------

The ``run-tests`` target in the top-level Makefile will build and
execute the test suites that are part of this software.

On `DragonFly BSD`_, FreeBSD_ and NetBSD_, use::

    % make run-tests

On Ubuntu GNU/Linux with the **bmake** package installed, use::

    % bmake run-tests

Installing the Software
=======================

The software may be installed using the ``install`` target.

On `DragonFly BSD`_, FreeBSD_, Minix_, NetBSD_ and OpenBSD_ use::

    % make install

On Ubuntu GNU/Linux with the **bmake** package installed, use::

    % bmake install


By default the ``install`` target will install utilities into
``/usr/bin/``, libraries into ``/usr/lib/`` and manual pages into
``/usr/share/man/man[0-9]/``.

The installation directory may be changed using the ``DESTDIR``
variable.  For example::

    % bmake DESTDIR=$HOME/local install


Additional Information
======================

Additional information about the project may be found on the `project
website`_.

.. _project website:  http://elftoolchain.sourceforge.net/

.. $Id$

.. Local Variables:
.. mode: rst
.. End:
