.. _readme-chplenv:

Setting up Your Environment for Chapel
======================================

To get started with Chapel, there are four environment settings that are
strongly recommended for effective use of the release, and a few other optional
settings that are useful for cross-compiling or overriding the default
settings.  To check the values of the Chapel environment variables that are set
or can be inferred, run the script::

  $CHPL_HOME/util/printchplenv

The ``setchplenv.*`` source scripts in the ``$CHPL_HOME/util/quickstart/`` and
``$CHPL_HOME/util/`` directories contain commands that set the following
variables for various shells and host platforms when they are sourced from the
``$CHPL_HOME`` directory.  Frequent Chapel users may want to add such settings
to their shell's dotfile(s); but for getting started the setchplenv.* scripts
can be convenient.

.. contents::

Recommended Settings
--------------------

.. _readme-chplenv.CHPL_HOME:

CHPL_HOME
~~~~~~~~~
   Set the ``CHPL_HOME`` environment variable to point to the location of the
   chapel/ directory that was created when you unpacked the release.
   For example:

    .. code-block:: sh

        export CHPL_HOME=~/chapel-1.13.1

   .. note::
     This, and all other examples in the Chapel documentation, assumes you're
     using the ``bash`` shell.  If using ``csh`` or ``tcsh``, mentally change
     ``export FOO=BAR`` to ``setenv FOO BAR``.  If using some other shell, make
     the appropriate adjustment.


.. _readme-chplenv.CHPL_HOST_PLATFORM:

CHPL_HOST_PLATFORM
~~~~~~~~~~~~~~~~~~
   Set the ``CHPL_HOST_PLATFORM`` environment variable to represent the platform on
   which you're working.  For standard UNIX workstations, this can be done by
   running the ``$CHPL_HOME/util/chplenv/chpl_platform.py`` script.  For
   example:

    .. code-block:: sh

        export CHPL_HOST_PLATFORM=`$CHPL_HOME/util/chplenv/chpl_platform.py`

   For other platforms that appear very similar to a UNIX workstation from the
   shell prompt (e.g., a Cray XK\ |trade|), the value may need to be set
   explicitly.  The strings for our currently-supported host platforms are as
   follows:

        ===========  ==================================
        Value        Description
        ===========  ==================================
        cygwin32     x86 Cygwin (Windows) platforms
        cygwin64     x86_64 Cygwin (Windows) platforms
        darwin       Macintosh OS X platforms
        linux32      32-bit Linux platforms
        linux64      64-bit Linux platforms
        marenostrum  BSC's MareNostrum platform
        netbsd32     32-bit NetBSD platforms
        netbsd64     64-bit NetBSD platforms
        pwr5         IBM Power5 SMP cluster
        pwr6         IBM Power6 SMP cluster
        sunos        SunOS platforms
        cray-cs      Cray CS\ |trade|
        cray-xc      Cray XC\ |trade|
        cray-xe      Cray XE\ |trade|
        cray-xk      Cray XK\ |trade|
        ===========  ==================================

   Platform-specific documentation is available for most of these platforms in
   :ref:`platforms-index`.

   The Chapel Makefiles and sources are designed to work for any UNIX-compatible
   environment that supports a GNU-compatible make utility.  The list above
   represents the set of platforms that we have access to and can test easily.
   We are interested in making our code framework portable to other platforms --
   if you are using Chapel on a platform other than the ones listed above,
   please refer to :ref:`platform-specific-settings` for ways to set up a
   Makefile for this platform and/or contact us at: chapel_info@cray.com

PATH
~~~~
   Set your ``PATH`` to include the directory
   ``$CHPL_HOME/bin/$CHPL_HOST_PLATFORM`` which is created when you build the
   compiler.  For example:

    .. code-block:: sh

        export PATH="$PATH":"$CHPL_HOME/bin/$CHPL_HOST_PLATFORM"


MANPATH
~~~~~~~
   Set your man path to include the directory ``$CHPL_HOME/man``.
   For example:

    .. code-block:: sh

        export MANPATH="$MANPATH":"$CHPL_HOME"/man

