[perl5.git] / README.amiga

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

=head1 NAME

perlamiga - Perl under Amiga OS

=head1 SYNOPSIS

One can read this document in the following formats:

	man perlamiga
	multiview perlamiga.guide

to list some (not all may be available simultaneously), or it may
be read I<as is>: either as F<README.amiga>, or F<pod/perlamiga.pod>.

=cut

Contents
 
 perlamiga - Perl under Amiga OS

       NAME 
       SYNOPSIS 
       DESCRIPTION 
         -  Prerequisites 
         -  Starting Perl programs under AmigaOS
       INSTALLATION 
       Accessing documentation 
         -  Manpages 
         -  HTML 
         -  GNU info files 
         -  LaTeX docs 
       BUILD 
         -  Prerequisites 
         -  Getting the perl source 
         -  Application of the patches 
         -  Making 
         -  Testing 
         -  Installing the built perl 
       AUTHOR 
       SEE ALSO 

=head1 DESCRIPTION

=head2 Prerequisites

=over 6

=item B<Unix emulation for AmigaOS: ixemul.library>

You need the Unix emulation for AmigaOS, whose most important part is
B<ixemul.library>. For a minimum setup, get the following archives from
ftp://ftp.ninemoons.com/pub/ade/current or a mirror:

ixemul-45.1-bin.lha
ixemul-45.1-env-bin.lha
pdksh-4.9-bin.lha
ADE-misc-bin.lha

Note that there might be newer versions available by the time you read
this.

Note also that this is a minimum setup; you might want to add other
packages of B<ADE> (the I<Amiga Developers Environment>).

=item B<Version of Amiga OS>

You need at the very least AmigaOS version 2.0. Recommended is version 3.1.

=back

=head2 Starting Perl programs under AmigaOS

Start your Perl program F<foo> with arguments C<arg1 arg2 arg3> the
same way as on any other platform, by

	perl foo arg1 arg2 arg3

If you want to specify perl options C<-my_opts> to the perl itself (as
opposed to to your program), use

	perl -my_opts foo arg1 arg2 arg3

Alternately, you can try to get a replacement for the system's B<Execute>
command that honors the #!/usr/bin/perl syntax in scripts and set the s-Bit
of your scripts. Then you can invoke your scripts like under UNIX with

	foo arg1 arg2 arg3

(Note that having *nixish full path to perl F</usr/bin/perl> is not
necessary, F<perl> would be enough, but having full path would make it
easier to use your script under *nix.)

=head1 INSTALLATION

Change to the installation directory (most probably ADE:), and
extract the binary distribution:

lha -mraxe x perl-5.003-bin.lha

or

tar xvzpf perl-5.003-bin.tgz

(Of course you need lha or tar and gunzip for this.)

For installation of the Unix emulation, read the appropriate docs.

=head1 Accessing documentation

=head2 Manpages

If you have C<man> installed on your system, and you installed perl
manpages, use something like this:

	man perlfunc
	man less
	man ExtUtils.MakeMaker

to access documentation for different components of Perl. Start with

	man perl

Note: You have to modify your man.conf file to search for manpages
in the /ade/lib/perl5/man/man3 directory, or the man pages for the
perl library will not be found. 

Note that dot (F<.>) is used as a package separator for documentation
for packages, and as usual, sometimes you need to give the section - C<3>
above - to avoid shadowing by the I<less(1) manpage>.


=head2 B<HTML>

If you have some WWW browser available, you can build B<HTML> docs.
Cd to directory with F<.pod> files, and do like this

	cd /ade/lib/perl5/pod
	pod2html

After this you can direct your browser the file F<perl.html> in this
directory, and go ahead with reading docs.

Alternatively you may be able to get these docs prebuilt from C<CPAN>.

=head2 B<GNU> C<info> files

Users of C<Emacs> would appreciate it very much, especially with
C<CPerl> mode loaded. You need to get latest C<pod2info> from C<CPAN>,
or, alternately, prebuilt info pages.

=head2 C<LaTeX> docs

can be constructed using C<pod2latex>.

=head1 BUILD

Here we discuss how to build Perl under AmigaOS.

=head2 Prerequisites

You need to have the latest B<ADE> (Amiga Developers Environment)
from ftp://ftp.ninemoons.com/pub/ade/current.
Also, you need a lot of free memory, probably at least 8MB.

