cicecore: add 'DEBUG_BLOCKS' CPP macro to debug block decomposition

As mentioned in the documentation, subroutines 'ice_blocks::create_blocks' and
'ice_distribution::create_local_block_ids' can print block information to
standard out if the local variable `dbug` is modified to ".true.".

For convenience, add a 'DEBUG_BLOCKS' CPP macro that can be used to easily
set both variables to true, and add a 'cice.setup' option to activate this
new macro.

Adjust the documentation accordingly.

cicecore/cicedynB/infrastructure/ice_blocks.F90

@@ -311,8 +311,10 @@ subroutine create_blocks(nx_global, ny_global, ew_boundary_type, &
       end do
    end do
 
-!   dbug = .true.
    dbug = .false.
+#ifdef DEBUG_BLOCKS
+   dbug = .true.
+#endif
    if (dbug) then
       if (my_task == master_task) then
       write(nu_diag,*) 'block i,j locations'

cicecore/shared/ice_distribution.F90

@@ -178,8 +178,10 @@ subroutine create_local_block_ids(block_ids, distribution)
 !
 !-----------------------------------------------------------------------
 
-!   dbug = .true.
    dbug = .false.
+#ifdef DEBUG_BLOCKS
+   dbug = .true.
+#endif
    if (bcount > 0) then
       do n=1,size(distribution%blockLocation)
          if (distribution%blockLocation(n) == my_task+1) then

configuration/scripts/options/set_env.debugblocks

@@ -0,0 +1 @@
+setenv ICE_CPPDEFS -DDEBUG_BLOCKS

doc/source/user_guide/ug_implementation.rst

@@ -167,14 +167,17 @@ set to -1, the code will compute a tentative ``max_blocks`` on the fly.
 
 A loop at the end of routine *create\_blocks* in module
 **ice\_blocks.F90** will print the locations for all of the blocks on
-the global grid if dbug is set to be true. Likewise, a similar loop at
+the global grid if the local variable ``dbug`` is set to be true. Likewise, a similar loop at
 the end of routine *create\_local\_block\_ids* in module
 **ice\_distribution.F90** will print the processor and local block
 number for each block. With this information, the grid decomposition
-into processors and blocks can be ascertained. The dbug flag must be
-manually set in the code in each case (independently of the dbug flag in
+into processors and blocks can be ascertained. This ``dbug`` variable must be
+manually set in the code in each case (independently of the ``dbug`` flag in
 **ice\_in**), as there may be hundreds or thousands of blocks to print
-and this information should be needed only rarely. This information is
+and this information should be needed only rarely. The local ``dbug`` variable
+can be set to true in both subroutines by
+compiling with the ``DEBUG_BLOCKS`` CPP macro, which can be done easily by using the
+``debugblocks`` option with **cice.setup**. This information is
 much easier to look at using a debugger such as Totalview.  There is also
 an output field that can be activated in `icefields\_nml`, ``f_blkmask``, 
 that prints out the variable ``blkmask`` to the history file and