Optional Settings
-----------------

.. _readme-chplenv.CHPL_TARGET_PLATFORM:

CHPL_TARGET_PLATFORM
~~~~~~~~~~~~~~~~~~~~
   If you are cross-compiling for a platform other than your
   ``$CHPL_HOST_PLATFORM``, set the ``CHPL_TARGET_PLATFORM`` environment
   variable to describe that platform.  See `CHPL_HOST_PLATFORM`_ above for
   legal values (though whether or not a given setting will support
   cross-compilation depends on your specific environment).

   .. note::
     If ``CHPL_TARGET_PLATFORM`` is not set, the target platform defaults to the
     same value as ``$CHPL_HOST_PLATFORM``.

.. _readme-chplenv.CHPL_COMPILER:

CHPL_*_COMPILER
~~~~~~~~~~~~~~~
   Optionally, you can set ``CHPL_HOST_COMPILER`` and/or
   ``CHPL_TARGET_COMPILER`` to indicate the compiler suite to use in building
   the sources.  ``CHPL_HOST_COMPILER`` is the compiler used to build the
   Chapel compiler itself so that it will run on ``CHPL_HOST_PLATFORM``.
   ``CHPL_TARGET_COMPILER`` is the compiler used to build the runtime libraries
   and generated code for ``CHPL_TARGET_PLATFORM``.  Currently supported values
   are as follows:

        =================  ===================================================
        Value              Description
        =================  ===================================================
        clang              The Clang compiler suite -- clang and clang++
        clang-included     The Clang compiler in third-party/llvm
        cray-prgenv-cray   The Cray PrgEnv compiler using the Cray CCE backend
        cray-prgenv-gnu    The Cray PrgEnv compiler using the GNU backend
        cray-prgenv-intel  The Cray PrgEnv compiler using the Intel backend
        cray-prgenv-pgi    The Cray PrgEnv compiler using the PGI backend
        gnu                The GNU compiler suite -- gcc and g++
        ibm                The IBM compiler suite -- xlc and xlC
        intel              The Intel compiler suite -- icc and icpc
        pgi                The PGI compiler suite -- pgcc and pgc++
        =================  ===================================================

   The default for ``CHPL_*_COMPILER`` depends on the value of the corresponding
   ``CHPL_*_PLATFORM`` environment variable:

        ============  ==================================================
        Platform      Compiler
        ============  ==================================================
        cray-x*       - gnu (for ``CHPL_HOST_COMPILER``)
                      - cray-prgenv-$PE_ENV (for ``CHPL_TARGET_COMPILER``,
                        where PE_ENV is set by PrgEnv-* modules)
        darwin        clang if available, otherwise gnu
        marenostrum   ibm
        pwr5, pwr6    ibm
        other         gnu
        ============  ==================================================

   If ``CHPL_HOST_PLATFORM == CHPL_TARGET_PLATFORM`` and is not ``cray-x*``,
   ``CHPL_TARGET_COMPILER`` will default to the same value as ``CHPL_HOST_COMPILER``.

   .. note::
     Note that builds with :ref:`readme-llvm` (i.e. when ``CHPL_LLVM=llvm``)
     will build the runtime twice: once with the compiler as described above and
     once with clang-included. We do this in order to avoid issues in linking
     objects built by different compilers.

.. _readme-chplenv.CHPL_TARGET_ARCH:

