.. _readme-building:

===============
Building Chapel
===============

To build the Chapel compiler, set up your environment as described in
:ref:`readme-chplenv`, cd to ``$CHPL_HOME`` (the root directory of
your unpacked Chapel release), and run GNU make.  This will build the
compiler and runtime libraries for your current environment as
indicated by running ``$CHPL_HOME/util/printchplenv --all``.

On many systems, GNU make is available simply as ``make``. On others,
it is called ``gmake``.  To check whether ``make`` refers to GNU make
on your system, run:

.. code-block:: bash

   make -v

If the first line includes "GNU Make", you have GNU Make.  The rest of
these instructions will assume ``make`` refers to GNU Make. If that's
not the case, you'll need to replace ``make`` with ``gmake``.

Now build the Chapel compiler:

.. code-block:: bash

   cd $CHPL_HOME
   make

Parallel builds such as ``make -j 6`` are also supported.

If everything works as intended, you ought to see:

1. each of the compiler source subdirectories being compiled

#. the compiler binary getting linked and stored as:

     ``$CHPL_HOME/bin/$CHPL_HOST_PLATFORM-$CHPL_HOST_ARCH/chpl``

#. the runtime support libraries being compiled, archived, and stored
   in a configuration-specific subdirectory under:

     ``$CHPL_HOME/lib/$CHPL_TARGET_PLATFORM/.../``

If you get an error or failure during the make process, double-check
that you have the required prerequisites (see
:ref:`readme-prereqs`). If you do, please submit a bug report for the
failure through :ref:`readme-bugs`.

After a successful build, you should be able to run the compiler and
display its help message using:

.. code-block:: sh

  chpl --help

In which case, you are ready to move on to compiling with the Chapel
compiler (see :ref:`readme-compiling`).  The next few sections provide
more information about using Chapel across multiple sessions,
installing Chapel, and supporting multiple Chapel configurations.
Following that are sections describing Chapel's Makefiles for advanced
users or developers of Chapel.


.. _using-chapel-in-other-sessions:

------------------------------------------------------
Using Chapel in a Different Shell / Terminal / Session
------------------------------------------------------

Once you have built Chapel, you can use it in other sessions (new
shells or terminals) as long as:

1. the ``chpl`` compiler is in your ``$PATH``

#. your ``$CHPL_`` environment variables are set or inferred to values
   that match a configuration you have already built

Typically, this is accomplished in one of the following ways:

* by manually re-sourcing the ``setchplenv.*`` file that you used
  when building Chapel.

* by editing your 'dot files' (e.g., ``.bashrc``, ``bash_profile``, or
  whatever your shell uses to start up each session) to explicitly set
  your path and ``$CHPL_`` settings as desired, or to source the
  appropriate ``setchplenv.*`` script.

* by creating a ``chplconfig`` file to store your preferred ``$CHPL_``
  settings (see :ref:`readme-chplenv.chplconfig` for further details
  on creating a chplconfig file).  Note, however, that some other
  standard technique is still required to ensure that ``chpl`` is in
  your path.

* by installing Chapel to a specific location that is in your path
  using the instructions in the next section.


.. _readme-installing:

-----------------
Installing Chapel
-----------------

Chapel can be built and installed to a specific location as follows:

.. code-block:: bash

  ./configure  # use './configure --help' for specific options
  make
  make install

Running ``./configure`` will save your current configuration of ``$CHPL_``
settings into a ``chplconfig`` file. This ``chplconfig`` file will be installed
wherever ``CHPL_HOME`` is. Running ``./configure`` with the ``--prefix`` or
``--chpl-home`` options permits you to specify where and how Chapel should be
installed during the ``make install`` step. Specifically:

* ``--prefix=/dir/for/install/`` causes the Chapel compiler,
  libraries, and supporting code to be installed into the directories:

  - ``/dir/for/install/bin``
  - ``/dir/for/install/lib``
  - ``/dir/for/install/share``

  This technique is designed to install Chapel using a standard
  directory structure for the purposes of integrating it into a
  standard location that is already in your path, such as
  ``/usr/local/``.  Note that elevated privileges are likely
  to be required for any system-wide installation locations.

  Please note that for any prefix-installed version of Chapel, the meaning of
  ``$CHPL_HOME`` (e.g., as printed by compiler messages) is the path printed by
  ``chpl --print-chpl-home``. This is typically
  ``/dir/for/install/share/chapel/x.yz`` where ``x.yz`` is the Chapel version
  that was installed.

