diff options
Diffstat (limited to 'gnu/usr.bin/perl/README.ce')
| -rw-r--r-- | gnu/usr.bin/perl/README.ce | 512 |
1 files changed, 59 insertions, 453 deletions
diff --git a/gnu/usr.bin/perl/README.ce b/gnu/usr.bin/perl/README.ce index 3559f1ff3ba..d02acf8e846 100644 --- a/gnu/usr.bin/perl/README.ce +++ b/gnu/usr.bin/perl/README.ce @@ -1,453 +1,59 @@ -If you read this file _as_is_, just ignore the funny characters you -see. It is written in the POD format (see pod/perlpod.pod) which is -specifically designed to be readable as is. - -=head1 NAME - -perlce - Perl for WinCE - -=head1 Building Perl for WinCE - -=head2 WARNING - -B<< Much of this document has become very out of date and needs updating, -rewriting or deleting. The build process was overhauled during the 5.19 -development track and the current instructions as of that time are given -in L</CURRENT BUILD INSTRUCTIONS>; the previous build instructions, which -are largely superseded but may still contain some useful information, are -left in L</OLD BUILD INSTRUCTIONS> but really need removing after anything -of use has been extracted from them. >> - -=head2 DESCRIPTION - -This file gives the instructions for building Perl5.8 and above for -WinCE. Please read and understand the terms under which this -software is distributed. - -=head2 General explanations on cross-compiling WinCE - -=over - -=item * - -F<miniperl> is built. This is a single executable (without DLL), intended -to run on Win32, and it will facilitate remaining build process; all binaries -built after it are foreign and should not run locally. - -F<miniperl> is built using F<./win32/Makefile>; this is part of normal -build process invoked as dependency from wince/Makefile.ce - -=item * - -After F<miniperl> is built, F<configpm> is invoked to create right F<Config.pm> -in right place and its corresponding Cross.pm. - -Unlike Win32 build, miniperl will not have F<Config.pm> of host within reach; -it rather will use F<Config.pm> from within cross-compilation directories. - -File F<Cross.pm> is dead simple: for given cross-architecture places in @INC -a path where perl modules are, and right F<Config.pm> in that place. - -That said, C<miniperl -Ilib -MConfig -we 1> should report an error, because -it can not find F<Config.pm>. If it does not give an error -- wrong F<Config.pm> -is substituted, and resulting binaries will be a mess. - -C<miniperl -MCross -MConfig -we 1> should run okay, and it will provide right -F<Config.pm> for further compilations. - -=item * - -During extensions build phase, a script F<./win32/buldext.pl> is invoked, -which in turn steps in F<./ext> subdirectories and performs a build of -each extension in turn. - -All invokes of F<Makefile.PL> are provided with C<-MCross> so to enable cross- -compile. - -=back - -=head2 CURRENT BUILD INSTRUCTIONS - -(These instructions assume the host is 32-bit Windows. If you're on 64-bit -Windows then change "C:\Program Files" to "C:\Program Files (x86)" throughout.) - -1. Install EVC4 from - - http://download.microsoft.com/download/c/3/f/c3f8b58b-9753-4c2e-8b96-2dfe3476a2f7/eVC4.exe - -Use the key mentioned at - - http://download.cnet.com/Microsoft-eMbedded-Visual-C/3000-2212_4-10108490.html?tag=bc - -The installer is ancient and has a few bugs on the paths it uses. You -will have to fix them later. Basically, some things go into "C:/Program -Files/Windows CE Tools", others go into "C:/Windows CE Tools" regardless -of the path you gave to the installer (the default will be "C:/Windows -CE Tools"). Reboots will be required for the installer to proceed. Also -.c and .h associations with Visual Studio might get overridden when -installing EVC4. You have been warned. - -2. Download celib from GitHub (using "Download ZIP") at - - https://github.com/bulk88/celib - -Extract it to a spaceless path but not into the perl build source. -I call this directory "celib-palm-3.0" but in the GitHub -snapshot it will be called "celib-master". Make a copy of the -"wince-arm-pocket-wce300-release" folder and rename the copy to -"wince-arm-pocket-wce400". This is a hack so we can build a CE 4.0 -binary by linking in CE 3.0 ARM asm; the linker doesn't care. Windows -Mobile/WinCE are backwards compatible with machine code like Desktop Windows. - -3. Download console-1.3-src.tar.gz from - - http://sourceforge.net/projects/perlce/files/PerlCE%20support%20files/console/ - -Extract it to a spaceless path but not into the perl build source. -Don't extract it into the same directory as celib. Make a copy of the -"wince-arm-pocket-wce300" folder and rename the copy to -"wince-arm-pocket-wce400". This is a hack so we can build a CE 4.0 -binary by linking in CE 3.0 ARM asm; the linker doesn't care. Windows -Mobile/WinCE are backwards compatible with machine code like Desktop Windows. - -4. Open a command prompt, run your regular batch file to set the environment -for desktop Visual C building, goto the perl source directory, cd into win32/, -fill out Makefile, and do a "nmake all" to build a Desktop Perl. - -5. Open win32/Makefile.ce in a text editor and do something similar to the -following patch. - - -CELIBDLLDIR = h:\src\wince\celib-palm-3.0 - -CECONSOLEDIR = h:\src\wince\w32console - +CELIBDLLDIR = C:\sources\celib-palm-3.0 - +CECONSOLEDIR = C:\sources\w32console - -Also change - - !if "$(MACHINE)" == "" - MACHINE=wince-arm-hpc-wce300 - #MACHINE=wince-arm-hpc-wce211 - #MACHINE=wince-sh3-hpc-wce211 - #MACHINE=wince-mips-hpc-wce211 - #MACHINE=wince-sh3-hpc-wce200 - #MACHINE=wince-mips-hpc-wce200 - #MACHINE=wince-arm-pocket-wce300 - #MACHINE=wince-mips-pocket-wce300 - #MACHINE=wince-sh3-pocket-wce300 - #MACHINE=wince-x86em-pocket-wce300 - #MACHINE=wince-mips-palm-wce211 - #MACHINE=wince-sh3-palm-wce211 - #MACHINE=wince-x86em-palm-wce211 - #MACHINE=wince-x86-hpc-wce300 - #MACHINE=wince-arm-pocket-wce400 - !endif - -to - - !if "$(MACHINE)" == "" - #MACHINE=wince-arm-hpc-wce300 - #MACHINE=wince-arm-hpc-wce211 - #MACHINE=wince-sh3-hpc-wce211 - #MACHINE=wince-mips-hpc-wce211 - #MACHINE=wince-sh3-hpc-wce200 - #MACHINE=wince-mips-hpc-wce200 - #MACHINE=wince-arm-pocket-wce300 - #MACHINE=wince-mips-pocket-wce300 - #MACHINE=wince-sh3-pocket-wce300 - #MACHINE=wince-x86em-pocket-wce300 - #MACHINE=wince-mips-palm-wce211 - #MACHINE=wince-sh3-palm-wce211 - #MACHINE=wince-x86em-palm-wce211 - #MACHINE=wince-x86-hpc-wce300 - MACHINE=wince-arm-pocket-wce400 - !endif - -so wince-arm-pocket-wce400 is the MACHINE type. - -6. Use a text editor to open "C:\Program Files\Microsoft eMbedded C++ -4.0\EVC\WCE400\BIN\WCEARMV4.BAT". Look for - - if "%SDKROOT%"=="" set SDKROOT=... - -On a new install it is "C:\Windows CE Tools". Goto -"C:\Windows CE Tools" in a file manager and see if "C:\Windows CE -Tools\wce400\STANDARDSDK\Include\Armv4" exists on your disk. If not -the SDKROOT need to be changed to "C:\Program Files\Windows CE Tools". - -Goto celib-palm-3.0\inc\cewin32.h, search for - - typedef struct _ABC { - -and uncomment the struct. - -7. Open another command prompt, ensure PLATFORM is not set to anything -already unless you know what you're doing (so that the correct default -value is set by the next command), and run "C:\Program Files\Microsoft -eMbedded C++ 4.0\EVC\WCE400\BIN\WCEARMV4.BAT" - -8. In the WinCE command prompt you made with WCEARMV4.BAT, goto the perl -source directory, cd into win32/ and run "nmake -f Makefile.ce". - -9. The ARM perl interpreter (perl519.dll and perl.exe) will be in something -like "C:\perl519\src\win32\wince-arm-pocket-wce400", with the XS DLLs in -"C:\perl519\src\xlib\wince-arm-hpc-wce400\auto". - -To prove success on the host machine, run -"dumpbin /headers wince-arm-pocket-wce400\perl.exe" from the win32/ folder -and look for "machine (ARM)" in the FILE HEADER VALUES and -"subsystem (Windows CE GUI)" in the OPTIONAL HEADER VALUES. - -=head2 OLD BUILD INSTRUCTIONS - -This section describes the steps to be performed to build PerlCE. -You may find additional information about building perl for WinCE -at L<http://perlce.sourceforge.net> and some pre-built binaries. - -=head3 Tools & SDK - -For compiling, you need following: - -=over 4 - -=item * Microsoft Embedded Visual Tools - -=item * Microsoft Visual C++ - -=item * Rainer Keuchel's celib-sources - -=item * Rainer Keuchel's console-sources - -=back - -Needed source files can be downloaded at -L<http://perlce.sourceforge.net> - -=head3 Make - -Normally you only need to edit F<./win32/ce-helpers/compile.bat> -to reflect your system and run it. - -File F<./win32/ce-helpers/compile.bat> is actually a wrapper to call -C<nmake -f makefile.ce> with appropriate parameters and it accepts extra -parameters and forwards them to C<nmake> command as additional -arguments. You should pass target this way. - -To prepare distribution you need to do following: - -=over 4 - -=item * go to F<./win32> subdirectory - -=item * edit file F<./win32/ce-helpers/compile.bat> - -=item * run - compile.bat - -=item * run - compile.bat dist - -=back - -F<Makefile.ce> has C<CROSS_NAME> macro, and it is used further to refer to -your cross-compilation scheme. You could assign a name to it, but this -is not necessary, because by default it is assigned after your machine -configuration name, such as "wince-sh3-hpc-wce211", and this is enough -to distinguish different builds at the same time. This option could be -handy for several different builds on same platform to perform, say, -threaded build. In a following example we assume that all required -environment variables are set properly for C cross-compiler (a special -*.bat file could fit perfectly to this purpose) and your F<compile.bat> -has proper "MACHINE" parameter set, to, say, C<wince-mips-pocket-wce300>. - - compile.bat - compile.bat dist - compile.bat CROSS_NAME=mips-wce300-thr "USE_ITHREADS=define" ^ - "USE_IMP_SYS=define" "USE_MULTI=define" - compile.bat CROSS_NAME=mips-wce300-thr "USE_ITHREADS=define" ^ - "USE_IMP_SYS=define" "USE_MULTI=define" dist - -If all goes okay and no errors during a build, you'll get two independent -distributions: C<wince-mips-pocket-wce300> and C<mips-wce300-thr>. - -Target C<dist> prepares distribution file set. Target C<zipdist> performs -same as C<dist> but additionally compresses distribution files into zip -archive. - -NOTE: during a build there could be created a number (or one) of F<Config.pm> -for cross-compilation ("foreign" F<Config.pm>) and those are hidden inside -F<../xlib/$(CROSS_NAME)> with other auxiliary files, but, and this is important to -note, there should be B<no> F<Config.pm> for host miniperl. -If you'll get an error that perl could not find Config.pm somewhere in building -process this means something went wrong. Most probably you forgot to -specify a cross-compilation when invoking miniperl.exe to Makefile.PL -When building an extension for cross-compilation your command line should -look like - - ..\miniperl.exe -I..\lib -MCross=mips-wce300-thr Makefile.PL - -or just - - ..\miniperl.exe -I..\lib -MCross Makefile.PL - -to refer a cross-compilation that was created last time. - -All questions related to building for WinCE devices could be asked in -F<perlce-user@lists.sourceforge.net> mailing list. - -=head1 Using Perl on WinCE - -=head2 DESCRIPTION - -PerlCE is currently linked with a simple console window, so it also -works on non-hpc devices. - -The simple stdio implementation creates the files F<stdin.txt>, -F<stdout.txt> and F<stderr.txt>, so you might examine them if your -console has only a limited number of cols. - -When exitcode is non-zero, a message box appears, otherwise the -console closes, so you might have to catch an exit with -status 0 in your program to see any output. - -stdout/stderr now go into the files F</perl-stdout.txt> and -F</perl-stderr.txt.> - -PerlIDE is handy to deal with perlce. - -=head2 LIMITATIONS - -No fork(), pipe(), popen() etc. - -=head2 ENVIRONMENT - -All environment vars must be stored in HKLM\Environment as -strings. They are read at process startup. - -=over - -=item PERL5LIB - -Usual perl lib path (semi-list). - -=item PATH - -Semi-list for executables. - -=item TMP - -- Tempdir. - -=item UNIXROOTPATH - -- Root for accessing some special files, i.e. F</dev/null>, F</etc/services>. - -=item ROWS/COLS - -- Rows/cols for console. - -=item HOME - -- Home directory. - -=item CONSOLEFONTSIZE - -- Size for console font. - -=back - -You can set these with cereg.exe, a (remote) registry editor -or via the PerlIDE. - -=head2 REGISTRY - -To start perl by clicking on a perl source file, you have -to make the according entries in HKCR (see F<ce-helpers/wince-reg.bat>). -cereg.exe (which must be executed on a desktop pc with -ActiveSync) is reported not to work on some devices. -You have to create the registry entries by hand using a -registry editor. - -=head2 XS - -The following Win32-Methods are built-in: - - newXS("Win32::GetCwd", w32_GetCwd, file); - newXS("Win32::SetCwd", w32_SetCwd, file); - newXS("Win32::GetTickCount", w32_GetTickCount, file); - newXS("Win32::GetOSVersion", w32_GetOSVersion, file); - newXS("Win32::IsWinNT", w32_IsWinNT, file); - newXS("Win32::IsWin95", w32_IsWin95, file); - newXS("Win32::IsWinCE", w32_IsWinCE, file); - newXS("Win32::CopyFile", w32_CopyFile, file); - newXS("Win32::Sleep", w32_Sleep, file); - newXS("Win32::MessageBox", w32_MessageBox, file); - newXS("Win32::GetPowerStatus", w32_GetPowerStatus, file); - newXS("Win32::GetOemInfo", w32_GetOemInfo, file); - newXS("Win32::ShellEx", w32_ShellEx, file); - -=head2 BUGS - -Opening files for read-write is currently not supported if -they use stdio (normal perl file handles). - -If you find bugs or if it does not work at all on your -device, send mail to the address below. Please report -the details of your device (processor, ceversion, -devicetype (hpc/palm/pocket)) and the date of the downloaded -files. - -=head2 INSTALLATION - -Currently installation instructions are at L<http://perlce.sourceforge.net/>. - -After installation & testing processes will stabilize, information will -be more precise. - -=head1 ACKNOWLEDGEMENTS - -The port for Win32 was used as a reference. - -=head1 History of WinCE port - -=over - -=item 5.6.0 - -Initial port of perl to WinCE. It was performed in separate directory -named F<wince>. This port was based on contents of F<./win32> directory. -F<miniperl> was not built, user must have HOST perl and properly edit -F<makefile.ce> to reflect this. - -=item 5.8.0 - -wince port was kept in the same F<./wince> directory, and F<wince/Makefile.ce> -was used to invoke native compiler to create HOST miniperl, which then -facilitates cross-compiling process. -Extension building support was added. - -=item 5.9.4 - -Two directories F<./win32> and F<./wince> were merged, so perlce build -process comes in F<./win32> directory. - -=back - -=head1 AUTHORS - -=over - -=item Rainer Keuchel <coyxc@rainer-keuchel.de> - -provided initial port of Perl, which appears to be most essential work, as -it was a breakthrough on having Perl ported at all. -Many thanks and obligations to Rainer! - -=item Vadim Konovalov - -made further support of WinCE port. - -=item Daniel Dragan - -updated the build process during the 5.19 development track. - -=back +If you read this file _as_is_, just ignore the funny characters you
+see. It is written in the POD format (see pod/perlpod.pod) which is
+specifically designed to be readable as is.
+
+=head1 Name
+
+Perl for WinCE
+
+=head1 Description
+
+This file gives the instructions for building Perl5.6 and above for
+WinCE. Please read and understand the terms under which this
+software is distributed.
+
+=head1 Build
+
+This section describes the steps to be performed to build PerlCE.
+
+=head2 Tools & SDK
+
+For compiling, you need Microsoft Embedded Visual Tools, my
+celib-sources, my console-sources and a perl for win32.
+
+Needed source files can be downloaded via:
+www.rainer-keuchel.de/wince/dirlist.html
+
+Some portions of the makefile need a shell for win32, rm, cp, mv,
+xmkdir (mkdir with a -p option). It also uses my cecopy program for
+copying files to the ce device.
+
+=head2 Make
+
+Miniperl is not built. A pre-existent win32 perl is used.
+
+The paths for tools and additional libraries have to be changed in
+wince/makefile.ce.
+
+Different ce targets can be specified with the TARGET macro.
+
+Before you start, you need to build celib.dll and w32console.
+See instructions in these packages for building.
+
+In the wince directory, type "nmake -f makefile.ce". This should
+build perl.exe and perl.dll. For building extension dlls,
+type "nmake -f makefile.ce dlls"
+
+When building ext dlls, you get lots of macro redefinition
+errors. Just ignore them.
+
+For further information, look in the text files in the wince
+sub-directory.
+
+=head1 Acknowledgements
+
+The port for Win32 was used as a reference.
+
+=head1 Author
+
+Rainer Keuchel (keuchel@netwave.de)
|