CHPL_TARGET_ARCH
~~~~~~~~~~~~~~~~
   Optionally, set the ``CHPL_TARGET_ARCH`` environment variable to indicate
   that the target executable should be specialized to the given architecture
   when using ``--specialize`` (and ``--fast``). Valid options are:

        ========  =============================================================
        Value     Description
        ========  =============================================================
        native    The C compiler will attempt to detect the architecture on the
                  machine that is compiling the target executable. This is a
                  good choice if you will be running on the same machine that
                  you are compiling on.  If you are not, see the options below.
        unknown   No specialization will be performed
        none      No specialization will be performed (will not warn)
        ========  =============================================================

        =========== ================
        Architecture-specific values
        ----------------------------
        intel       amd
        =========== ================
        core2           k8
        nehalem         k8sse3
        westmere        barcelona
        sandybridge     bdver1
        ivybridge       bdver2
        haswell         bdver3
        broadwell       bdver4
        =========== ================

   These values are defined to be the same as in GCC 4.9:

        https://gcc.gnu.org/onlinedocs/gcc-4.9.0/gcc/i386-and-x86-64-Options.html

   If you do not want ``CHPL_TARGET_ARCH`` to have any effect, you can set it
   to either ``unknown`` or ``none``. Both will disable specialization, but the
   latter will not warn if ``--specialize`` is used.

   Setting ``CHPL_TARGET_ARCH`` to an incorrect value for your processor may
   result in an invalid binary that will not run on the intended machine.
   Special care should be taken to select the lowest common denominator when
   running on machines with heterogeneous processor architectures.

   The default value for this setting will vary based on settings in your
   environment, in order of application these rules are:

        * If :ref:`CHPL_TARGET_COMPILER <readme-chplenv.chpl_compiler>` is ``cray-prgenv-*`` you do not need to
          set anything in ``CHPL_TARGET_ARCH``. One of the ``craype-*`` modules
          (e.g.  ``craype-sandybridge``) should be loaded to provide equivalent
          functionality. Once the proper module is loaded, ``CRAY_CPU_TARGET``
          will have the architecture being used in it.

        * If ``CHPL_TARGET_COMPILER`` is ``cray``, ``pgi``, or ``ibm``,
          ``CHPL_TARGET_ARCH`` will be set to ``none`` and no specialization
          will occur.

        * If :ref:`readme-chplenv.CHPL_COMM` is set, no attempt to set a useful value will be
          made, ``CHPL_TARGET_ARCH`` will be ``unknown``.

        * If :ref:`readme-chplenv.CHPL_TARGET_PLATFORM` is ``darwin``, ``linux*``, or
          ``cygwin*`` ``CHPL_TARGET_ARCH`` will be ``native``, passing the
          responsibility off to the backend C compiler to detect the specifics
          of the hardware.


.. _readme-chplenv.CHPL_MAKE:

CHPL_MAKE
~~~~~~~~~
   Optionally, set the ``CHPL_MAKE`` environment variable to indicate the
   GNU-compatible make utility that you want the compiler back-end to invoke
   when compiling the generated C code.  If not set, this will default to a
   value based on ``$CHPL_HOST_PLATFORM``:

        ==================    ============
        platform              make utility
        ==================    ============
        cygwin*, darwin       make
        linux32, linux64      gmake if available, otherwise make
        other                 gmake
        ==================    ============


.. _readme-chplenv.CHPL_MODULE_PATH:

CHPL_MODULE_PATH
~~~~~~~~~~~~~~~~
   Optionally, set the ``CHPL_MODULE_PATH`` environment variable to provide a
   list of directories to be added to the :ref:`readme-module_search`.  The
   value of this environment variable should be a colon-separated list of
   directory paths.

   The module search path is used to satisfy 'use' statements in the Chapel
   program.  The complete search path can be displayed using the compiler option
   ``--print-search-dirs``.  It will also include the compiler's standard module
   search paths, those introduced by the ``-M`` flag on the command line and
   directories containing the .chpl files named explicitly on the compiler
   command line.


.. _readme-chplenv.CHPL_LOCALE_MODEL:

CHPL_LOCALE_MODEL
~~~~~~~~~~~~~~~~~
   Optionally, set the ``CHPL_LOCALE_MODEL`` environment variable to
   indicate the locale model you want to use.  Current options are:

        ======== =============================================
        Value    Description
        ======== =============================================
        flat     top-level locales are not further subdivided
        numa     top-level locales are further subdivided into
                 sublocales, each one a NUMA domain
        ======== =============================================

   If unset, ``CHPL_LOCALE_MODEL`` defaults to ``flat``.

   See :ref:`readme-localeModels` for more information about
   locale models.