* ``--chpl-home=/dir/for/install`` copies key files and directories
  from the Chapel source tree into ``/dir/for/install``, preserving
  Chapel's traditional directory structure.  As you might expect, the
  meaning of ``$CHPL_HOME`` for such installs is ``/dir/for/install``.


-----------------------------------------
Switching Between Multiple Configurations
-----------------------------------------

A single installation of Chapel can simultaneously support multiple
configuration options, such as target platforms or compilers, because
all binary files and executables are stored in unique subdirectories
as determined by the ``CHPL_`` environment variables.  However, note
that each ``make`` command only builds the compiler and runtime for
the current set of ``CHPL_`` environment variables defined by—and
inferred for—your environment.  To build support for additional
configurations, you will need to modify your ``CHPL_`` environment
variables and re-make.

Once you have built multiple configurations, you can switch between
them either by setting your ``CHPL_`` environment variables to the
same values as when the configuration was built, or using the ``chpl``
compiler's command-line options that correspond to the environment
variables (see the 'Compiler Configuration Options' section of the
:ref:`man-chpl` man page for details).


----------------
Makefile Targets
----------------

The Chapel sources are structured so that a GNU-compatible ``make``
utility can be used in any source directory to build the sources
contained in that directory and its subdirectories.  All of these
Makefiles support the following targets:

  +-----------+------------------------------------------------------+
  | Target    | Action                                               |
  +===========+======================================================+
  | (nothing) | Build the appropriate targets — e.g., objects files, |
  | default   | libraries, executables                               |
  | all       |                                                      |
  +-----------+------------------------------------------------------+
  | check     | verify basic functionality of a Chapel build         |
  +-----------+------------------------------------------------------+
  | clean     | Remove the intermediate files for this configuration |
  +-----------+------------------------------------------------------+
  | cleanall  | Remove the intermediate files for all configurations |
  +-----------+------------------------------------------------------+
  | clobber   | Remove everything created by the Makefiles           |
  |           | as well as ``chplconfig``                            |
  +-----------+------------------------------------------------------+
  | install   | Install Chapel to a previously configured location   |
  +-----------+------------------------------------------------------+

Each target processes all subdirectories, then the current directory.


----------------
Makefile Options
----------------

The Chapel Makefiles have a few options that enable or disable
optimization, debugging support, profiling, and back-end C compiler
warnings. The variables are described below. Set the value to 1 to
enable the feature or 0 to disable it (e.g., ``make DEBUG=1 OPTIMIZE=1
WARNINGS=0``).

  ========  ================================================================
  Option    Effect
  ========  ================================================================
  ASSERTS   Enables correctness assertions in the compiler and runtime
  DEBUG     Generate debug information (e.g., pass ``-g`` to the C compiler)
  OPTIMIZE  Enable optimizations (e.g., pass ``-O3`` to the C compiler)
  PROFILE   Enable profiling support (e.g., pass ``-pg`` to C compiler)
  WARNINGS  Enable more warnings and treat them as errors
  ========  ================================================================

Note that these settings only affect how the ``chpl`` compiler and its
runtime libraries are built, as well as the third-party packages that
they rely upon.  In particular, building Chapel with ``DEBUG`` or
``OPTIMIZE`` set will not cause invocations of the resulting ``chpl``
compiler to automatically generate executables with debugging or
optimizations enabled.


------------------------
Controlling Build Output
------------------------

Aside from the default build output, the Chapel compiler Makefile also supports
two options to increase or decrease the verbosity of the build. These options
can be set either on the command-line as arguments to ``make``, or through the
environment. To enable either option, set the variable to 1
(e.g., ``make VERBOSE=1`` or ``export VERBOSE=1``).

  ========  ================================================================
  Option    Effect
  ========  ================================================================
  VERBOSE   Print verbose CMake output and all commands executed by the Makefiles
  QUIET     Print the minimum output from CMake (e.g., only errors, warnings)
  ========  ================================================================
