1 If you read this file _as_is_, just ignore the funny characters you
2 see. It is written in the POD format (see pod/perlpod.pod) which is
3 specifically designed to be readable as is.
7 perlce - Perl for WinCE
9 =head1 Building Perl for WinCE
13 This file gives the instructions for building Perl5.8 and above for
14 WinCE. Please read and understand the terms under which this
15 software is distributed.
17 =head2 General explanations on cross-compiling WinCE
23 C<miniperl> is built. This is a single executable (without DLL), intended
24 to run on Win32, and it will facilitate remaining build process; all binaries
25 built after it are foreign and should not run locally.
27 C<miniperl> is built using ../win32/Makefile; this is part of normal
28 build process invoked as dependency from wince/Makefile.ce
32 After C<miniperl> is built, 'configpm' is invoked to create right Config.pm
33 in right place and its corresponding Cross.pm.
35 Unlike Win32 build, miniperl will not have Config.pm of host within reach;
36 it rather will use Config.pm from within cross-compilation directories.
38 File Cross.pm is dead simple: for given cross-architecture places in @INC
39 a path where perl modules are, and right Config.pm in that place.
41 That said, C<miniperl -Ilib -MConfig -we 1> should report an error, because
42 it can not find Config.pm. If it does not gives an error -- wrong Config.pm
43 is substituted, and resulting binaries will be a mess.
45 C<miniperl -MCross -MConfig -we 1> should run okay, and it will provide right
46 Config.pm for further compilations.
50 During extensions build phase, a script C<./win32/buldext.pl> is invoked,
51 which in turn steps in ./ext subdirectories and performs a build of
52 each extension in turn.
54 All invokes of Makefile.PL are provided with C<-MCross> so to enable cross-
63 This section describes the steps to be performed to build PerlCE.
64 You may find additional information about building perl for WinCE
65 at L<http://perlce.sourceforge.net> and some pre-built binaries.
69 For compiling, you need following:
73 =item * Microsoft Embedded Visual Tools
75 =item * Microsoft Visual C++
77 =item * Rainer Keuchel's celib-sources
79 =item * Rainer Keuchel's console-sources
83 Needed source files can be downloaded at
84 L<http://www.rainer-keuchel.de/wince/dirlist.html>
88 Normally you only need to edit ./wince/compile.bat
89 to reflect your system and run it.
91 File ./wince/compile.bat is actually a wrapper to call
92 nmake -f makefile.ce with appropriate parameters and it accepts extra
93 parameters and forwards them to "nmake" command as additional
94 arguments. You should pass target this way.
96 To prepare distribution you need to do following:
100 =item * go to ./wince subdirectory
102 =item * edit file compile.bat
112 makefile.ce has CROSS_NAME macro, and it is used further to refer to
113 your cross-compilation scheme. You could assign a name to it, but this
114 is not necessary, because by default it is assigned after your machine
115 configuration name, such as "wince-sh3-hpc-wce211", and this is enough
116 to distinguish different builds at the same time. This option could be
117 handy for several different builds on same platform to perform, say,
118 threaded build. In a following example we assume that all required
119 environment variables are set properly for C cross-compiler (a special
120 *.bat file could fit perfectly to this purpose) and your compile.bat
121 has proper "MACHINE" parameter set, to, say, "wince-mips-pocket-wce300".
125 compile.bat CROSS_NAME=mips-wce300-thr "USE_ITHREADS=define" "USE_IMP_SYS=define" "USE_MULTI=define"
126 compile.bat CROSS_NAME=mips-wce300-thr "USE_ITHREADS=define" "USE_IMP_SYS=define" "USE_MULTI=define" dist
128 If all goes okay and no errors during a build, you'll get two independent
129 distributions: "wince-mips-pocket-wce300" and "mips-wce300-thr".
131 Target 'dist' prepares distribution file set. Target 'zipdist' performs
132 same as 'dist' but additionally compresses distribution files into zip
135 NOTE: during a build there could be created a number (or one) of Config.pm
136 for cross-compilation ("foreign" Config.pm) and those are hidden inside
137 ../xlib/$(CROSS_NAME) with other auxilary files, but, and this is important to
138 note, there should be *no* Config.pm for host miniperl.
139 If you'll get an error that perl could not find Config.pm somewhere in building
140 process this means something went wrong. Most probably you forgot to
141 specify a cross-compilation when invoking miniperl.exe to Makefile.PL
142 When building an extension for cross-compilation your command line should
145 ..\miniperl.exe -I..\lib -MCross=mips-wce300-thr Makefile.PL
149 ..\miniperl.exe -I..\lib -MCross Makefile.PL
151 to refer a cross-compilation that was created last time.
153 All questions related to building for WinCE devices could be asked in
154 perlce-users@lists.sourceforge.net mailing list.
156 =head1 Using Perl on WinCE
160 PerlCE is currently linked with a simple console window, so it also
161 works on non-hpc devices.
163 The simple stdio implementation creates the files stdin.txt,
164 stdout.txt and stderr.txt, so you might examine them if your
165 console has only a liminted number of cols.
167 When exitcode is non-zero, a message box appears, otherwise the
168 console closes, so you might have to catch an exit with
169 status 0 in your program to see any output.
171 stdout/stderr now go into the files /perl-stdout.txt and
176 No fork(), pipe(), popen() etc.
180 All environment vars must be stored in HKLM\Environment as
181 strings. They are read at process startup.
183 PERL5LIB - Usual perl lib path (semi-list).
184 PATH - Semi-list for executables.
186 UNIXROOTPATH - Root for accessing some special files,
187 i.e. /dev/null, /etc/services.
188 ROWS/COLS - Rows/cols for console.
189 HOME - Home directory.
190 CONSOLEFONTSIZE - Size for console font.
192 You can set these with cereg.exe, a (remote) registry editor
197 To start perl by clicking on a perl source file, you have
198 to make the according entries in HKCR (see wince-reg.bat).
199 cereg.exe (which must be executed on a desktop pc with
200 ActiveSync) is reported not to work on some devices.
201 You have to create the registry entries by hand using a
206 The following files are a reasonable minimum if you want to do
211 ./auto/DynaLoader/autosplit.ix
212 ./auto/DynaLoader/dl_expandspec.al
213 ./auto/DynaLoader/dl_findfile.al
214 ./auto/DynaLoader/dl_find_symbol_anywhere.al
219 ./auto/Socket/Socket.bs
220 ./auto/Socket/Socket.dll
239 ./warnings/register.pm
245 The following Win32-Methods are built-in:
247 newXS("Win32::GetCwd", w32_GetCwd, file);
248 newXS("Win32::SetCwd", w32_SetCwd, file);
249 newXS("Win32::GetTickCount", w32_GetTickCount, file);
250 newXS("Win32::GetOSVersion", w32_GetOSVersion, file);
251 newXS("Win32::IsWinNT", w32_IsWinNT, file);
252 newXS("Win32::IsWin95", w32_IsWin95, file);
253 newXS("Win32::IsWinCE", w32_IsWinCE, file);
254 newXS("Win32::CopyFile", w32_CopyFile, file);
255 newXS("Win32::Sleep", w32_Sleep, file);
256 newXS("Win32::MessageBox", w32_MessageBox, file);
257 newXS("Win32::GetPowerStatus", w32_GetPowerStatus, file);
258 newXS("Win32::GetOemInfo", w32_GetOemInfo, file);
259 newXS("Win32::ShellEx", w32_ShellEx, file);
263 Opening files for read-write is currently not supported if
264 they use stdio (normal perl file handles).
266 If you find bugs or if it does not work at all on your
267 device, send mail to the address below. Please report
268 the details of your device (processor, ceversion,
269 devicetype (hpc/palm/pocket)) and the date of the downloaded
274 Currently installation instructions are at L<http://perlce.sourceforge.net/>.
276 After installation & testing processes will stabilize, information will
279 =head1 ACKNOWLEDGEMENTS
281 The port for Win32 was used as a reference.
287 =item Rainer Keuchel <coyxc@rainer-keuchel.de>
289 provided initial port of Perl, which appears to be most essential work, as
290 it was a breakthrough on having Perl ported at all.
291 Many thanks and obligations to Rainer!
293 =item Vadim Konovalov
295 made further support of WinCE port.