1If you read this file _as_is_, just ignore the funny characters you
2see.  It is written in the POD format (see pod/perlpod.pod) which is
3specifically designed to be readable as is.
4
5=head1 NAME
6
7perlce - Perl for WinCE
8
9=head1 DESCRIPTION
10
11This file gives the instructions for building Perl5.8 and above for
12WinCE.  Please read and understand the terms under which this
13software is distributed.
14
15=head1 BUILD
16
17This section describes the steps to be performed to build PerlCE.
18You may find additional and newer information about building perl
19for WinCE using following URL:
20
21  http://perlce.sourceforge.net
22
23There should also be pre-built binaries there.
24
25Don't be confused by large size of downloaded distribution or constructed
26binaries: entire distribution could be large for WinCE ideology, but
27you may strip it at your wish and use only required parts.
28
29=head2 Tools & SDK
30
31For compiling, you need following:
32
33=over 4
34
35=item * Microsoft Embedded Visual Tools
36
37=item * Microsoft Visual C++
38
39=item * Rainer Keuchel's celib-sources
40
41=item * Rainer Keuchel's console-sources
42
43=back
44
45Needed source files can be downloaded via:
46www.rainer-keuchel.de/wince/dirlist.html
47
48=head2 Make
49
50Please pay attention that starting from 5.8.0 miniperl *is* built
51and it facilitates in further building process. This means that
52in addition to compiler installation for mobile device you also need
53to have Microsoft Visual C++ installed as well.
54
55On the bright side, you do not need to edit any files from ./win32
56subdirectory. Normally you only need to edit ./wince/compile.bat
57to reflect your system and run it.
58
59File ./wince/compile.bat is actually a wrapper to call
60nmake -f makefile.ce with appropriate parameters and it accepts extra
61parameters and forwards them to "nmake" command as additional
62arguments. You should pass target this way.
63
64To prepare distribution you need to do following:
65
66=over 4
67
68=item * go to ./wince subdirectory
69
70=item * edit file compile.bat
71
72=item * run
73  compile.bat
74
75=item * run
76  compile.bat dist
77
78=back
79
80makefile.ce has CROSS_NAME macro, and it is used further to refer to
81your cross-compilation scheme. You could assign a name to it, but this
82is not necessary, because by default it is assigned after your machine
83configuration name, such as "wince-sh3-hpc-wce211", and this is enough
84to distinguish different builds at the same time. This option could be
85handy for several different builds on same platform to perform, say,
86threaded build. In a following example we assume that all required
87environment variables are set properly for C cross-compiler (a special
88*.bat file could fit perfectly to this purpose) and your compile.bat
89has proper "MACHINE" parameter set, to, say, "wince-mips-pocket-wce300".
90
91  compile.bat
92  compile.bat dist
93  compile.bat CROSS_NAME=mips-wce300-thr "USE_ITHREADS=define" "USE_IMP_SYS=define" "USE_MULTI=define"
94  compile.bat CROSS_NAME=mips-wce300-thr "USE_ITHREADS=define" "USE_IMP_SYS=define" "USE_MULTI=define" dist
95
96If all goes okay and no errors during a build, you'll get two independent
97distributions: "wince-mips-pocket-wce300" and "mips-wce300-thr".
98
99Target 'dist' prepares distribution file set. Target 'zipdist' performs
100same as 'dist' but additionally compresses distribution files into zip
101archive.
102
103NOTE: during a build there could be created a number (or one) of Config.pm
104for cross-compilation ("foreign" Config.pm) and those are hidden inside
105../xlib/$(CROSS_NAME) with other auxilary files, but, and this is important to
106note, there should be *no* Config.pm for host miniperl.
107If you'll get an error that perl could not find Config.pm somewhere in building
108process this means something went wrong. Most probably you forgot to
109specify a cross-compilation when invoking miniperl.exe to Makefile.PL
110When building an extension for cross-compilation your command line should
111look like
112
113  ..\miniperl.exe -I..\lib -MCross=mips-wce300-thr Makefile.PL
114
115or just
116
117  ..\miniperl.exe -I..\lib -MCross Makefile.PL
118
119to refer a cross-compilation that was created last time.
120
121
122If you decided to build with fcrypt.c file, please refer to README.win32
123file, as long as all legal considerations and steps to do are exactly same
124in this case.
125
126All questions related to building for WinCE devices could be asked in
127perlce-users@lists.sourceforge.net mailing list.
128
129=head1 ACKNOWLEDGEMENTS
130
131The port for Win32 was used as a reference.
132
133=head1 AUTHORS
134
135Rainer Keuchel (keuchel@netwave.de)
136Vadim Konovalov (vkonovalov@spb.lucent.com)
137
138