.. _readme-chplenv.CHPL_TASKS:

CHPL_TASKS
~~~~~~~~~~
   Optionally, set the ``CHPL_TASKS`` environment variable to indicate what
   tasking layer you want to use to implement intra-locale parallelism (see
   :ref:`readme-tasks` for more information on this option).  Current options
   are:

        ============== ===================================================
        Value          Description
        ============== ===================================================
        qthreads       use Sandia's Qthreads package
        fifo           use POSIX threads
        massivethreads use U Tokyo's MassiveThreads package
        muxed          use Cray-specific lightweight threading (with Cray
                       pre-built module only)
        ============== ===================================================

   If ``CHPL_TASKS`` is not set it defaults to ``qthreads`` in all cases
   except for a few specific configurations in which it defaults to
   ``fifo``:

     * target platform is ``cygwin*``
     * target platform is ``netbsd*``

   .. note::
     Note that the Chapel ``util/quickstart/setchplenv.*`` source scripts set
     ``CHPL_TASKS`` to ``fifo`` to reduce build-time and third-party dependences,
     while the ``util/setchplenv.*`` versions leave it unset, resulting in the
     behavior described just above.

   See :ref:`readme-tasks` for more information about executing using the
   various ``CHPL_TASKS`` options.  See also :ref:`readme-cray` for more
   information about Cray-specific runtime layers.


.. _readme-chplenv.CHPL_COMM:

CHPL_COMM
~~~~~~~~~
   Optionally, set the ``CHPL_COMM`` environment variable to indicate what
   communication layer you want to use to implement inter-locale communication.
   Current options are:

        ======= ============================================
        Value   Description
        ======= ============================================
        none    only supports single-locale execution
        gasnet  use the GASNet-based communication layer
        ugni    Cray-specific native communications (with
                Cray pre-built module only)
        ======= ============================================

   If unset, ``CHPL_COMM`` defaults to ``none`` in most cases.  On a Cray
   system it defaults to ``gasnet`` except when using a pre-built module on a
   Cray XC or XE\ |trade| system, where it defaults to ``ugni``.  See
   :ref:`readme-multilocale` for more information on executing Chapel programs
   using multiple locales.  See also :ref:`readme-cray` for more information
   about Cray-specific runtime layers.


.. _readme-chplenv.CHPL_MEM:

CHPL_MEM
~~~~~~~~
   Optionally, the ``CHPL_MEM`` environment variable can be used to select
   a memory management layer.  Current options are:

        ========= =======================================================
        Value     Description
        ========= =======================================================
        cstdlib   use the standard C malloc/free commands
        jemalloc  use Jason Evan's memory allocation package
        ========= =======================================================

   If unset, ``CHPL_MEM`` defaults to ``jemalloc`` for most configurations.
   If the target platform is ``cygwin*``, the target compiler is ``*pgi``,
   or the target platform is ``darwin`` and the target compiler is ``gnu``
   it defaults to ``cstdlib``


.. _readme-chplenv.CHPL_LAUNCHER:

CHPL_LAUNCHER
~~~~~~~~~~~~~
   Optionally, the ``CHPL_LAUNCHER`` environment variable can be used to select
   a launcher to get your program up and running.  See :ref:`readme-launcher`
   for more information on this variable's default and possible settings.


.. _readme-chplenv.CHPL_ATOMICS:

