example/simple-assertions: add an explicit allocation

LFortran generates a segfault upon first assignemnt to the allocatable array
without a preceding allocation.

Also, add some comments to clarify the math error in this example code
is deliberate, and update the documentation to match the actual program.

Author: bonachea

example/README.md

@@ -23,7 +23,7 @@ fpm run --example invoke-via-macro --flag "-DASSERTIONS"
 Simple examples
 ---------------
 
-The [simple_assertions.f90] example demonstrates a precondition and a
+The [simple-assertions.f90] example demonstrates a precondition and a
 postcondition, each with an assertion that checks the truth of a logical
 expression based on scalar, real values.
 
@@ -32,20 +32,20 @@ Running the examples
 
 ### Single-image execution
 ```
-fpm run --example simple_assertions
+fpm run --example simple-assertions --flag "-DASSERTIONS"
 ```
 where `fpm run` automatically invokes `fpm build` if necessary, .e.g., if the package's source code
 has changed since the most recent build.  If `assert` is working correctly, the `fpm run` above
 will error-terminate with the character stop code similar to the following
 ```
-Assertion failure on image 1: reciprocal: abs(error) < tolerance
+Assertion failure on image 1: All residuals within tolerance
 ```
 
 ### Multi-image execution with `gfortran` and OpenCoarrays
 ```
 git clone [email protected]/sourceryinstitute/assert
 cd assert
-fpm run --compiler caf --runner "cafrun -n 2" --example simple_assertions
+fpm run --compiler caf --runner "cafrun -n 2" --example simple-assertions --flag "-DASSERTIONS"
 ```
 Replace either instance of `2` above with the desired number of images to run for parallel execution.
 If `assert` is working correctly, both of the latter `fpm run` commands will error-terminate with one
@@ -55,7 +55,7 @@ or more images providing stop codes analogous to those quoted in the [Single-ima
 [OpenCoarrays]: https://github.com/sourceryinstitute/opencoarrays
 [Enforcing programming contracts]: #enforcing-programming-contracts
 [Single-image execution]: #single-image-execution
-[simple_assertions.f90]: ./simple_assertions.f90
+[simple-assertions.f90]: ./simple-assertions.f90
 [invoke-via-macro.F90]: ./invoke-via-macro.F90
 [UML]: https://en.wikipedia.org/wiki/Unified_Modeling_Language
 [OCL]: https://en.wikipedia.org/wiki/Object_Constraint_Language

example/simple-assertions.f90

@@ -18,9 +18,12 @@ pure function roots(a,b,c) result(zeros)
 
     associate(discriminant => b**2 - 4*a*c)
       call assert(assertion = discriminant >= 0., description = "discriminant >= 0") ! precondition
+      allocate(zeros(2))
+      ! there's a deliberate math bug in the following line, to help demonstrate assertion failure
       zeros = -b + [sqrt(discriminant), -sqrt(discriminant)]
     end associate
 
+    ! This assertion will fail (due to the defect above) when ASSERTIONS are enabled:
     call assert(all(abs(a*zeros**2 + b*zeros + c) < tolerance), "All residuals within tolerance.") ! postcondition
   end function