=head2 Getting the perl source

You can either get the latest perl-for-amiga source from Ninemoons
and extract it with:

  tar xvzpf perl-5.004-src.tgz

or get the official source from CPAN:

  http://www.perl.com/CPAN/src/5.0

Extract it like this

  tar xvzpf perl5.004.tar.gz

You will see a message about errors while extracting F<Configure>. This
is normal and expected. (There is a conflict with a similarly-named file
F<configure>, but it causes no harm.)

=head2 Making

  sh configure.gnu --prefix=/ade

Now

  make

=head2 Testing

Now run

  make test

Some tests will fail. Here is which, and why:

=over 8

=item F<io/fs.t>, F<op/stat.t>, F<lib/*dbm.t>, F<lib/db-*.t>

Check I<file system> operations. Failures result from the inability to
emulate some Unixisms with the standard Amiga filesystem.

=item F<io/pipe.t>, F<op/fork.t>, F<lib/filehand.t>, F<lib/open2.t>,
      F<lib/open3.t>, F<lib/io_pipe.t>, F<lib/io_sock.t>

These tests will be skipped because they use the fork() function, which is not
supported under AmigaOS.

=item F<op/magic.t>

The ixemul.library doesn't set the expected values for $0 and $^X.

=back

=head2 Installing the built perl

Run

  make install

=head1 AUTHOR

Norbert Pueschel, pueschel@imsdd.meb.uni-bonn.de

=head1 SEE ALSO

perl(1).

=cut
Commit	Line	Data
0a753a76	1	If you read this file _as_is_, just ignore the funny characters you
	2	see. It is written in the POD format (see perlpod manpage) which is
	3	specially designed to be readable as is.
	4
	5	=head1 NAME
	6
	7	perlamiga - Perl under Amiga OS
	8
	9	=head1 SYNOPSIS
	10
	11	One can read this document in the following formats:
	12
	13	man perlamiga
	14	multiview perlamiga.guide
	15
	16	to list some (not all may be available simultaneously), or it may
	17	be read I<as is>: either as F<README.amiga>, or F<pod/perlamiga.pod>.
	18
	19	=cut
	20
	21	Contents
	22
	23	perlamiga - Perl under Amiga OS
	24
	25	NAME
	26	SYNOPSIS
	27	DESCRIPTION
	28	- Prerequisites
	29	- Starting Perl programs under AmigaOS
	30	INSTALLATION
	31	Accessing documentation
	32	- Manpages
	33	- HTML
	34	- GNU info files
	35	- LaTeX docs
	36	BUILD
	37	- Prerequisites
	38	- Getting the perl source
	39	- Application of the patches
	40	- Making
	41	- Testing
	42	- Installing the built perl
	43	AUTHOR
	44	SEE ALSO
	45
	46	=head1 DESCRIPTION
	47
	48	=head2 Prerequisites
	49
	50	=over 6
	51
	52	=item B<Unix emulation for AmigaOS: ixemul.library>
	53
	54	You need the Unix emulation for AmigaOS, whose most important part is
	55	B<ixemul.library>. For a minimum setup, get the following archives from
	56	ftp://ftp.ninemoons.com/pub/ade/current or a mirror:
	57
	58	ixemul-45.1-bin.lha
	59	ixemul-45.1-env-bin.lha
	60	pdksh-4.9-bin.lha
	61	ADE-misc-bin.lha
	62
	63	Note that there might be newer versions available by the time you read
	64	this.
65
66	Note also that this is a minimum setup; you might want to add other
67	packages of B<ADE> (the I<Amiga Developers Environment>).
68
69	=item B<Version of Amiga OS>
70
71	You need at the very least AmigaOS version 2.0. Recommended is version 3.1.
72
73	=back
74
75	=head2 Starting Perl programs under AmigaOS
76
77	Start your Perl program F<foo> with arguments C<arg1 arg2 arg3> the
78	same way as on any other platform, by
79
80	perl foo arg1 arg2 arg3
81
82	If you want to specify perl options C<-my_opts> to the perl itself (as
83	opposed to to your program), use
84
85	perl -my_opts foo arg1 arg2 arg3
86
87	Alternately, you can try to get a replacement for the system's B<Execute>
88	command that honors the #!/usr/bin/perl syntax in scripts and set the s-Bit
89	of your scripts. Then you can invoke your scripts like under UNIX with
90
91	foo arg1 arg2 arg3
92
93	(Note that having *nixish full path to perl F</usr/bin/perl> is not
94	necessary, F<perl> would be enough, but having full path would make it
95	easier to use your script under *nix.)
96
97	=head1 INSTALLATION
98
99	Change to the installation directory (most probably ADE:), and
100	extract the binary distribution:
101
102	lha -mraxe x perl-5.003-bin.lha
103
104	or
105
106	tar xvzpf perl-5.003-bin.tgz
107
108	(Of course you need lha or tar and gunzip for this.)
109
110	For installation of the Unix emulation, read the appropriate docs.
111
112	=head1 Accessing documentation
113
114	=head2 Manpages
115
116	If you have C<man> installed on your system, and you installed perl
117	manpages, use something like this:
118
119	man perlfunc
120	man less
121	man ExtUtils.MakeMaker
122
123	to access documentation for different components of Perl. Start with
124
125	man perl
126
127	Note: You have to modify your man.conf file to search for manpages
128	in the /ade/lib/perl5/man/man3 directory, or the man pages for the
129	perl library will not be found.
130
131	Note that dot (F<.>) is used as a package separator for documentation
132	for packages, and as usual, sometimes you need to give the section - C<3>
133	above - to avoid shadowing by the I<less(1) manpage>.
134
135
136	=head2 B<HTML>
137
138	If you have some WWW browser available, you can build B<HTML> docs.
139	Cd to directory with F<.pod> files, and do like this
140
141	cd /ade/lib/perl5/pod
142	pod2html
143
144	After this you can direct your browser the file F<perl.html> in this
145	directory, and go ahead with reading docs.
146
147	Alternatively you may be able to get these docs prebuilt from C<CPAN>.
148
149	=head2 B<GNU> C<info> files
150
151	Users of C<Emacs> would appreciate it very much, especially with
152	C<CPerl> mode loaded. You need to get latest C<pod2info> from C<CPAN>,
153	or, alternately, prebuilt info pages.
154
155	=head2 C<LaTeX> docs
156
157	can be constructed using C<pod2latex>.
158
159	=head1 BUILD
160
161	Here we discuss how to build Perl under AmigaOS.
162
163	=head2 Prerequisites
164
165	You need to have the latest B<ADE> (Amiga Developers Environment)
166	from ftp://ftp.ninemoons.com/pub/ade/current.
167	Also, you need a lot of free memory, probably at least 8MB.
168
169	=head2 Getting the perl source
170
171	You can either get the latest perl-for-amiga source from Ninemoons
172	and extract it with:
173
174	tar xvzpf perl-5.004-src.tgz
175
176	or get the official source from CPAN:
177
178	http://www.perl.com/CPAN/src/5.0
179
180	Extract it like this
181
182	tar xvzpf perl5.004.tar.gz
183
184	You will see a message about errors while extracting F<Configure>. This
185	is normal and expected. (There is a conflict with a similarly-named file
186	F<configure>, but it causes no harm.)
187
188	=head2 Making
189
190	sh configure.gnu --prefix=/ade
191
192	Now
193
194	make
195
196	=head2 Testing
197
198	Now run
199
200	make test
201
202	Some tests will fail. Here is which, and why:
203
204	=over 8
205
206	=item F<io/fs.t>, F<op/stat.t>, F<lib/dbm.t>, F<lib/db-.t>
207
208	Check I<file system> operations. Failures result from the inability to
209	emulate some Unixisms with the standard Amiga filesystem.
210
211	=item F<io/pipe.t>, F<op/fork.t>, F<lib/filehand.t>, F<lib/open2.t>,
212	F<lib/open3.t>, F<lib/io_pipe.t>, F<lib/io_sock.t>
213
214	These tests will be skipped because they use the fork() function, which is not
215	supported under AmigaOS.
216
f86702cc	217	=item F<op/magic.t>
	218
	219	The ixemul.library doesn't set the expected values for $0 and $^X.
	220
0a753a76	221	=back
	222
	223	=head2 Installing the built perl
	224
	225	Run
	226
	227	make install
	228
	229	=head1 AUTHOR
	230
	231	Norbert Pueschel, pueschel@imsdd.meb.uni-bonn.de
	232
	233	=head1 SEE ALSO
	234
	235	perl(1).
	236
	237	=cut