[perl5.git] / README.epoc

=================================================
Perl 5 README file for the EPOC operating system.
==================================================

Olaf Flebbe <o.flebbe@gmx.de>
http://www.fortunecity.de/wolkenkratzer/trumpet/84/perl5.html
Aug 25, 1999

Introduction
------------ 

This is a port of Perl version 5.005_60 to EPOC. 

There are many features left out, because of restrictions of the POSIX
support in the SDK.


Installation/Usage
------------------

You will need ~4MB free space in order to run perl.

Install perl.sis on the EPOC machine (most likely a PSION Series
5). If you do not know how to do that, you are on your own. You may
have to use a CF Card in order to work with perl. The perl debugger
uses more then 1.5 MB additional RAM. The heap is limited to 2 MB.

Perl itself and its standard library are using 1.7MB disk space. I
left out UTF support and modules which will not work with this
version. (For details look into epoc/createpkg.pl). 

Copy eshell.exe to the same location as perl. Start eshell.exe with a
double click.

Now you can enter: perl -de 0 in order to run the perl debugger. If
you are leaving perl, you have to switch back manually to eshell.exe
(With Ctrl-System or the button in the upper right corner of the
System screen.) When perl is running, you will see a task with the
name STDOUT in the task list. 

You can redirect the output with the UNIX bourne shell syntax (this is
built into perl rather then eshell) For instance the following command
line will run the script test.pl with the output redirected to
stdout_file, the errors to stderr_file and input from stdin_file.

perl test.pl >stdout_file <stdin_file 2>stderr_file

Alternativly you can use 2>&1 in order to add the standard error output to
stdout.

Pathnames to executables in eshell.exe have to be written with
backslashes, file arguments to perl with slashes. The default drive of
perl is the same as the drive perl.exe is located on, the default path
is the path perl.exe is / (???).

i.e. command lines look a little bit funny:

D:\perl.exe C:/test.pl >C:/output.txt

In order to use Getopt::Long you have to autosplit this module by hand: run

\perl.exe \autosplit.pl in order to create the necessary files.

You may have a problem to create perl scripts. A cumbersome workaround
is to use the OPL Editor and exporting to text.

Problems
--------

The following known problems exist:

1) no support for system, backquoting, pipes etc. One cannot exec a
   different process.

2) no signals, kill, alarm. Do not try to use them. This may be
   impossible to implement on EPOC.

3) select is missing.

4) binmode does not exist. (No CR LF to LF translation for text files)

5) Only a stub Config.pm

6) EPOC does not handle the notion of current drive and current
   directory very well (i.e. not at all, but it tries hard to emulate
   one)

7) sockets may hardly of any use.

8) You need the shell eshell.exe in order to run perl.exe and supply
   it with arguments.


Compiling Perl 5 on the EPOC cross compiling envionment.
--------------------------------------------------------

0. You will need the C++ SDK from
   http://developer.epocworld.com/. Install it on a separate
   drive.

1. Get the Perl sources from your nearest CPAN site.
   Unpack the sources of perl5.005_60 in the epoc development drive.
 
2. Copy all files in the directory perl5.005_60/epoc to perl5.005_60.

3. Check the perl.mmp file: It should have the correct locations for
   project und subproject (see step 1)

4. Change to the EPOC development drive and run 
     makmake perl marm
     nmake -f perl.marm
     makesis perl.pkg perl5.005.sis

5. Beam the perl5.005.sis to the Psion5, install and enjoy!

You can use epoc\createpkg.pl to generate a new perl.pkg file. 


Wish List
---------

- Implement an OPX to get rid of eshell.exe.

- Implement system(), in order to run the  tests.

- Implement getprotcolbyname() and relatives.

Support Status
--------------

I'm offering this port "as is".  You can ask me questions, but I can't
guarantee I'll be able to answer them; I don't know much about Perl
internals myself;
Commit	Line	Data
4d2c4e07 OF	1	=================================================
	2	Perl 5 README file for the EPOC operating system.
	3	==================================================
	4
832c1cda	5	Olaf Flebbe <o.flebbe@gmx.de>
4d2c4e07	6	http://www.fortunecity.de/wolkenkratzer/trumpet/84/perl5.html
ae2d1787	7	Aug 25, 1999
4d2c4e07 OF	8
	9	Introduction
	10	------------
	11
