X-Git-Url: https://perl5.git.perl.org/perl5.git/blobdiff_plain/e1caacb4fdb62cb28dc825ca0115faf95e569339..f567cd8d0d381c5daff62c3871dfdbc66495e625:/README.ce diff --git a/README.ce b/README.ce index a216f33..fdf636f 100644 --- a/README.ce +++ b/README.ce @@ -2,58 +2,452 @@ 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 +=head1 NAME -Perl for WinCE +perlce - Perl for WinCE -=head1 Description +=head1 Building Perl for WinCE -This file gives the instructions for building Perl5.6 and above for +=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; the previous build instructions, which +are largely superseded but may still contain some useful information, are +left in L 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. -=head1 Build +=head2 General explanations on cross-compiling WinCE + +=over + +=item * + +F 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 is built using F<./win32/Makefile>; this is part of normal +build process invoked as dependency from wince/Makefile.ce + +=item * + +After F is built, F is invoked to create right F +in right place and its corresponding Cross.pm. + +Unlike Win32 build, miniperl will not have F of host within reach; +it rather will use F from within cross-compilation directories. + +File F is dead simple: for given cross-architecture places in @INC +a path where perl modules are, and right F in that place. + +That said, C should report an error, because +it can not find F. If it does not give an error -- wrong F +is substituted, and resulting binaries will be a mess. + +C should run okay, and it will provide right +F for further compilations. + +=item * + +During extensions build phase, a script F<./win32/buildext.pl> is invoked, +which in turn steps in F<./ext> subdirectories and performs a build of +each extension in turn. + +All invokes of F 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 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 + +=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 with appropriate parameters and it accepts extra +parameters and forwards them to C command as additional +arguments. You should pass target this way. -=head2 Tools & SDK +To prepare distribution you need to do following: -For compiling, you need Microsoft Embedded Visual Tools, my -celib-sources, my console-sources and a perl for win32. +=over 4 -Needed source files can be downloaded via: -www.rainer-keuchel.de/wince/dirlist.html +=item * go to F<./win32> subdirectory -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. +=item * edit file F<./win32/ce-helpers/compile.bat> -=head2 Make +=item * run + compile.bat -Miniperl is not built. A pre-existent win32 perl is used. +=item * run + compile.bat dist -The paths for tools and additional libraries have to be changed in -wince/makefile.ce. +=back -Different ce targets can be specified with the TARGET macro. +F has C 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 +has proper "MACHINE" parameter set, to, say, C. -Before you start, you need to build celib.dll and w32console. -See instructions in these packages for building. + 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 -In the wince directory, type "nmake -f makefile.ce". This should -build perl.exe and and perl.dll. For building extension dlls, -type "nmake -f makefile.ce dlls" +If all goes okay and no errors during a build, you'll get two independent +distributions: C and C. -When building ext dlls, you get lots of macro redefinition -errors. Just ignore them. +Target C prepares distribution file set. Target C performs +same as C but additionally compresses distribution files into zip +archive. -For further information, look in the text files in the wince -sub-directory. +NOTE: during a build there could be created a number (or one) of F +for cross-compilation ("foreign" F) and those are hidden inside +F<../xlib/$(CROSS_NAME)> with other auxiliary files, but, and this is important to +note, there should be B F 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 -=head1 Acknowledgements + ..\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 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, +F and F, 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 and +F + +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, F. + +=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). +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. + +After installation & testing processes will stabilize, information will +be more precise. + +=head1 ACKNOWLEDGEMENTS The port for Win32 was used as a reference. -=head1 Author +=head1 History of WinCE port + +=over + +=item 5.6.0 + +Initial port of perl to WinCE. It was performed in separate directory +named F. This port was based on contents of F<./win32> directory. +F was not built, user must have HOST perl and properly edit +F to reflect this. + +=item 5.8.0 + +wince port was kept in the same F<./wince> directory, and F +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 + +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. -Rainer Keuchel (keuchel@netwave.de) +=back