CHPL_ATOMICS
~~~~~~~~~~~~
   Optionally, the ``CHPL_ATOMICS`` environment variable can be used to
   select an implementation for atomic operations in the runtime.  Current
   options are:

        ===========  =====================================================
        Value        Description
        ===========  =====================================================
        intrinsics   implement atomics using target compiler intrinsics
                     (which typically map down to hardware capabilities)
        locks        implement atomics by using Chapel sync variables to
                     protect normal operations
        ===========  =====================================================

   If unset, CHPL_ATOMICS defaults to ``intrinsics`` for most configurations.
   On some 32 bit platforms, or if the target compiler is ``pgi`` or
   ``cray-prgenv-pgi`` it defaults to ``locks``.

   .. note::
     gcc 4.8.1 added support for 64 bit atomics on 32 bit platforms.  We
     default to ``intrinsics`` for 32 bit platforms when using the target
     compiler ``gnu`` with a recent enough version of gcc.  For older versions
     or other target compilers we default to ``locks``

   See the Chapel Language Specification for more information about atomic
   operations in Chapel or :ref:`readme-atomics` for more information about the
   runtime implementation.


.. _readme-chplenv.CHPL_TIMERS:

CHPL_TIMERS
~~~~~~~~~~~
   Optionally, the ``CHPL_TIMERS`` environment variable can be used to
   select an implementation for Chapel's timers.  Current options are:

       generic
         use a ``gettimeofday()``-based implementation

   If unset, ``CHPL_TIMERS`` defaults to ``generic``


.. _readme-chplenv.CHPL_GMP:

