X-Git-Url: https://perl5.git.perl.org/perl5.git/blobdiff_plain/8f33b42a5befbbd0d1d798a463bfe4ac2ba9bf10..cfc4a7da389202132834a0ef4ed2d46dd167c176:/README.ce diff --git a/README.ce b/README.ce index e8d4c49..5d338c8 100644 --- a/README.ce +++ b/README.ce @@ -2,31 +2,67 @@ 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 + +=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 -This section describes the steps to be performed to build PerlCE. -You may find additional and newer information about building perl -for WinCE using following URL: +=over + +=item * + +C 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. + +C is built using C<./win32/Makefile>; this is part of normal +build process invoked as dependency from wince/Makefile.ce + +=item * + +After C is built, C is invoked to create right C +in right place and its corresponding Cross.pm. + +Unlike Win32 build, miniperl will not have C of host within reach; +it rather will use C from within cross-compilation directories. + +File C is dead simple: for given cross-architecture places in @INC +a path where perl modules are, and right C in that place. - http://perlce.sourceforge.net +That said, C should report an error, because +it can not find C. If it does not gives an error -- wrong C +is substituted, and resulting binaries will be a mess. -There should also be pre-built binaries there. +C should run okay, and it will provide right +C for further compilations. -Don't be confused by large size of downloaded distribution or constructed -binaries: entire distribution could be large for WinCE ideology, but -you may strip it at your wish and use only required parts. +=item * -=head2 Tools & SDK +During extensions build phase, a script C<./win32/buldext.pl> is invoked, +which in turn steps in C<./ext> subdirectories and performs a build of +each extension in turn. + +All invokes of C are provided with C<-MCross> so to enable cross- +compile. + +=back + +=head2 BUILD + +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: @@ -42,32 +78,26 @@ For compiling, you need following: =back -Needed source files can be downloaded via: -www.rainer-keuchel.de/wince/dirlist.html +Needed source files can be downloaded at +L -=head2 Make +=head3 Make -Please pay attention that starting from 5.8.0 miniperl *is* built -and it facilitates in further building process. This means that -in addition to compiler installation for mobile device you also need -to have Microsoft Visual C++ installed as well. - -On the bright side, you do not need to edit any files from ./win32 -subdirectory. Normally you only need to edit ./wince/compile.bat +Normally you only need to edit C<./win32/ce-helpers/compile.bat> to reflect your system and run it. -File ./wince/compile.bat is actually a wrapper to call -nmake -f makefile.ce with appropriate parameters and it accepts extra -parameters and forwards them to "nmake" command as additional +File C<./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. To prepare distribution you need to do following: =over 4 -=item * go to ./wince subdirectory +=item * go to C<./win32> subdirectory -=item * edit file compile.bat +=item * edit file C<./win32/ce-helpers/compile.bat> =item * run compile.bat @@ -77,7 +107,7 @@ To prepare distribution you need to do following: =back -makefile.ce has CROSS_NAME macro, and it is used further to refer to +C 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 @@ -85,8 +115,8 @@ 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 compile.bat -has proper "MACHINE" parameter set, to, say, "wince-mips-pocket-wce300". +*.bat file could fit perfectly to this purpose) and your C +has proper "MACHINE" parameter set, to, say, C. compile.bat compile.bat dist @@ -94,16 +124,16 @@ has proper "MACHINE" parameter set, to, say, "wince-mips-pocket-wce300". 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: "wince-mips-pocket-wce300" and "mips-wce300-thr". +distributions: C and C. -Target 'dist' prepares distribution file set. Target 'zipdist' performs -same as 'dist' but additionally compresses distribution files into zip +Target C prepares distribution file set. Target C performs +same as C but additionally compresses distribution files into zip archive. -NOTE: during a build there could be created a number (or one) of Config.pm -for cross-compilation ("foreign" Config.pm) and those are hidden inside -../xlib/$(CROSS_NAME) with other auxilary files, but, and this is important to -note, there should be *no* Config.pm for host miniperl. +NOTE: during a build there could be created a number (or one) of C +for cross-compilation ("foreign" C) and those are hidden inside +C<../xlib/$(CROSS_NAME)> with other auxilary files, but, and this is important to +note, there should be B C 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 @@ -118,20 +148,159 @@ or just 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 -If you decided to build with fcrypt.c file, please refer to README.win32 -file, as long as all legal considerations and steps to do are exactly same -in this case. +=head2 DESCRIPTION -All questions related to building for WinCE devices could be asked in -perlce-users@lists.sourceforge.net mailing list. +PerlCE is currently linked with a simple console window, so it also +works on non-hpc devices. + +The simple stdio implementation creates the files C, +C and C, so you might examine them if your +console has only a liminted 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 C and +C + +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 -=head1 Acknowledgements +- Root for accessing some special files, i.e. C, C. + +=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 C). +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 History of WinCE port + +=over + +=item 5.6.0 + +Initial port of perl to WinCE. It was performed in separate directory +named C. This port was based on contents of C<./win32> directory. +C was not built, user must have HOST perl and properly edit +C to reflect this. + +=item 5.8.0 + +wince port was kept in the same C<./wince> directory, and C +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 C<./win32> and C<./wince> were merged, so perlce build +process comes in C<./win32> directory. + +=back + =head1 AUTHORS -Rainer Keuchel (keuchel@netwave.de) -Vadim Konovalov (vkonovalov@spb.lucent.com) +=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. + +=back