… | |
… | |
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 | |
… | |
… | |
704 | Last not least, if you need accurate line numbers in error messages, |
705 | Last not least, if you need accurate line numbers in error messages, |
705 | or in the unlikely case where C<pod> is too slow, or some module gets |
706 | or in the unlikely case where C<pod> is too slow, or some module gets |
706 | mistreated, you can specify C<none> to not mangle included perl sources in |
707 | mistreated, you can specify C<none> to not mangle included perl sources in |
707 | any way. |
708 | any way. |
708 | |
709 | |
|
|
710 | =item C<--compress> C<none>|C<lzf> |
|
|
711 | |
|
|
712 | Compress each included library file with C<lzf> (default), or do not |
|
|
713 | compress (C<none>). LZF compression typically halves the size of the |
|
|
714 | included library data at almost no overhead, but is counterproductive if |
|
|
715 | you are using another compression solution such as C<UPX>, so it can be |
|
|
716 | disabled. |
|
|
717 | |
709 | =item C<--perl> |
718 | =item C<--perl> |
710 | |
719 | |
711 | 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 |
712 | will be called F<perl> and will be left in the current working |
721 | will be called F<perl> and will be left in the current working |
713 | directory. The bundle files will be removed. |
722 | directory. The bundle files will be removed. |
… | |
… | |
746 | |
755 | |
747 | =item C<--ignore-env> |
756 | =item C<--ignore-env> |
748 | |
757 | |
749 | Generates extra code to unset some environment variables before |
758 | Generates extra code to unset some environment variables before |
750 | initialising/running perl. Perl supports a lot of environment variables |
759 | initialising/running perl. Perl supports a lot of environment variables |
751 | that might alter execution in ways that might be undesirablre for |
760 | that might alter execution in ways that might be undesirable for |
752 | standalone applications, and this option removes those known to cause |
761 | standalone applications, and this option removes those known to cause |
753 | trouble. |
762 | trouble. |
754 | |
763 | |
755 | Specifically, these are removed: |
764 | Specifically, these are removed: |
756 | |
765 | |
… | |
… | |
777 | 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 |
778 | modules are linked statically, but all external libraries are still |
787 | modules are linked statically, but all external libraries are still |
779 | referenced dynamically). |
788 | referenced dynamically). |
780 | |
789 | |
781 | 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 |
782 | 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 |
783 | 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 |
784 | 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 |
785 | statically. |
794 | statically. |
786 | |
795 | |
787 | =item C<--staticlib> libname |
796 | =item C<--staticlib> libname |
788 | |
797 | |
… | |
… | |
868 | In them you can override shell variables, or define shell functions |
877 | In them you can override shell variables, or define shell functions |
869 | ("hooks") to be called at specific phases during installation. For |
878 | ("hooks") to be called at specific phases during installation. For |
870 | example, you could define a C<postinstall> hook to install additional |
879 | example, you could define a C<postinstall> hook to install additional |
871 | modules from CPAN each time you start from scratch. |
880 | modules from CPAN each time you start from scratch. |
872 | |
881 | |
873 | 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> |
874 | 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 |
875 | shell files in order: |
884 | following shell files in order: |
876 | |
885 | |
877 | /etc/staticperlrc |
886 | /etc/staticperlrc |
878 | ~/.staticperlrc |
887 | ~/.staticperlrc |
879 | $STATICPERL/rc |
888 | $STATICPERL/rc |
880 | |
889 | |
… | |
… | |
955 | =item C<PERL_CONFIGURE> |
964 | =item C<PERL_CONFIGURE> |
956 | |
965 | |
957 | Additional Configure options - these are simply passed to the perl |
966 | Additional Configure options - these are simply passed to the perl |
958 | Configure script. For example, if you wanted to enable dynamic loading, |
967 | Configure script. For example, if you wanted to enable dynamic loading, |
959 | 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 |
960 | 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 |
961 | and so on. |
970 | C<-Duseithreads> and so on. |
962 | |
971 | |
963 | More commonly, you would either activate 64 bit integer support |
972 | More commonly, you would either activate 64 bit integer support |
964 | (C<-Duse64bitint>), or disable large files support (-Uuselargefiles), to |
973 | (C<-Duse64bitint>), or disable large files support (C<-Uuselargefiles>), |
965 | reduce filesize further. |
974 | to reduce file size further. |
966 | |
975 | |
967 | =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> |
968 | |
977 | |
969 | 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 |
970 | 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 |
… | |
… | |
974 | F<~/.staticperlrc> to override them. |
983 | F<~/.staticperlrc> to override them. |
975 | |
984 | |
976 | Most of the variables override (or modify) the corresponding F<Configure> |
985 | Most of the variables override (or modify) the corresponding F<Configure> |
977 | variable, except C<PERL_CCFLAGS>, which gets appended. |
986 | variable, except C<PERL_CCFLAGS>, which gets appended. |
978 | |
987 | |
979 | 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 |
980 | 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 |
981 | all) systems. |
990 | for most (but not all) systems. |
982 | |
991 | |
983 | For other compilers or more customised optimisation settings, you need to |
992 | For other compilers or more customised optimisation settings, you need to |
984 | adjust these, e.g. in your F<~/.staticperlrc>. |
993 | adjust these, e.g. in your F<~/.staticperlrc>. |
985 | |
994 | |
986 | 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: |
987 | |
996 | |
988 | -Os -ffunction-sections -fdata-sections -finline-limit=8 -mpush-args |
997 | -Os -ffunction-sections -fdata-sections -finline-limit=8 -mpush-args |
989 | -mno-inline-stringops-dynamically -mno-align-stringops |
998 | -mno-inline-stringops-dynamically -mno-align-stringops |
990 | |
999 | |
991 | 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 |
992 | 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 |
993 | -mtune=core2 or something newer for much faster code, too): |
1002 | C<-mtune=core2> or something newer for much faster code, too): |
994 | |
1003 | |
995 | -fomit-frame-pointer -march=pentium3 -mtune=i386 |
1004 | -fomit-frame-pointer -march=pentium3 -mtune=i386 |
996 | |
1005 | |
997 | =back |
1006 | =back |
998 | |
1007 | |
… | |
… | |
1065 | Called after building, but before installing perl. Current working |
1074 | Called after building, but before installing perl. Current working |
1066 | directory is the perl source directory. |
1075 | directory is the perl source directory. |
1067 | |
1076 | |
1068 | I have no clue what this could be used for - tell me. |
1077 | I have no clue what this could be used for - tell me. |
1069 | |
1078 | |
|
|
1079 | =item postcpanconfig |
|
|
1080 | |
|
|
1081 | Called just after CPAN has been configured, but before it has been used to |
|
|
1082 | install anything. You can further change the configuration like this: |
|
|
1083 | |
|
|
1084 | "$PERL_PREFIX"/bin/perl -MCPAN::MyConfig -MCPAN -e ' |
|
|
1085 | CPAN::Shell->o (conf => urllist => push => "'"$CPAN"'"); |
|
|
1086 | ' || fatal "error while initialising CPAN in postcpanconfig" |
|
|
1087 | |
1070 | =item postinstall |
1088 | =item postinstall |
1071 | |
1089 | |
1072 | Called after perl and any extra modules have been installed in C<$PREFIX>, |
1090 | Called after perl and any extra modules have been installed in C<$PREFIX>, |
1073 | but before setting the "installation O.K." flag. |
1091 | but before setting the "installation O.K." flag. |
1074 | |
1092 | |
… | |
… | |
1126 | staticperl_init (0); |
1144 | staticperl_init (0); |
1127 | newXSproto ("myapp::xsfunction", xsfunction, __FILE__, "$$;$"); |
1145 | newXSproto ("myapp::xsfunction", xsfunction, __FILE__, "$$;$"); |
1128 | eval_pv ("require myapp::main", 1); // executes "myapp/main.pm" |
1146 | eval_pv ("require myapp::main", 1); // executes "myapp/main.pm" |
1129 | } |
1147 | } |
1130 | |
1148 | |
1131 | 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 |
1132 | 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 |
1133 | 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 |
1134 | but before the preamble code is executed: |
1152 | before the preamble code is executed: |
1135 | |
1153 | |
1136 | static void |
1154 | static void |
1137 | xs_init (pTHX) |
1155 | xs_init (pTHX) |
1138 | { |
1156 | { |
1139 | newXSproto ("myapp::xsfunction", xsfunction, __FILE__, "$$;$"); |
1157 | newXSproto ("myapp::xsfunction", xsfunction, __FILE__, "$$;$"); |
… | |
… | |
1224 | |
1242 | |
1225 | =item any letter |
1243 | =item any letter |
1226 | |
1244 | |
1227 | 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, |
1228 | 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 |
1229 | F<Coro/jit.pl> corresponds to C<require "Coro/jit.pl">. |
1247 | F<Coro/jit.pl> corresponds to C<require "Coro/jit.pl">. |
1230 | |
1248 | |
1231 | Obviously, module names shouldn't start with any other characters than |
1249 | Obviously, module names shouldn't start with any other characters than |
1232 | letters :) |
1250 | letters :) |
1233 | |
1251 | |
1234 | =back |
1252 | =back |
… | |
… | |
1279 | |
1297 | |
1280 | =over 4 |
1298 | =over 4 |
1281 | |
1299 | |
1282 | =item utf8 |
1300 | =item utf8 |
1283 | |
1301 | |
1284 | Some functionality in the utf8 module, such as swash handling (used |
1302 | Some functionality in the C<utf8> module, such as swash handling |
1285 | for unicode character ranges in regexes) is implemented in the |
1303 | (used for unicode character ranges in regexes) is implemented in the |
1286 | C<"utf8_heavy.pl"> library: |
1304 | C<utf8_heavy.pl> library: |
1287 | |
1305 | |
1288 | -Mutf8_heavy.pl |
1306 | -Mutf8_heavy.pl |
1289 | |
1307 | |
1290 | Many Unicode properties in turn are defined in separate modules, |
1308 | Many Unicode properties in turn are defined in separate modules, |
1291 | 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 |
1292 | 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 |
1293 | are big (7MB uncompressed, although F<staticperl> contains special |
1311 | are big (7MB uncompressed, although F<staticperl> contains special |
1294 | 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 |
1295 | application might pay off. |
1313 | application might pay off. |
1296 | |
1314 | |
1297 | To simply include the whole unicode database, use: |
1315 | To simply include the whole unicode database, use: |
… | |
… | |
1342 | |
1360 | |
1343 | =item Net::SSLeay |
1361 | =item Net::SSLeay |
1344 | |
1362 | |
1345 | This module hasn't been significantly updated since OpenSSL is called |
1363 | This module hasn't been significantly updated since OpenSSL is called |
1346 | OpenSSL, and fails to properly link against dependent libraries, most |
1364 | OpenSSL, and fails to properly link against dependent libraries, most |
1347 | commonly, it forgets to specify -ldl when linking. |
1365 | commonly, it forgets to specify C<-ldl> when linking. |
1348 | |
1366 | |
1349 | 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 |
1350 | 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 |
1351 | chance. |
1369 | chance. |
1352 | |
1370 | |
1353 | 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 |
1354 | 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 |
1355 | 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: |
1356 | |
1374 | |
1357 | postinstall() { |
1375 | postinstall() { |
1358 | # first install it |
1376 | # first install it |
1359 | instcpan Net::SSLeay |
1377 | instcpan Net::SSLeay |