RE: [PATCH-for-28089] wince yet another step

From: "Konovalov, Vadim Vladimirovich (Vadim)** CTR **" <vkonovalov@Lucent.com>
Message-ID: <E3FB32585BF1D411B9E900805FF51A0801BCB454@ru0022exch001u.ru.lucent.com>

p4raw-id: //depot/perl@28100

1 files changed, 91 insertions, 79 deletions

diff --git a/README.ce b/README.ce
index ecb574d7fa..41be58be83 100644
--- a/README.ce
+++ b/README.ce
@@ -24,34 +24,34 @@ 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 ../win32/Makefile; this is part of normal
+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, 'configpm' is invoked to create right Config.pm
+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 Config.pm of host within reach;
-it rather will use Config.pm from within cross-compilation directories.
+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 Cross.pm is dead simple: for given cross-architecture places in @INC
-a path where perl modules are, and right Config.pm in that place.
+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 Config.pm. If it does not gives an error -- wrong Config.pm
+it can not find C<Config.pm>. If it does not gives 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
-Config.pm for further compilations.
+C<Config.pm> for further compilations.
 
 =item *
 
 During extensions build phase, a script C<./win32/buldext.pl> is invoked,
-which in turn steps in ./ext subdirectories and performs a build of
+which in turn steps in C<./ext> subdirectories and performs a build of
 each extension in turn.
 
-All invokes of Makefile.PL are provided with C<-MCross> so to enable cross-
+All invokes of C<Makefile.PL> are provided with C<-MCross> so to enable cross-
 compile.
 
 =item *
@@ -85,21 +85,21 @@ L<http://www.rainer-keuchel.de/wince/dirlist.html>
 
 =head3 Make
 
-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<./wince/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 ./wince subdirectory
+=item * go to C<./win32> subdirectory
 
-=item * edit file compile.bat
+=item * edit file C<compile.bat>
 
 =item * run 
   compile.bat
@@ -109,7 +109,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<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
@@ -117,8 +117,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<compile.bat>
+has proper "MACHINE" parameter set, to, say, C<wince-mips-pocket-wce300>.
 
   compile.bat
   compile.bat dist
@@ -126,16 +126,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<wince-mips-pocket-wce300> and C<mips-wce300-thr>.
 
-Target 'dist' prepares distribution file set. Target 'zipdist' performs
-same as 'dist' but additionally compresses distribution files into zip
+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 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<Config.pm>
+for cross-compilation ("foreign" C<Config.pm>) and those are hidden inside
+C<../xlib/$(CROSS_NAME)> with other auxilary 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
@@ -151,7 +151,7 @@ or just
 to refer a cross-compilation that was created last time.
 
 All questions related to building for WinCE devices could be asked in
-perlce-users@lists.sourceforge.net mailing list.
+L<perlce-user@lists.sourceforge.net> mailing list.
 
 =head1 Using Perl on WinCE
 
@@ -160,16 +160,18 @@ 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 stdin.txt,
-stdout.txt and stderr.txt, so you might examine them if your
+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 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 /perl-stdout.txt and
-/perl-stderr.txt.
+stdout/stderr now go into the files C</perl-stdout.txt> and
+C</perl-stderr.txt.>
+
+PerlIDE is handy to deal with perlce.
 
 =head2 LIMITATIONS
 
@@ -180,14 +182,37 @@ No fork(), pipe(), popen() etc.
 All environment vars must be stored in HKLM\Environment as
 strings. They are read at process startup.
 
-	PERL5LIB	- Usual perl lib path (semi-list).
-	PATH		- Semi-list for executables.
-	TMP		- Tempdir.
-	UNIXROOTPATH	- Root for accessing some special files,
-			  i.e. /dev/null, /etc/services.
-	ROWS/COLS	- Rows/cols for console.
-	HOME		- Home directory.
-	CONSOLEFONTSIZE - Size for console font.
+=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.
@@ -195,51 +220,12 @@ 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 wince-reg.bat).
+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 PERLFILES
-
-The following files are a reasonable minimum if you want to do
-some socket stuff:
-
-	./auto
-	./auto/DynaLoader
-	./auto/DynaLoader/autosplit.ix
-	./auto/DynaLoader/dl_expandspec.al
-	./auto/DynaLoader/dl_findfile.al
-	./auto/DynaLoader/dl_find_symbol_anywhere.al
-	./auto/IO
-	./auto/IO/IO.bs
-	./auto/IO/IO.dll
-	./auto/Socket
-	./auto/Socket/Socket.bs
-	./auto/Socket/Socket.dll
-	./Carp
-	./Carp/Heavy.pm
-	./Carp.pm
-	./Config.pm
-	./DynaLoader.pm
-	./Exporter
-	./Exporter/Heavy.pm
-	./Exporter.pm
-	./IO
-	./IO/File.pm
-	./IO/Handle.pm
-	./IO/Socket.pm
-	./IO.pm
-	./SelectSaver.pm
-	./Socket.pm
-	./strict.pm
-	./Symbol.pm
-	./warnings
-	./warnings/register.pm
-	./warnings.pm
-	./XSLoader.pm
-
 =head2 XS
 
 The following Win32-Methods are built-in:
@@ -280,6 +266,32 @@ be more precise.
 
 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<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.
+
+=over
+
+
 =head1 AUTHORS
 
 =over