ae2d1787	12	This is a port of Perl version 5.005_60 to EPOC.
4d2c4e07	13
ae2d1787	14	There are many features left out, because of restrictions of the POSIX
4d2c4e07 OF	15	support in the SDK.
4d2c4e07 OF	16
4d2c4e07	17
ae2d1787 OF	18	Installation/Usage
ae2d1787 OF	19	------------------
4d2c4e07	20
ae2d1787 OF	21	You will need ~4MB free space in order to run perl.
	22
	23	Install perl.sis on the EPOC machine (most likely a PSION Series
	24	5). If you do not know how to do that, you are on your own. You may
	25	have to use a CF Card in order to work with perl. The perl debugger
	26	uses more then 1.5 MB additional RAM. The heap is limited to 2 MB.
	27
	28	Perl itself and its standard library are using 1.7MB disk space. I
	29	left out UTF support and modules which will not work with this
	30	version. (For details look into epoc/createpkg.pl).
	31
	32	Copy eshell.exe to the same location as perl. Start eshell.exe with a
	33	double click.
	34
	35	Now you can enter: perl -de 0 in order to run the perl debugger. If
	36	you are leaving perl, you have to switch back manually to eshell.exe
	37	(With Ctrl-System or the button in the upper right corner of the
	38	System screen.) When perl is running, you will see a task with the
	39	name STDOUT in the task list.
	40
	41	You can redirect the output with the UNIX bourne shell syntax (this is
	42	built into perl rather then eshell) For instance the following command
	43	line will run the script test.pl with the output redirected to
	44	stdout_file, the errors to stderr_file and input from stdin_file.
	45
	46	perl test.pl >stdout_file <stdin_file 2>stderr_file
	47
	48	Alternativly you can use 2>&1 in order to add the standard error output to
	49	stdout.
	50
	51	Pathnames to executables in eshell.exe have to be written with
	52	backslashes, file arguments to perl with slashes. The default drive of
	53	perl is the same as the drive perl.exe is located on, the default path
	54	is the path perl.exe is / (???).
	55
	56	i.e. command lines look a little bit funny:
	57
	58	D:\perl.exe C:/test.pl >C:/output.txt
4d2c4e07	59
ae2d1787	60	In order to use Getopt::Long you have to autosplit this module by hand: run
4d2c4e07	61
ae2d1787	62	\perl.exe \autosplit.pl in order to create the necessary files.
4d2c4e07	63
ae2d1787 OF	64	You may have a problem to create perl scripts. A cumbersome workaround
ae2d1787 OF	65	is to use the OPL Editor and exporting to text.
4d2c4e07	66
ae2d1787 OF	67	Problems
ae2d1787 OF	68	--------
4d2c4e07	69
ae2d1787	70	The following known problems exist:
4d2c4e07	71
ae2d1787 OF	72	1) no support for system, backquoting, pipes etc. One cannot exec a
	73	different process.
	74
	75	2) no signals, kill, alarm. Do not try to use them. This may be
	76	impossible to implement on EPOC.
	77
	78	3) select is missing.
	79
	80	4) binmode does not exist. (No CR LF to LF translation for text files)
	81
	82	5) Only a stub Config.pm
	83
	84	6) EPOC does not handle the notion of current drive and current
	85	directory very well (i.e. not at all, but it tries hard to emulate
	86	one)
4d2c4e07	87
ae2d1787	88	7) sockets may hardly of any use.
4d2c4e07	89
ae2d1787 OF	90	8) You need the shell eshell.exe in order to run perl.exe and supply
ae2d1787 OF	91	it with arguments.
4d2c4e07 OF	92
	93
	94	Compiling Perl 5 on the EPOC cross compiling envionment.
	95	--------------------------------------------------------
	96
	97	0. You will need the C++ SDK from
ae2d1787 OF	98	http://developer.epocworld.com/. Install it on a separate
ae2d1787 OF	99	drive.
4d2c4e07	100
ae2d1787 OF	101	1. Get the Perl sources from your nearest CPAN site.
	102	Unpack the sources of perl5.005_60 in the epoc development drive.
	103
	104	2. Copy all files in the directory perl5.005_60/epoc to perl5.005_60.
4d2c4e07 OF	105
	106	3. Check the perl.mmp file: It should have the correct locations for
	107	project und subproject (see step 1)
	108
	109	4. Change to the EPOC development drive and run
	110	makmake perl marm
	111	nmake -f perl.marm
	112	makesis perl.pkg perl5.005.sis
	113
	114	5. Beam the perl5.005.sis to the Psion5, install and enjoy!
	115
ae2d1787 OF	116	You can use epoc\createpkg.pl to generate a new perl.pkg file.
	117
	118
	119	Wish List
4d2c4e07 OF	120	---------
4d2c4e07 OF	121
ae2d1787	122	- Implement an OPX to get rid of eshell.exe.
4d2c4e07	123
ae2d1787	124	- Implement system(), in order to run the tests.
4d2c4e07 OF	125
	126	- Implement getprotcolbyname() and relatives.
	127
4d2c4e07 OF	128	Support Status
	129	--------------
	130
	131	I'm offering this port "as is". You can ask me questions, but I can't
	132	guarantee I'll be able to answer them; I don't know much about Perl
ae2d1787	133	internals myself;