.. _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. Running it 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/`` or ``~/``. 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) typically refers to ``/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) ======== ================================================================