[perl5.git] / README.ce

If you read this file _as_is_, just ignore the funny characters you
see.  It is written in the POD format (see pod/perlpod.pod) which is
specifically designed to be readable as is.

=head1 NAME

perlce - Perl for WinCE

=head1 Building Perl for WinCE

=head2 WARNING

B<< Much of this document has become very out of date and needs updating,
rewriting or deleting. The build process was overhauled during the 5.19
development track and the current instructions as of that time are given
in L</CURRENT BUILD INSTRUCTIONS>; the previous build instructions, which
are largely superseded but may still contain some useful information, are
left in L</OLD BUILD INSTRUCTIONS> but really need removing after anything
of use has been extracted from them. >>

=head2 DESCRIPTION

This file gives the instructions for building Perl5.8 and above for
WinCE.  Please read and understand the terms under which this
software is distributed.

=head2 General explanations on cross-compiling WinCE

=over

=item *

F<miniperl> is built. This is a single executable (without DLL), intended
to run on Win32, and it will facilitate remaining build process; all binaries
built after it are foreign and should not run locally.

F<miniperl> is built using F<./win32/Makefile>; this is part of normal
build process invoked as dependency from wince/Makefile.ce

=item *

After F<miniperl> is built, F<configpm> is invoked to create right F<Config.pm>
in right place and its corresponding Cross.pm.

Unlike Win32 build, miniperl will not have F<Config.pm> of host within reach;
it rather will use F<Config.pm> from within cross-compilation directories.

File F<Cross.pm> is dead simple: for given cross-architecture places in @INC
a path where perl modules are, and right F<Config.pm> in that place.

That said, C<miniperl -Ilib -MConfig -we 1> should report an error, because
it can not find F<Config.pm>. If it does not give an error -- wrong F<Config.pm>
is substituted, and resulting binaries will be a mess.

C<miniperl -MCross -MConfig -we 1> should run okay, and it will provide right
F<Config.pm> for further compilations.

=item *

During extensions build phase, a script F<./win32/buildext.pl> is invoked,
which in turn steps in F<./ext> subdirectories and performs a build of
each extension in turn.

All invokes of F<Makefile.PL> are provided with C<-MCross> so to enable cross-
compile.

=back

=head2 CURRENT BUILD INSTRUCTIONS

(These instructions assume the host is 32-bit Windows. If you're on 64-bit
Windows then change "C:\Program Files" to "C:\Program Files (x86)" throughout.)

1. Install EVC4 from

 http://download.microsoft.com/download/c/3/f/c3f8b58b-9753-4c2e-8b96-2dfe3476a2f7/eVC4.exe

Use the key mentioned at 

 http://download.cnet.com/Microsoft-eMbedded-Visual-C/3000-2212_4-10108490.html?tag=bc

