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 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 *
+
+C<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.
+
+C<miniperl> is built using C<./win32/Makefile>; this is part of normal
+build process invoked as dependency from wince/Makefile.ce
+
+=item *
+
+After C<miniperl> is built, C<configpm> is invoked to create right C<Config.pm>
+in right place and its corresponding Cross.pm.
+
+Unlike Win32 build, miniperl will not have C<Config.pm> of host within reach;
+it rather will use C<Config.pm> from within cross-compilation directories.
+
+File C<Cross.pm> is dead simple: for given cross-architecture places in @INC
+a path where perl modules are, and right C<Config.pm> in that place.
+
+That said, C<miniperl -Ilib -MConfig -we 1> should report an error, because
+it can not find C<Config.pm>. If it does not give an error -- wrong C<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
+C<Config.pm> for further compilations.
+
+=item *
+
+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<Makefile.PL> 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<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://www.rainer-keuchel.de/wince/dirlist.html>
+
+=head3 Make
+
+Normally you only need to edit C<./win32/ce-helpers/compile.bat>
+to reflect your system and run it.
+
+File C<./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 C<./win32> subdirectory
+
+=item * edit file C<./win32/ce-helpers/compile.bat>
+
+=item * run
+ compile.bat
+
+=item * run
+ compile.bat dist
+
+=back
+
+C<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 C<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 C<Config.pm>
+for cross-compilation ("foreign" C<Config.pm>) and those are hidden inside
+C<../xlib/$(CROSS_NAME)> with other auxiliary files, but, and this is important to
+note, there should be B<no> C<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
-=head2 Tools & SDK
+to refer a cross-compilation that was created last time.
-For compiling, you need Microsoft Embedded Visual Tools, my
-celib-sources, my console-sources and a perl for win32.
+All questions related to building for WinCE devices could be asked in
+F<perlce-user@lists.sourceforge.net> mailing list.
-Needed source files can be downloaded via:
-www.rainer-keuchel.de/wince/dirlist.html
+=head1 Using Perl on WinCE
-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 DESCRIPTION
-=head2 Make
+PerlCE is currently linked with a simple console window, so it also
+works on non-hpc devices.
-Miniperl is not built. A pre-existent win32 perl is used.
+The simple stdio implementation creates the files C<stdin.txt>,
+C<stdout.txt> and C<stderr.txt>, so you might examine them if your
+console has only a limited number of cols.
-The paths for tools and additional libraries have to be changed in
-wince/makefile.ce.
+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.
-Different ce targets can be specified with the TARGET macro.
+stdout/stderr now go into the files C</perl-stdout.txt> and
+C</perl-stderr.txt.>
-Before you start, you need to build celib.dll and w32console.
-See instructions in these packages for building.
+PerlIDE is handy to deal with perlce.
-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"
+=head2 LIMITATIONS
-When building ext dlls, you get lots of macro redefinition
-errors. Just ignore them.
+No fork(), pipe(), popen() etc.
-For further information, look in the text files in the wince
-sub-directory.
+=head2 ENVIRONMENT
-=head1 Acknowledgements
+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. C</dev/null>, C</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 C<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 Author
+=head1 History of WinCE port
+
+=over
+
+=item 5.6.0
+
+Initial port of perl to WinCE. It was performed in separate directory
+named C<wince>. This port was based on contents of C<./win32> directory.
+C<miniperl> was not built, user must have HOST perl and properly edit
+C<makefile.ce> to reflect this.
+
+=item 5.8.0
+
+wince port was kept in the same C<./wince> directory, and C<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 C<./win32> and C<./wince> were merged, so perlce build
+process comes in C<./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.
-Rainer Keuchel (keuchel@netwave.de)
+=back
https://perl5.git.perl.org / perl5.git / blobdiff