.. _best-practices-chpl-developer:

=======================================
The CHPL_DEVELOPER environment variable
=======================================

It is strongly recommended that all Chapel development work be done
with ``CHPL_DEVELOPER`` set by default (to any non-empty value,
e.g. ``true``).  In particular, all code that is committed should be
able to be built with ``CHPL_DEVELOPER`` is set; otherwise, that code is
considered to break the build.

Setting ``CHPL_DEVELOPER`` has a number of impacts on how things behave,
most of which are set up to serve the typical developer as best
possible.  In particular:

1) When building the compiler and runtime, it causes:

   (a) debugging to be turned on

   (b) computation of dependences to be turned on

   (c) optimizations to be turned off

   (d) a number of warnings to be turned on with the goal of making
       our code as portable and bulletproof as possible

2) When doing ``make clean`` on the compiler, it causes intermediate
   files generated by compiling the ``chapel.y`` and ``chapel.lex`` files to
   be deleted.  We don't delete these for end-users in case they don't
   have **flex/bison** installed.

3) Performs sanity checks while building the compiler like checking to
   see whether we've accidentally ``#included`` any old-style C headers
   rather than their snazzy new C++ equivalents.  (That may currently
   be the only one; others have existed in the past).

4) Builds an emacs TAGS and BROWSE file for the compiler and a TAGS
   file for the runtime.

5) Turns on ``--devel`` by default when invoking the ``chpl`` compiler.  This
   in turn has the following effects:

   (a) Prints out ``hidden`` developer flags when invoking ``chpl --help``
       (these flags are equally available to developers and
       non-developers).

   (b) Causes internal errors to not be obfuscated as they are for an
       end-user.

   (c) Causes error messages printed by the compiler to have the
       compiler filename: `line#` to be postfixed to the error message
       itself.

   (d) Permits filename: `line#` information that is printed for
       execution-time errors in the user code to refer to internal
       modules rather than trying to hide this from the end-user by
       always pointing to the most recent call in their code.

   (e) Causes TAGS files to be generated when compiling with the
       ``--savec`` flag to index the generated code in addition to the runtime
       sources.

   (f) Turns on ``--cc-warnings`` by default.  This generates warnings in
       the generated C code (with the intention that we get rid of
       them).

   (g) Turns on ``--no-cpp-lines`` by default.  This squashes the
       generation of C preprocessor #line directives in the generated
       code (which are used for end-users to fool tools into reporting
       things in terms of Chapel source line numbers).

   (h) Causes internal modules to be printed out when compiling with
       the ``--print-module-files`` flag.

   (i) Prints a greater amount of instantiation information when
       function resolution is printing candidate functions in the case
       of an error (?).

   (j) Causes the ``--report-optimized-on`` flag to describe optimizations
       in internal and standard modules in addition to user modules.

   (k) Prints out a 4-point version number even if the revision number
       is **0** (indicating an official release)


Notes:

* ``--devel`` can always be invoked manually on the compiler instead of
  setting the environment variable; similarly, ``--no-devel`` can be used
  to override the default implied by the presence of the environment
  variable.

* the ``start_test`` script will always unset ``CHPL_DEVELOPER`` to ensure
  that the testing system is running from an end-user perspective and
  not from a developer perspective.

* the ``nightly`` script used to run cron jobs does not set ``CHPL_DEVELOPER``. Instead, it sets ``WARNINGS=1``, ``DEBUG=0``, and ``OPTIMIZE=1``
  when calling make.