CHPL_GMP
~~~~~~~~
   Optionally, the ``CHPL_GMP`` environment variable can select between
   no GMP support, using the GMP distributed with Chapel in third-party, or
   using a system GMP. Current options are:

       =======  ============================================================
       Value     Description
       =======  ============================================================
       system   assume GMP is already installed (#include gmp.h, -lgmp)
       none     do not build GMP support into the Chapel runtime
       gmp      use the GMP distribution bundled with Chapel in third-party
       =======  ============================================================

   If unset, Chapel will attempt to build GMP using
   :ref:`CHPL_TARGET_COMPILER<readme-chplenv.CHPL_COMPILER>` (noting that the bundled version
   may not be supported by all compilers).  Based on the outcome, Chapel will
   default to:

       ======= ====================================================
       Value   Description
       ======= ====================================================
       gmp     if the build was successful
       system  if unsuccessful and :ref:`readme-chplenv.CHPL_TARGET_PLATFORM` is cray-x*
       none    otherwise
       ======= ====================================================

   .. note::
     Note that the Chapel ``util/quickstart/setchplenv.*`` source scripts set
     ``CHPL_GMP`` to ``none`` while the ``util/setchplenv.*`` versions leave it
     unset, resulting in the behavior described just above.


.. _readme-chplenv.CHPL_HWLOC:

CHPL_HWLOC
~~~~~~~~~~
   Optionally, the ``CHPL_HWLOC`` environment variable can select between
   no hwloc support or using the hwloc package distributed with Chapel in
   third-party.  Note that hwloc is only used by the qthreads tasking layer,
   and does not need to be built for other tasking layers.  Current options
   are:

       ======= ==============================================================
       Value   Description
       ======= ==============================================================
       none    do not build hwloc support into the Chapel runtime
       hwloc   use the hwloc distribution bundled with Chapel in third-party
       ======= ==============================================================

   If unset, ``CHPL_HWLOC`` defaults to ``hwloc`` if :ref:`readme-chplenv.CHPL_TASKS` is
   ``qthreads``.  In all other cases it defaults to ``none``.  In the unlikely
   event the bundled hwloc distribution does not build successfully, it should
   still be possible to use qthreads.  To do this, manually set ``CHPL_HWLOC``
   to ``none`` and rebuild (and please file a bug with the Chapel team.) Note
   that building without hwloc will have a negative impact on performance.


.. _readme-chplenv.CHPL_REGEXP:

CHPL_REGEXP
~~~~~~~~~~~
   Optionally, the ``CHPL_REGEXP`` environment variable can be used to enable
   regular expression operations as defined in :chpl:mod:`Regexp`.  Current
   options are:

       ======= ==============================================
       Value   Description
       ======= ==============================================
       re2     use the re2 distribution in third-party
       none    do not support regular expression operations
       ======= ==============================================

   If unset, Chapel will attempt to build RE2 using :ref:`CHPL_TARGET_COMPILER<readme-chplenv.CHPL_COMPILER>`
   (noting that the bundled version may not be supported by all compilers).
   Based on the outcome, Chapel will default to:

       ======= ===============================
       Value   Description
       ======= ===============================
       re2     if the build was successful
       none    otherwise
       ======= ===============================

   .. note::
     Note that the Chapel ``util/quickstart/setchplenv.*`` source scripts set
     ``CHPL_REGEXP`` to ``'none`` while the ``util/setchplenv.*`` versions
     leave it unset, resulting in the behavior described just above.


.. _readme-chplenv.CHPL_AUX_FILESYS:

CHPL_AUX_FILESYS
~~~~~~~~~~~~~~~~
   Optionally, the ``CHPL_AUX_FILESYS`` environment variable can be used to
   request that runtime support for filesystems beyond the usual Linux one be
   present.  Current options are:

       ====== =================================================
       Value  Description
       ====== =================================================
       none   only support traditional Linux filesystems
       hdfs   also support HDFS filesystems using Apache Hadoop libhdfs
       hdfs3  support for HDFS filesystems using Pivotal libhdfs3
       curl   also support CURL as a filesystem interface
       ====== =================================================

   If unset, ``CHPL_AUX_FILESYS`` defaults to ``none``.

   See :ref:`readme-auxIO`, :chpl:mod:`HDFS`, and :chpl:mod:`Curl` for more
   information about HDFS and CURL support.


.. _readme-chplenv.CHPL_LLVM:

CHPL_LLVM
~~~~~~~~~
   Optionally, the ``CHPL_LLVM`` environment variable can be used to
   enable support for the LLVM back-end to the Chapel compiler (see
   :ref:`readme-llvm`) or to support extern blocks in Chapel code via
   the Clang compiler (see :ref:`readme-extern`).  Current options are:

       ====== ======================================================
       Value  Description
       ====== ======================================================
       llvm   use the llvm/clang distribution in third-party
       none   do not support llvm-/clang-related features
       ====== ======================================================

   If unset, ``CHPL_LLVM`` defaults to ``llvm`` if you've already installed
   llvm in third-party and ``none`` otherwise.


.. _readme-chplenv.CHPL_WIDE_POINTERS:

CHPL_WIDE_POINTERS
~~~~~~~~~~~~~~~~~~
   Optionally, the ``CHPL_WIDE_POINTERS`` environment variable can be used to
   specify the wide pointer format for multilocale programs.  Current options
   are:

       ======== =============================================================
       Value    Description
       ======== =============================================================
       struct   store wide pointers in structures which may span more than
                one word
       nodeN    ("N" a number, 2 <= N <= 60) store wide pointers in single
                words, with N bits used to store the node (top level locale)
                number and the rest containing the address on that node
       ======== =============================================================

   ``CHPL_WIDE_POINTERS`` is used to select between two modes of operation.  One is
   universally applicable; the other has restricted applicability but may
   reduce remote communication.

   If unset, ``CHPL_WIDE_POINTERS`` defaults to ``struct``.  This setting works in
   all situations and in particular, it is compatible with all locale models
   including the hierarchical ones.  The ``nodeN`` option does not work with
   hierarchical locale models and is only useful with the LLVM backend, which
   is currently experimental.  However, when used, it allows LLVM to understand
   and optimize remote transfers, potentially reducing the amount of
   communication a program performs.  See :ref:`readme-llvm` for more
   information about ``CHPL_WIDE_POINTERS=nodeN``.

Compiler Command Line Option Defaults
-------------------------------------

Most of the compiler's command line options support setting a default value for
the option via an environment variable.  To see a list of the environment
variables that support each option, run the compiler with the ``--help-env``
flag.  For boolean flags and toggles, setting the environment variable to any
value selects that flag.


.. |trade|  unicode:: U+02122 .. TRADE MARK SIGN
