Commit | Line | Data |
---|---|---|
e1caacb4 JH |
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 | ||
7a5cdbdf | 5 | =head1 NAME |
e1caacb4 | 6 | |
7a5cdbdf | 7 | perlce - Perl for WinCE |
e1caacb4 | 8 | |
74fe5f67 NC |
9 | =head1 Building Perl for WinCE |
10 | ||
11 | =head2 DESCRIPTION | |
e1caacb4 | 12 | |
dab75801 | 13 | This file gives the instructions for building Perl5.8 and above for |
e1caacb4 JH |
14 | WinCE. Please read and understand the terms under which this |
15 | software is distributed. | |
16 | ||
74fe5f67 | 17 | =head2 General explanations on cross-compiling WinCE |
e1caacb4 | 18 | |
74fe5f67 NC |
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. | |
dab75801 | 34 | |
74fe5f67 NC |
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. | |
dab75801 | 37 | |
74fe5f67 NC |
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. | |
e1caacb4 | 40 | |
74fe5f67 NC |
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 | |
42272d83 | 60 | |
74fe5f67 NC |
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 | |
e1caacb4 | 68 | |
dab75801 JH |
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 | |
e1caacb4 | 82 | |
74fe5f67 NC |
83 | Needed source files can be downloaded at |
84 | L<http://www.rainer-keuchel.de/wince/dirlist.html> | |
e1caacb4 | 85 | |
74fe5f67 | 86 | =head3 Make |
e1caacb4 | 87 | |
74fe5f67 | 88 | Normally you only need to edit ./wince/compile.bat |
dab75801 | 89 | to reflect your system and run it. |
e1caacb4 | 90 | |
dab75801 JH |
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. | |
e1caacb4 | 95 | |
42272d83 | 96 | To prepare distribution you need to do following: |
dab75801 JH |
97 | |
98 | =over 4 | |
99 | ||
100 | =item * go to ./wince subdirectory | |
101 | ||
102 | =item * edit file compile.bat | |
e1caacb4 | 103 | |
dab75801 JH |
104 | =item * run |
105 | compile.bat | |
e1caacb4 | 106 | |
dab75801 JH |
107 | =item * run |
108 | compile.bat dist | |
e1caacb4 | 109 | |
dab75801 JH |
110 | =back |
111 | ||
42272d83 JH |
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 | ||
42272d83 JH |
153 | All questions related to building for WinCE devices could be asked in |
154 | perlce-users@lists.sourceforge.net mailing list. | |
e1caacb4 | 155 | |
74fe5f67 NC |
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 | ||
7a5cdbdf | 279 | =head1 ACKNOWLEDGEMENTS |
e1caacb4 JH |
280 | |
281 | The port for Win32 was used as a reference. | |
282 | ||
dab75801 | 283 | =head1 AUTHORS |
e1caacb4 | 284 | |
74fe5f67 NC |
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 | |
dab75801 | 298 |