1If you read this file _as_is_, just ignore the funny characters you 2see. It is written in the POD format (see pod/perlpod.pod) which is 3specifically designed to be readable as is. 4 5=head1 NAME 6 7perlce - Perl for WinCE 8 9=head1 Building Perl for WinCE 10 11=head2 WARNING 12 13B<< Much of this document has become very out of date and needs updating, 14rewriting or deleting. The build process was overhauled during the 5.19 15development track and the current instructions as of that time are given 16in L</CURRENT BUILD INSTRUCTIONS>; the previous build instructions, which 17are largely superseded but may still contain some useful information, are 18left in L</OLD BUILD INSTRUCTIONS> but really need removing after anything 19of use has been extracted from them. >> 20 21=head2 DESCRIPTION 22 23This file gives the instructions for building Perl5.8 and above for 24WinCE. Please read and understand the terms under which this 25software is distributed. 26 27=head2 General explanations on cross-compiling WinCE 28 29=over 30 31=item * 32 33F<miniperl> is built. This is a single executable (without DLL), intended 34to run on Win32, and it will facilitate remaining build process; all binaries 35built after it are foreign and should not run locally. 36 37F<miniperl> is built using F<./win32/Makefile>; this is part of normal 38build process invoked as dependency from wince/Makefile.ce 39 40=item * 41 42After F<miniperl> is built, F<configpm> is invoked to create right F<Config.pm> 43in right place and its corresponding Cross.pm. 44 45Unlike Win32 build, miniperl will not have F<Config.pm> of host within reach; 46it rather will use F<Config.pm> from within cross-compilation directories. 47 48File F<Cross.pm> is dead simple: for given cross-architecture places in @INC 49a path where perl modules are, and right F<Config.pm> in that place. 50 51That said, C<miniperl -Ilib -MConfig -we 1> should report an error, because 52it can not find F<Config.pm>. If it does not give an error -- wrong F<Config.pm> 53is substituted, and resulting binaries will be a mess. 54 55C<miniperl -MCross -MConfig -we 1> should run okay, and it will provide right 56F<Config.pm> for further compilations. 57 58=item * 59 60During extensions build phase, a script F<./win32/buildext.pl> is invoked, 61which in turn steps in F<./ext> subdirectories and performs a build of 62each extension in turn. 63 64All invokes of F<Makefile.PL> are provided with C<-MCross> so to enable cross- 65compile. 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 72Windows then change "C:\Program Files" to "C:\Program Files (x86)" throughout.) 73 741. Install EVC4 from 75 76 http://download.microsoft.com/download/c/3/f/c3f8b58b-9753-4c2e-8b96-2dfe3476a2f7/eVC4.exe 77 78Use the key mentioned at 79 80 http://download.cnet.com/Microsoft-eMbedded-Visual-C/3000-2212_4-10108490.html?tag=bc 81 82The installer is ancient and has a few bugs on the paths it uses. You 83will have to fix them later. Basically, some things go into "C:/Program 84Files/Windows CE Tools", others go into "C:/Windows CE Tools" regardless 85of the path you gave to the installer (the default will be "C:/Windows 86CE Tools"). Reboots will be required for the installer to proceed. Also 87.c and .h associations with Visual Studio might get overridden when 88installing EVC4. You have been warned. 89 902. Download celib from GitHub (using "Download ZIP") at 91 92 https://github.com/bulk88/celib 93 94Extract it to a spaceless path but not into the perl build source. 95I call this directory "celib-palm-3.0" but in the GitHub 96snapshot 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 99binary by linking in CE 3.0 ARM asm; the linker doesn't care. Windows 100Mobile/WinCE are backwards compatible with machine code like Desktop Windows. 101 1023. Download console-1.3-src.tar.gz from 103 104 http://sourceforge.net/projects/perlce/files/PerlCE%20support%20files/console/ 105 106Extract it to a spaceless path but not into the perl build source. 107Don'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 110binary by linking in CE 3.0 ARM asm; the linker doesn't care. Windows 111Mobile/WinCE are backwards compatible with machine code like Desktop Windows. 112 1134. Open a command prompt, run your regular batch file to set the environment 114for desktop Visual C building, goto the perl source directory, cd into win32/, 115fill out Makefile, and do a "nmake all" to build a Desktop Perl. 116 1175. Open win32/Makefile.ce in a text editor and do something similar to the 118following 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 125Also 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 145to 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 165so wince-arm-pocket-wce400 is the MACHINE type. 166 1676. Use a text editor to open "C:\Program Files\Microsoft eMbedded C++ 1684.0\EVC\WCE400\BIN\WCEARMV4.BAT". Look for 169 170 if "%SDKROOT%"=="" set SDKROOT=... 171 172On 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 174Tools\wce400\STANDARDSDK\Include\Armv4" exists on your disk. If not 175the SDKROOT need to be changed to "C:\Program Files\Windows CE Tools". 176 177Goto celib-palm-3.0\inc\cewin32.h, search for 178 179 typedef struct _ABC { 180 181and uncomment the struct. 182 1837. Open another command prompt, ensure PLATFORM is not set to anything 184already unless you know what you're doing (so that the correct default 185value is set by the next command), and run "C:\Program Files\Microsoft 186eMbedded C++ 4.0\EVC\WCE400\BIN\WCEARMV4.BAT" 187 1888. In the WinCE command prompt you made with WCEARMV4.BAT, goto the perl 189source directory, cd into win32/ and run "nmake -f Makefile.ce". 190 1919. The ARM perl interpreter (perl519.dll and perl.exe) will be in something 192like "C:\perl519\src\win32\wince-arm-pocket-wce400", with the XS DLLs in 193"C:\perl519\src\xlib\wince-arm-hpc-wce400\auto". 194 195To prove success on the host machine, run 196"dumpbin /headers wince-arm-pocket-wce400\perl.exe" from the win32/ folder 197and 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 202This section describes the steps to be performed to build PerlCE. 203You may find additional information about building perl for WinCE 204at L<http://perlce.sourceforge.net> and some pre-built binaries. 205 206=head3 Tools & SDK 207 208For 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 222Needed source files can be downloaded at 223L<http://perlce.sourceforge.net> 224 225=head3 Make 226 227Normally you only need to edit F<./win32/ce-helpers/compile.bat> 228to reflect your system and run it. 229 230File F<./win32/ce-helpers/compile.bat> is actually a wrapper to call 231C<nmake -f makefile.ce> with appropriate parameters and it accepts extra 232parameters and forwards them to C<nmake> command as additional 233arguments. You should pass target this way. 234 235To 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 251F<Makefile.ce> has C<CROSS_NAME> macro, and it is used further to refer to 252your cross-compilation scheme. You could assign a name to it, but this 253is not necessary, because by default it is assigned after your machine 254configuration name, such as "wince-sh3-hpc-wce211", and this is enough 255to distinguish different builds at the same time. This option could be 256handy for several different builds on same platform to perform, say, 257threaded build. In a following example we assume that all required 258environment variables are set properly for C cross-compiler (a special 259*.bat file could fit perfectly to this purpose) and your F<compile.bat> 260has 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 269If all goes okay and no errors during a build, you'll get two independent 270distributions: C<wince-mips-pocket-wce300> and C<mips-wce300-thr>. 271 272Target C<dist> prepares distribution file set. Target C<zipdist> performs 273same as C<dist> but additionally compresses distribution files into zip 274archive. 275 276NOTE: during a build there could be created a number (or one) of F<Config.pm> 277for cross-compilation ("foreign" F<Config.pm>) and those are hidden inside 278F<../xlib/$(CROSS_NAME)> with other auxiliary files, but, and this is important to 279note, there should be B<no> F<Config.pm> for host miniperl. 280If you'll get an error that perl could not find Config.pm somewhere in building 281process this means something went wrong. Most probably you forgot to 282specify a cross-compilation when invoking miniperl.exe to Makefile.PL 283When building an extension for cross-compilation your command line should 284look like 285 286 ..\miniperl.exe -I..\lib -MCross=mips-wce300-thr Makefile.PL 287 288or just 289 290 ..\miniperl.exe -I..\lib -MCross Makefile.PL 291 292to refer a cross-compilation that was created last time. 293 294All questions related to building for WinCE devices could be asked in 295F<perlce-user@lists.sourceforge.net> mailing list. 296 297=head1 Using Perl on WinCE 298 299=head2 DESCRIPTION 300 301PerlCE is currently linked with a simple console window, so it also 302works on non-hpc devices. 303 304The simple stdio implementation creates the files F<stdin.txt>, 305F<stdout.txt> and F<stderr.txt>, so you might examine them if your 306console has only a limited number of cols. 307 308When exitcode is non-zero, a message box appears, otherwise the 309console closes, so you might have to catch an exit with 310status 0 in your program to see any output. 311 312stdout/stderr now go into the files F</perl-stdout.txt> and 313F</perl-stderr.txt.> 314 315PerlIDE is handy to deal with perlce. 316 317=head2 LIMITATIONS 318 319No fork(), pipe(), popen() etc. 320 321=head2 ENVIRONMENT 322 323All environment vars must be stored in HKLM\Environment as 324strings. They are read at process startup. 325 326=over 327 328=item PERL5LIB 329 330Usual perl lib path (semi-list). 331 332=item PATH 333 334Semi-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 358You can set these with cereg.exe, a (remote) registry editor 359or via the PerlIDE. 360 361=head2 REGISTRY 362 363To start perl by clicking on a perl source file, you have 364to make the according entries in HKCR (see F<ce-helpers/wince-reg.bat>). 365cereg.exe (which must be executed on a desktop pc with 366ActiveSync) is reported not to work on some devices. 367You have to create the registry entries by hand using a 368registry editor. 369 370=head2 XS 371 372The 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 390Opening files for read-write is currently not supported if 391they use stdio (normal perl file handles). 392 393If you find bugs or if it does not work at all on your 394device, send mail to the address below. Please report 395the details of your device (processor, ceversion, 396devicetype (hpc/palm/pocket)) and the date of the downloaded 397files. 398 399=head2 INSTALLATION 400 401Currently installation instructions are at L<http://perlce.sourceforge.net/>. 402 403After installation & testing processes will stabilize, information will 404be more precise. 405 406=head1 ACKNOWLEDGEMENTS 407 408The 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 416Initial port of perl to WinCE. It was performed in separate directory 417named F<wince>. This port was based on contents of F<./win32> directory. 418F<miniperl> was not built, user must have HOST perl and properly edit 419F<makefile.ce> to reflect this. 420 421=item 5.8.0 422 423wince port was kept in the same F<./wince> directory, and F<wince/Makefile.ce> 424was used to invoke native compiler to create HOST miniperl, which then 425facilitates cross-compiling process. 426Extension building support was added. 427 428=item 5.9.4 429 430Two directories F<./win32> and F<./wince> were merged, so perlce build 431process 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 441provided initial port of Perl, which appears to be most essential work, as 442it was a breakthrough on having Perl ported at all. 443Many thanks and obligations to Rainer! 444 445=item Vadim Konovalov 446 447made further support of WinCE port. 448 449=item Daniel Dragan 450 451updated the build process during the 5.19 development track. 452 453=back 454