| 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 | |
| 5 | =head1 NAME |
| 6 | |
| 7 | perlce - Perl for WinCE |
| 8 | |
| 9 | =head1 Building Perl for WinCE |
| 10 | |
| 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 | |
| 21 | =head2 DESCRIPTION |
| 22 | |
| 23 | This file gives the instructions for building Perl5.8 and above for |
| 24 | WinCE. Please read and understand the terms under which this |
| 25 | software is distributed. |
| 26 | |
| 27 | =head2 General explanations on cross-compiling WinCE |
| 28 | |
| 29 | =over |
| 30 | |
| 31 | =item * |
| 32 | |
| 33 | F<miniperl> is built. This is a single executable (without DLL), intended |
| 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 | |
| 37 | F<miniperl> is built using F<./win32/Makefile>; this is part of normal |
| 38 | build process invoked as dependency from wince/Makefile.ce |
| 39 | |
| 40 | =item * |
| 41 | |
| 42 | After F<miniperl> is built, F<configpm> is invoked to create right F<Config.pm> |
| 43 | in right place and its corresponding Cross.pm. |
| 44 | |
| 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. |
| 47 | |
| 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. |
| 50 | |
| 51 | That said, C<miniperl -Ilib -MConfig -we 1> should report an error, because |
| 52 | it can not find F<Config.pm>. If it does not give an error -- wrong F<Config.pm> |
| 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 |
| 56 | F<Config.pm> for further compilations. |
| 57 | |
| 58 | =item * |
| 59 | |
| 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 |
| 62 | each extension in turn. |
| 63 | |
| 64 | All invokes of F<Makefile.PL> are provided with C<-MCross> so to enable cross- |
| 65 | compile. |
| 66 | |
| 67 | =back |
| 68 | |
| 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 |
| 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 |
| 207 | |
| 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 |
| 221 | |
| 222 | Needed source files can be downloaded at |
| 223 | L<http://perlce.sourceforge.net> |
| 224 | |
| 225 | =head3 Make |
| 226 | |
| 227 | Normally you only need to edit F<./win32/ce-helpers/compile.bat> |
| 228 | to reflect your system and run it. |
| 229 | |
| 230 | File F<./win32/ce-helpers/compile.bat> is actually a wrapper to call |
| 231 | C<nmake -f makefile.ce> with appropriate parameters and it accepts extra |
| 232 | parameters and forwards them to C<nmake> command as additional |
| 233 | arguments. You should pass target this way. |
| 234 | |
| 235 | To prepare distribution you need to do following: |
| 236 | |
| 237 | =over 4 |
| 238 | |
| 239 | =item * go to F<./win32> subdirectory |
| 240 | |
| 241 | =item * edit file F<./win32/ce-helpers/compile.bat> |
| 242 | |
| 243 | =item * run |
| 244 | compile.bat |
| 245 | |
| 246 | =item * run |
| 247 | compile.bat dist |
| 248 | |
| 249 | =back |
| 250 | |
| 251 | F<Makefile.ce> has C<CROSS_NAME> macro, and it is used further to refer to |
| 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 |
| 259 | *.bat file could fit perfectly to this purpose) and your F<compile.bat> |
| 260 | has proper "MACHINE" parameter set, to, say, C<wince-mips-pocket-wce300>. |
| 261 | |
| 262 | compile.bat |
| 263 | compile.bat dist |
| 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 |
| 268 | |
| 269 | If all goes okay and no errors during a build, you'll get two independent |
| 270 | distributions: C<wince-mips-pocket-wce300> and C<mips-wce300-thr>. |
| 271 | |
| 272 | Target C<dist> prepares distribution file set. Target C<zipdist> performs |
| 273 | same as C<dist> but additionally compresses distribution files into zip |
| 274 | archive. |
| 275 | |
| 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. |
| 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 | |
| 294 | All questions related to building for WinCE devices could be asked in |
| 295 | F<perlce-user@lists.sourceforge.net> mailing list. |
| 296 | |
| 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 | |
| 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 |
| 306 | console has only a limited number of cols. |
| 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 | |
| 312 | stdout/stderr now go into the files F</perl-stdout.txt> and |
| 313 | F</perl-stderr.txt.> |
| 314 | |
| 315 | PerlIDE is handy to deal with perlce. |
| 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 | |
| 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 | |
| 342 | - Root for accessing some special files, i.e. F</dev/null>, F</etc/services>. |
| 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 |
| 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 |
| 364 | to make the according entries in HKCR (see F<ce-helpers/wince-reg.bat>). |
| 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 | |
| 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 | |
| 406 | =head1 ACKNOWLEDGEMENTS |
| 407 | |
| 408 | The port for Win32 was used as a reference. |
| 409 | |
| 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 |
| 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. |
| 420 | |
| 421 | =item 5.8.0 |
| 422 | |
| 423 | wince port was kept in the same F<./wince> directory, and F<wince/Makefile.ce> |
| 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 | |
| 430 | Two directories F<./win32> and F<./wince> were merged, so perlce build |
| 431 | process comes in F<./win32> directory. |
| 432 | |
| 433 | =back |
| 434 | |
| 435 | =head1 AUTHORS |
| 436 | |
| 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 | |
| 449 | =item Daniel Dragan |
| 450 | |
| 451 | updated the build process during the 5.19 development track. |
| 452 | |
| 453 | =back |