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 DESCRIPTION
  12
  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.
  16
  17 =head2 General explanations on cross-compiling WinCE
  18
  19 =over
  20
  21 =item *
  22
  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.
  26
  27 C<miniperl> is built using ../win32/Makefile; this is part of normal
  28 build process invoked as dependency from wince/Makefile.ce
  29
  30 =item *
  31
  32 After C<miniperl> is built, 'configpm' is invoked to create right Config.pm
  33 in right place and its corresponding Cross.pm.
  34
  35 Unlike Win32 build, miniperl will not have Config.pm of host within reach;
  36 it rather will use Config.pm from within cross-compilation directories.
  37
  38 File Cross.pm is dead simple: for given cross-architecture places in @INC
  39 a path where perl modules are, and right Config.pm in that place.
  40
  41 That said, C<miniperl -Ilib -MConfig -we 1> should report an error, because
  42 it can not find Config.pm. If it does not gives an error -- wrong Config.pm
  43 is substituted, and resulting binaries will be a mess.
  44
  45 C<miniperl -MCross -MConfig -we 1> should run okay, and it will provide right
  46 Config.pm for further compilations.
  47
  48 =item *
  49
  50 During extensions build phase, a script C<./win32/buldext.pl> is invoked,
  51 which in turn steps in ./ext subdirectories and performs a build of
  52 each extension in turn.
  53
  54 All invokes of Makefile.PL are provided with C<-MCross> so to enable cross-
  55 compile.
  56
  57 =item *
  58
  59 =back
  60
  61 =head2 BUILD
  62
  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.
  66
  67 =head3 Tools & SDK
  68
  69 For compiling, you need following:
  70
  71 =over 4
  72
  73 =item * Microsoft Embedded Visual Tools
  74
  75 =item * Microsoft Visual C++
  76
  77 =item * Rainer Keuchel's celib-sources
  78
  79 =item * Rainer Keuchel's console-sources
  80
  81 =back
  82
  83 Needed source files can be downloaded at
  84 L<http://www.rainer-keuchel.de/wince/dirlist.html>
  85
  86 =head3 Make
  87
  88 Normally you only need to edit ./wince/compile.bat
  89 to reflect your system and run it.
  90
  91 File ./wince/compile.bat is actually a wrapper to call
  92 nmake -f makefile.ce with appropriate parameters and it accepts extra
  93 parameters and forwards them to "nmake" command as additional
  94 arguments. You should pass target this way.
  95
  96 To prepare distribution you need to do following:
  97
  98 =over 4
  99
 100 =item * go to ./wince subdirectory
 101
 102 =item * edit file compile.bat
 103
 104 =item * run
 105   compile.bat
 106
 107 =item * run
 108   compile.bat dist
 109
 110 =back
 111
 112 makefile.ce has 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 compile.bat
 121 has proper "MACHINE" parameter set, to, say, "wince-mips-pocket-wce300".
 122
 123   compile.bat
 124   compile.bat dist
 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
 127
 128 If all goes okay and no errors during a build, you'll get two independent
 129 distributions: "wince-mips-pocket-wce300" and "mips-wce300-thr".
 130
 131 Target 'dist' prepares distribution file set. Target 'zipdist' performs
 132 same as 'dist' but additionally compresses distribution files into zip
 133 archive.
 134
 135 NOTE: during a build there could be created a number (or one) of Config.pm
 136 for cross-compilation ("foreign" Config.pm) and those are hidden inside
 137 ../xlib/$(CROSS_NAME) with other auxilary files, but, and this is important to
 138 note, there should be *no* 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
 143 look like
 144
 145   ..\miniperl.exe -I..\lib -MCross=mips-wce300-thr Makefile.PL
 146
 147 or just
 148
 149   ..\miniperl.exe -I..\lib -MCross Makefile.PL
 150
 151 to refer a cross-compilation that was created last time.
 152
 153 All questions related to building for WinCE devices could be asked in
 154 perlce-users@lists.sourceforge.net mailing list.
 155
 156 =head1 Using Perl on WinCE
 157
 158 =head2 DESCRIPTION
 159
 160 PerlCE is currently linked with a simple console window, so it also
 161 works on non-hpc devices.
 162
 163 The simple stdio implementation creates the files stdin.txt,
 164 stdout.txt and stderr.txt, so you might examine them if your
 165 console has only a liminted number of cols.
 166
 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.
 170
 171 stdout/stderr now go into the files /perl-stdout.txt and
 172 /perl-stderr.txt.
 173
 174 =head2 LIMITATIONS
 175
 176 No fork(), pipe(), popen() etc.
 177
 178 =head2 ENVIRONMENT
 179
 180 All environment vars must be stored in HKLM\Environment as
 181 strings. They are read at process startup.
 182
 183         PERL5LIB        - Usual perl lib path (semi-list).
 184         PATH            - Semi-list for executables.
 185         TMP             - Tempdir.
 186         UNIXROOTPATH    - Root for accessing some special files,
 187                           i.e. /dev/null, /etc/services.
 188         ROWS/COLS       - Rows/cols for console.
 189         HOME            - Home directory.
 190         CONSOLEFONTSIZE - Size for console font.
 191
 192 You can set these with cereg.exe, a (remote) registry editor
 193 or via the PerlIDE.
 194
 195 =head2 REGISTRY
 196
 197 To start perl by clicking on a perl source file, you have
 198 to make the according entries in HKCR (see wince-reg.bat).
 199 cereg.exe (which must be executed on a desktop pc with
 200 ActiveSync) is reported not to work on some devices.
 201 You have to create the registry entries by hand using a
 202 registry editor.
 203
 204 =head2 PERLFILES
 205
 206 The following files are a reasonable minimum if you want to do
 207 some socket stuff:
 208
 209         ./auto
 210         ./auto/DynaLoader
 211         ./auto/DynaLoader/autosplit.ix
 212         ./auto/DynaLoader/dl_expandspec.al
 213         ./auto/DynaLoader/dl_findfile.al
 214         ./auto/DynaLoader/dl_find_symbol_anywhere.al
 215         ./auto/IO
 216         ./auto/IO/IO.bs
 217         ./auto/IO/IO.dll
 218         ./auto/Socket
 219         ./auto/Socket/Socket.bs
 220         ./auto/Socket/Socket.dll
 221         ./Carp
 222         ./Carp/Heavy.pm
 223         ./Carp.pm
 224         ./Config.pm
 225         ./DynaLoader.pm
 226         ./Exporter
 227         ./Exporter/Heavy.pm
 228         ./Exporter.pm
 229         ./IO
 230         ./IO/File.pm
 231         ./IO/Handle.pm
 232         ./IO/Socket.pm
 233         ./IO.pm
 234         ./SelectSaver.pm
 235         ./Socket.pm
 236         ./strict.pm
 237         ./Symbol.pm
 238         ./warnings
 239         ./warnings/register.pm
 240         ./warnings.pm
 241         ./XSLoader.pm
 242
 243 =head2 XS
 244
 245 The following Win32-Methods are built-in:
 246
 247         newXS("Win32::GetCwd", w32_GetCwd, file);
 248         newXS("Win32::SetCwd", w32_SetCwd, file);
 249         newXS("Win32::GetTickCount", w32_GetTickCount, file);
 250         newXS("Win32::GetOSVersion", w32_GetOSVersion, file);
 251         newXS("Win32::IsWinNT", w32_IsWinNT, file);
 252         newXS("Win32::IsWin95", w32_IsWin95, file);
 253         newXS("Win32::IsWinCE", w32_IsWinCE, file);
 254         newXS("Win32::CopyFile", w32_CopyFile, file);
 255         newXS("Win32::Sleep", w32_Sleep, file);
 256         newXS("Win32::MessageBox", w32_MessageBox, file);
 257         newXS("Win32::GetPowerStatus", w32_GetPowerStatus, file);
 258         newXS("Win32::GetOemInfo", w32_GetOemInfo, file);
 259         newXS("Win32::ShellEx", w32_ShellEx, file);
 260
 261 =head2 BUGS
 262
 263 Opening files for read-write is currently not supported if
 264 they use stdio (normal perl file handles).
 265
 266 If you find bugs or if it does not work at all on your
 267 device, send mail to the address below. Please report
 268 the details of your device (processor, ceversion,
 269 devicetype (hpc/palm/pocket)) and the date of the downloaded
 270 files.
 271
 272 =head2 INSTALLATION
 273
 274 Currently installation instructions are at L<http://perlce.sourceforge.net/>.
 275
 276 After installation & testing processes will stabilize, information will
 277 be more precise.
 278
 279 =head1 ACKNOWLEDGEMENTS
 280
 281 The port for Win32 was used as a reference.
 282
 283 =head1 AUTHORS
 284
 285 =over
 286
 287 =item Rainer Keuchel <coyxc@rainer-keuchel.de>
 288
 289 provided initial port of Perl, which appears to be most essential work, as
 290 it was a breakthrough on having Perl ported at all.
 291 Many thanks and obligations to Rainer!
 292
 293 =item Vadim Konovalov
 294
 295 made further support of WinCE port.
 296
 297 =back
 298