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 | ||
c7bcd97d | 5 | =head1 NAME |
e1caacb4 | 6 | |
c7bcd97d | 7 | perlce - Perl for WinCE |
e1caacb4 | 8 | |
75472953 VK |
9 | =head1 Building Perl for WinCE |
10 | ||
11 | =head2 DESCRIPTION | |
e1caacb4 | 12 | |
2e64bfdb | 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 | ||
75472953 | 17 | =head2 General explanations on cross-compiling WinCE |
e1caacb4 | 18 | |
75472953 VK |
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 | ||
45496817 | 27 | C<miniperl> is built using C<./win32/Makefile>; this is part of normal |
75472953 VK |
28 | build process invoked as dependency from wince/Makefile.ce |
29 | ||
30 | =item * | |
31 | ||
45496817 | 32 | After C<miniperl> is built, C<configpm> is invoked to create right C<Config.pm> |
75472953 | 33 | in right place and its corresponding Cross.pm. |
2e64bfdb | 34 | |
45496817 VK |
35 | Unlike Win32 build, miniperl will not have C<Config.pm> of host within reach; |
36 | it rather will use C<Config.pm> from within cross-compilation directories. | |
2e64bfdb | 37 | |
45496817 VK |
38 | File C<Cross.pm> is dead simple: for given cross-architecture places in @INC |
39 | a path where perl modules are, and right C<Config.pm> in that place. | |
e1caacb4 | 40 | |
75472953 | 41 | That said, C<miniperl -Ilib -MConfig -we 1> should report an error, because |
608969de | 42 | it can not find C<Config.pm>. If it does not give an error -- wrong C<Config.pm> |
75472953 VK |
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 | |
45496817 | 46 | C<Config.pm> for further compilations. |
75472953 VK |
47 | |
48 | =item * | |
49 | ||
50 | During extensions build phase, a script C<./win32/buldext.pl> is invoked, | |
45496817 | 51 | which in turn steps in C<./ext> subdirectories and performs a build of |
75472953 VK |
52 | each extension in turn. |
53 | ||
45496817 | 54 | All invokes of C<Makefile.PL> are provided with C<-MCross> so to enable cross- |
75472953 VK |
55 | compile. |
56 | ||
75472953 | 57 | =back |
8f33b42a | 58 | |
75472953 VK |
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 | |
e1caacb4 | 66 | |
2e64bfdb JH |
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 | |
e1caacb4 | 80 | |
75472953 VK |
81 | Needed source files can be downloaded at |
82 | L<http://www.rainer-keuchel.de/wince/dirlist.html> | |
e1caacb4 | 83 | |
75472953 | 84 | =head3 Make |
e1caacb4 | 85 | |
45496817 | 86 | Normally you only need to edit C<./win32/ce-helpers/compile.bat> |
2e64bfdb | 87 | to reflect your system and run it. |
e1caacb4 | 88 | |
01e90026 | 89 | File C<./win32/ce-helpers/compile.bat> is actually a wrapper to call |
45496817 VK |
90 | C<nmake -f makefile.ce> with appropriate parameters and it accepts extra |
91 | parameters and forwards them to C<nmake> command as additional | |
2e64bfdb | 92 | arguments. You should pass target this way. |
e1caacb4 | 93 | |
8f33b42a | 94 | To prepare distribution you need to do following: |
2e64bfdb JH |
95 | |
96 | =over 4 | |
97 | ||
45496817 | 98 | =item * go to C<./win32> subdirectory |
2e64bfdb | 99 | |
01e90026 | 100 | =item * edit file C<./win32/ce-helpers/compile.bat> |
e1caacb4 | 101 | |
2e64bfdb JH |
102 | =item * run |
103 | compile.bat | |
e1caacb4 | 104 | |
2e64bfdb JH |
105 | =item * run |
106 | compile.bat dist | |
e1caacb4 | 107 | |
2e64bfdb JH |
108 | =back |
109 | ||
45496817 | 110 | C<Makefile.ce> has C<CROSS_NAME> macro, and it is used further to refer to |
8f33b42a VK |
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 | |
45496817 VK |
118 | *.bat file could fit perfectly to this purpose) and your C<compile.bat> |
119 | has proper "MACHINE" parameter set, to, say, C<wince-mips-pocket-wce300>. | |
8f33b42a VK |
120 | |
121 | compile.bat | |
122 | compile.bat dist | |
123 | compile.bat CROSS_NAME=mips-wce300-thr "USE_ITHREADS=define" "USE_IMP_SYS=define" "USE_MULTI=define" | |
124 | compile.bat CROSS_NAME=mips-wce300-thr "USE_ITHREADS=define" "USE_IMP_SYS=define" "USE_MULTI=define" dist | |
125 | ||
126 | If all goes okay and no errors during a build, you'll get two independent | |
45496817 | 127 | distributions: C<wince-mips-pocket-wce300> and C<mips-wce300-thr>. |
8f33b42a | 128 | |
45496817 VK |
129 | Target C<dist> prepares distribution file set. Target C<zipdist> performs |
130 | same as C<dist> but additionally compresses distribution files into zip | |
8f33b42a VK |
131 | archive. |
132 | ||
45496817 VK |
133 | NOTE: during a build there could be created a number (or one) of C<Config.pm> |
134 | for cross-compilation ("foreign" C<Config.pm>) and those are hidden inside | |
135 | C<../xlib/$(CROSS_NAME)> with other auxilary files, but, and this is important to | |
136 | note, there should be B<no> C<Config.pm> for host miniperl. | |
8f33b42a VK |
137 | If you'll get an error that perl could not find Config.pm somewhere in building |
138 | process this means something went wrong. Most probably you forgot to | |
139 | specify a cross-compilation when invoking miniperl.exe to Makefile.PL | |
140 | When building an extension for cross-compilation your command line should | |
141 | look like | |
142 | ||
143 | ..\miniperl.exe -I..\lib -MCross=mips-wce300-thr Makefile.PL | |
144 | ||
145 | or just | |
146 | ||
147 | ..\miniperl.exe -I..\lib -MCross Makefile.PL | |
148 | ||
149 | to refer a cross-compilation that was created last time. | |
150 | ||
8f33b42a | 151 | All questions related to building for WinCE devices could be asked in |
ef39d023 | 152 | F<perlce-user@lists.sourceforge.net> mailing list. |
e1caacb4 | 153 | |
75472953 VK |
154 | =head1 Using Perl on WinCE |
155 | ||
156 | =head2 DESCRIPTION | |
157 | ||
158 | PerlCE is currently linked with a simple console window, so it also | |
159 | works on non-hpc devices. | |
160 | ||
45496817 VK |
161 | The simple stdio implementation creates the files C<stdin.txt>, |
162 | C<stdout.txt> and C<stderr.txt>, so you might examine them if your | |
75472953 VK |
163 | console has only a liminted number of cols. |
164 | ||
165 | When exitcode is non-zero, a message box appears, otherwise the | |
166 | console closes, so you might have to catch an exit with | |
167 | status 0 in your program to see any output. | |
168 | ||
45496817 VK |
169 | stdout/stderr now go into the files C</perl-stdout.txt> and |
170 | C</perl-stderr.txt.> | |
171 | ||
172 | PerlIDE is handy to deal with perlce. | |
75472953 VK |
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 | ||
45496817 VK |
183 | =over |
184 | ||
185 | =item PERL5LIB | |
186 | ||
187 | Usual perl lib path (semi-list). | |
188 | ||
189 | =item PATH | |
190 | ||
191 | Semi-list for executables. | |
192 | ||
193 | =item TMP | |
194 | ||
195 | - Tempdir. | |
196 | ||
197 | =item UNIXROOTPATH | |
198 | ||
199 | - Root for accessing some special files, i.e. C</dev/null>, C</etc/services>. | |
200 | ||
201 | =item ROWS/COLS | |
202 | ||
203 | - Rows/cols for console. | |
204 | ||
205 | =item HOME | |
206 | ||
207 | - Home directory. | |
208 | ||
209 | =item CONSOLEFONTSIZE | |
210 | ||
211 | - Size for console font. | |
212 | ||
213 | =back | |
75472953 VK |
214 | |
215 | You can set these with cereg.exe, a (remote) registry editor | |
216 | or via the PerlIDE. | |
217 | ||
218 | =head2 REGISTRY | |
219 | ||
220 | To start perl by clicking on a perl source file, you have | |
45496817 | 221 | to make the according entries in HKCR (see C<ce-helpers/wince-reg.bat>). |
75472953 VK |
222 | cereg.exe (which must be executed on a desktop pc with |
223 | ActiveSync) is reported not to work on some devices. | |
224 | You have to create the registry entries by hand using a | |
225 | registry editor. | |
226 | ||
75472953 VK |
227 | =head2 XS |
228 | ||
229 | The following Win32-Methods are built-in: | |
230 | ||
231 | newXS("Win32::GetCwd", w32_GetCwd, file); | |
232 | newXS("Win32::SetCwd", w32_SetCwd, file); | |
233 | newXS("Win32::GetTickCount", w32_GetTickCount, file); | |
234 | newXS("Win32::GetOSVersion", w32_GetOSVersion, file); | |
235 | newXS("Win32::IsWinNT", w32_IsWinNT, file); | |
236 | newXS("Win32::IsWin95", w32_IsWin95, file); | |
237 | newXS("Win32::IsWinCE", w32_IsWinCE, file); | |
238 | newXS("Win32::CopyFile", w32_CopyFile, file); | |
239 | newXS("Win32::Sleep", w32_Sleep, file); | |
240 | newXS("Win32::MessageBox", w32_MessageBox, file); | |
241 | newXS("Win32::GetPowerStatus", w32_GetPowerStatus, file); | |
242 | newXS("Win32::GetOemInfo", w32_GetOemInfo, file); | |
243 | newXS("Win32::ShellEx", w32_ShellEx, file); | |
244 | ||
245 | =head2 BUGS | |
246 | ||
247 | Opening files for read-write is currently not supported if | |
248 | they use stdio (normal perl file handles). | |
249 | ||
250 | If you find bugs or if it does not work at all on your | |
251 | device, send mail to the address below. Please report | |
252 | the details of your device (processor, ceversion, | |
253 | devicetype (hpc/palm/pocket)) and the date of the downloaded | |
254 | files. | |
255 | ||
256 | =head2 INSTALLATION | |
257 | ||
258 | Currently installation instructions are at L<http://perlce.sourceforge.net/>. | |
259 | ||
260 | After installation & testing processes will stabilize, information will | |
261 | be more precise. | |
262 | ||
c7bcd97d | 263 | =head1 ACKNOWLEDGEMENTS |
e1caacb4 JH |
264 | |
265 | The port for Win32 was used as a reference. | |
266 | ||
45496817 VK |
267 | =head1 History of WinCE port |
268 | ||
269 | =over | |
270 | ||
271 | =item 5.6.0 | |
272 | ||
273 | Initial port of perl to WinCE. It was performed in separate directory | |
274 | named C<wince>. This port was based on contents of C<./win32> directory. | |
275 | C<miniperl> was not built, user must have HOST perl and properly edit | |
276 | C<makefile.ce> to reflect this. | |
277 | ||
278 | =item 5.8.0 | |
279 | ||
280 | wince port was kept in the same C<./wince> directory, and C<wince/Makefile.ce> | |
281 | was used to invoke native compiler to create HOST miniperl, which then | |
282 | facilitates cross-compiling process. | |
283 | Extension building support was added. | |
284 | ||
285 | =item 5.9.4 | |
286 | ||
287 | Two directories C<./win32> and C<./wince> were merged, so perlce build | |
288 | process comes in C<./win32> directory. | |
289 | ||
ef39d023 | 290 | =back |
45496817 | 291 | |
2e64bfdb | 292 | =head1 AUTHORS |
e1caacb4 | 293 | |
75472953 VK |
294 | =over |
295 | ||
296 | =item Rainer Keuchel <coyxc@rainer-keuchel.de> | |
297 | ||
298 | provided initial port of Perl, which appears to be most essential work, as | |
299 | it was a breakthrough on having Perl ported at all. | |
300 | Many thanks and obligations to Rainer! | |
301 | ||
302 | =item Vadim Konovalov | |
303 | ||
304 | made further support of WinCE port. | |
305 | ||
306 | =back |