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 C<./win32/Makefile>; this is part of normal
28 build process invoked as dependency from wince/Makefile.ce
32 After C<miniperl> is built, C<configpm> is invoked to create right C<Config.pm>
33 in right place and its corresponding Cross.pm.
35 Unlike Win32 build, miniperl will not have C<Config.pm> of host within reach;
36 it rather will use C<Config.pm> from within cross-compilation directories.
38 File C<Cross.pm> is dead simple: for given cross-architecture places in @INC
39 a path where perl modules are, and right C<Config.pm> in that place.
41 That said, C<miniperl -Ilib -MConfig -we 1> should report an error, because
42 it can not find C<Config.pm>. If it does not gives an error -- wrong C<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 C<Config.pm> for further compilations.
50 During extensions build phase, a script C<./win32/buldext.pl> is invoked,
51 which in turn steps in C<./ext> subdirectories and performs a build of
52 each extension in turn.
54 All invokes of C<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 C<./win32/ce-helpers/compile.bat>
89 to reflect your system and run it.
91 File C<./wince/compile.bat> is actually a wrapper to call
92 C<nmake -f makefile.ce> with appropriate parameters and it accepts extra
93 parameters and forwards them to C<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 C<./win32> subdirectory
102 =item * edit file C<compile.bat>
112 C<Makefile.ce> has C<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 C<compile.bat>
121 has proper "MACHINE" parameter set, to, say, C<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: C<wince-mips-pocket-wce300> and C<mips-wce300-thr>.
131 Target C<dist> prepares distribution file set. Target C<zipdist> performs
132 same as C<dist> but additionally compresses distribution files into zip
135 NOTE: during a build there could be created a number (or one) of C<Config.pm>
136 for cross-compilation ("foreign" C<Config.pm>) and those are hidden inside
137 C<../xlib/$(CROSS_NAME)> with other auxilary files, but, and this is important to
138 note, there should be B<no> C<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 L<perlce-user@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 C<stdin.txt>,
164 C<stdout.txt> and C<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 C</perl-stdout.txt> and
174 PerlIDE is handy to deal with perlce.
178 No fork(), pipe(), popen() etc.
182 All environment vars must be stored in HKLM\Environment as
183 strings. They are read at process startup.
189 Usual perl lib path (semi-list).
193 Semi-list for executables.
201 - Root for accessing some special files, i.e. C</dev/null>, C</etc/services>.
205 - Rows/cols for console.
211 =item CONSOLEFONTSIZE
213 - Size for console font.
217 You can set these with cereg.exe, a (remote) registry editor
222 To start perl by clicking on a perl source file, you have
223 to make the according entries in HKCR (see C<ce-helpers/wince-reg.bat>).
224 cereg.exe (which must be executed on a desktop pc with
225 ActiveSync) is reported not to work on some devices.
226 You have to create the registry entries by hand using a
231 The following Win32-Methods are built-in:
233 newXS("Win32::GetCwd", w32_GetCwd, file);
234 newXS("Win32::SetCwd", w32_SetCwd, file);
235 newXS("Win32::GetTickCount", w32_GetTickCount, file);
236 newXS("Win32::GetOSVersion", w32_GetOSVersion, file);
237 newXS("Win32::IsWinNT", w32_IsWinNT, file);
238 newXS("Win32::IsWin95", w32_IsWin95, file);
239 newXS("Win32::IsWinCE", w32_IsWinCE, file);
240 newXS("Win32::CopyFile", w32_CopyFile, file);
241 newXS("Win32::Sleep", w32_Sleep, file);
242 newXS("Win32::MessageBox", w32_MessageBox, file);
243 newXS("Win32::GetPowerStatus", w32_GetPowerStatus, file);
244 newXS("Win32::GetOemInfo", w32_GetOemInfo, file);
245 newXS("Win32::ShellEx", w32_ShellEx, file);
249 Opening files for read-write is currently not supported if
250 they use stdio (normal perl file handles).
252 If you find bugs or if it does not work at all on your
253 device, send mail to the address below. Please report
254 the details of your device (processor, ceversion,
255 devicetype (hpc/palm/pocket)) and the date of the downloaded
260 Currently installation instructions are at L<http://perlce.sourceforge.net/>.
262 After installation & testing processes will stabilize, information will
265 =head1 ACKNOWLEDGEMENTS
267 The port for Win32 was used as a reference.
269 =head1 History of WinCE port
275 Initial port of perl to WinCE. It was performed in separate directory
276 named C<wince>. This port was based on contents of C<./win32> directory.
277 C<miniperl> was not built, user must have HOST perl and properly edit
278 C<makefile.ce> to reflect this.
282 wince port was kept in the same C<./wince> directory, and C<wince/Makefile.ce>
283 was used to invoke native compiler to create HOST miniperl, which then
284 facilitates cross-compiling process.
285 Extension building support was added.
289 Two directories C<./win32> and C<./wince> were merged, so perlce build
290 process comes in C<./win32> directory.
299 =item Rainer Keuchel <coyxc@rainer-keuchel.de>
301 provided initial port of Perl, which appears to be most essential work, as
302 it was a breakthrough on having Perl ported at all.
303 Many thanks and obligations to Rainer!
305 =item Vadim Konovalov
307 made further support of WinCE port.