Squeeze more flag manipulations together in sv_setsv_flags.
[perl.git] / 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