| 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 | F<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 | F<miniperl> is built using F<./win32/Makefile>; this is part of normal |
| 28 | build process invoked as dependency from wince/Makefile.ce |
| 29 | |
| 30 | =item * |
| 31 | |
| 32 | After F<miniperl> is built, F<configpm> is invoked to create right F<Config.pm> |
| 33 | in right place and its corresponding Cross.pm. |
| 34 | |
| 35 | Unlike Win32 build, miniperl will not have F<Config.pm> of host within reach; |
| 36 | it rather will use F<Config.pm> from within cross-compilation directories. |
| 37 | |
| 38 | File F<Cross.pm> is dead simple: for given cross-architecture places in @INC |
| 39 | a path where perl modules are, and right F<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 F<Config.pm>. If it does not give an error -- wrong F<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 | F<Config.pm> for further compilations. |
| 47 | |
| 48 | =item * |
| 49 | |
| 50 | During extensions build phase, a script F<./win32/buldext.pl> is invoked, |
| 51 | which in turn steps in F<./ext> subdirectories and performs a build of |
| 52 | each extension in turn. |
| 53 | |
| 54 | All invokes of F<Makefile.PL> are provided with C<-MCross> so to enable cross- |
| 55 | compile. |
| 56 | |
| 57 | =back |
| 58 | |
| 59 | =head2 BUILD |
| 60 | |
| 61 | This section describes the steps to be performed to build PerlCE. |
| 62 | You may find additional information about building perl for WinCE |
| 63 | at L<http://perlce.sourceforge.net> and some pre-built binaries. |
| 64 | |
| 65 | =head3 Tools & SDK |
| 66 | |
| 67 | For compiling, you need following: |
| 68 | |
| 69 | =over 4 |
| 70 | |
| 71 | =item * Microsoft Embedded Visual Tools |
| 72 | |
| 73 | =item * Microsoft Visual C++ |
| 74 | |
| 75 | =item * Rainer Keuchel's celib-sources |
| 76 | |
| 77 | =item * Rainer Keuchel's console-sources |
| 78 | |
| 79 | =back |
| 80 | |
| 81 | Needed source files can be downloaded at |
| 82 | L<http://perlce.sourceforge.net> |
| 83 | |
| 84 | =head3 Make |
| 85 | |
| 86 | Normally you only need to edit F<./win32/ce-helpers/compile.bat> |
| 87 | to reflect your system and run it. |
| 88 | |
| 89 | File F<./win32/ce-helpers/compile.bat> is actually a wrapper to call |
| 90 | C<nmake -f makefile.ce> with appropriate parameters and it accepts extra |
| 91 | parameters and forwards them to C<nmake> command as additional |
| 92 | arguments. You should pass target this way. |
| 93 | |
| 94 | To prepare distribution you need to do following: |
| 95 | |
| 96 | =over 4 |
| 97 | |
| 98 | =item * go to F<./win32> subdirectory |
| 99 | |
| 100 | =item * edit file F<./win32/ce-helpers/compile.bat> |
| 101 | |
| 102 | =item * run |
| 103 | compile.bat |
| 104 | |
| 105 | =item * run |
| 106 | compile.bat dist |
| 107 | |
| 108 | =back |
| 109 | |
| 110 | F<Makefile.ce> has C<CROSS_NAME> macro, and it is used further to refer to |
| 111 | your cross-compilation scheme. You could assign a name to it, but this |
| 112 | is not necessary, because by default it is assigned after your machine |
| 113 | configuration name, such as "wince-sh3-hpc-wce211", and this is enough |
| 114 | to distinguish different builds at the same time. This option could be |
| 115 | handy for several different builds on same platform to perform, say, |
| 116 | threaded build. In a following example we assume that all required |
| 117 | environment variables are set properly for C cross-compiler (a special |
| 118 | *.bat file could fit perfectly to this purpose) and your F<compile.bat> |
| 119 | has proper "MACHINE" parameter set, to, say, C<wince-mips-pocket-wce300>. |
| 120 | |
| 121 | compile.bat |
| 122 | compile.bat dist |
| 123 | compile.bat CROSS_NAME=mips-wce300-thr "USE_ITHREADS=define" ^ |
| 124 | "USE_IMP_SYS=define" "USE_MULTI=define" |
| 125 | compile.bat CROSS_NAME=mips-wce300-thr "USE_ITHREADS=define" ^ |
| 126 | "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: C<wince-mips-pocket-wce300> and C<mips-wce300-thr>. |
| 130 | |
| 131 | Target C<dist> prepares distribution file set. Target C<zipdist> performs |
| 132 | same as C<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 F<Config.pm> |
| 136 | for cross-compilation ("foreign" F<Config.pm>) and those are hidden inside |
| 137 | F<../xlib/$(CROSS_NAME)> with other auxiliary files, but, and this is important to |
| 138 | note, there should be B<no> F<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 | F<perlce-user@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 F<stdin.txt>, |
| 164 | F<stdout.txt> and F<stderr.txt>, so you might examine them if your |
| 165 | console has only a limited 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 F</perl-stdout.txt> and |
| 172 | F</perl-stderr.txt.> |
| 173 | |
| 174 | PerlIDE is handy to deal with perlce. |
| 175 | |
| 176 | =head2 LIMITATIONS |
| 177 | |
| 178 | No fork(), pipe(), popen() etc. |
| 179 | |
| 180 | =head2 ENVIRONMENT |
| 181 | |
| 182 | All environment vars must be stored in HKLM\Environment as |
| 183 | strings. They are read at process startup. |
| 184 | |
| 185 | =over |
| 186 | |
| 187 | =item PERL5LIB |
| 188 | |
| 189 | Usual perl lib path (semi-list). |
| 190 | |
| 191 | =item PATH |
| 192 | |
| 193 | Semi-list for executables. |
| 194 | |
| 195 | =item TMP |
| 196 | |
| 197 | - Tempdir. |
| 198 | |
| 199 | =item UNIXROOTPATH |
| 200 | |
| 201 | - Root for accessing some special files, i.e. F</dev/null>, F</etc/services>. |
| 202 | |
| 203 | =item ROWS/COLS |
| 204 | |
| 205 | - Rows/cols for console. |
| 206 | |
| 207 | =item HOME |
| 208 | |
| 209 | - Home directory. |
| 210 | |
| 211 | =item CONSOLEFONTSIZE |
| 212 | |
| 213 | - Size for console font. |
| 214 | |
| 215 | =back |
| 216 | |
| 217 | You can set these with cereg.exe, a (remote) registry editor |
| 218 | or via the PerlIDE. |
| 219 | |
| 220 | =head2 REGISTRY |
| 221 | |
| 222 | To start perl by clicking on a perl source file, you have |
| 223 | to make the according entries in HKCR (see F<ce-helpers/wince-reg.bat>). |
| 224 | cereg.exe (which must be executed on a desktop pc with |
| 225 | ActiveSync) is reported not to work on some devices. |
| 226 | You have to create the registry entries by hand using a |
| 227 | registry editor. |
| 228 | |
| 229 | =head2 XS |
| 230 | |
| 231 | The following Win32-Methods are built-in: |
| 232 | |
| 233 | newXS("Win32::GetCwd", w32_GetCwd, file); |
| 234 | newXS("Win32::SetCwd", w32_SetCwd, file); |
| 235 | newXS("Win32::GetTickCount", w32_GetTickCount, file); |
| 236 | newXS("Win32::GetOSVersion", w32_GetOSVersion, file); |
| 237 | newXS("Win32::IsWinNT", w32_IsWinNT, file); |
| 238 | newXS("Win32::IsWin95", w32_IsWin95, file); |
| 239 | newXS("Win32::IsWinCE", w32_IsWinCE, file); |
| 240 | newXS("Win32::CopyFile", w32_CopyFile, file); |
| 241 | newXS("Win32::Sleep", w32_Sleep, file); |
| 242 | newXS("Win32::MessageBox", w32_MessageBox, file); |
| 243 | newXS("Win32::GetPowerStatus", w32_GetPowerStatus, file); |
| 244 | newXS("Win32::GetOemInfo", w32_GetOemInfo, file); |
| 245 | newXS("Win32::ShellEx", w32_ShellEx, file); |
| 246 | |
| 247 | =head2 BUGS |
| 248 | |
| 249 | Opening files for read-write is currently not supported if |
| 250 | they use stdio (normal perl file handles). |
| 251 | |
| 252 | If you find bugs or if it does not work at all on your |
| 253 | device, send mail to the address below. Please report |
| 254 | the details of your device (processor, ceversion, |
| 255 | devicetype (hpc/palm/pocket)) and the date of the downloaded |
| 256 | files. |
| 257 | |
| 258 | =head2 INSTALLATION |
| 259 | |
| 260 | Currently installation instructions are at L<http://perlce.sourceforge.net/>. |
| 261 | |
| 262 | After installation & testing processes will stabilize, information will |
| 263 | be more precise. |
| 264 | |
| 265 | =head1 ACKNOWLEDGEMENTS |
| 266 | |
| 267 | The port for Win32 was used as a reference. |
| 268 | |
| 269 | =head1 History of WinCE port |
| 270 | |
| 271 | =over |
| 272 | |
| 273 | =item 5.6.0 |
| 274 | |
| 275 | Initial port of perl to WinCE. It was performed in separate directory |
| 276 | named F<wince>. This port was based on contents of F<./win32> directory. |
| 277 | F<miniperl> was not built, user must have HOST perl and properly edit |
| 278 | F<makefile.ce> to reflect this. |
| 279 | |
| 280 | =item 5.8.0 |
| 281 | |
| 282 | wince port was kept in the same F<./wince> directory, and F<wince/Makefile.ce> |
| 283 | was used to invoke native compiler to create HOST miniperl, which then |
| 284 | facilitates cross-compiling process. |
| 285 | Extension building support was added. |
| 286 | |
| 287 | =item 5.9.4 |
| 288 | |
| 289 | Two directories F<./win32> and F<./wince> were merged, so perlce build |
| 290 | process comes in F<./win32> directory. |
| 291 | |
| 292 | =back |
| 293 | |
| 294 | =head1 AUTHORS |
| 295 | |
| 296 | =over |
| 297 | |
| 298 | =item Rainer Keuchel <coyxc@rainer-keuchel.de> |
| 299 | |
| 300 | provided initial port of Perl, which appears to be most essential work, as |
| 301 | it was a breakthrough on having Perl ported at all. |
| 302 | Many thanks and obligations to Rainer! |
| 303 | |
| 304 | =item Vadim Konovalov |
| 305 | |
| 306 | made further support of WinCE port. |
| 307 | |
| 308 | =back |