The installer is ancient and has a few bugs on the paths it uses. You 
will have to fix them later. Basically, some things go into "C:/Program 
Files/Windows CE Tools", others go into "C:/Windows CE Tools" regardless 
of the path you gave to the installer (the default will be "C:/Windows 
CE Tools"). Reboots will be required for the installer to proceed. Also 
.c and .h associations with Visual Studio might get overridden when 
installing EVC4. You have been warned.

2. Download celib from GitHub (using "Download ZIP") at

    https://github.com/bulk88/celib 

Extract it to a spaceless path but not into the perl build source.
I call this directory "celib-palm-3.0" but in the GitHub 
snapshot it will be called "celib-master". Make a copy of the 
"wince-arm-pocket-wce300-release" folder and rename the copy to 
"wince-arm-pocket-wce400". This is a hack so we can build a CE 4.0 
binary by linking in CE 3.0 ARM asm; the linker doesn't care. Windows 
Mobile/WinCE are backwards compatible with machine code like Desktop Windows.

3. Download console-1.3-src.tar.gz from 

 http://sourceforge.net/projects/perlce/files/PerlCE%20support%20files/console/

Extract it to a spaceless path but not into the perl build source. 
Don't extract it into the same directory as celib. Make a copy of the 
"wince-arm-pocket-wce300" folder and rename the copy to 
"wince-arm-pocket-wce400". This is a hack so we can build a CE 4.0 
binary by linking in CE 3.0 ARM asm; the linker doesn't care. Windows 
Mobile/WinCE are backwards compatible with machine code like Desktop Windows.

4. Open a command prompt, run your regular batch file to set the environment
for desktop Visual C building, goto the perl source directory, cd into win32/,
fill out Makefile, and do a "nmake all" to build a Desktop Perl.

5. Open win32/Makefile.ce in a text editor and do something similar to the 
following patch.

    -CELIBDLLDIR  = h:\src\wince\celib-palm-3.0
    -CECONSOLEDIR = h:\src\wince\w32console
    +CELIBDLLDIR  = C:\sources\celib-palm-3.0
    +CECONSOLEDIR = C:\sources\w32console

Also change

    !if "$(MACHINE)" == ""
    MACHINE=wince-arm-hpc-wce300
    #MACHINE=wince-arm-hpc-wce211
    #MACHINE=wince-sh3-hpc-wce211
    #MACHINE=wince-mips-hpc-wce211
    #MACHINE=wince-sh3-hpc-wce200
    #MACHINE=wince-mips-hpc-wce200
    #MACHINE=wince-arm-pocket-wce300
    #MACHINE=wince-mips-pocket-wce300
    #MACHINE=wince-sh3-pocket-wce300
    #MACHINE=wince-x86em-pocket-wce300
    #MACHINE=wince-mips-palm-wce211
    #MACHINE=wince-sh3-palm-wce211
    #MACHINE=wince-x86em-palm-wce211
    #MACHINE=wince-x86-hpc-wce300
    #MACHINE=wince-arm-pocket-wce400
    !endif

to

    !if "$(MACHINE)" == ""
    #MACHINE=wince-arm-hpc-wce300
    #MACHINE=wince-arm-hpc-wce211
    #MACHINE=wince-sh3-hpc-wce211
    #MACHINE=wince-mips-hpc-wce211
    #MACHINE=wince-sh3-hpc-wce200
    #MACHINE=wince-mips-hpc-wce200
    #MACHINE=wince-arm-pocket-wce300
    #MACHINE=wince-mips-pocket-wce300
    #MACHINE=wince-sh3-pocket-wce300
    #MACHINE=wince-x86em-pocket-wce300
    #MACHINE=wince-mips-palm-wce211
    #MACHINE=wince-sh3-palm-wce211
    #MACHINE=wince-x86em-palm-wce211
    #MACHINE=wince-x86-hpc-wce300
    MACHINE=wince-arm-pocket-wce400
    !endif

so wince-arm-pocket-wce400 is the MACHINE type.

6. Use a text editor to open "C:\Program Files\Microsoft eMbedded C++ 
4.0\EVC\WCE400\BIN\WCEARMV4.BAT". Look for

    if "%SDKROOT%"=="" set SDKROOT=...

On a new install it is "C:\Windows CE Tools". Goto 
"C:\Windows CE Tools" in a file manager and see if "C:\Windows CE 
Tools\wce400\STANDARDSDK\Include\Armv4" exists on your disk. If not
the SDKROOT need to be changed to "C:\Program Files\Windows CE Tools".

Goto celib-palm-3.0\inc\cewin32.h, search for

    typedef struct _ABC {

and uncomment the struct.

7. Open another command prompt, ensure PLATFORM is not set to anything
already unless you know what you're doing (so that the correct default
value is set by the next command), and run "C:\Program Files\Microsoft
eMbedded C++ 4.0\EVC\WCE400\BIN\WCEARMV4.BAT"

8. In the WinCE command prompt you made with WCEARMV4.BAT, goto the perl 
source directory, cd into win32/ and run "nmake -f Makefile.ce".

9. The ARM perl interpreter (perl519.dll and perl.exe) will be in something
like "C:\perl519\src\win32\wince-arm-pocket-wce400", with the XS DLLs in
"C:\perl519\src\xlib\wince-arm-hpc-wce400\auto".

To prove success on the host machine, run
"dumpbin /headers wince-arm-pocket-wce400\perl.exe" from the win32/ folder
and look for "machine (ARM)" in the FILE HEADER VALUES and
"subsystem (Windows CE GUI)" in the OPTIONAL HEADER VALUES.

=head2 OLD BUILD INSTRUCTIONS

This section describes the steps to be performed to build PerlCE.
You may find additional information about building perl for WinCE
at L<http://perlce.sourceforge.net> and some pre-built binaries.

=head3 Tools & SDK

For compiling, you need following:

=over 4

=item * Microsoft Embedded Visual Tools

=item * Microsoft Visual C++

=item * Rainer Keuchel's celib-sources

=item * Rainer Keuchel's console-sources

=back

Needed source files can be downloaded at
L<http://perlce.sourceforge.net>

=head3 Make

Normally you only need to edit F<./win32/ce-helpers/compile.bat>
to reflect your system and run it.

File F<./win32/ce-helpers/compile.bat> is actually a wrapper to call
C<nmake -f makefile.ce> with appropriate parameters and it accepts extra
parameters and forwards them to C<nmake> command as additional
arguments. You should pass target this way.

To prepare distribution you need to do following:

=over 4

=item * go to F<./win32> subdirectory

=item * edit file F<./win32/ce-helpers/compile.bat>

=item * run 
  compile.bat

=item * run 
  compile.bat dist

=back

F<Makefile.ce> has C<CROSS_NAME> macro, and it is used further to refer to
your cross-compilation scheme. You could assign a name to it, but this
is not necessary, because by default it is assigned after your machine
configuration name, such as "wince-sh3-hpc-wce211", and this is enough
to distinguish different builds at the same time. This option could be
handy for several different builds on same platform to perform, say,
threaded build. In a following example we assume that all required
environment variables are set properly for C cross-compiler (a special
*.bat file could fit perfectly to this purpose) and your F<compile.bat>
has proper "MACHINE" parameter set, to, say, C<wince-mips-pocket-wce300>.

  compile.bat
  compile.bat dist
  compile.bat CROSS_NAME=mips-wce300-thr "USE_ITHREADS=define" ^
    "USE_IMP_SYS=define" "USE_MULTI=define"
  compile.bat CROSS_NAME=mips-wce300-thr "USE_ITHREADS=define" ^
    "USE_IMP_SYS=define" "USE_MULTI=define" dist

If all goes okay and no errors during a build, you'll get two independent
distributions: C<wince-mips-pocket-wce300> and C<mips-wce300-thr>.

Target C<dist> prepares distribution file set. Target C<zipdist> performs
same as C<dist> but additionally compresses distribution files into zip
archive.

NOTE: during a build there could be created a number (or one) of F<Config.pm>
for cross-compilation ("foreign" F<Config.pm>) and those are hidden inside
F<../xlib/$(CROSS_NAME)> with other auxiliary files, but, and this is important to
note, there should be B<no> F<Config.pm> for host miniperl.
If you'll get an error that perl could not find Config.pm somewhere in building
process this means something went wrong. Most probably you forgot to
specify a cross-compilation when invoking miniperl.exe to Makefile.PL
When building an extension for cross-compilation your command line should
look like

  ..\miniperl.exe -I..\lib -MCross=mips-wce300-thr Makefile.PL

or just

  ..\miniperl.exe -I..\lib -MCross Makefile.PL

to refer a cross-compilation that was created last time.

All questions related to building for WinCE devices could be asked in
F<perlce-user@lists.sourceforge.net> mailing list.

=head1 Using Perl on WinCE

=head2 DESCRIPTION

PerlCE is currently linked with a simple console window, so it also
works on non-hpc devices.

The simple stdio implementation creates the files F<stdin.txt>,
F<stdout.txt> and F<stderr.txt>, so you might examine them if your
console has only a limited number of cols.

When exitcode is non-zero, a message box appears, otherwise the
console closes, so you might have to catch an exit with
status 0 in your program to see any output.

stdout/stderr now go into the files F</perl-stdout.txt> and
F</perl-stderr.txt.>

PerlIDE is handy to deal with perlce.

=head2 LIMITATIONS

No fork(), pipe(), popen() etc.

=head2 ENVIRONMENT

All environment vars must be stored in HKLM\Environment as
strings. They are read at process startup.

=over

=item PERL5LIB

Usual perl lib path (semi-list).

=item PATH

Semi-list for executables.

=item TMP

- Tempdir.

=item UNIXROOTPATH

- Root for accessing some special files, i.e. F</dev/null>, F</etc/services>.

=item ROWS/COLS

- Rows/cols for console.

=item HOME

- Home directory.

=item CONSOLEFONTSIZE

- Size for console font.

=back

You can set these with cereg.exe, a (remote) registry editor
or via the PerlIDE.

=head2 REGISTRY

To start perl by clicking on a perl source file, you have
to make the according entries in HKCR (see F<ce-helpers/wince-reg.bat>).
cereg.exe (which must be executed on a desktop pc with
ActiveSync) is reported not to work on some devices.
You have to create the registry entries by hand using a 
registry editor.

=head2 XS

The following Win32-Methods are built-in:

	newXS("Win32::GetCwd", w32_GetCwd, file);
	newXS("Win32::SetCwd", w32_SetCwd, file);
	newXS("Win32::GetTickCount", w32_GetTickCount, file);
	newXS("Win32::GetOSVersion", w32_GetOSVersion, file);
	newXS("Win32::IsWinNT", w32_IsWinNT, file);
	newXS("Win32::IsWin95", w32_IsWin95, file);
	newXS("Win32::IsWinCE", w32_IsWinCE, file);
	newXS("Win32::CopyFile", w32_CopyFile, file);
	newXS("Win32::Sleep", w32_Sleep, file);
	newXS("Win32::MessageBox", w32_MessageBox, file);
	newXS("Win32::GetPowerStatus", w32_GetPowerStatus, file);
	newXS("Win32::GetOemInfo", w32_GetOemInfo, file);
	newXS("Win32::ShellEx", w32_ShellEx, file);

=head2 BUGS

Opening files for read-write is currently not supported if
they use stdio (normal perl file handles).

If you find bugs or if it does not work at all on your
device, send mail to the address below. Please report
the details of your device (processor, ceversion, 
devicetype (hpc/palm/pocket)) and the date of the downloaded
files. 

=head2 INSTALLATION

Currently installation instructions are at L<http://perlce.sourceforge.net/>.

After installation & testing processes will stabilize, information will
be more precise.

=head1 ACKNOWLEDGEMENTS

The port for Win32 was used as a reference.

=head1 History of WinCE port

=over

=item 5.6.0

Initial port of perl to WinCE. It was performed in separate directory
named F<wince>. This port was based on contents of F<./win32> directory.
F<miniperl> was not built, user must have HOST perl and properly edit
F<makefile.ce> to reflect this.

=item 5.8.0

wince port was kept in the same F<./wince> directory, and F<wince/Makefile.ce>
was used to invoke native compiler to create HOST miniperl, which then
facilitates cross-compiling process.
Extension building support was added.

=item 5.9.4

Two directories F<./win32> and F<./wince> were merged, so perlce build
process comes in F<./win32> directory.

=back

=head1 AUTHORS

=over

=item Rainer Keuchel <coyxc@rainer-keuchel.de>

provided initial port of Perl, which appears to be most essential work, as
it was a breakthrough on having Perl ported at all.
Many thanks and obligations to Rainer!

=item Vadim Konovalov

made further support of WinCE port.

=item Daniel Dragan

updated the build process during the 5.19 development track.

=back
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
75472953 VK	10
69104b65 SH	11	=head2 WARNING
	12
	13	B<< Much of this document has become very out of date and needs updating,
	14	rewriting or deleting. The build process was overhauled during the 5.19
	15	development track and the current instructions as of that time are given
	16	in L</CURRENT BUILD INSTRUCTIONS>; the previous build instructions, which
	17	are largely superseded but may still contain some useful information, are
	18	left in L</OLD BUILD INSTRUCTIONS> but really need removing after anything
	19	of use has been extracted from them. >>
	20
75472953	21	=head2 DESCRIPTION
e1caacb4	22
2e64bfdb	23	This file gives the instructions for building Perl5.8 and above for
e1caacb4 JH	24	WinCE. Please read and understand the terms under which this
	25	software is distributed.
	26
75472953	27	=head2 General explanations on cross-compiling WinCE
e1caacb4	28
75472953 VK	29	=over
	30
	31	=item *
	32
9b15f68e	33	F<miniperl> is built. This is a single executable (without DLL), intended
75472953 VK	34	to run on Win32, and it will facilitate remaining build process; all binaries
	35	built after it are foreign and should not run locally.
	36
9b15f68e	37	F<miniperl> is built using F<./win32/Makefile>; this is part of normal
75472953 VK	38	build process invoked as dependency from wince/Makefile.ce
	39
	40	=item *
	41
9b15f68e	42	After F<miniperl> is built, F<configpm> is invoked to create right F<Config.pm>
75472953	43	in right place and its corresponding Cross.pm.
2e64bfdb	44
9b15f68e KW	45	Unlike Win32 build, miniperl will not have F<Config.pm> of host within reach;
9b15f68e KW	46	it rather will use F<Config.pm> from within cross-compilation directories.
2e64bfdb	47
9b15f68e KW	48	File F<Cross.pm> is dead simple: for given cross-architecture places in @INC
9b15f68e KW	49	a path where perl modules are, and right F<Config.pm> in that place.
e1caacb4	50
75472953	51	That said, C<miniperl -Ilib -MConfig -we 1> should report an error, because
9b15f68e	52	it can not find F<Config.pm>. If it does not give an error -- wrong F<Config.pm>
75472953 VK	53	is substituted, and resulting binaries will be a mess.
	54
	55	C<miniperl -MCross -MConfig -we 1> should run okay, and it will provide right
9b15f68e	56	F<Config.pm> for further compilations.
75472953 VK	57
	58	=item *
	59
cb0ee57a	60	During extensions build phase, a script F<./win32/buildext.pl> is invoked,
9b15f68e	61	which in turn steps in F<./ext> subdirectories and performs a build of
75472953 VK	62	each extension in turn.
75472953 VK	63
9b15f68e	64	All invokes of F<Makefile.PL> are provided with C<-MCross> so to enable cross-
75472953 VK	65	compile.
75472953 VK	66
75472953	67	=back
8f33b42a	68
69104b65 SH	69	=head2 CURRENT BUILD INSTRUCTIONS
	70
	71	(These instructions assume the host is 32-bit Windows. If you're on 64-bit
	72	Windows then change "C:\Program Files" to "C:\Program Files (x86)" throughout.)
	73
	74	1. Install EVC4 from
	75
f185f654	76	http://download.microsoft.com/download/c/3/f/c3f8b58b-9753-4c2e-8b96-2dfe3476a2f7/eVC4.exe
69104b65 SH	77
	78	Use the key mentioned at
	79
f185f654	80	http://download.cnet.com/Microsoft-eMbedded-Visual-C/3000-2212_4-10108490.html?tag=bc
69104b65 SH	81
	82	The installer is ancient and has a few bugs on the paths it uses. You
	83	will have to fix them later. Basically, some things go into "C:/Program
	84	Files/Windows CE Tools", others go into "C:/Windows CE Tools" regardless
	85	of the path you gave to the installer (the default will be "C:/Windows
	86	CE Tools"). Reboots will be required for the installer to proceed. Also
	87	.c and .h associations with Visual Studio might get overridden when
	88	installing EVC4. You have been warned.
	89
	90	2. Download celib from GitHub (using "Download ZIP") at
	91
	92	https://github.com/bulk88/celib
	93
	94	Extract it to a spaceless path but not into the perl build source.
	95	I call this directory "celib-palm-3.0" but in the GitHub
	96	snapshot it will be called "celib-master". Make a copy of the
	97	"wince-arm-pocket-wce300-release" folder and rename the copy to
	98	"wince-arm-pocket-wce400". This is a hack so we can build a CE 4.0
	99	binary by linking in CE 3.0 ARM asm; the linker doesn't care. Windows
	100	Mobile/WinCE are backwards compatible with machine code like Desktop Windows.
	101
	102	3. Download console-1.3-src.tar.gz from
	103
f185f654	104	http://sourceforge.net/projects/perlce/files/PerlCE%20support%20files/console/
69104b65 SH	105
	106	Extract it to a spaceless path but not into the perl build source.
	107	Don't extract it into the same directory as celib. Make a copy of the
	108	"wince-arm-pocket-wce300" folder and rename the copy to
	109	"wince-arm-pocket-wce400". This is a hack so we can build a CE 4.0
	110	binary by linking in CE 3.0 ARM asm; the linker doesn't care. Windows
	111	Mobile/WinCE are backwards compatible with machine code like Desktop Windows.
	112
	113	4. Open a command prompt, run your regular batch file to set the environment
	114	for desktop Visual C building, goto the perl source directory, cd into win32/,
	115	fill out Makefile, and do a "nmake all" to build a Desktop Perl.
	116
	117	5. Open win32/Makefile.ce in a text editor and do something similar to the
	118	following patch.
	119
	120	-CELIBDLLDIR = h:\src\wince\celib-palm-3.0
	121	-CECONSOLEDIR = h:\src\wince\w32console
	122	+CELIBDLLDIR = C:\sources\celib-palm-3.0
	123	+CECONSOLEDIR = C:\sources\w32console
	124
	125	Also change
	126
	127	!if "$(MACHINE)" == ""
	128	MACHINE=wince-arm-hpc-wce300
	129	#MACHINE=wince-arm-hpc-wce211
	130	#MACHINE=wince-sh3-hpc-wce211
	131	#MACHINE=wince-mips-hpc-wce211
	132	#MACHINE=wince-sh3-hpc-wce200
	133	#MACHINE=wince-mips-hpc-wce200
	134	#MACHINE=wince-arm-pocket-wce300
	135	#MACHINE=wince-mips-pocket-wce300
	136	#MACHINE=wince-sh3-pocket-wce300
	137	#MACHINE=wince-x86em-pocket-wce300
	138	#MACHINE=wince-mips-palm-wce211
	139	#MACHINE=wince-sh3-palm-wce211
	140	#MACHINE=wince-x86em-palm-wce211
	141	#MACHINE=wince-x86-hpc-wce300
	142	#MACHINE=wince-arm-pocket-wce400
	143	!endif
	144
	145	to
	146
	147	!if "$(MACHINE)" == ""
	148	#MACHINE=wince-arm-hpc-wce300
	149	#MACHINE=wince-arm-hpc-wce211
	150	#MACHINE=wince-sh3-hpc-wce211
	151	#MACHINE=wince-mips-hpc-wce211
	152	#MACHINE=wince-sh3-hpc-wce200
	153	#MACHINE=wince-mips-hpc-wce200
	154	#MACHINE=wince-arm-pocket-wce300
	155	#MACHINE=wince-mips-pocket-wce300
	156	#MACHINE=wince-sh3-pocket-wce300
	157	#MACHINE=wince-x86em-pocket-wce300
	158	#MACHINE=wince-mips-palm-wce211
	159	#MACHINE=wince-sh3-palm-wce211
	160	#MACHINE=wince-x86em-palm-wce211
	161	#MACHINE=wince-x86-hpc-wce300
	162	MACHINE=wince-arm-pocket-wce400
	163	!endif
	164
	165	so wince-arm-pocket-wce400 is the MACHINE type.
	166
	167	6. Use a text editor to open "C:\Program Files\Microsoft eMbedded C++
	168	4.0\EVC\WCE400\BIN\WCEARMV4.BAT". Look for
169
170	if "%SDKROOT%"=="" set SDKROOT=...
171
172	On a new install it is "C:\Windows CE Tools". Goto
173	"C:\Windows CE Tools" in a file manager and see if "C:\Windows CE
174	Tools\wce400\STANDARDSDK\Include\Armv4" exists on your disk. If not
175	the SDKROOT need to be changed to "C:\Program Files\Windows CE Tools".
176
177	Goto celib-palm-3.0\inc\cewin32.h, search for
178
179	typedef struct _ABC {
180
181	and uncomment the struct.
182
183	7. Open another command prompt, ensure PLATFORM is not set to anything
184	already unless you know what you're doing (so that the correct default
185	value is set by the next command), and run "C:\Program Files\Microsoft
186	eMbedded C++ 4.0\EVC\WCE400\BIN\WCEARMV4.BAT"
187
188	8. In the WinCE command prompt you made with WCEARMV4.BAT, goto the perl
189	source directory, cd into win32/ and run "nmake -f Makefile.ce".
190
191	9. The ARM perl interpreter (perl519.dll and perl.exe) will be in something
192	like "C:\perl519\src\win32\wince-arm-pocket-wce400", with the XS DLLs in
193	"C:\perl519\src\xlib\wince-arm-hpc-wce400\auto".
194
195	To prove success on the host machine, run
196	"dumpbin /headers wince-arm-pocket-wce400\perl.exe" from the win32/ folder
197	and look for "machine (ARM)" in the FILE HEADER VALUES and
198	"subsystem (Windows CE GUI)" in the OPTIONAL HEADER VALUES.
199
200	=head2 OLD BUILD INSTRUCTIONS
75472953 VK	201
	202	This section describes the steps to be performed to build PerlCE.
	203	You may find additional information about building perl for WinCE
	204	at L<http://perlce.sourceforge.net> and some pre-built binaries.
	205
	206	=head3 Tools & SDK
e1caacb4	207
2e64bfdb JH	208	For compiling, you need following:
	209
	210	=over 4
	211
	212	=item * Microsoft Embedded Visual Tools
	213
	214	=item * Microsoft Visual C++
	215
	216	=item * Rainer Keuchel's celib-sources
	217
	218	=item * Rainer Keuchel's console-sources
	219
	220	=back
e1caacb4	221
75472953	222	Needed source files can be downloaded at
464a08e7	223	L<http://perlce.sourceforge.net>
e1caacb4	224
75472953	225	=head3 Make
e1caacb4	226
9b15f68e	227	Normally you only need to edit F<./win32/ce-helpers/compile.bat>
2e64bfdb	228	to reflect your system and run it.
e1caacb4	229
9b15f68e	230	File F<./win32/ce-helpers/compile.bat> is actually a wrapper to call
45496817 VK	231	C<nmake -f makefile.ce> with appropriate parameters and it accepts extra
45496817 VK	232	parameters and forwards them to C<nmake> command as additional
2e64bfdb	233	arguments. You should pass target this way.
e1caacb4	234
8f33b42a	235	To prepare distribution you need to do following:
2e64bfdb JH	236
	237	=over 4
	238
9b15f68e	239	=item * go to F<./win32> subdirectory
2e64bfdb	240
9b15f68e	241	=item * edit file F<./win32/ce-helpers/compile.bat>
e1caacb4	242
2e64bfdb JH	243	=item * run
2e64bfdb JH	244	compile.bat
e1caacb4	245
2e64bfdb JH	246	=item * run
2e64bfdb JH	247	compile.bat dist
e1caacb4	248
2e64bfdb JH	249	=back
2e64bfdb JH	250
9b15f68e	251	F<Makefile.ce> has C<CROSS_NAME> macro, and it is used further to refer to
8f33b42a VK	252	your cross-compilation scheme. You could assign a name to it, but this
	253	is not necessary, because by default it is assigned after your machine
	254	configuration name, such as "wince-sh3-hpc-wce211", and this is enough
	255	to distinguish different builds at the same time. This option could be
	256	handy for several different builds on same platform to perform, say,
	257	threaded build. In a following example we assume that all required
	258	environment variables are set properly for C cross-compiler (a special
9b15f68e	259	*.bat file could fit perfectly to this purpose) and your F<compile.bat>
45496817	260	has proper "MACHINE" parameter set, to, say, C<wince-mips-pocket-wce300>.
8f33b42a VK	261
	262	compile.bat
	263	compile.bat dist
1dcc3c19 DG	264	compile.bat CROSS_NAME=mips-wce300-thr "USE_ITHREADS=define" ^
	265	"USE_IMP_SYS=define" "USE_MULTI=define"
	266	compile.bat CROSS_NAME=mips-wce300-thr "USE_ITHREADS=define" ^
	267	"USE_IMP_SYS=define" "USE_MULTI=define" dist
8f33b42a VK	268
8f33b42a VK	269	If all goes okay and no errors during a build, you'll get two independent
45496817	270	distributions: C<wince-mips-pocket-wce300> and C<mips-wce300-thr>.
8f33b42a	271
45496817 VK	272	Target C<dist> prepares distribution file set. Target C<zipdist> performs
45496817 VK	273	same as C<dist> but additionally compresses distribution files into zip
8f33b42a VK	274	archive.
8f33b42a VK	275
9b15f68e KW	276	NOTE: during a build there could be created a number (or one) of F<Config.pm>
	277	for cross-compilation ("foreign" F<Config.pm>) and those are hidden inside
	278	F<../xlib/$(CROSS_NAME)> with other auxiliary files, but, and this is important to
	279	note, there should be B<no> F<Config.pm> for host miniperl.
8f33b42a VK	280	If you'll get an error that perl could not find Config.pm somewhere in building
	281	process this means something went wrong. Most probably you forgot to
	282	specify a cross-compilation when invoking miniperl.exe to Makefile.PL
	283	When building an extension for cross-compilation your command line should
	284	look like
	285
	286	..\miniperl.exe -I..\lib -MCross=mips-wce300-thr Makefile.PL
	287
	288	or just
	289
	290	..\miniperl.exe -I..\lib -MCross Makefile.PL
	291
	292	to refer a cross-compilation that was created last time.
	293
8f33b42a	294	All questions related to building for WinCE devices could be asked in
ef39d023	295	F<perlce-user@lists.sourceforge.net> mailing list.
e1caacb4	296
75472953 VK	297	=head1 Using Perl on WinCE
	298
	299	=head2 DESCRIPTION
	300
	301	PerlCE is currently linked with a simple console window, so it also
	302	works on non-hpc devices.
	303
9b15f68e KW	304	The simple stdio implementation creates the files F<stdin.txt>,
9b15f68e KW	305	F<stdout.txt> and F<stderr.txt>, so you might examine them if your
f858446f	306	console has only a limited number of cols.
75472953 VK	307
	308	When exitcode is non-zero, a message box appears, otherwise the
	309	console closes, so you might have to catch an exit with
	310	status 0 in your program to see any output.
	311
9b15f68e KW	312	stdout/stderr now go into the files F</perl-stdout.txt> and
9b15f68e KW	313	F</perl-stderr.txt.>
45496817 VK	314
45496817 VK	315	PerlIDE is handy to deal with perlce.
75472953 VK	316
	317	=head2 LIMITATIONS
	318
	319	No fork(), pipe(), popen() etc.
	320
	321	=head2 ENVIRONMENT
	322
	323	All environment vars must be stored in HKLM\Environment as
	324	strings. They are read at process startup.
	325
45496817 VK	326	=over
	327
	328	=item PERL5LIB
	329
	330	Usual perl lib path (semi-list).
	331
	332	=item PATH
	333
	334	Semi-list for executables.
	335
	336	=item TMP
	337
	338	- Tempdir.
	339
	340	=item UNIXROOTPATH
	341
9b15f68e	342	- Root for accessing some special files, i.e. F</dev/null>, F</etc/services>.
45496817 VK	343
	344	=item ROWS/COLS
	345
	346	- Rows/cols for console.
	347
	348	=item HOME
	349
	350	- Home directory.
	351
	352	=item CONSOLEFONTSIZE
	353
	354	- Size for console font.
	355
	356	=back
75472953 VK	357
	358	You can set these with cereg.exe, a (remote) registry editor
	359	or via the PerlIDE.
	360
	361	=head2 REGISTRY
	362
	363	To start perl by clicking on a perl source file, you have
9b15f68e	364	to make the according entries in HKCR (see F<ce-helpers/wince-reg.bat>).
75472953 VK	365	cereg.exe (which must be executed on a desktop pc with
	366	ActiveSync) is reported not to work on some devices.
	367	You have to create the registry entries by hand using a
	368	registry editor.
	369
75472953 VK	370	=head2 XS
	371
	372	The following Win32-Methods are built-in:
	373
	374	newXS("Win32::GetCwd", w32_GetCwd, file);
	375	newXS("Win32::SetCwd", w32_SetCwd, file);
	376	newXS("Win32::GetTickCount", w32_GetTickCount, file);
	377	newXS("Win32::GetOSVersion", w32_GetOSVersion, file);
	378	newXS("Win32::IsWinNT", w32_IsWinNT, file);
	379	newXS("Win32::IsWin95", w32_IsWin95, file);
	380	newXS("Win32::IsWinCE", w32_IsWinCE, file);
	381	newXS("Win32::CopyFile", w32_CopyFile, file);
	382	newXS("Win32::Sleep", w32_Sleep, file);
	383	newXS("Win32::MessageBox", w32_MessageBox, file);
	384	newXS("Win32::GetPowerStatus", w32_GetPowerStatus, file);
	385	newXS("Win32::GetOemInfo", w32_GetOemInfo, file);
	386	newXS("Win32::ShellEx", w32_ShellEx, file);
	387
	388	=head2 BUGS
	389
	390	Opening files for read-write is currently not supported if
	391	they use stdio (normal perl file handles).
	392
	393	If you find bugs or if it does not work at all on your
	394	device, send mail to the address below. Please report
	395	the details of your device (processor, ceversion,
	396	devicetype (hpc/palm/pocket)) and the date of the downloaded
	397	files.
	398
	399	=head2 INSTALLATION
	400
	401	Currently installation instructions are at L<http://perlce.sourceforge.net/>.
	402
	403	After installation & testing processes will stabilize, information will
	404	be more precise.
	405
c7bcd97d	406	=head1 ACKNOWLEDGEMENTS
e1caacb4 JH	407
	408	The port for Win32 was used as a reference.
	409
45496817 VK	410	=head1 History of WinCE port
	411
	412	=over
	413
	414	=item 5.6.0
	415
	416	Initial port of perl to WinCE. It was performed in separate directory
9b15f68e KW	417	named F<wince>. This port was based on contents of F<./win32> directory.
	418	F<miniperl> was not built, user must have HOST perl and properly edit
	419	F<makefile.ce> to reflect this.
45496817 VK	420
	421	=item 5.8.0
	422
9b15f68e	423	wince port was kept in the same F<./wince> directory, and F<wince/Makefile.ce>
45496817 VK	424	was used to invoke native compiler to create HOST miniperl, which then
	425	facilitates cross-compiling process.
	426	Extension building support was added.
	427
	428	=item 5.9.4
	429
9b15f68e KW	430	Two directories F<./win32> and F<./wince> were merged, so perlce build
9b15f68e KW	431	process comes in F<./win32> directory.
45496817	432
ef39d023	433	=back
45496817	434
2e64bfdb	435	=head1 AUTHORS
e1caacb4	436
75472953 VK	437	=over
	438
	439	=item Rainer Keuchel <coyxc@rainer-keuchel.de>
	440
	441	provided initial port of Perl, which appears to be most essential work, as
	442	it was a breakthrough on having Perl ported at all.
	443	Many thanks and obligations to Rainer!
	444
	445	=item Vadim Konovalov
	446
	447	made further support of WinCE port.
	448
69104b65 SH	449	=item Daniel Dragan
	450
	451	updated the build process during the 5.19 development track.
	452
75472953	453	=back