Commit | Line | Data |
---|---|---|
e1caacb4 JH |
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. | |
4 | ||
c7bcd97d | 5 | =head1 NAME |
e1caacb4 | 6 | |
c7bcd97d | 7 | perlce - Perl for WinCE |
e1caacb4 | 8 | |
75472953 VK |
9 | =head1 Building Perl for WinCE |
10 | ||
69104b65 SH |
11 | =head2 WARNING |
12 | ||
13 | B<< Much of this document has become very out of date and needs updating, | |
14 | rewriting or deleting. The build process was overhauled during the 5.19 | |
15 | development track and the current instructions as of that time are given | |
16 | in L</CURRENT BUILD INSTRUCTIONS>; the previous build instructions, which | |
17 | are largely superseded but may still contain some useful information, are | |
18 | left in L</OLD BUILD INSTRUCTIONS> but really need removing after anything | |
19 | of use has been extracted from them. >> | |
20 | ||
75472953 | 21 | =head2 DESCRIPTION |
e1caacb4 | 22 | |
2e64bfdb | 23 | This file gives the instructions for building Perl5.8 and above for |
e1caacb4 JH |
24 | WinCE. Please read and understand the terms under which this |
25 | software is distributed. | |
26 | ||
75472953 | 27 | =head2 General explanations on cross-compiling WinCE |
e1caacb4 | 28 | |
75472953 VK |
29 | =over |
30 | ||
31 | =item * | |
32 | ||
9b15f68e | 33 | F<miniperl> is built. This is a single executable (without DLL), intended |
75472953 VK |
34 | to run on Win32, and it will facilitate remaining build process; all binaries |
35 | built after it are foreign and should not run locally. | |
36 | ||
9b15f68e | 37 | F<miniperl> is built using F<./win32/Makefile>; this is part of normal |
75472953 VK |
38 | build process invoked as dependency from wince/Makefile.ce |
39 | ||
40 | =item * | |
41 | ||
9b15f68e | 42 | After F<miniperl> is built, F<configpm> is invoked to create right F<Config.pm> |
75472953 | 43 | in right place and its corresponding Cross.pm. |
2e64bfdb | 44 | |
9b15f68e KW |
45 | Unlike Win32 build, miniperl will not have F<Config.pm> of host within reach; |
46 | it rather will use F<Config.pm> from within cross-compilation directories. | |
2e64bfdb | 47 | |
9b15f68e KW |
48 | File F<Cross.pm> is dead simple: for given cross-architecture places in @INC |
49 | a path where perl modules are, and right F<Config.pm> in that place. | |
e1caacb4 | 50 | |
75472953 | 51 | That said, C<miniperl -Ilib -MConfig -we 1> should report an error, because |
9b15f68e | 52 | it can not find F<Config.pm>. If it does not give an error -- wrong F<Config.pm> |
75472953 VK |
53 | is substituted, and resulting binaries will be a mess. |
54 | ||
55 | C<miniperl -MCross -MConfig -we 1> should run okay, and it will provide right | |
9b15f68e | 56 | F<Config.pm> for further compilations. |
75472953 VK |
57 | |
58 | =item * | |
59 | ||
9b15f68e KW |
60 | During extensions build phase, a script F<./win32/buldext.pl> is invoked, |
61 | which in turn steps in F<./ext> subdirectories and performs a build of | |
75472953 VK |
62 | each extension in turn. |
63 | ||
9b15f68e | 64 | All invokes of F<Makefile.PL> are provided with C<-MCross> so to enable cross- |
75472953 VK |
65 | compile. |
66 | ||
75472953 | 67 | =back |
8f33b42a | 68 | |
69104b65 SH |
69 | =head2 CURRENT BUILD INSTRUCTIONS |
70 | ||
71 | (These instructions assume the host is 32-bit Windows. If you're on 64-bit | |
72 | Windows then change "C:\Program Files" to "C:\Program Files (x86)" throughout.) | |
73 | ||
74 | 1. Install EVC4 from | |
75 | ||
76 | http://download.microsoft.com/download/c/3/f/c3f8b58b-9753-4c2e-8b96-2dfe3476a2f7/eVC4.exe | |
77 | ||
78 | Use the key mentioned at | |
79 | ||
80 | http://download.cnet.com/Microsoft-eMbedded-Visual-C/3000-2212_4-10108490.html?tag=bc | |
81 | ||
82 | The installer is ancient and has a few bugs on the paths it uses. You | |
83 | will have to fix them later. Basically, some things go into "C:/Program | |
84 | Files/Windows CE Tools", others go into "C:/Windows CE Tools" regardless | |
85 | of the path you gave to the installer (the default will be "C:/Windows | |
86 | CE Tools"). Reboots will be required for the installer to proceed. Also | |
87 | .c and .h associations with Visual Studio might get overridden when | |
88 | installing EVC4. You have been warned. | |
89 | ||
90 | 2. Download celib from GitHub (using "Download ZIP") at | |
91 | ||
92 | https://github.com/bulk88/celib | |
93 | ||
94 | Extract it to a spaceless path but not into the perl build source. | |
95 | I call this directory "celib-palm-3.0" but in the GitHub | |
96 | snapshot it will be called "celib-master". Make a copy of the | |
97 | "wince-arm-pocket-wce300-release" folder and rename the copy to | |
98 | "wince-arm-pocket-wce400". This is a hack so we can build a CE 4.0 | |
99 | binary by linking in CE 3.0 ARM asm; the linker doesn't care. Windows | |
100 | Mobile/WinCE are backwards compatible with machine code like Desktop Windows. | |
101 | ||
102 | 3. Download console-1.3-src.tar.gz from | |
103 | ||
104 | http://sourceforge.net/projects/perlce/files/PerlCE%20support%20files/console/ | |
105 | ||
106 | Extract it to a spaceless path but not into the perl build source. | |
107 | Don't extract it into the same directory as celib. Make a copy of the | |
108 | "wince-arm-pocket-wce300" folder and rename the copy to | |
109 | "wince-arm-pocket-wce400". This is a hack so we can build a CE 4.0 | |
110 | binary by linking in CE 3.0 ARM asm; the linker doesn't care. Windows | |
111 | Mobile/WinCE are backwards compatible with machine code like Desktop Windows. | |
112 | ||
113 | 4. Open a command prompt, run your regular batch file to set the environment | |
114 | for desktop Visual C building, goto the perl source directory, cd into win32/, | |
115 | fill out Makefile, and do a "nmake all" to build a Desktop Perl. | |
116 | ||
117 | 5. Open win32/Makefile.ce in a text editor and do something similar to the | |
118 | following patch. | |
119 | ||
120 | -CELIBDLLDIR = h:\src\wince\celib-palm-3.0 | |
121 | -CECONSOLEDIR = h:\src\wince\w32console | |
122 | +CELIBDLLDIR = C:\sources\celib-palm-3.0 | |
123 | +CECONSOLEDIR = C:\sources\w32console | |
124 | ||
125 | Also change | |
126 | ||
127 | !if "$(MACHINE)" == "" | |
128 | MACHINE=wince-arm-hpc-wce300 | |
129 | #MACHINE=wince-arm-hpc-wce211 | |
130 | #MACHINE=wince-sh3-hpc-wce211 | |
131 | #MACHINE=wince-mips-hpc-wce211 | |
132 | #MACHINE=wince-sh3-hpc-wce200 | |
133 | #MACHINE=wince-mips-hpc-wce200 | |
134 | #MACHINE=wince-arm-pocket-wce300 | |
135 | #MACHINE=wince-mips-pocket-wce300 | |
136 | #MACHINE=wince-sh3-pocket-wce300 | |
137 | #MACHINE=wince-x86em-pocket-wce300 | |
138 | #MACHINE=wince-mips-palm-wce211 | |
139 | #MACHINE=wince-sh3-palm-wce211 | |
140 | #MACHINE=wince-x86em-palm-wce211 | |
141 | #MACHINE=wince-x86-hpc-wce300 | |
142 | #MACHINE=wince-arm-pocket-wce400 | |
143 | !endif | |
144 | ||
145 | to | |
146 | ||
147 | !if "$(MACHINE)" == "" | |
148 | #MACHINE=wince-arm-hpc-wce300 | |
149 | #MACHINE=wince-arm-hpc-wce211 | |
150 | #MACHINE=wince-sh3-hpc-wce211 | |
151 | #MACHINE=wince-mips-hpc-wce211 | |
152 | #MACHINE=wince-sh3-hpc-wce200 | |
153 | #MACHINE=wince-mips-hpc-wce200 | |
154 | #MACHINE=wince-arm-pocket-wce300 | |
155 | #MACHINE=wince-mips-pocket-wce300 | |
156 | #MACHINE=wince-sh3-pocket-wce300 | |
157 | #MACHINE=wince-x86em-pocket-wce300 | |
158 | #MACHINE=wince-mips-palm-wce211 | |
159 | #MACHINE=wince-sh3-palm-wce211 | |
160 | #MACHINE=wince-x86em-palm-wce211 | |
161 | #MACHINE=wince-x86-hpc-wce300 | |
162 | MACHINE=wince-arm-pocket-wce400 | |
163 | !endif | |
164 | ||
165 | so wince-arm-pocket-wce400 is the MACHINE type. | |
166 | ||
167 | 6. Use a text editor to open "C:\Program Files\Microsoft eMbedded C++ | |
168 | 4.0\EVC\WCE400\BIN\WCEARMV4.BAT". Look for | |
169 | ||
170 | if "%SDKROOT%"=="" set SDKROOT=... | |
171 | ||
172 | On a new install it is "C:\Windows CE Tools". Goto | |
173 | "C:\Windows CE Tools" in a file manager and see if "C:\Windows CE | |
174 | Tools\wce400\STANDARDSDK\Include\Armv4" exists on your disk. If not | |
175 | the SDKROOT need to be changed to "C:\Program Files\Windows CE Tools". | |
176 | ||
177 | Goto celib-palm-3.0\inc\cewin32.h, search for | |
178 | ||
179 | typedef struct _ABC { | |
180 | ||
181 | and uncomment the struct. | |
182 | ||
183 | 7. Open another command prompt, ensure PLATFORM is not set to anything | |
184 | already unless you know what you're doing (so that the correct default | |
185 | value is set by the next command), and run "C:\Program Files\Microsoft | |
186 | eMbedded C++ 4.0\EVC\WCE400\BIN\WCEARMV4.BAT" | |
187 | ||
188 | 8. In the WinCE command prompt you made with WCEARMV4.BAT, goto the perl | |
189 | source directory, cd into win32/ and run "nmake -f Makefile.ce". | |
190 | ||
191 | 9. The ARM perl interpreter (perl519.dll and perl.exe) will be in something | |
192 | like "C:\perl519\src\win32\wince-arm-pocket-wce400", with the XS DLLs in | |
193 | "C:\perl519\src\xlib\wince-arm-hpc-wce400\auto". | |
194 | ||
195 | To prove success on the host machine, run | |
196 | "dumpbin /headers wince-arm-pocket-wce400\perl.exe" from the win32/ folder | |
197 | and look for "machine (ARM)" in the FILE HEADER VALUES and | |
198 | "subsystem (Windows CE GUI)" in the OPTIONAL HEADER VALUES. | |
199 | ||
200 | =head2 OLD BUILD INSTRUCTIONS | |
75472953 VK |
201 | |
202 | This section describes the steps to be performed to build PerlCE. | |
203 | You may find additional information about building perl for WinCE | |
204 | at L<http://perlce.sourceforge.net> and some pre-built binaries. | |
205 | ||
206 | =head3 Tools & SDK | |
e1caacb4 | 207 | |
2e64bfdb JH |
208 | For compiling, you need following: |
209 | ||
210 | =over 4 | |
211 | ||
212 | =item * Microsoft Embedded Visual Tools | |
213 | ||
214 | =item * Microsoft Visual C++ | |
215 | ||
216 | =item * Rainer Keuchel's celib-sources | |
217 | ||
218 | =item * Rainer Keuchel's console-sources | |
219 | ||
220 | =back | |
e1caacb4 | 221 | |
75472953 | 222 | Needed source files can be downloaded at |
464a08e7 | 223 | L<http://perlce.sourceforge.net> |
e1caacb4 | 224 | |
75472953 | 225 | =head3 Make |
e1caacb4 | 226 | |
9b15f68e | 227 | Normally you only need to edit F<./win32/ce-helpers/compile.bat> |
2e64bfdb | 228 | to reflect your system and run it. |
e1caacb4 | 229 | |
9b15f68e | 230 | File F<./win32/ce-helpers/compile.bat> is actually a wrapper to call |
45496817 VK |
231 | C<nmake -f makefile.ce> with appropriate parameters and it accepts extra |
232 | parameters and forwards them to C<nmake> command as additional | |
2e64bfdb | 233 | arguments. You should pass target this way. |
e1caacb4 | 234 | |
8f33b42a | 235 | To prepare distribution you need to do following: |
2e64bfdb JH |
236 | |
237 | =over 4 | |
238 | ||
9b15f68e | 239 | =item * go to F<./win32> subdirectory |
2e64bfdb | 240 | |
9b15f68e | 241 | =item * edit file F<./win32/ce-helpers/compile.bat> |
e1caacb4 | 242 | |
2e64bfdb JH |
243 | =item * run |
244 | compile.bat | |
e1caacb4 | 245 | |
2e64bfdb JH |
246 | =item * run |
247 | compile.bat dist | |
e1caacb4 | 248 | |
2e64bfdb JH |
249 | =back |
250 | ||
9b15f68e | 251 | F<Makefile.ce> has C<CROSS_NAME> macro, and it is used further to refer to |
8f33b42a VK |
252 | your cross-compilation scheme. You could assign a name to it, but this |
253 | is not necessary, because by default it is assigned after your machine | |
254 | configuration name, such as "wince-sh3-hpc-wce211", and this is enough | |
255 | to distinguish different builds at the same time. This option could be | |
256 | handy for several different builds on same platform to perform, say, | |
257 | threaded build. In a following example we assume that all required | |
258 | environment variables are set properly for C cross-compiler (a special | |
9b15f68e | 259 | *.bat file could fit perfectly to this purpose) and your F<compile.bat> |
45496817 | 260 | has proper "MACHINE" parameter set, to, say, C<wince-mips-pocket-wce300>. |
8f33b42a VK |
261 | |
262 | compile.bat | |
263 | compile.bat dist | |
1dcc3c19 DG |
264 | compile.bat CROSS_NAME=mips-wce300-thr "USE_ITHREADS=define" ^ |
265 | "USE_IMP_SYS=define" "USE_MULTI=define" | |
266 | compile.bat CROSS_NAME=mips-wce300-thr "USE_ITHREADS=define" ^ | |
267 | "USE_IMP_SYS=define" "USE_MULTI=define" dist | |
8f33b42a VK |
268 | |
269 | If all goes okay and no errors during a build, you'll get two independent | |
45496817 | 270 | distributions: C<wince-mips-pocket-wce300> and C<mips-wce300-thr>. |
8f33b42a | 271 | |
45496817 VK |
272 | Target C<dist> prepares distribution file set. Target C<zipdist> performs |
273 | same as C<dist> but additionally compresses distribution files into zip | |
8f33b42a VK |
274 | archive. |
275 | ||
9b15f68e KW |
276 | NOTE: during a build there could be created a number (or one) of F<Config.pm> |
277 | for cross-compilation ("foreign" F<Config.pm>) and those are hidden inside | |
278 | F<../xlib/$(CROSS_NAME)> with other auxiliary files, but, and this is important to | |
279 | note, there should be B<no> F<Config.pm> for host miniperl. | |
8f33b42a VK |
280 | If you'll get an error that perl could not find Config.pm somewhere in building |
281 | process this means something went wrong. Most probably you forgot to | |
282 | specify a cross-compilation when invoking miniperl.exe to Makefile.PL | |
283 | When building an extension for cross-compilation your command line should | |
284 | look like | |
285 | ||
286 | ..\miniperl.exe -I..\lib -MCross=mips-wce300-thr Makefile.PL | |
287 | ||
288 | or just | |
289 | ||
290 | ..\miniperl.exe -I..\lib -MCross Makefile.PL | |
291 | ||
292 | to refer a cross-compilation that was created last time. | |
293 | ||
8f33b42a | 294 | All questions related to building for WinCE devices could be asked in |
ef39d023 | 295 | F<perlce-user@lists.sourceforge.net> mailing list. |
e1caacb4 | 296 | |
75472953 VK |
297 | =head1 Using Perl on WinCE |
298 | ||
299 | =head2 DESCRIPTION | |
300 | ||
301 | PerlCE is currently linked with a simple console window, so it also | |
302 | works on non-hpc devices. | |
303 | ||
9b15f68e KW |
304 | The simple stdio implementation creates the files F<stdin.txt>, |
305 | F<stdout.txt> and F<stderr.txt>, so you might examine them if your | |
f858446f | 306 | console has only a limited number of cols. |
75472953 VK |
307 | |
308 | When exitcode is non-zero, a message box appears, otherwise the | |
309 | console closes, so you might have to catch an exit with | |
310 | status 0 in your program to see any output. | |
311 | ||
9b15f68e KW |
312 | stdout/stderr now go into the files F</perl-stdout.txt> and |
313 | F</perl-stderr.txt.> | |
45496817 VK |
314 | |
315 | PerlIDE is handy to deal with perlce. | |
75472953 VK |
316 | |
317 | =head2 LIMITATIONS | |
318 | ||
319 | No fork(), pipe(), popen() etc. | |
320 | ||
321 | =head2 ENVIRONMENT | |
322 | ||
323 | All environment vars must be stored in HKLM\Environment as | |
324 | strings. They are read at process startup. | |
325 | ||
45496817 VK |
326 | =over |
327 | ||
328 | =item PERL5LIB | |
329 | ||
330 | Usual perl lib path (semi-list). | |
331 | ||
332 | =item PATH | |
333 | ||
334 | Semi-list for executables. | |
335 | ||
336 | =item TMP | |
337 | ||
338 | - Tempdir. | |
339 | ||
340 | =item UNIXROOTPATH | |
341 | ||
9b15f68e | 342 | - Root for accessing some special files, i.e. F</dev/null>, F</etc/services>. |
45496817 VK |
343 | |
344 | =item ROWS/COLS | |
345 | ||
346 | - Rows/cols for console. | |
347 | ||
348 | =item HOME | |
349 | ||
350 | - Home directory. | |
351 | ||
352 | =item CONSOLEFONTSIZE | |
353 | ||
354 | - Size for console font. | |
355 | ||
356 | =back | |
75472953 VK |
357 | |
358 | You can set these with cereg.exe, a (remote) registry editor | |
359 | or via the PerlIDE. | |
360 | ||
361 | =head2 REGISTRY | |
362 | ||
363 | To start perl by clicking on a perl source file, you have | |
9b15f68e | 364 | to make the according entries in HKCR (see F<ce-helpers/wince-reg.bat>). |
75472953 VK |
365 | cereg.exe (which must be executed on a desktop pc with |
366 | ActiveSync) is reported not to work on some devices. | |
367 | You have to create the registry entries by hand using a | |
368 | registry editor. | |
369 | ||
75472953 VK |
370 | =head2 XS |
371 | ||
372 | The following Win32-Methods are built-in: | |
373 | ||
374 | newXS("Win32::GetCwd", w32_GetCwd, file); | |
375 | newXS("Win32::SetCwd", w32_SetCwd, file); | |
376 | newXS("Win32::GetTickCount", w32_GetTickCount, file); | |
377 | newXS("Win32::GetOSVersion", w32_GetOSVersion, file); | |
378 | newXS("Win32::IsWinNT", w32_IsWinNT, file); | |
379 | newXS("Win32::IsWin95", w32_IsWin95, file); | |
380 | newXS("Win32::IsWinCE", w32_IsWinCE, file); | |
381 | newXS("Win32::CopyFile", w32_CopyFile, file); | |
382 | newXS("Win32::Sleep", w32_Sleep, file); | |
383 | newXS("Win32::MessageBox", w32_MessageBox, file); | |
384 | newXS("Win32::GetPowerStatus", w32_GetPowerStatus, file); | |
385 | newXS("Win32::GetOemInfo", w32_GetOemInfo, file); | |
386 | newXS("Win32::ShellEx", w32_ShellEx, file); | |
387 | ||
388 | =head2 BUGS | |
389 | ||
390 | Opening files for read-write is currently not supported if | |
391 | they use stdio (normal perl file handles). | |
392 | ||
393 | If you find bugs or if it does not work at all on your | |
394 | device, send mail to the address below. Please report | |
395 | the details of your device (processor, ceversion, | |
396 | devicetype (hpc/palm/pocket)) and the date of the downloaded | |
397 | files. | |
398 | ||
399 | =head2 INSTALLATION | |
400 | ||
401 | Currently installation instructions are at L<http://perlce.sourceforge.net/>. | |
402 | ||
403 | After installation & testing processes will stabilize, information will | |
404 | be more precise. | |
405 | ||
c7bcd97d | 406 | =head1 ACKNOWLEDGEMENTS |
e1caacb4 JH |
407 | |
408 | The port for Win32 was used as a reference. | |
409 | ||
45496817 VK |
410 | =head1 History of WinCE port |
411 | ||
412 | =over | |
413 | ||
414 | =item 5.6.0 | |
415 | ||
416 | Initial port of perl to WinCE. It was performed in separate directory | |
9b15f68e KW |
417 | named F<wince>. This port was based on contents of F<./win32> directory. |
418 | F<miniperl> was not built, user must have HOST perl and properly edit | |
419 | F<makefile.ce> to reflect this. | |
45496817 VK |
420 | |
421 | =item 5.8.0 | |
422 | ||
9b15f68e | 423 | wince port was kept in the same F<./wince> directory, and F<wince/Makefile.ce> |
45496817 VK |
424 | was used to invoke native compiler to create HOST miniperl, which then |
425 | facilitates cross-compiling process. | |
426 | Extension building support was added. | |
427 | ||
428 | =item 5.9.4 | |
429 | ||
9b15f68e KW |
430 | Two directories F<./win32> and F<./wince> were merged, so perlce build |
431 | process comes in F<./win32> directory. | |
45496817 | 432 | |
ef39d023 | 433 | =back |
45496817 | 434 | |
2e64bfdb | 435 | =head1 AUTHORS |
e1caacb4 | 436 | |
75472953 VK |
437 | =over |
438 | ||
439 | =item Rainer Keuchel <coyxc@rainer-keuchel.de> | |
440 | ||
441 | provided initial port of Perl, which appears to be most essential work, as | |
442 | it was a breakthrough on having Perl ported at all. | |
443 | Many thanks and obligations to Rainer! | |
444 | ||
445 | =item Vadim Konovalov | |
446 | ||
447 | made further support of WinCE port. | |
448 | ||
69104b65 SH |
449 | =item Daniel Dragan |
450 | ||
451 | updated the build process during the 5.19 development track. | |
452 | ||
75472953 | 453 | =back |