README.ce

   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/buildext.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