Document the reason for the early return in Perl_newPROG() for OP_STUB.

diff --git a/op.c b/op.c
index 9ad4499..cdfd7e4 100644 (file)
--- a/op.c
+++ b/op.c
@@ -2981,6 +2981,21 @@ Perl_newPROG(pTHX_ OP *o)
     }
     else {
        if (o->op_type == OP_STUB) {
+            /* This block is entered if nothing is compiled for the main
+               program. This will be the case for an genuinely empty main
+               program, or one which only has BEGIN blocks etc, so already
+               run and freed.
+
+               Historically (5.000) the guard above was !o. However, commit
+               f8a08f7b8bd67b28 (Jun 2001), integrated to blead as
+               c71fccf11fde0068, changed perly.y so that newPROG() is now
+               called with the output of block_end(), which returns a new
+               OP_STUB for the case of an empty optree. ByteLoader (and
+               maybe other things) also take this path, because they set up
+               PL_main_start and PL_main_root directly, without generating an
+               optree.
+            */
+
            PL_comppad_name = 0;
            PL_compcv = 0;
            S_op_destroy(aTHX_ o);