260206.163115.CET [skip ci] add comments in examples/README.txt about the compiler flags to force the automatic arrays on the heap; this is needed for big problems to avoid stack overflow

Author: zaikunzhang

fortran/examples/README.txt

@@ -3,6 +3,29 @@ implementation of Powell's derivative-free optimization solvers.
 
 N.B.:
 
+0. In real applications, if the dimension of the problem is big (e.g., more than 100), then
+compilers should be instructed to compile PRIMA with the automatic arrays allocated on the heap.
+Otherwise, those arrays may be allocated on the stack, which may lead to stack overflow. Since
+PRIMA is designed to solve problems with expensive function evaluations, we do not worry about
+the performance of heap arrays.
+
+The compiler flags for heap arrays are as follows:
+- AMD AOCC Flang: -fno-stack-arrays
+- AMD AOMP Flang: -fno-stack-arrays -mmlir -fdynamic-heap-array
+- Arm Fortran Compiler: -fno-stack-arrays -mmlir -fdynamic-heap-array
+- LLVM Flang: -fno-stack-arrays -mmlir -fdynamic-heap-array
+- GNU gfortran: -fno-stack-arrays
+- Intel ifx: -heap-arrays
+- Intel ifort: -heap-arrays
+- NAG Fortran Compiler: NO (unknown)
+- NVIDIA nvfortran: -Mnostack_arrays
+
+If ever a segmentation fault occurs, check whether the above flags are used in the compilation.
+
+N.B.: For LLVM Flang and relatives, `-mmlir -fdynamic-heap-array` is needed as of LLVM 21.1.8. See
+https://github.com/llvm/llvm-project/issues/88344
+https://github.com/zequipe/sigsegv_armflang
+
 1. See the Makefiles for how to compile the examples.
 
 2. The first example in every folder, example_1, uses the same objective function:

fortran/tests/makefiles/Makefile.common

@@ -343,6 +343,8 @@ AFLANG := $(shell find -L /opt/AMD -type f -name flang -exec test -x {} \; -prin
 AFLANG := $(AFLANG) -pedantic-errors -Werror
 ifeq ($(TESTDIM),small)
 	AFLANG := $(AFLANG) -Mstack_arrays
+else
+	AFLANG := $(AFLANG) -fno-stack-arrays  # -Mnostack_arrays is not recognized by AOCC 5.1
 endif
 # Strangely, with `-Mchkptr`, the compiler may not print the error message of `-Mbounds` anymore.
 DFORT := $(AFLANG) -std=f$(FSTD) -pedantic -Weverything -Wall -Wextra -Minform=warn -Mstandard -Mbounds -Mrecursive #-Kieee #-Mchkptr
@@ -646,7 +648,7 @@ vtest_i2_r16_d1_tst_c vtest_i4_r16_d1_tst_c vtest_i8_r16_d1_tst_c vtest_i2_r16_d
 	FCF := $(VFORT) -Ktrap=divz,ovf,inv $(VFF)
 
 
-# ARM Flang
+# Arm Flang
 RFORT := $(shell find -L /opt/arm -type f -name armflang -exec test -x {} \; -print 2>/dev/null | sort | tail -n 1)
 ifeq ($(TESTDIM),small)
 	RFORT := $(RFORT) -fstack-arrays