Permalink
Browse files

C: POD DESCRIPTION for package walker, CAVEAT warnings explained

  • Loading branch information...
1 parent 1049b74 commit 424f9c6b55aff482edd81601f005d5eaed5beffa @rurban committed May 10, 2012
Showing with 68 additions and 4 deletions.
  1. +68 −4 lib/B/C.pm
View
@@ -2572,7 +2572,7 @@ sub B::PVMG::save_magic {
# stored by some PMOP *pm = cLOGOP->op_other (pp_ctl.c) in C.xs
my $pmop = $Regexp{$rx};
if (!$pmop) {
- warn "C.xs Warning: PMOP missing for QR\n";
+ warn "Warning: C.xs PMOP missing for QR\n";
} else {
my ($resym, $relen);
if ($PERL56) {
@@ -6194,11 +6194,25 @@ execution speed of your program but may improve the start-up time.
Depending on the environment in which your program runs this may be
either a help or a hindrance.
+The compiler detects all immediate objects in the main (or optionally other)
+package, and then in a second pass tries to verify if all not by the compiler
+itself loaded packages are used by the program. This is done in a loop until
+no new packages are found. These package detection passes are not fool proof,
+since there are either too many unneeded compiled packages with its
+sub-dependencies (i.e. too big executable size) or some packages are missed,
+e.g. C<eval "require $name;">. Nevertheless are all detected functions, objects
+and methods compiled.
+
+You can tune these steps with the options C<-u> (I<used>) and C<-U>
+(I<unused>). Not statically detected packages will be loaded then at run-time
+at the client environment, with the compile-time @INC path. Note that fully
+self-contained executables should include all at the client needed packages.
+
=head1 OPTIONS
If there are any non-option arguments, they are taken to be
-names of objects to be saved (probably doesn't work properly yet).
-Without extra arguments, it saves the main program.
+names of objects (packages, functions, scalars) to be saved.
+Without extra arguments, it saves the main program, i.e. %main::
=over 4
@@ -6551,6 +6565,56 @@ help make use of this compiler.
perl -MO=C,-v,-DcA,-l2048 bar.pl > /dev/null
+=head1 CAVEAT
+
+With 5.6 it is not possible to use the __DATA__ filehandle, because
+compatible access via PerlIO::scalar was added with 5.8.1
+
+It is generally not possible to restore all of the compiled BEGIN-time state.
+Esp. problematic are non-standard filehandles (i.e. fd>2), process ids,
+environment specific knowledge, because only with the compiler BEGIN blocks
+are not executed in the client environment.
+
+The compiler produces some warnings, which might need source code changes
+or changed compiler options.
+
+=over
+
+=item Warning: Problem with require "$name" - $INC{file.pm}
+
+Dynamic load of $name did not add the expected %INC key.
+
+=item Warning: C.xs PMOP missing for QR
+
+In an initial C.xs runloop all QR regex ops are stored, so that they
+can matched later to PMOPs.
+
+=item Warning: DynaLoader broken with 5.15.2-5.15.3.
+
+[perl #100138] DynaLoader symbols were XS_INTERNAL. Strict linking
+could not resolve it. Usually libperl was patched to overcome this
+for these two versions.
+Setting the environment variable NO_DL_WARN=1 omits this warning.
+
+=item Warning: __DATA__ handle $fullname not stored. Need -O2 or -fsave-data.
+
+Since processing the __DATA__ filehandle involves some overhead, requiring
+PerlIO::scalar with all its dependencies, you must use -O2 or -fsave-data.
+
+=item Warning: Write BEGIN-block $fullname to FileHandle $iotype \&$fd
+
+Critical problem. This must be fixed in the source.
+
+=item Warning: Read BEGIN-block $fullname from FileHandle $iotype \&$fd
+
+Critical problem. This must be fixed in the source.
+
+=item Warning: -o argument ignored with -c
+
+-c does only check, but not accumulate C output lines.
+
+=back
+
=head1 BUGS
Current status: A few known bugs.
@@ -6563,7 +6627,7 @@ Current status: A few known bugs.
&XSLoader::load sometimes missing
reading from __DATA__ handles (15) non-threaded
handling npP magic for shared threaded variables (41-43)
- destruction of variables in END blocks
+ destruction of shared strings in end of scope and END blocks
=head1 AUTHOR

0 comments on commit 424f9c6

Please sign in to comment.