[ViewVC] Diff of: cvs/App-Staticperl/staticperl.pod

Comparing App-Staticperl/staticperl.pod (file contents):
Revision 1.47 by root, Sat Jul 9 18:26:27 2011 UTC vs.
Revision 1.48 by root, Sun Jul 10 01:37:56 2011 UTC

 Just like C<--add>, except that it treats the file as binary and adds it
 without any postprocessing (perl files might get stripped to reduce their
 size).
-If you specify an alias you should probably add a C<&> prefix to avoid
+If you specify an alias you should probably add a C</> prefix to avoid
-clashing with embedded perl files (whose paths never start with C<&>),
+clashing with embedded perl files (whose paths never start with C</>),
-and/or use a special directory prefix, such as C<&res/name>.
+and/or use a special directory prefix, such as C</res/name>.
 You can later get a copy of these files by calling C<staticperl::find
 "alias">.
 An alternative way to embed binary files is to convert them to perl and
 use C<do> to get the contents - this method is a bit cumbersome, but works
-both inside and outside of a staticperl bundle:
+both inside and outside of a staticperl bundle, without extra ado:
    # a "binary" file, call it "bindata.pl"
    <<'SOME_MARKER'
    binary data NOT containing SOME_MARKER
    SOME_MARKER
    # load the binary
    chomp (my $data = do "bindata.pl");
-=item C<--allow-dlls>
+=item C<--allow-dynamic>
 By default, when F<mkbundle> hits a dynamic perl extension (e.g. a F<.so>
 or F<.dll> file), it will stop with a fatal error.
-This option instead packages the shared object into the bundle, with a
+When this option is enabled, F<mkbundle> packages the shared
-prefix of F<&fs/perl/> (e.g. F<&fs/perl/auto/List/Util/Util.so>). What you
+object into the bundle instead, with a prefix of F<!>
-do with that is up to you, F<staticperl> has no special support for this
+(e.g. F<!auto/List/Util/Util.so>). What you do with that is currently up
-at the moment, apart from working around the lack of availability of
+to you, F<staticperl> has no special support for this at the moment, apart
-F<PerlIO::scalar> while bootstrapping, at a speed cost.
+from working around the lack of availability of F<PerlIO::scalar> while
+bootstrapping, at a speed cost.
-One way to deal with this is to write all files starting with F<&fs/> into
+One way to deal with this is to write all files starting with F<!> into
-some directory and C<unshift>ing the path corresponding to F<&fs/perl/>
+some directory and then C<unshift> that path onto C<@INC>.
-onto C<@INC>.
 #TODO: example
 =back
 =back
 =head1 RUNTIME FUNCTIONALITY
-Binaries created with C<mkbundle>/C<mkperl> contain extra functions, which
+Binaries created with C<mkbundle>/C<mkperl> contain extra functionality,
-are required to access the bundled perl sources, but might be useful for
+mostly related to the extra files bundled in the binary (the virtual
-other purposes.
+filesystem). All of this data is statically compiled into the binary, and
+accessing means copying it from a read-only section of your binary. Data
+pages in this way is usually freed by the operating system, as it isn't
+use more the onace.
+=head2 VIRTUAL FILESYSTEM
+Every bundle has a virtual filesystem. The only information stored in it
+is the path and contents of each file that was bundled.
+=head3 LAYOUT
+Any path starting with an ampersand (F<&>) or exclamation mark (F<!>) are
+reserved by F<staticperl>. They must only be used as described in this
+section.
+=over 4
+=item !
+All files that typically cannot be loaded from memory (such as dynamic
+objects or shared libraries), but have to reside in the filesystem, are
+prefixed with F<!>. Typically these files get written out to some
+(semi-)temporary directory shortly after program startup, or before being
+used.
+=item !boot
+The bootstrap file, if specified during bundling.
+=item !auto/
+Shared objects or dlls corresponding to dynamically-linked perl extensions
+are stored with an F<!auto/> prefix.
+=item !lib/
+External shared libraries are stored in this directory.
+=item any letter
+Any path starting with a letter is a perl library file. For example,
+F<Coro/AIO.pm> corresponds to the file loaded by C<use Coro::AIO>, and
+F<Coro/jit.pl> corresponds to C<require "Coro/jit.pl">.
+Obviously, module names shouldn't start with any other characters than
+letters :)
+=back
+=head3 FUNCTIONS
+=over 4
+=item $file = staticperl::find $path
+Returns the data associated with the given C<$path>
+(e.g. C<Digest/MD5.pm>, C<auto/POSIX/autosplit.ix>).
+Returns C<undef> if the file isn't embedded.
+=item @paths = staticperl::list
+Returns the list of all paths embedded in this binary.
+=back
+=head2 EXTRA FEATURES
 In addition, for the embedded loading of perl files to work, F<staticperl>
 overrides the C<@INC> array.
-=over 4
-=item $file = staticperl::find $path
-Returns the data associated with the given C<$path>
-(e.g. C<Digest/MD5.pm>, C<auto/POSIX/autosplit.ix>), which is basically
-the UNIX path relative to the perl library directory.
-Returns C<undef> if the file isn't embedded.
-=item @paths = staticperl::list
-Returns the list of all paths embedded in this binary.
-=back
 =head1 FULLY STATIC BINARIES - UCLIBC AND BUILDROOT
 To make truly static (Linux-) libraries, you might want to have a look at
 buildroot (L<http://buildroot.uclibc.org/>).

Diff Legend

-–
+Removed lines
-+
+Added lines
-<
+Changed lines
->
+Changed lines

Comparing App-Staticperl/staticperl.pod (file contents): Revision 1.47 by root, Sat Jul 9 18:26:27 2011 UTC vs. Revision 1.48 by root, Sun Jul 10 01:37:56 2011 UTC

Diff Legend

Comparing App-Staticperl/staticperl.pod (file contents):
Revision 1.47 by root, Sat Jul 9 18:26:27 2011 UTC vs.
Revision 1.48 by root, Sun Jul 10 01:37:56 2011 UTC