… | |
… | |
124 | |
124 | |
125 | =head1 THE F<STATICPERL> SCRIPT |
125 | =head1 THE F<STATICPERL> SCRIPT |
126 | |
126 | |
127 | This module installs a script called F<staticperl> into your perl |
127 | This module installs a script called F<staticperl> into your perl |
128 | binary directory. The script is fully self-contained, and can be |
128 | binary directory. The script is fully self-contained, and can be |
129 | used without perl (for example, in an uClibc chroot environment). In |
129 | used without perl (for example, in an uClibc/dietlibc/musl chroot |
130 | fact, it can be extracted from the C<App::Staticperl> distribution |
130 | environment). In fact, it can be extracted from the C<App::Staticperl> |
131 | tarball as F<bin/staticperl>, without any installation. The |
131 | distribution tarball as F<bin/staticperl>, without any installation. The |
132 | newest (possibly alpha) version can also be downloaded from |
132 | newest (possibly alpha) version can also be downloaded from |
133 | L<http://staticperl.schmorp.de/staticperl>. |
133 | L<http://staticperl.schmorp.de/staticperl>. |
134 | |
134 | |
135 | F<staticperl> interprets the first argument as a command to execute, |
135 | F<staticperl> interprets the first argument as a command to execute, |
136 | optionally followed by any parameters. |
136 | optionally followed by any parameters. |
… | |
… | |
189 | Wipes the perl installation directory (usually F<~/.staticperl/perl>) and |
189 | Wipes the perl installation directory (usually F<~/.staticperl/perl>) and |
190 | installs the perl distribution, potentially after building it first. |
190 | installs the perl distribution, potentially after building it first. |
191 | |
191 | |
192 | =item F<staticperl perl> [args...] |
192 | =item F<staticperl perl> [args...] |
193 | |
193 | |
194 | Invokes the compiled perl interpreter with the given args. Basically the |
194 | Invokes the compiled perl interpreter with the given |
195 | same as starting perl directly (usually via F<~/.staticperl/bin/perl>), |
195 | arguments. Basically the same as starting perl directly (usually via |
196 | but beats typing the path sometimes. |
196 | F<~/.staticperl/bin/perl>), but beats typing the path sometimes. |
197 | |
197 | |
198 | Example: check that the Gtk2 module is installed and loadable. |
198 | Example: check that the Gtk2 module is installed and loadable. |
199 | |
199 | |
200 | staticperl perl -MGtk2 -e0 |
200 | staticperl perl -MGtk2 -e0 |
201 | |
201 | |
… | |
… | |
546 | my $res = do "myfiles/file3.pl"; |
546 | my $res = do "myfiles/file3.pl"; |
547 | |
547 | |
548 | =item C<--addbin> F<file> | C<--addbin> "F<file> alias" |
548 | =item C<--addbin> F<file> | C<--addbin> "F<file> alias" |
549 | |
549 | |
550 | Just like C<--add>, except that it treats the file as binary and adds it |
550 | Just like C<--add>, except that it treats the file as binary and adds it |
551 | without any postprocessing (perl files might get stripped to reduce their |
551 | without any post-processing (perl files might get stripped to reduce their |
552 | size). |
552 | size). |
553 | |
553 | |
554 | If you specify an alias you should probably add a C</> prefix to avoid |
554 | If you specify an alias you should probably add a C</> prefix to avoid |
555 | clashing with embedded perl files (whose paths never start with C</>), |
555 | clashing with embedded perl files (whose paths never start with C</>), |
556 | and/or use a special directory prefix, such as C</res/name>. |
556 | and/or use a special directory prefix, such as C</res/name>. |
… | |
… | |
583 | bootstrapping, at a speed cost. |
583 | bootstrapping, at a speed cost. |
584 | |
584 | |
585 | One way to deal with this is to write all files starting with F<!> into |
585 | One way to deal with this is to write all files starting with F<!> into |
586 | some directory and then C<unshift> that path onto C<@INC>. |
586 | some directory and then C<unshift> that path onto C<@INC>. |
587 | |
587 | |
588 | #TODO: example |
588 | (TODO for future self: write and insert a suitable example here, if |
|
|
589 | somebody requests it). |
589 | |
590 | |
590 | =back |
591 | =back |
591 | |
592 | |
592 | =item Step 2: filter all files using C<--include> and C<--exclude> options. |
593 | =item Step 2: filter all files using C<--include> and C<--exclude> options. |
593 | |
594 | |
… | |
… | |
709 | =item C<--compress> C<none>|C<lzf> |
710 | =item C<--compress> C<none>|C<lzf> |
710 | |
711 | |
711 | Compress each included library file with C<lzf> (default), or do not |
712 | Compress each included library file with C<lzf> (default), or do not |
712 | compress (C<none>). LZF compression typically halves the size of the |
713 | compress (C<none>). LZF compression typically halves the size of the |
713 | included library data at almost no overhead, but is counterproductive if |
714 | included library data at almost no overhead, but is counterproductive if |
714 | you are using another compression solution such as C<UPX>, so it cna be |
715 | you are using another compression solution such as C<UPX>, so it can be |
715 | disabled. |
716 | disabled. |
716 | |
717 | |
717 | =item C<--perl> |
718 | =item C<--perl> |
718 | |
719 | |
719 | After writing out the bundle files, try to link a new perl interpreter. It |
720 | After writing out the bundle files, try to link a new perl interpreter. It |
… | |
… | |
754 | |
755 | |
755 | =item C<--ignore-env> |
756 | =item C<--ignore-env> |
756 | |
757 | |
757 | Generates extra code to unset some environment variables before |
758 | Generates extra code to unset some environment variables before |
758 | initialising/running perl. Perl supports a lot of environment variables |
759 | initialising/running perl. Perl supports a lot of environment variables |
759 | that might alter execution in ways that might be undesirablre for |
760 | that might alter execution in ways that might be undesirable for |
760 | standalone applications, and this option removes those known to cause |
761 | standalone applications, and this option removes those known to cause |
761 | trouble. |
762 | trouble. |
762 | |
763 | |
763 | Specifically, these are removed: |
764 | Specifically, these are removed: |
764 | |
765 | |
… | |
… | |
785 | The default is to link the new binary dynamically (that means all perl |
786 | The default is to link the new binary dynamically (that means all perl |
786 | modules are linked statically, but all external libraries are still |
787 | modules are linked statically, but all external libraries are still |
787 | referenced dynamically). |
788 | referenced dynamically). |
788 | |
789 | |
789 | Keep in mind that Solaris doesn't support static linking at all, and |
790 | Keep in mind that Solaris doesn't support static linking at all, and |
790 | systems based on GNU libc don't really support it in a very usable |
791 | systems based on GNU libc don't really support it in a very usable fashion |
791 | fashion either. Try uClibc if you want to create fully statically linked |
792 | either. Try dietlibc or musl if you want to create fully statically linked |
792 | executables, or try the C<--staticlib> option to link only some libraries |
793 | executables, or try the C<--staticlib> option to link only some libraries |
793 | statically. |
794 | statically. |
794 | |
795 | |
795 | =item C<--staticlib> libname |
796 | =item C<--staticlib> libname |
796 | |
797 | |
… | |
… | |
876 | In them you can override shell variables, or define shell functions |
877 | In them you can override shell variables, or define shell functions |
877 | ("hooks") to be called at specific phases during installation. For |
878 | ("hooks") to be called at specific phases during installation. For |
878 | example, you could define a C<postinstall> hook to install additional |
879 | example, you could define a C<postinstall> hook to install additional |
879 | modules from CPAN each time you start from scratch. |
880 | modules from CPAN each time you start from scratch. |
880 | |
881 | |
881 | If the env variable C<$STATICPERLRC> is set, then F<staticperl> will try |
882 | If the environment variable C<$STATICPERLRC> is set, then F<staticperl> |
882 | to source the file named with it only. Otherwise, it tries the following |
883 | will try to source the file named with it only. Otherwise, it tries the |
883 | shell files in order: |
884 | following shell files in order: |
884 | |
885 | |
885 | /etc/staticperlrc |
886 | /etc/staticperlrc |
886 | ~/.staticperlrc |
887 | ~/.staticperlrc |
887 | $STATICPERL/rc |
888 | $STATICPERL/rc |
888 | |
889 | |
… | |
… | |
963 | =item C<PERL_CONFIGURE> |
964 | =item C<PERL_CONFIGURE> |
964 | |
965 | |
965 | Additional Configure options - these are simply passed to the perl |
966 | Additional Configure options - these are simply passed to the perl |
966 | Configure script. For example, if you wanted to enable dynamic loading, |
967 | Configure script. For example, if you wanted to enable dynamic loading, |
967 | you could pass C<-Dusedl>. To enable ithreads (Why would you want that |
968 | you could pass C<-Dusedl>. To enable ithreads (Why would you want that |
968 | insanity? Don't! Use L<forks> instead!) you would pass C<-Duseithreads> |
969 | insanity? Don't! Use L<Coro> or L<forks> instead!) you would pass |
969 | and so on. |
970 | C<-Duseithreads> and so on. |
970 | |
971 | |
971 | More commonly, you would either activate 64 bit integer support |
972 | More commonly, you would either activate 64 bit integer support |
972 | (C<-Duse64bitint>), or disable large files support (-Uuselargefiles), to |
973 | (C<-Duse64bitint>), or disable large files support (C<-Uuselargefiles>), |
973 | reduce filesize further. |
974 | to reduce file size further. |
974 | |
975 | |
975 | =item C<PERL_CC>, C<PERL_CCFLAGS>, C<PERL_OPTIMIZE>, C<PERL_LDFLAGS>, C<PERL_LIBS> |
976 | =item C<PERL_CC>, C<PERL_CCFLAGS>, C<PERL_OPTIMIZE>, C<PERL_LDFLAGS>, C<PERL_LIBS> |
976 | |
977 | |
977 | These flags are passed to perl's F<Configure> script, and are generally |
978 | These flags are passed to perl's F<Configure> script, and are generally |
978 | optimised for small size (at the cost of performance). Since they also |
979 | optimised for small size (at the cost of performance). Since they also |
… | |
… | |
982 | F<~/.staticperlrc> to override them. |
983 | F<~/.staticperlrc> to override them. |
983 | |
984 | |
984 | Most of the variables override (or modify) the corresponding F<Configure> |
985 | Most of the variables override (or modify) the corresponding F<Configure> |
985 | variable, except C<PERL_CCFLAGS>, which gets appended. |
986 | variable, except C<PERL_CCFLAGS>, which gets appended. |
986 | |
987 | |
987 | The default for C<PERL_OPTIMIZE> is C<-Os> (assuming gcc), and for |
988 | The default for C<PERL_OPTIMIZE> is C<-Os> (assuming gcc or compatible |
988 | C<PERL_LIBS> is C<-lm -lcrypt>, which should be good for most (but not |
989 | compilers), and for C<PERL_LIBS> is C<-lm -lcrypt>, which should be good |
989 | all) systems. |
990 | for most (but not all) systems. |
990 | |
991 | |
991 | For other compilers or more customised optimisation settings, you need to |
992 | For other compilers or more customised optimisation settings, you need to |
992 | adjust these, e.g. in your F<~/.staticperlrc>. |
993 | adjust these, e.g. in your F<~/.staticperlrc>. |
993 | |
994 | |
994 | With gcc on x86 and amd64, you can get more space-savings by using: |
995 | With gcc on x86 and amd64, you can often get more space-savings by using: |
995 | |
996 | |
996 | -Os -ffunction-sections -fdata-sections -finline-limit=8 -mpush-args |
997 | -Os -ffunction-sections -fdata-sections -finline-limit=8 -mpush-args |
997 | -mno-inline-stringops-dynamically -mno-align-stringops |
998 | -mno-inline-stringops-dynamically -mno-align-stringops |
998 | |
999 | |
999 | And on x86 and pentium3 and newer (basically everything you might ever |
1000 | And on x86 and pentium3 and newer (basically everything you might ever |
1000 | want to run on), adding these is even better for space-savings (use |
1001 | want to run on), adding these is even better for space-savings (use |
1001 | -mtune=core2 or something newer for much faster code, too): |
1002 | C<-mtune=core2> or something newer for much faster code, too): |
1002 | |
1003 | |
1003 | -fomit-frame-pointer -march=pentium3 -mtune=i386 |
1004 | -fomit-frame-pointer -march=pentium3 -mtune=i386 |
1004 | |
1005 | |
1005 | =back |
1006 | =back |
1006 | |
1007 | |
… | |
… | |
1143 | staticperl_init (0); |
1144 | staticperl_init (0); |
1144 | newXSproto ("myapp::xsfunction", xsfunction, __FILE__, "$$;$"); |
1145 | newXSproto ("myapp::xsfunction", xsfunction, __FILE__, "$$;$"); |
1145 | eval_pv ("require myapp::main", 1); // executes "myapp/main.pm" |
1146 | eval_pv ("require myapp::main", 1); // executes "myapp/main.pm" |
1146 | } |
1147 | } |
1147 | |
1148 | |
1148 | When your bootcode already wants to access some XS functions at |
1149 | When your boot code already wants to access some XS functions at compile |
1149 | compiletime, then you need to supply an C<xs_init> function pointer that |
1150 | time, then you need to supply an C<xs_init> function pointer that is |
1150 | is called as soon as perl is initialised enough to define XS functions, |
1151 | called as soon as perl is initialised enough to define XS functions, but |
1151 | but before the preamble code is executed: |
1152 | before the preamble code is executed: |
1152 | |
1153 | |
1153 | static void |
1154 | static void |
1154 | xs_init (pTHX) |
1155 | xs_init (pTHX) |
1155 | { |
1156 | { |
1156 | newXSproto ("myapp::xsfunction", xsfunction, __FILE__, "$$;$"); |
1157 | newXSproto ("myapp::xsfunction", xsfunction, __FILE__, "$$;$"); |
… | |
… | |
1241 | |
1242 | |
1242 | =item any letter |
1243 | =item any letter |
1243 | |
1244 | |
1244 | Any path starting with a letter is a perl library file. For example, |
1245 | Any path starting with a letter is a perl library file. For example, |
1245 | F<Coro/AIO.pm> corresponds to the file loaded by C<use Coro::AIO>, and |
1246 | F<Coro/AIO.pm> corresponds to the file loaded by C<use Coro::AIO>, and |
1246 | F<Coro/jit.pl> corresponds to C<require "Coro/jit.pl">. |
1247 | F<Coro/jit.pl> corresponds to C<require "Coro/jit.pl">. |
1247 | |
1248 | |
1248 | Obviously, module names shouldn't start with any other characters than |
1249 | Obviously, module names shouldn't start with any other characters than |
1249 | letters :) |
1250 | letters :) |
1250 | |
1251 | |
1251 | =back |
1252 | =back |
… | |
… | |
1296 | |
1297 | |
1297 | =over 4 |
1298 | =over 4 |
1298 | |
1299 | |
1299 | =item utf8 |
1300 | =item utf8 |
1300 | |
1301 | |
1301 | Some functionality in the utf8 module, such as swash handling (used |
1302 | Some functionality in the C<utf8> module, such as swash handling |
1302 | for unicode character ranges in regexes) is implemented in the |
1303 | (used for unicode character ranges in regexes) is implemented in the |
1303 | C<"utf8_heavy.pl"> library: |
1304 | C<utf8_heavy.pl> library: |
1304 | |
1305 | |
1305 | -Mutf8_heavy.pl |
1306 | -Mutf8_heavy.pl |
1306 | |
1307 | |
1307 | Many Unicode properties in turn are defined in separate modules, |
1308 | Many Unicode properties in turn are defined in separate modules, |
1308 | such as C<"unicore/Heavy.pl"> and more specific data tables such as |
1309 | such as C<unicore/Heavy.pl> and more specific data tables such as |
1309 | C<"unicore/To/Digit.pl"> or C<"unicore/lib/Perl/Word.pl">. These tables |
1310 | C<unicore/To/Digit.pl> or C<unicore/lib/Perl/Word.pl>. These tables |
1310 | are big (7MB uncompressed, although F<staticperl> contains special |
1311 | are big (7MB uncompressed, although F<staticperl> contains special |
1311 | handling for those files), so including them only on demand in your |
1312 | handling for those files), so including them only on demand in your |
1312 | application might pay off. |
1313 | application might pay off. |
1313 | |
1314 | |
1314 | To simply include the whole unicode database, use: |
1315 | To simply include the whole unicode database, use: |
… | |
… | |
1359 | |
1360 | |
1360 | =item Net::SSLeay |
1361 | =item Net::SSLeay |
1361 | |
1362 | |
1362 | This module hasn't been significantly updated since OpenSSL is called |
1363 | This module hasn't been significantly updated since OpenSSL is called |
1363 | OpenSSL, and fails to properly link against dependent libraries, most |
1364 | OpenSSL, and fails to properly link against dependent libraries, most |
1364 | commonly, it forgets to specify -ldl when linking. |
1365 | commonly, it forgets to specify C<-ldl> when linking. |
1365 | |
1366 | |
1366 | On GNU/Linux systems this usually goes undetected, as perl usually links |
1367 | On GNU/Linux systems this usually goes undetected, as perl usually links |
1367 | against -ldl itself and OpenSSL just happens to pick it up that way, by |
1368 | against C<-ldl> itself and OpenSSL just happens to pick it up that way, by |
1368 | chance. |
1369 | chance. |
1369 | |
1370 | |
1370 | For static builds, you either have to configure -ldl manually, or you |
1371 | For static builds, you either have to configure C<-ldl> manually, or you |
1371 | cna use the following snippet in your C<postinstall> hook which patches |
1372 | can use the following snippet in your C<postinstall> hook which patches |
1372 | Net::SSLeay after installation, which happens to work most of the time: |
1373 | Net::SSLeay after installation, which happens to work most of the time: |
1373 | |
1374 | |
1374 | postinstall() { |
1375 | postinstall() { |
1375 | # first install it |
1376 | # first install it |
1376 | instcpan Net::SSLeay |
1377 | instcpan Net::SSLeay |