EditPageHistoryDiffInfoLikePages

Annotated edit history of perlos2(1) version 2, including all changes. View license author blame.

Rev	Author	#	Line
1	perry	1	PERLOS2
		2	!!!PERLOS2
		3	NAME
		4	SYNOPSIS
		5	DESCRIPTION
		6	Frequently asked questions
		7	INSTALLATION
		8	Accessing documentation
		9	BUILD
		10	Build FAQ
		11	Specific (mis)features of OS/2 port
		12	Perl flavors
		13	ENVIRONMENT
		14	Evolution
		15	AUTHOR
		16	SEE ALSO
		17	----
		18	!!NAME
		19
		20
		21	perlos2 - Perl under OS/2 , DOS , Win0.3*, Win0.95 and WinNT.
		22	!!SYNOPSIS
		23
		24
		25	One can read this document in the following
		26	formats:
		27
		28
		29	man perlos2
		30	view perl perlos2
		31	explorer perlos2.html
		32	info perlos2
		33	to list some (not all may be available simultaneously), or it may be read ''as is'': either as ''README .os2'', or ''pod/perlos2.pod''.
		34
		35
		36	To read the ''.INF'' version of documentation
		37	(__very__ recommended) outside of OS/2 ,
		38	one needs an IBM 's reader (may be available
		39	on IBM ftp sites (?) ( URL
		40	anyone?)) or shipped with PC DOS 7.0 and
		41	IBM 's Visual Age C ++
		42	3.5.
		43
		44
		45	A copy of a Win* viewer is contained in the ``Just add
		46	OS/2 Warp'' package
		47
		48
		49	ftp://ftp.software.ibm.com/ps/products/os2/tools/jaow/jaow.zip
		50	in ''?:JUST_ADDview.exe''. This gives one an access to EMX 's ''.INF'' docs as well (text form is available in ''/emx/doc'' in EMX 's distribution).
		51
		52
		53	Note that if you have ''lynx.exe'' installed, you can
		54	follow WWW links from this document in
		55	''.INF'' format. If you have EMX docs
		56	installed correctly, you can follow library links (you need
		57	to have view emxbook working by setting
		58	EMXBOOK environment variable as it is described in
		59	EMX docs).
		60	!!DESCRIPTION
		61
		62
		63	__Target__
		64
		65
		66	The target is to make OS/2 the best supported
		67	platform for using/building/developing Perl and ''Perl
		68	applications'', as well as make Perl the best language to
		69	use under OS/2 . The secondary target is to
		70	try to make this work under DOS and Win* as
		71	well (but not __too__ hard).
		72
		73
		74	The current state is quite close to this target. Known
		75	limitations:
		76
		77
		78	Some *nix programs use ''fork()'' a lot; with the mostly
		79	useful flavors of perl for OS/2 (there are
		80	several built simultaneously) this is supported; some
		81	flavors do not. Using ''fork()'' after ''use''ing
		82	dynamically loading extensions would not work with very old
		83	versions of EMX .
		84
		85
		86	You need a separate perl executable ''perl__.exe'' (see
		87	perl__.exe) if you want to use PM code in
		88	your application (as Perl/Tk or OpenGL Perl modules do)
		89	without having a text-mode window present.
		90
		91
		92	While using the standard ''perl.exe'' from a text-mode
		93	window is possible too, I have seen cases when this causes
		94	degradation of the system stability. Using ''perl__.exe''
		95	avoids such a degradation.
		96
		97
		98	There is no simple way to access WPS objects.
		99	The only way I know is via OS2::REXX extension (see
		100	OS2::REXX ), and we do not have access to
		101	convenience methods of Object-REXX. (Is it possible at all?
		102	I know of no Object-REXX API .) The
		103	SOM extension (currently in alpha-text) may
		104	eventually remove this shortcoming.
		105
		106
		107	Please keep this list up-to-date by informing me about other
		108	items.
		109
		110
		111	__Other OSes__
		112
		113
		114	Since OS/2 port of perl uses a remarkable
		115	EMX environment, it can run (and build
		116	extensions, and - possibly - be built itself) under any
		117	environment which can run EMX . The current
		118	list is DOS , DOS-inside-OS/2, Win0.3*,
		119	Win0.95 and WinNT. Out of many perl flavors, only one works,
		120	see ``perl_.exe''.
		121
		122
		123	Note that not all features of Perl are available under these
		124	environments. This depends on the features the
		125	''extender'' - most probably RSX - decided
		126	to implement.
		127
		128
		129	Cf. Prerequisites.
		130
		131
		132	__Prerequisites__
		133
		134
		135	EMX
		136
		137
		138	EMX runtime is required (may be substituted
		139	by RSX ). Note that it is possible to make
		140	''perl_.exe'' to run under DOS without any
		141	external support by binding ''emx.exe''/''rsx.exe'' to
		142	it, see emxbind. Note that under DOS for best
		143	results one should use RSX runtime, which has
		144	much more functions working (like fork,
		145	popen and so on). In fact RSX is
		146	required if there is no VCPI present. Note
		147	the RSX requires DPMI
		148	.
		149
		150
		151	Only the latest runtime is supported, currently 0.9d fix
		152	03. Perl may run under earlier versions of
		153	EMX , but this is not tested.
		154
		155
		156	One can get different parts of EMX from,
		157	say
		158
		159
		160	http://www.leo.org/pub/comp/os/os2/leo/gnu/emx+gcc/
		161	http://powerusersbbs.com/pub/os2/dev/ [[EMX+GCC Development]
		162	http://hobbes.nmsu.edu/pub/os2/dev/emx/v0.9d/
		163	The runtime component should have the name ''emxrt.zip''.
		164
		165
		166	__NOTE__ . It is enough to have
		167	''emx.exe''/''rsx.exe'' on your path. One does not
		168	need to specify them explicitly (though this
		169
		170
		171	emx perl_.exe -de 0
		172	will work as well.)
		173
		174
		175	RSX
		176
		177
		178	To run Perl on DPMI platforms one needs
		179	RSX runtime. This is needed under
		180	DOS-inside-OS/2, Win0.3*, Win0.95 and WinNT (see ``Other
		181	OSes''). RSX would not work with
		182	VCPI only, as EMX would, it
		183	requires DMPI .
		184
		185
		186	Having RSX and the latest ''sh.exe'' one
		187	gets a fully functional __*nix__-ish environment under
		188	DOS , say, fork, `` and
2	perry	189	pipe-open work. In fact, !MakeMaker works (for
1	perry	190	static build), so one can have Perl development environment
		191	under DOS .
		192
		193
		194	One can get RSX from, say
		195
		196
		197	ftp://ftp.cdrom.com/pub/os2/emx09c/contrib
		198	ftp://ftp.uni-bielefeld.de/pub/systems/msdos/misc
		199	ftp://ftp.leo.org/pub/comp/os/os2/leo/devtools/emx+gcc/contrib
		200	Contact the author on rainer@mathematik.uni-bielefeld.de.
		201
		202
		203	The latest ''sh.exe'' with DOS hooks is
		204	available in
		205
		206
		207	ftp://ftp.math.ohio-state.edu/pub/users/ilya/os2/
		208	as ''sh_dos.zip'' or under similar names starting with sh, pdksh etc.
		209
		210
		211	HPFS
		212
		213
		214	Perl does not care about file systems, but to install the
		215	whole perl library intact one needs a file system which
		216	supports long file names.
		217
		218
		219	Note that if you do not plan to build the perl itself, it
		220	may be possible to fool EMX to truncate file
		221	names. This is not supported, read EMX docs
		222	to see how to do it.
		223
		224
		225	pdksh
		226
		227
		228	To start external programs with complicated command lines
		229	(like with pipes in between, and/or quoting of arguments),
		230	Perl uses an external shell. With EMX port
		231	such shell should be named ''sh.exe'', and located either
		232	in the wired-in-during-compile locations (usually
		233	''F:/bin''), or in configurable location (see ``
		234	PERL_SH_DIR '').
		235
		236
		237	For best results use EMX pdksh. The standard
		238	binary (5.2.14 or later) runs under DOS (with
		239	RSX ) as well, see
		240
		241
		242	ftp://ftp.math.ohio-state.edu/pub/users/ilya/os2/
		243
		244
		245	__Starting Perl programs under OS/2 (and
		246	DOS and...)__
		247
		248
		249	Start your Perl program ''foo.pl'' with arguments
		250	arg1 arg2 arg3 the same way as on any other
		251	platform, by
		252
		253
		254	perl foo.pl arg1 arg2 arg3
		255	If you want to specify perl options -my_opts to the perl itself (as opposed to to your program), use
		256
		257
		258	perl -my_opts foo.pl arg1 arg2 arg3
		259	Alternately, if you use OS/2-ish shell, like CMD or 4os2, put the following at the start of your perl script:
		260
		261
		262	extproc perl -S -my_opts
		263	rename your program to ''foo.cmd'', and start it by typing
		264
		265
		266	foo arg1 arg2 arg3
		267	Note that because of stupid OS/2 limitations the full path of the perl script is not available when you use extproc, thus you are forced to use -S perl switch, and your script should be on the PATH. As a plus side, if you know a full path to your script, you may still start it with
		268
		269
		270	perl ../../blah/foo.cmd arg1 arg2 arg3
		271	(note that the argument -my_opts is taken care of by the extproc line in your script, see extproc on the first line
		272
		273
		274	To understand what the above ''magic'' does, read perl
		275	docs about -S switch - see perlrun, and cmdref
		276	about extproc:
		277
		278
		279	view perl perlrun
		280	man perlrun
		281	view cmdref extproc
		282	help extproc
		283	or whatever method you prefer.
		284
		285
		286	There are also endless possibilities to use ''executable
		287	extensions'' of 4os2, ''associations'' of
		288	WPS and so on... However, if you use *nixish
		289	shell (like ''sh.exe'' supplied in the binary
		290	distribution), you need to follow the syntax specified in
		291	``Switches'' in perlrun.
		292
		293
		294	Note that __-S__ switch enables a search with additional
		295	extensions ''.cmd'', ''.btm'', ''.bat'', ''.pl''
		296	as well.
		297
		298
		299	__Starting OS/2 (and DOS )
		300	programs under Perl__
		301
		302
		303	This is what ''system()'' (see ``system'' in perlfunc),
		304	`` (see ``I/O Operators'' in perlop), and ''open
		305	pipe'' (see ``open'' in perlfunc) are for. (Avoid
		306	''exec()'' (see ``exec'' in perlfunc) unless you know
		307	what you do).
		308
		309
		310	Note however that to use some of these operators you need to
		311	have a sh-syntax shell installed (see ``Pdksh'',
		312	``Frequently asked questions''), and perl should be able to
		313	find it (see `` PERL_SH_DIR '').
		314
		315
		316	The cases when the shell is used are:
		317
		318
		319	1
		320
		321
		322	One-argument ''system()'' (see ``system'' in perlfunc),
		323	''exec()'' (see ``exec'' in perlfunc) with redirection or
		324	shell meta-characters;
		325
		326
		327	2
		328
		329
		330	Pipe-open (see ``open'' in perlfunc) with the command which
		331	contains redirection or shell meta-characters;
		332
		333
		334	3
		335
		336
		337	Backticks `` (see ``I/O Operators'' in perlop) with
		338	the command which contains redirection or shell
		339	meta-characters;
		340
		341
		342	4
		343
		344
		345	If the executable called by
		346	''system()''/''exec()''/pipe-''open()''/``
		347	is a script with the ``magic'' #! line or
		348	extproc line which specifies shell;
		349
		350
		351	5
		352
		353
		354	If the executable called by
		355	''system()''/''exec()''/pipe-''open()''/``
		356	is a script without ``magic'' line, and
		357	$ENV{EXECSHELL} is set to shell;
		358
		359
		360	6
		361
		362
		363	If the executable called by
		364	''system()''/''exec()''/pipe-''open()''/``
		365	is not found;
		366
		367
		368	7
		369
		370
		371	For globbing (see ``glob'' in perlfunc, ``I/O Operators'' in
		372	perlop).
		373
		374
		375	For the sake of speed for a common case, in the above
		376	algorithms backslashes in the command name are not
		377	considered as shell metacharacters.
		378
		379
		380	Perl starts scripts which begin with cookies
		381	extproc or #! directly, without an
		382	intervention of shell. Perl uses the same algorithm to find
		383	the executable as ''pdksh'': if the path on #!
		384	line does not work, and contains /, then the
		385	executable is searched in ''.'' and on PATH. To
		386	find arguments for these scripts Perl uses a different
		387	algorithm than ''pdksh'': up to 3 arguments are
		388	recognized, and trailing whitespace is
		389	stripped.
		390
		391
		392	If a script does not contain such a cooky, then to avoid
		393	calling ''sh.exe'', Perl uses the same algorithm as
		394	''pdksh'': if $ENV{EXECSHELL} is set, the script
		395	is given as the first argument to this command, if not set,
		396	then $ENV{COMSPEC} /c is used (or a hardwired guess
		397	if $ENV{COMSPEC} is not set).
		398
		399
		400	If starting scripts directly, Perl will use exactly the same
		401	algorithm as for the search of script given by __-S__
		402	command-line option: it will look in the current directory,
		403	then on components of $ENV{PATH} using the
		404	following order of appended extensions: no extension,
		405	''.cmd'', ''.btm'', ''.bat'',
		406	''.pl''.
		407
		408
		409	Note that Perl will start to look for scripts only if
		410	OS/2 cannot start the specified application,
		411	thus system 'blah' will not look for a script if
		412	there is an executable file ''blah.exe anywhere'' on
		413	PATH.
		414
		415
		416	Note also that executable files on OS/2 can
		417	have an arbitrary extension, but ''.exe'' will be
		418	automatically appended if no dot is present in the name. The
		419	workaround as as simple as that: since ''blah.'' and
		420	''blah'' denote the same file, to start an executable
		421	residing in file ''n:/bin/blah'' (no extension) give an
		422	argument n:/bin/blah. (dot appended) to
		423	''system()''.
		424
		425
		426	Perl will correctly start PM programs from
		427	VIO (=text-mode) Perl process; the opposite
		428	is not true: when you start a non-PM program from a
		429	PM Perl process, it would not run it in a
		430	separate session. If a separate session is desired, either
		431	ensure that shell will be used, as in system 'cmd /c
		432	myprog', or start it using optional arguments to
		433	''system()'' documented in OS2::Process module.
		434	This is considered to be a feature.
		435	!!Frequently asked questions
		436
		437
		438	__``It does not work''__
		439
		440
		441	Perl binary distributions come with a ''testperl.cmd''
		442	script which tries to detect common problems with
		443	misconfigured installations. There is a pretty large chance
		444	it will discover which step of the installation you managed
		445	to goof. ;-)
		446
		447
		448	__I cannot run external programs__
		449
		450
		451	Did you run your programs with -w switch? See ``2
		452	(and DOS ) programs under Perl'' in Starting
		453	OS .
		454
		455
		456	Do you try to run ''internal'' shell commands, like
		457	`copy a b` (internal for ''cmd.exe''), or
		458	`glob a*b` (internal for ksh)? You need to specify
		459	your shell explicitly, like `cmd /c copy a b`,
		460	since Perl cannot deduce which commands are internal to your
		461	shell.
		462
		463
		464	__I cannot embed perl into my program, or use__
		465	''perl.dll'' __from my program.__
		466
		467
		468	Is your program EMX-compiled with -Zmt
		469	-Zcrtdll?
		470
		471
		472	If not, you need to build a stand-alone DLL
		473	for perl. Contact me, I did it once. Sockets would not work,
		474	as a lot of other stuff.
		475
		476
2	perry	477	Did you use !ExtUtils::Embed?
1	perry	478
		479
		480	I had reports it does not work. Somebody would need to fix
		481	it.
		482
		483
		484	`` __and pipe-__open __do not work
		485	under DOS .__
		486
		487
		488	This may a variant of just ``I cannot run external
		489	programs'', or a deeper problem. Basically: you ''need''
		490	RSX (see ``Prerequisites'') for these
		491	commands to work, and you may need a port of ''sh.exe''
		492	which understands command arguments. One of such ports is
		493	listed in ``Prerequisites'' under RSX . Do
		494	not forget to set variable `` PERL_SH_DIR
		495	'' as well.
		496
		497
		498	DPMI is required for RSX
		499	.
		500
		501
		502	__Cannot start__ find.exe ``pattern''
		503	file
		504
		505
		506	Use one of
		507
		508
		509	system 'cmd', '/c', 'find
		510	This would start ''find.exe'' via ''cmd.exe'' via sh.exe via perl.exe, but this is a price to pay if you want to use non-conforming program. In fact ''find.exe'' cannot be started at all using C library API only. Otherwise the following command-lines would be equivalent:
		511
		512
		513	find
		514	!!INSTALLATION
		515
		516
		517	__Automatic binary installation__
		518
		519
		520	The most convenient way of installing a binary distribution
		521	of perl is via perl installer ''install.exe''. Just
		522	follow the instructions, and 99% of the installation blues
		523	would go away.
		524
		525
		526	Note however, that you need to have ''unzip.exe'' on your
		527	path, and EMX environment ''running''. The
		528	latter means that if you just installed EMX ,
		529	and made all the needed changes to ''Config.sys'', you
		530	may need to reboot in between. Check EMX
		531	runtime by running
		532
		533
		534	emxrev
		535	A folder is created on your desktop which contains some useful objects.
		536
		537
		538	__Things not taken care of by automatic binary
		539	installation:__
		540
		541
		542	PERL_BADLANG
		543
		544
		545	may be needed if you change your codepage ''after'' perl
		546	installation, and the new value is not supported by
		547	EMX . See `` PERL_BADLANG
		548	''.
		549
		550
		551	PERL_BADFREE
		552
		553
		554	see `` PERL_BADFREE ''.
		555
		556
		557	''Config.pm''
		558
		559
		560	This file resides somewhere deep in the location you
		561	installed your perl library, find it out by
		562
		563
		564	perl -MConfig -le
		565	While most important values in this file ''are'' updated by the binary installer, some of them may need to be hand-edited. I know no such data, please keep me informed if you find one.
		566
		567
		568	__NOTE__ . Because of a typo the binary
		569	installer of 5.00305 would install a variable
		570	PERL_SHPATH into ''Config.sys''. Please remove
		571	this variable and put PERL_SH_DIR
		572	instead.
		573
		574
		575	__Manual binary installation__
		576
		577
		578	As of version 5.00305, OS/2 perl binary
		579	distribution comes split into 11 components. Unfortunately,
		580	to enable configurable binary installation, the file paths
		581	in the zip files are not absolute, but relative to some
		582	directory.
		583
		584
		585	Note that the extraction with the stored paths is still
		586	necessary (default with unzip, specify -d to
		587	pkunzip). However, you need to know where to extract the
		588	files. You need also to manually change entries in
		589	''Config.sys'' to reflect where did you put the files.
		590	Note that if you have some primitive unzipper (like
		591	pkunzip), you may get a lot of warnings/errors during
		592	unzipping. Upgrade to (w)unzip.
		593
		594
		595	Below is the sample of what to do to reproduce the
		596	configuration on my machine:
		597
		598
		599	Perl VIO and PM executables
		600	(dynamically linked)
		601
		602
		603	unzip perl_exc.zip *.exe *.ico -d f:/emx.add/bin
		604	unzip perl_exc.zip *.dll -d f:/emx.add/dll
		605	(have the directories with *.exe on PATH , and *.dll on LIBPATH );
		606
		607
		608	Perl_ VIO executable (statically
		609	linked)
		610
		611
		612	unzip perl_aou.zip -d f:/emx.add/bin
		613	(have the directory on PATH );
		614
		615
		616	Executables for Perl utilities
		617
		618
		619	unzip perl_utl.zip -d f:/emx.add/bin
		620	(have the directory on PATH );
		621
		622
		623	Main Perl library
		624
		625
		626	unzip perl_mlb.zip -d f:/perllib/lib
		627	If this directory is exactly the same as the prefix which was compiled into ''perl.exe'', you do not need to change anything. However, for perl to find the library if you use a different path, you need to set PERLLIB_PREFIX in ''Config.sys'', see `` PERLLIB_PREFIX ''.
		628
		629
		630	Additional Perl modules
		631
		632
		633	unzip perl_ste.zip -d f:/perllib/lib/site_perl/5.8.3/
		634	Same remark as above applies. Additionally, if this directory is not one of directories on @INC (and @INC is influenced by PERLLIB_PREFIX), you need to put this directory and subdirectory ''./os2'' in PERLLIB or PERL5LIB variable. Do not use PERL5LIB unless you have it set already. See `` ENVIRONMENT '' in perl.
		635
		636
		637	Tools to compile Perl modules
		638
		639
		640	unzip perl_blb.zip -d f:/perllib/lib
		641	Same remark as for ''perl_ste.zip''.
		642
		643
		644	Manpages for Perl and utilities
		645
		646
		647	unzip perl_man.zip -d f:/perllib/man
		648	This directory should better be on MANPATH. You need to have a working man to access these files.
		649
		650
		651	Manpages for Perl modules
		652
		653
		654	unzip perl_mam.zip -d f:/perllib/man
		655	This directory should better be on MANPATH. You need to have a working man to access these files.
		656
		657
		658	Source for Perl documentation
		659
		660
		661	unzip perl_pod.zip -d f:/perllib/lib
2	perry	662	This is used by the perldoc program (see perldoc), and may be used to generate HTML documentation usable by WWW browsers, and documentation in zillions of other formats: info, LaTeX, Acrobat, !FrameMaker and so on.
1	perry	663
		664
		665	Perl manual in ''.INF'' format
		666
		667
		668	unzip perl_inf.zip -d d:/os2/book
		669	This directory should better be on BOOKSHELF.
		670
		671
		672	Pdksh
		673
		674
		675	unzip perl_sh.zip -d f:/bin
		676	This is used by perl to run external commands which explicitly require shell, like the commands using ''redirection'' and ''shell metacharacters''. It is also used instead of explicit ''/bin/sh''.
		677
		678
		679	Set PERL_SH_DIR (see `` PERL_SH_DIR
		680	'') if you move ''sh.exe'' from the above
		681	location.
		682
		683
		684	__Note.__ It may be possible to use some other
		685	sh-compatible shell (file globbing - if done via shell - may
		686	break).
		687
		688
		689	After you installed the components you needed and updated
		690	the ''Config.sys'' correspondingly, you need to hand-edit
		691	''Config.pm''. This file resides somewhere deep in the
		692	location you installed your perl library, find it out
		693	by
		694
		695
		696	perl -MConfig -le
		697	You need to correct all the entries which look like file paths (they currently start with f:/).
		698
		699
		700	__Warning__
		701
		702
		703	The automatic and manual perl installation leave precompiled
		704	paths inside perl executables. While these paths are
		705	overwriteable (see `` PERLLIB_PREFIX '', ``
		706	PERL_SH_DIR ''), one may get better results
		707	by binary editing of paths inside the
		708	executables/DLLs.
		709	!!Accessing documentation
		710
		711
		712	Depending on how you built/installed perl you may have
		713	(otherwise identical) Perl documentation in the following
		714	formats:
		715
		716
		717	__OS/2__ ''.INF''
		718	__file__
		719
		720
		721	Most probably the most convenient form. Under
		722	OS/2 view it as
		723
		724
		725	view perl
		726	view perl perlfunc
		727	view perl less
2	perry	728	view perl !ExtUtils::!MakeMaker
1	perry	729	(currently the last two may hit a wrong location, but this may improve soon). Under Win* see `` SYNOPSIS ''.
		730
		731
		732	If you want to build the docs yourself, and have
		733	''OS/2 toolkit'', run
		734
		735
		736	pod2ipf
		737	in ''/perllib/lib/pod'' directory, then
		738
		739
		740	ipfc /inf perl.ipf
		741	(Expect a lot of errors during the both steps.) Now move it on your BOOKSHELF path.
		742
		743
		744	__Plain text__
		745
		746
		747	If you have perl documentation in the source form, perl
		748	utilities installed, and GNU groff installed,
		749	you may use
		750
		751
		752	perldoc perlfunc
		753	perldoc less
2	perry	754	perldoc !ExtUtils::!MakeMaker
1	perry	755	to access the perl documentation in the text form (note that you may get better results using perl manpages).
		756
		757
		758	Alternately, try running pod2text on ''.pod''
		759	files.
		760
		761
		762	__Manpages__
		763
		764
		765	If you have man installed on your system, and you installed
		766	perl manpages, use something like this:
		767
		768
		769	man perlfunc
		770	man 3 less
2	perry	771	man !ExtUtils.!MakeMaker
1	perry	772	to access documentation for different components of Perl. Start with
		773
		774
		775	man perl
		776	Note that dot (''.'') is used as a package separator for documentation for packages, and as usual, sometimes you need to give the section - 3 above - to avoid shadowing by the ''less(1) manpage''.
		777
		778
		779	Make sure that the directory __above__ the directory with
		780	manpages is on our MANPATH, like this
		781
		782
		783	set MANPATH=c:/man;f:/perllib/man
		784	for Perl manpages in f:/perllib/man/man1/ etc.
		785
		786
		787	__HTML__
		788
		789
		790	If you have some WWW browser available,
		791	installed the Perl documentation in the source form, and
		792	Perl utilities, you can build HTML docs. Cd
		793	to directory with ''.pod'' files, and do like
		794	this
		795
		796
		797	cd f:/perllib/lib/pod
		798	pod2html
		799	After this you can direct your browser the file ''perl.html'' in this directory, and go ahead with reading docs, like this:
		800
		801
		802	explore file:///f:/perllib/lib/pod/perl.html
		803	Alternatively you may be able to get these docs prebuilt from CPAN .
		804
		805
		806	__GNU__ info
		807	__files__
		808
		809
		810	Users of Emacs would appreciate it very much, especially
		811	with CPerl mode loaded. You need to get latest
		812	pod2info from CPAN, or, alternately,
		813	prebuilt info pages.
		814
		815
		816	for Acrobat are available on CPAN
		817	(for slightly old version of perl).
		818
		819
		820	LaTeX __docs__
		821
		822
		823	can be constructed using pod2latex.
		824	!!BUILD
		825
		826
		827	Here we discuss how to build Perl under OS/2
		828	. There is an alternative (but maybe older) view on
		829	http://www.shadow.net/~troc/os2perl.html
		830
		831
		832	__The short story__
		833
		834
		835	Assume that you are a seasoned porter, so are sure that all
		836	the necessary tools are already present on your system, and
		837	you know how to get the Perl source distribution. Untar it,
		838	change to the extract directory, and
		839
		840
		841	gnupatch -p0
		842	This puts the executables in f:/perllib/bin. Manually move them to the PATH, manually move the built ''perl*.dll'' to LIBPATH (here ''*'' is a not-very-meaningful hex checksum), and run
		843
		844
		845	make installcmd INSTALLCMDDIR=d:/ir/on/path
		846	What follows is a detailed guide through these steps.
		847
		848
		849	__Prerequisites__
		850
		851
		852	You need to have the latest EMX development
		853	environment, the full GNU tool suite (gawk
		854	renamed to awk, and GNU ''find.exe''
		855	earlier on path than the OS/2
		856	''find.exe'', same with ''sort.exe'', to check
		857	use
		858
		859
		860	find --version
		861	sort --version
		862	). You need the latest version of ''pdksh'' installed as ''sh.exe''.
		863
		864
		865	Check that you have __BSD__ libraries and
		866	headers installed, and - optionally - Berkeley
		867	DB headers and libraries, and
		868	crypt.
		869
		870
		871	Possible locations to get this from are
		872
		873
		874	ftp://hobbes.nmsu.edu/os2/unix/
		875	ftp://ftp.cdrom.com/pub/os2/unix/
		876	ftp://ftp.cdrom.com/pub/os2/dev32/
		877	ftp://ftp.cdrom.com/pub/os2/emx09c/
		878	It is reported that the following archives contain enough utils to build perl: ''gnufutil.zip'', ''gnusutil.zip'', ''gnututil.zip'', ''gnused.zip'', ''gnupatch.zip'', ''gnuawk.zip'', ''gnumake.zip'', ''bsddev.zip'' and ''ksh527rt.zip'' (or a later version). Note that all these utilities are known to be available from LEO:
		879
		880
		881	ftp://ftp.leo.org/pub/comp/os/os2/leo/gnu
		882	If you have ''exactly the same version of Perl'' installed already, make sure that no copies or perl are currently running. Later steps of the build may fail since an older version of ''perl.dll'' loaded into memory may be found.
		883
		884
		885	Also make sure that you have ''/tmp'' directory on the
		886	current drive, and ''.'' directory in your
		887	LIBPATH. One may try to correct the latter
		888	condition by
		889
		890
		891	set BEGINLIBPATH .
		892	if you use something like ''CMD .EXE'' or latest versions of ''4os2.exe''.
		893
		894
		895	Make sure your gcc is good for -Zomf linking: run
		896	omflibs script in ''/emx/lib''
		897	directory.
		898
		899
		900	Check that you have link386 installed. It comes standard
		901	with OS/2 , but may be not installed due to
		902	customization. If typing
		903
		904
		905	link386
		906	shows you do not have it, do ''Selective install'', and choose Link object modules in ''Optional system utilities/More''. If you get into link386 prompts, press Ctrl-C to exit.
		907
		908
		909	__Getting perl source__
		910
		911
		912	You need to fetch the latest perl source (including
		913	developers releases). With some probability it is located
		914	in
		915
		916
		917	http://www.perl.com/CPAN/src/5.0
		918	http://www.perl.com/CPAN/src/5.0/unsupported
		919	If not, you may need to dig in the indices to find it in the directory of the current maintainer.
		920
		921
		922	Quick cycle of developers release may break the
		923	OS/2 build time to time, looking
		924	into
		925
		926
		927	http://www.perl.com/CPAN/ports/os2/ilyaz/
		928	may indicate the latest release which was publicly released by the maintainer. Note that the release may include some additional patches to apply to the current source of perl.
		929
		930
		931	Extract it like this
		932
		933
		934	tar vzxf perl5.00409.tar.gz
		935	You may see a message about errors while extracting ''Configure''. This is because there is a conflict with a similarly-named file ''configure''.
		936
		937
		938	Change to the directory of extraction.
		939
		940
		941	__Application of the patches__
		942
		943
		944	You need to apply the patches in ''./os2/diff.*'' like
		945	this:
		946
		947
		948	gnupatch -p0
		949	You may also need to apply the patches supplied with the binary distribution of perl.
		950
		951
		952	Note also that the ''db.lib'' and ''db.a'' from the
		953	EMX distribution are not suitable for
		954	multi-threaded compile (even single-threaded flavor of Perl
		955	uses multi-threaded C RTL , for compatibility
		956	with XFree86-OS/2). Get a corrected one from
		957
		958
		959	ftp://ftp.math.ohio-state.edu/pub/users/ilya/os2/db_mt.zip
		960
		961
		962	__Hand-editing__
		963
		964
		965	You may look into the file ''./hints/os2.sh'' and correct
		966	anything wrong you find there. I do not expect it is needed
		967	anywhere.
		968
		969
		970	__Making__
		971
		972
		973	sh Configure -des -D prefix=f:/perllib
		974	prefix means: where to install the resulting perl library. Giving correct prefix you may avoid the need to specify PERLLIB_PREFIX, see `` PERLLIB_PREFIX ''.
		975
		976
		977	''Ignore the message about missing ln, and about -c option
		978	to tr''. The latter is most probably already fixed, if you
		979	see it and can trace where the latter spurious warning comes
		980	from, please inform me.
		981
		982
		983	Now
		984
		985
		986	make
		987	At some moment the built may die, reporting a ''version mismatch'' or ''unable to run perl''. This means that you do not have ''.'' in your LIBPATH , so ''perl.exe'' cannot find the needed ''perl67B2.dll'' (treat these hex digits as line noise). After this is fixed the build should finish without a lot of fuss.
		988
		989
		990	__Testing__
		991
		992
		993	Now run
		994
		995
		996	make test
		997	All tests should succeed (with some of them skipped).
		998
		999
		1000	Some tests may generate extra messages similar
		1001	to
		1002
		1003
		1004	A lot of bad free
		1005
		1006
		1007	in database tests related to Berkeley DB .
		1008	''This should be fixed already.'' If it persists, you may
		1009	disable this warnings, see `` PERL_BADFREE
		1010	''.
		1011
		1012
		1013	Process terminated by
		1014	SIGTERM/SIGINT
		1015
		1016
		1017	This is a standard message issued by OS/2
		1018	applications. *nix applications die in silence. It is
		1019	considered to be a feature. One can easily disable this by
		1020	appropriate sighandlers.
		1021
		1022
		1023	However the test engine bleeds these message to screen in
		1024	unexpected moments. Two messages of this kind ''should''
		1025	be present during testing.
		1026
		1027
		1028	To get finer test reports, call
		1029
		1030
		1031	perl t/harness
		1032	The report with ''io/pipe.t'' failing may look like this:
		1033
		1034
		1035	Failed Test Status Wstat Total Fail Failed List of failed
		1036	------------------------------------------------------------
		1037	io/pipe.t 12 1 8.33% 9
		1038	7 tests skipped, plus 56 subtests skipped.
		1039	Failed 1/195 test scripts, 99.49% okay. 1/6542 subtests failed, 99.98% okay.
		1040	The reasons for most important skipped tests are:
		1041
		1042
		1043	''op/fs.t''
		1044
		1045
		1046	18
		1047
		1048
		1049	Checks atime and mtime of stat()
		1050	- unfortunately, HPFS provides only 2sec time
		1051	granularity (for compatibility with FAT
		1052	?).
		1053
		1054
		1055	25
		1056
		1057
		1058	Checks truncate() on a filehandle just opened for
		1059	write - I do not know why this should or should not
		1060	work.
		1061
		1062
		1063	''op/stat.t''
		1064
		1065
		1066	Checks stat(). Tests:
		1067
		1068
		1069	4
		1070
		1071
		1072	Checks atime and mtime of stat()
		1073	- unfortunately, HPFS provides only 2sec time
		1074	granularity (for compatibility with FAT
		1075	?).
		1076
		1077
		1078	__Installing the built perl__
		1079
		1080
		1081	If you haven't yet moved perl.dll onto
		1082	LIBPATH , do it now.
		1083
		1084
		1085	Run
		1086
		1087
		1088	make install
		1089	It would put the generated files into needed locations. Manually put ''perl.exe'', ''perl__.exe'' and ''perl___.exe'' to a location on your PATH , ''perl.dll'' to a location on your LIBPATH .
		1090
		1091
		1092	Run
		1093
		1094
		1095	make installcmd INSTALLCMDDIR=d:/ir/on/path
		1096	to convert perl utilities to ''.cmd'' files and put them on PATH . You need to put ''.EXE''-utilities on path manually. They are installed in $prefix/bin, here $prefix is what you gave to ''Configure'', see Making.
		1097
		1098
		1099	a.out__-style build__
		1100
		1101
		1102	Proceed as above, but make ''perl_.exe'' (see
		1103	``perl_.exe'') by
		1104
		1105
		1106	make perl_
		1107	test and install by
		1108
		1109
		1110	make aout_test
		1111	make aout_install
		1112	Manually put ''perl_.exe'' to a location on your PATH .
		1113
		1114
		1115	__Note.__ The build process for perl_ ''does
		1116	not know'' about all the dependencies, so you should make
		1117	sure that anything is up-to-date, say, by doing
		1118
		1119
		1120	make perl_dll
		1121	first.
		1122	!!Build FAQ
		1123
		1124
		1125	__Some__ / __became__ \ __in
		1126	pdksh.__
		1127
		1128
		1129	You have a very old pdksh. See Prerequisites.
		1130
		1131
		1132	You do not have MT-safe ''db.lib''. See
		1133	Prerequisites.
		1134
		1135
		1136	__Problems with tr or sed__
		1137
		1138
		1139	reported with very old version of tr and sed.
		1140
		1141
		1142	__Some problem (forget which ;-)__
		1143
		1144
		1145	You have an older version of ''perl.dll'' on your
		1146	LIBPATH , which broke the build of
		1147	extensions.
		1148
		1149
		1150	__Library ... not found__
		1151
		1152
		1153	You did not run omflibs. See
		1154	Prerequisites.
		1155
		1156
		1157	__Segfault in make__
		1158
		1159
		1160	You use an old version of GNU make. See
		1161	Prerequisites.
		1162
		1163
		1164	__op/sprintf test failure__
		1165
		1166
		1167	This can result from a bug in emx sprintf which was fixed in
		1168	0.9d fix 03.
		1169	!!Specific (mis)features of OS/2 port
		1170
		1171
		1172	setpriority__,__
		1173	getpriority
		1174
		1175
		1176	Note that these functions are compatible with *nix, not with
		1177	the older ports of '94 - 95. The priorities are absolute, go
		1178	from 32 to -95, lower is quicker. 0 is the default
		1179	priority.
		1180
		1181
		1182	__WARNING__ . Calling getpriority
		1183	on a non-existing process can lock the system before Warp3
		1184	fixpak22.
		1185
		1186
		1187	system()
		1188
		1189
		1190	Multi-argument form of system() allows an
		1191	additional numeric argument. The meaning of this argument is
		1192	described in OS2::Process.
		1193
		1194
		1195	When finding a program to run, Perl first asks the
		1196	OS to look for executables on PATH.
		1197	If not found, it looks for a script with possible extensions
		1198	added in this order: no extension, ''.cmd'', ''.btm'',
		1199	''.bat'', ''.pl''. If found, Perl checks the start of
		1200	the file for magic strings and
		1201	. If found, Perl uses the rest
		1202	of the first line as the beginning of the command line to
		1203	run this script. The only mangling done to the first line is
		1204	extraction of arguments (currently up to 3), and ignoring of
		1205	the path-part of the ``interpreter'' name if it can't be
		1206	found using the full path.
		1207
		1208
		1209	E.g., system 'foo', 'bar', 'baz' may lead Perl to
		1210	finding ''C:/emx/bin/foo.cmd'' with the first line
		1211	being
		1212
		1213
		1214	extproc /bin/bash -x -c
		1215	If ''/bin/bash'' is not found, and appending of executable extensions to ''/bin/bash'' does not help either, then Perl looks for an executable ''bash'' on PATH. If found in ''C:/emx.add/bin/bash.exe'', then the above ''system()'' is translated to
		1216
		1217
		1218	system qw(C:/emx.add/bin/bash.exe -x -c C:/emx/bin/foo.cmd bar baz)
		1219	One additional translation is performed: instead of ''/bin/sh'' Perl uses the hardwired-or-customized shell (see `` PERL_SH_DIR '').
		1220
		1221
		1222	The above search for ``interpreter'' is recursive: if
		1223	''bash'' executable is not found, but ''bash.btm'' is
		1224	found, Perl will investigate its first line etc. The only
		1225	hardwired limit on the recursion depth is implicit: there is
		1226	a limit 4 on the number of additional arguments inserted
		1227	before the actual arguments given to ''system()''. In
		1228	particular, if no additional arguments are specified on the
		1229	``magic'' first lines, then the limit on the depth is
		1230	4.
		1231
		1232
		1233	If Perl finds that the found executable is of different type
		1234	than the current session, it will start the new process in a
		1235	separate session of necessary type. Call via
		1236	OS2::Process to disable this magic.
		1237
		1238
		1239	extproc __on the first line__
		1240
		1241
		1242	If the first chars of a Perl script are
		1243	, this line is treated as #!-line, thus
		1244	all the switches on this line are processed (twice if script
		1245	was started via cmd.exe). See `` DESCRIPTION
		1246	'' in perlrun.
		1247
		1248
		1249	__Additional modules:__
		1250
		1251
		1252	OS2::Process, OS2::DLL ,
2	perry	1253	OS2::REXX , OS2::PrfDB, OS2::!ExtAttr. These
1	perry	1254	modules provide access to additional numeric argument for
		1255	system and to the information about the running
		1256	process, to DLLs having functions with REXX
		1257	signature and to the REXX runtime, to
		1258	OS/2 databases in the ''.INI'' format, and
		1259	to Extended Attributes.
		1260
		1261
		1262	Two additional extensions by Andreas Kaiser,
		1263	OS2::UPM, and OS2::FTP, are included into
		1264	ILYAZ directory, mirrored on CPAN
		1265	.
		1266
		1267
		1268	__Prebuilt methods:__
		1269
		1270
		1271	File::Copy::syscopy
		1272
		1273
		1274	used by File::Copy::copy, see
		1275	File::Copy.
		1276
		1277
2	perry	1278	!DynaLoader::mod2fname
1	perry	1279
		1280
2	perry	1281	used by !DynaLoader for DLL name
1	perry	1282	mangling.
		1283
		1284
		1285	Cwd::current_drive()
		1286
		1287
		1288	Self explanatory.
		1289
		1290
		1291	Cwd::sys_chdir(name)
		1292
		1293
		1294	leaves drive as it is.
		1295
		1296
		1297	Cwd::change_drive(name)
		1298
		1299
		1300	chanes the ``current'' drive.
		1301
		1302
		1303	Cwd::sys_is_absolute(name)
		1304
		1305
		1306	means has drive letter and is_rooted.
		1307
		1308
		1309	Cwd::sys_is_rooted(name)
		1310
		1311
		1312	means has leading [[/\] (maybe after a
		1313	drive-letter:).
		1314
		1315
		1316	Cwd::sys_is_relative(name)
		1317
		1318
		1319	means changes with current dir.
		1320
		1321
		1322	Cwd::sys_cwd(name)
		1323
		1324
		1325	Interface to cwd from EMX . Used by
		1326	Cwd::cwd.
		1327
		1328
		1329	Cwd::sys_abspath(name, dir)
		1330
		1331
		1332	Really really odious function to implement. Returns absolute
		1333	name of file which would have name if
		1334	CWD were dir. Dir defaults
		1335	to the current dir.
		1336
		1337
		1338	Cwd::extLibpath([[type])
		1339
		1340
		1341	Get current value of extended library search path. If
		1342	type is present and ''true'', works with
		1343	END_LIBPATH , otherwise with
		1344	BEGIN_LIBPATH.
		1345
		1346
		1347	Cwd::extLibpath_set( path [[, type ] )
		1348
		1349
		1350	Set current value of extended library search path. If
		1351	type is present and ''true'', works with
		1352	END_LIBPATH , otherwise with
		1353	BEGIN_LIBPATH.
		1354
		1355
		1356	OS2::Error(do_harderror,do_exception)
		1357
		1358
		1359	Returns undef if it was not called yet, otherwise
		1360	bit 1 is set if on the previous call do_harderror was
		1361	enabled, bit 2 is set if if on previous call do_exception
		1362	was enabled.
		1363
		1364
		1365	This function enables/disables error popups associated with
		1366	hardware errors (Disk not ready etc.) and software
		1367	exceptions.
		1368
		1369
		1370	I know of no way to find out the state of popups
		1371	''before'' the first call to this function.
		1372
		1373
		1374	OS2::Errors2Drive(drive)
		1375
		1376
		1377	Returns undef if it was not called yet, otherwise
		1378	return false if errors were not requested to be written to a
		1379	hard drive, or the drive letter if this was
		1380	requested.
		1381
		1382
		1383	This function may redirect error popups associated with
		1384	hardware errors (Disk not ready etc.) and software
		1385	exceptions to the file POPUPLOG .OS2 at the
		1386	root directory of the specified drive. Overrides
		1387	''OS2::Error()'' specified by individual programs. Given
		1388	argument undef will disable redirection.
		1389
		1390
		1391	Has global effect, persists after the application
		1392	exits.
		1393
		1394
		1395	I know of no way to find out the state of redirection of
		1396	popups to the disk ''before'' the first call to this
		1397	function.
		1398
		1399
2	perry	1400	''OS2::!SysInfo()''
1	perry	1401
		1402
		1403	Returns a hash with system information. The keys of the hash
		1404	are
		1405
		1406
		1407	MAX_PATH_LENGTH, MAX_TEXT_SESSIONS, MAX_PM_SESSIONS,
		1408	MAX_VDM_SESSIONS, BOOT_DRIVE, DYN_PRI_VARIATION,
		1409	MAX_WAIT, MIN_SLICE, MAX_SLICE, PAGE_SIZE,
		1410	VERSION_MAJOR, VERSION_MINOR, VERSION_REVISION,
		1411	MS_COUNT, TIME_LOW, TIME_HIGH, TOTPHYSMEM, TOTRESMEM,
		1412	TOTAVAILMEM, MAXPRMEM, MAXSHMEM, TIMER_INTERVAL,
		1413	MAX_COMP_LENGTH, FOREGROUND_FS_SESSION,
		1414	FOREGROUND_PROCESS
		1415
		1416
2	perry	1417	''OS2::!BootDrive()''
1	perry	1418
		1419
		1420	Returns a letter without colon.
		1421
		1422
		1423	OS2::MorphPM(serve),
		1424	OS2::UnMorphPM(serve)
		1425
		1426
		1427	Transforms the current application into a PM
		1428	application and back. The argument true means that a real
		1429	message loop is going to be served. ''OS2::MorphPM()''
		1430	returns the PM message queue handle as an
		1431	integer.
		1432
		1433
		1434	See ``Centralized management of resources'' for additional
		1435	details.
		1436
		1437
		1438	OS2::Serve_Messages(force)
		1439
		1440
		1441	Fake on-demand retrieval of outstanding PM
		1442	messages. If force is false, will not dispatch
		1443	messages if a real message loop is known to be present.
		1444	Returns number of messages retrieved.
		1445
		1446
		1447	Dies with ``QUITing...'' if WM_QUIT message
		1448	is obtained.
		1449
		1450
		1451	OS2::Process_Messages(force [[, cnt])
		1452
		1453
		1454	Retrieval of PM messages until window
		1455	creation/destruction. If force is false, will not
		1456	dispatch messages if a real message loop is known to be
		1457	present.
		1458
		1459
		1460	Returns change in number of windows. If cnt is
		1461	given, it is incremented by the number of messages
		1462	retrieved.
		1463
		1464
		1465	Dies with ``QUITing...'' if WM_QUIT message
		1466	is obtained.
		1467
		1468
		1469	OS2::_control87(new,mask)
		1470
		1471
		1472	the same as ''_control87''(3) of EMX .
		1473	Takes integers as arguments, returns the previous
		1474	coprocessor control word as an integer. Only bits in
		1475	new which are present in mask are changed
		1476	in the control word.
		1477
		1478
		1479	''OS2::get_control87()''
		1480
		1481
		1482	gets the coprocessor control word as an
		1483	integer.
		1484
		1485
		1486	OS2::set_control87_em(new=MCW_EM,mask=MCW_EM)
		1487
		1488
		1489	The variant of ''OS2::_control87()'' with default values
		1490	good for handling exception mask: if no mask, uses
		1491	exception mask part of new only. If no
		1492	new, disables all the floating point
		1493	exceptions.
		1494
		1495
		1496	See ``Misfeatures'' for details.
		1497
		1498
		1499	(Note that some of these may be moved to different libraries
		1500	- eventually).
		1501
		1502
		1503	__Prebuilt variables:__
		1504
		1505
		1506	$OS2::emx_rev
		1507
		1508
		1509	same as _emx_rev of EMX , a string similar to
		1510	0.9c.
		1511
		1512
		1513	$OS2::emx_env
		1514
		1515
		1516	same as _emx_env of EMX , a number similar to
		1517	0x8001.
		1518
		1519
		1520	$OS2::os_ver
		1521
		1522
		1523	a number OS_MAJOR + 0.001 * OS_MINOR.
		1524
		1525
		1526	__Misfeatures__
		1527
		1528
		1529	Since flock(3) is present in EMX , but
		1530	is not functional, it is emulated by perl. To disable the
		1531	emulations, set environment variable
		1532	USE_PERL_FLOCK=0.
		1533
		1534
		1535	Here is the list of things which may be ``broken'' on
		1536	EMX (from EMX
		1537	docs):
		1538
		1539
		1540	The functions recvmsg(3), sendmsg(3), and
		1541	socketpair(3) are not implemented.
		1542
		1543
		1544	''sock_init''(3) is not required and not
		1545	implemented.
		1546
		1547
		1548	flock(3) is not yet implemented (dummy function).
		1549	(Perl has a workaround.)
		1550
		1551
		1552	kill(3): Special treatment of PID=0, PID=1 and PID=-1
		1553	is not implemented.
		1554
		1555
		1556	waitpid(3):
		1557
		1558
		1559	WUNTRACED
		1560	Not implemented.
		1561	waitpid() is not implemented for negative values of PID.
		1562
		1563
		1564	Note that kill -9 does not work with the current
		1565	version of EMX .
		1566
		1567
		1568	Since ''sh.exe'' is used for globing (see ``glob'' in
		1569	perlfunc), the bugs of ''sh.exe'' plague perl as
		1570	well.
		1571
		1572
		1573	In particular, uppercase letters do not work in
		1574	[[...]-patterns with the current pdksh.
		1575
		1576
		1577	Unix-domain sockets on OS/2 live in a
		1578	pseudo-file-system /sockets/.... To avoid a failure
		1579	to create a socket with a name of a different form,
		1580	is prepended to the socket
		1581	name (unless it starts with this already).
		1582
		1583
		1584	This may lead to problems later in case the socket is
		1585	accessed via the ``usual'' file-system calls using the
		1586	``initial'' name.
		1587
		1588
		1589	Apparently, IBM used a compiler (for some
		1590	period of time around '95?) which changes FP
		1591	mask right and left. This is not ''that'' bad for
		1592	IBM 's programs, but the same compiler was
		1593	used for DLLs which are used with general-purpose
		1594	applications. When these DLLs are used, the state of
		1595	floating-point flags in the application is not
		1596	predictable.
		1597
		1598
		1599	What is much worse, some DLLs change the floating point
		1600	flags when in ''_DLLInitTerm()'' (e.g.,
		1601	''TCP32IP'' ). This means that even if you
		1602	do not ''call'' any function in the DLL ,
		1603	just the act of loading this DLL will reset
		1604	your flags. What is worse, the same compiler was used to
		1605	compile some HOOK DLLs. Given that
		1606	HOOK dlls are executed in the context of
		1607	''all'' the applications in the system, this means a
		1608	complete unpredictablity of floating point flags on systems
		1609	using such HOOK DLLs. E.g.,
		1610	''GAMESRVR .DLL'' of
		1611	__DIVE__ origin changes the floating point
		1612	flags on each write to the TTY of a
		1613	VIO (windowed text-mode)
		1614	applications.
		1615
		1616
		1617	Some other (not completely debugged) situations when
		1618	FP flags change include some video drivers
		1619	(?), and some operations related to creation of the windows.
		1620	People who code __OpenGL__ may have more experience on
		1621	this.
		1622
		1623
		1624	Perl is generally used in the situation when all the
		1625	floating-point exceptions are ignored, as is the default
		1626	under EMX . If they are not ignored, some
		1627	benign Perl programs would get a SIGFPE and would
		1628	die a horrible death.
		1629
		1630
		1631	To circumvent this, Perl uses two hacks. They help against
		1632	''one'' type of damage only: FP flags
		1633	changed when loading a DLL .
		1634
		1635
		1636	One of the hacks is to disable floating point exceptions on
		1637	startup (as is the default with EMX ). This
		1638	helps only with compile-time-linked DLLs changing the flags
		1639	before ''main()'' had a chance to be called.
		1640
		1641
		1642	The other hack is to restore FP flags after a
		1643	call to ''dlopen()''. This helps against similar damage
		1644	done by DLLs ''_DLLInitTerm()'' at runtime. Currently no
		1645	way to switch these hacks off is provided.
		1646
		1647
		1648	__Modifications__
		1649
		1650
		1651	Perl modifies some standard C library calls in the following
		1652	ways:
		1653
		1654
		1655	popen
		1656
		1657
		1658	my_popen uses ''sh.exe'' if shell is required,
		1659	cf. `` PERL_SH_DIR ''.
		1660
		1661
		1662	tmpnam
		1663
		1664
		1665	is created using TMP or TEMP environment
		1666	variable, via tempnam.
		1667
		1668
		1669	tmpfile
		1670
		1671
		1672	If the current directory is not writable, file is created
		1673	using modified tmpnam, so there may be a race
		1674	condition.
		1675
		1676
		1677	ctermid
		1678
		1679
		1680	a dummy implementation.
		1681
		1682
		1683	stat
		1684
		1685
		1686	os2_stat special-cases ''/dev/tty'' and
		1687	''/dev/con''.
		1688
		1689
		1690	mkdir, rmdir
		1691
		1692
		1693	these EMX functions do not work if the path
		1694	contains a trailing /. Perl contains a workaround
		1695	for this.
		1696
		1697
		1698	flock
		1699
		1700
		1701	Since flock(3) is present in EMX , but
		1702	is not functional, it is emulated by perl. To disable the
		1703	emulations, set environment variable
		1704	USE_PERL_FLOCK=0.
		1705
		1706
		1707	__Identifying DLLs__
		1708
		1709
		1710	All the DLLs built with the current versions of Perl have
		1711	ID strings identifying the name of the
		1712	extension, its version, and the version of Perl required for
		1713	this DLL . Run bldlevel DLL-name to
		1714	find this info.
		1715
		1716
		1717	__Centralized management of resources__
		1718
		1719
		1720	Since to call certain OS/2 API one needs to
		1721	have a correctly initialized Win subsystem,
		1722	OS/2-specific extensions may require getting HABs
		1723	and HMQs. If an extension would do it on its own,
		1724	another extension could fail to initialize.
		1725
		1726
		1727	Perl provides a centralized management of these
		1728	resources:
		1729
		1730
		1731	HAB
		1732
		1733
		1734	To get the HAB , the extension should call
		1735	hab = perl_hab_GET() in C. After this call is
		1736	performed, hab may be accessed as
		1737	Perl_hab. There is no need to release the
		1738	HAB after it is used.
		1739
		1740
		1741	If by some reasons ''perl.h'' cannot be included,
		1742	use
		1743
		1744
		1745	extern int Perl_hab_GET(void);
		1746	instead.
		1747
		1748
		1749	HMQ
		1750
		1751
		1752	There are two cases:
		1753
		1754
		1755	the extension needs an HMQ only because some
		1756	API will not work otherwise. Use serve =
		1757	0 below.
		1758
		1759
		1760	the extension needs an HMQ since it wants to engage
		1761	in a PM event loop. Use serve = 1
		1762	below.
		1763
		1764
		1765	To get an HMQ, the extension should call hmq =
		1766	perl_hmq_GET(serve) in C. After this call is performed,
		1767	hmq may be accessed as
		1768	Perl_hmq.
		1769
		1770
		1771	To signal to Perl that HMQ is not needed any
		1772	more, call perl_hmq_UNSET(serve). Perl process will
		1773	automatically morph/unmorph itself into/from a
		1774	PM process if HMQ is
		1775	needed/not-needed. Perl will automatically enable/disable
		1776	WM_QUIT message during shutdown if the message
		1777	queue is served/not-served.
		1778
		1779
		1780	__NOTE__ . If during a shutdown there is a
		1781	message queue which did not disable WM_QUIT ,
		1782	and which did not process the received
		1783	WM_QUIT message, the shutdown will be
		1784	automatically cancelled. Do not call
		1785	perl_hmq_GET(1) unless you are going to process
		1786	messages on an orderly basis.
		1787	!!Perl flavors
		1788
		1789
		1790	Because of idiosyncrasies of OS/2 one cannot
		1791	have all the eggs in the same basket (though
		1792	EMX environment tries hard to overcome this
		1793	limitations, so the situation may somehow improve). There
		1794	are 4 executables for Perl provided by the
		1795	distribution:
		1796
		1797
		1798	''perl.exe''
		1799
		1800
		1801	The main workhorse. This is a chimera executable: it is
		1802	compiled as an a.out-style executable, but is
		1803	linked with omf-style dynamic library
		1804	''perl.dll'', and with dynamic CRT DLL .
		1805	This executable is a VIO
		1806	application.
		1807
		1808
		1809	It can load perl dynamic extensions, and it can
		1810	''fork()''.
		1811
		1812
		1813	__Note.__ Keep in mind that ''fork()'' is needed to
		1814	open a pipe to yourself.
		1815
		1816
		1817	''perl_.exe''
		1818
		1819
		1820	This is a statically linked a.out-style executable.
		1821	It cannot load dynamic Perl extensions. The executable
		1822	supplied in binary distributions has a lot of extensions
		1823	prebuilt, thus the above restriction is important only if
		1824	you use custom-built extensions. This executable is a
		1825	VIO application.
		1826
		1827
		1828	''This is the only executable with does not require
		1829	OS/2 .'' The friends locked into
		1830	M$ world would appreciate the fact that this
		1831	executable runs under DOS , Win0.3*, Win0.95
		1832	and WinNT with an appropriate extender. See ``Other
		1833	OSes''.
		1834
		1835
		1836	''perl__.exe''
		1837
		1838
		1839	This is the same executable as ''perl___.exe'', but it is
		1840	a PM application.
		1841
		1842
		1843	__Note.__ Usually (unless explicitly redirected during
		1844	the startup) STDIN , STDERR ,
		1845	and STDOUT of a PM application
		1846	are redirected to ''nul''. However, it is possible to
		1847	''see'' them if you start perl__.exe from a
		1848	PM program which emulates a console window,
		1849	like ''Shell mode'' of Emacs or EPM . Thus
		1850	it ''is possible'' to use Perl debugger (see perldebug)
		1851	to debug your PM application (but beware of
		1852	the message loop lockups - this will not work if you have a
		1853	message queue to serve, unless you hook the serving into the
		1854	''getc()'' function of the debugger).
		1855
		1856
		1857	Another way to see the output of a PM program
		1858	is to run it as
		1859
		1860
		1861	pm_prog args 2
		1862	with a shell ''different'' from ''cmd.exe'', so that it does not create a link between a VIO session and the session of pm_porg. (Such a link closes the VIO window.) E.g., this works with ''sh.exe'' - or with Perl!
		1863
		1864
		1865	open P, 'pm_prog args 2
		1866	The flavor ''perl__.exe'' is required if you want to start your program without a VIO window present, but not detached (run help detach for more info). Very useful for extensions which use PM , like Perl/Tk or OpenGL.
		1867
		1868
		1869	''perl___.exe''
		1870
		1871
		1872	This is an omf-style executable which is
		1873	dynamically linked to ''perl.dll'' and CRT
		1874	DLL . I know no advantages of this executable over
		1875	perl.exe, but it cannot ''fork()'' at all. Well,
		1876	one advantage is that the build process is not so convoluted
		1877	as with perl.exe.
		1878
		1879
		1880	It is a VIO application.
		1881
		1882
		1883	__Why strange names?__
		1884
		1885
		1886	Since Perl processes the #!-line (cf. ``
		1887	DESCRIPTION '' in perlrun, ``Switches'' in
		1888	perlrun, ``Not a perl script'' in perldiag, ``No Perl script
		1889	found in input'' in perldiag), it should know when a program
		1890	''is a Perl''. There is some naming convention which
		1891	allows Perl to distinguish correct lines from wrong ones.
		1892	The above names are almost the only names allowed by this
		1893	convention which do not contain digits (which have
		1894	absolutely different semantics).
		1895
		1896
		1897	__Why dynamic linking?__
		1898
		1899
		1900	Well, having several executables dynamically linked to the
		1901	same huge library has its advantages, but this would not
		1902	substantiate the additional work to make it compile. The
		1903	reason is the complicated-to-developers but very quick and
		1904	convenient-to-users ``hard'' dynamic linking used by
		1905	OS/2 .
		1906
		1907
		1908	There are two distinctive features of the dyna-linking model
		1909	of OS/2: all the references to external
		1910	functions are resolved at the compile time; there is no
		1911	runtime fixup of the DLLs after they are loaded into memory.
		1912	The first feature is an enormous advantage over other
		1913	models: it avoids conflicts when several DLLs used by an
		1914	application export entries with the same name. In such cases
		1915	``other'' models of dyna-linking just choose between these
		1916	two entry points using some random criterion - with
		1917	predictable disasters as results. But it is the second
		1918	feature which requires the build of
		1919	''perl.dll''.
		1920
		1921
		1922	The address tables of DLLs are patched only once, when they
		1923	are loaded. The addresses of the entry points into DLLs are
		1924	guaranteed to be the same for all the programs which use the
		1925	same DLL . This removes the runtime fixup -
		1926	once DLL is loaded, its code is
		1927	read-only.
		1928
		1929
		1930	While this allows some (significant?) performance
		1931	advantages, this makes life much harder for developers,
		1932	since the above scheme makes it impossible for a
		1933	DLL to be ``linked'' to a symbol in the
		1934	''.EXE'' file. Indeed, this would need a
		1935	DLL to have different relocations tables for
		1936	the (different) executables which use this
		1937	DLL .
		1938
		1939
		1940	However, a dynamically loaded Perl extension is forced to
		1941	use some symbols from the perl executable, e.g., to know how
		1942	to find the arguments to the functions: the arguments live
		1943	on the perl internal evaluation stack. The solution is to
		1944	put the main code of the interpreter into a
		1945	DLL , and make the ''.EXE'' file which
		1946	just loads this DLL into memory and supplies
		1947	command-arguments. The extension DLL cannot
		1948	link to symbols in ''.EXE'', but it has no problem
		1949	linking to symbols in the ''.DLL''.
		1950
		1951
		1952	This ''greatly'' increases the load time for the
		1953	application (as well as complexity of the compilation).
		1954	Since interpreter is in a DLL , the C
		1955	RTL is basically forced to reside in a
		1956	DLL as well (otherwise extensions would not
		1957	be able to use CRT ). There are some
		1958	advantages if you use different flavors of perl, such as
		1959	running ''perl.exe'' and ''perl__.exe''
		1960	simultaneously: they share the memory of
		1961	''perl.dll''.
		1962
		1963
		1964	__NOTE__ . There is one additional effect
		1965	which makes DLLs more wasteful: DLLs are loaded in the
		1966	shared memory region, which is a scarse resource given the
		1967	512M barrier of the ``standard'' OS/2 virtual
		1968	memory. The code of ''.EXE'' files is also shared by all
		1969	the processes which use the particular ''.EXE'', but they
		1970	are ``shared in the private address space of the process'';
		1971	this is possible because the address at which different
		1972	sections of the ''.EXE'' file are loaded is decided at
		1973	compile-time, thus all the processes have these sections
		1974	loaded at same addresses, and no fixup of internal links
		1975	inside the ''.EXE'' is needed.
		1976
		1977
		1978	Since DLLs may be loaded at run time, to have the same
		1979	mechanism for for DLLs one needs to have the address range
		1980	of ''any of the loaded'' DLLs in the system to be
		1981	available ''in all the processes'' which did not load a
		1982	particular DLL yet. This is why the DLLs are
		1983	mapped to the shared memory region.
		1984
		1985
		1986	__Why chimera build?__
		1987
		1988
		1989	Current EMX environment does not allow DLLs
		1990	compiled using Unixish a.out format to export
		1991	symbols for data (or at least some types of data). This
		1992	forces omf-style compile of
		1993	''perl.dll''.
		1994
		1995
		1996	Current EMX environment does not allow
		1997	''.EXE'' files compiled in omf format to
		1998	''fork()''. ''fork()'' is needed for exactly three
		1999	Perl operations:
		2000
		2001
		2002	explicit ''fork()'' in the script,
		2003
		2004
		2005	open FH,
		2006
		2007
		2008	open FH, , in other words, opening
		2009	pipes to itself.
		2010
		2011
		2012	While these operations are not questions of life and death,
		2013	they are needed for a lot of useful scripts. This forces
		2014	a.out-style compile of
		2015	''perl.exe''.
		2016	!!ENVIRONMENT
		2017
		2018
		2019	Here we list environment variables with are either
		2020	OS/2- and DOS- and
		2021	Win*-specific, or are more important under
		2022	OS/2 than under other OSes.
		2023
		2024
		2025	PERLLIB_PREFIX
		2026
		2027
		2028	Specific for EMX port. Should have the
		2029	form
		2030
		2031
		2032	path1;path2
		2033	or
		2034
		2035
		2036	path1 path2
		2037	If the beginning of some prebuilt path matches ''path1'', it is substituted with ''path2''.
		2038
		2039
		2040	Should be used if the perl library is moved from the default
		2041	location in preference to PERL(5)LIB, since this
		2042	would not leave wrong entries in @INC. For example,
		2043	if the compiled version of perl looks for @INC in
		2044	''f:/perllib/lib'', and you want to install the library
		2045	in ''h:/opt/gnu'', do
		2046
		2047
		2048	set PERLLIB_PREFIX=f:/perllib/lib;h:/opt/gnu
		2049	This will cause Perl with the prebuilt @INC of
		2050
		2051
		2052	f:/perllib/lib/5.00553/os2
		2053	f:/perllib/lib/5.00553
		2054	f:/perllib/lib/site_perl/5.00553/os2
		2055	f:/perllib/lib/site_perl/5.00553
		2056	.
		2057	to use the following @INC:
		2058
		2059
		2060	h:/opt/gnu/5.00553/os2
		2061	h:/opt/gnu/5.00553
		2062	h:/opt/gnu/site_perl/5.00553/os2
		2063	h:/opt/gnu/site_perl/5.00553
		2064	.
		2065
		2066
		2067	PERL_BADLANG
		2068
		2069
		2070	If 0, perl ignores ''setlocale()'' failing. May be useful
		2071	with some strange ''locale''s.
		2072
		2073
		2074	PERL_BADFREE
		2075
		2076
		2077	If 0, perl would not warn of in case of unwarranted
		2078	''free()''. With older perls this might be useful in
		2079	conjunction with the module DB_File, which was buggy when
		2080	dynamically linked and OMF-built.
		2081
		2082
		2083	Should not be set with newer Perls, since this may hide some
		2084	''real'' problems.
		2085
		2086
		2087	PERL_SH_DIR
		2088
		2089
		2090	Specific for EMX port. Gives the directory
		2091	part of the location for ''sh.exe''.
		2092
		2093
		2094	USE_PERL_FLOCK
		2095
		2096
		2097	Specific for EMX port. Since flock(3)
		2098	is present in EMX , but is not functional, it
		2099	is emulated by perl. To disable the emulations, set
		2100	environment variable USE_PERL_FLOCK=0.
		2101
		2102
		2103	TMP __or__ TEMP
		2104
		2105
		2106	Specific for EMX port. Used as storage place
		2107	for temporary files.
		2108	!!Evolution
		2109
		2110
		2111	Here we list major changes which could make you by
		2112	surprise.
		2113
		2114
		2115	__Priorities__
		2116
		2117
		2118	setpriority and getpriority are not
		2119	compatible with earlier ports by Andreas Kaiser. See
		2120	.
		2121
		2122
		2123	__DLL name mangling__
		2124
		2125
		2126	With the release 5.003_01 the dynamically loadable libraries
		2127	should be rebuilt when a different version of Perl is
		2128	compiled. In particular, DLLs (including ''perl.dll'')
		2129	are now created with the names which contain a checksum,
		2130	thus allowing workaround for OS/2 scheme of
		2131	caching DLLs.
		2132
		2133
		2134	It may be possible to code a simple workaround which
		2135	would
		2136
		2137
		2138	find the old DLLs looking through the old
		2139	@INC;
		2140
		2141
		2142	mangle the names according to the scheme of new perl and
		2143	copy the DLLs to these names;
		2144
		2145
		2146	edit the internal LX tables of DLL
		2147	to reflect the change of the name (probably not needed for
		2148	Perl extension DLLs, since the internally coded names are
		2149	not used for ``specific'' DLLs, they used only for
		2150	``global'' DLLs).
		2151
		2152
		2153	edit the internal IMPORT tables and change the name
		2154	of the ``old'' ''perl????.dll'' to the ``new''
		2155	''perl????.dll''.
		2156
		2157
		2158	__Threading__
		2159
		2160
		2161	As of release 5.003_01 perl is linked to multithreaded C
		2162	RTL DLL . If perl itself is not compiled
		2163	multithread-enabled, so will not be perl's ''malloc()''.
		2164	However, extensions may use multiple thread on their own
		2165	risk.
		2166
		2167
		2168	This was needed to compile Perl/Tk for XFree86-OS/2
		2169	out-of-the-box, and link with DLLs for other useful
		2170	libraries, which typically are compiled with -Zmt
		2171	-Zcrtdll.
		2172
		2173
		2174	__Calls to external programs__
		2175
		2176
		2177	Due to a popular demand the perl external program calling
		2178	has been changed wrt Andreas Kaiser's port. ''If'' perl
		2179	needs to call an external program ''via shell'', the
		2180	''f:/bin/sh.exe'' will be called, or whatever is the
		2181	override, see `` PERL_SH_DIR ''.
		2182
		2183
		2184	Thus means that you need to get some copy of a ''sh.exe''
		2185	as well (I use one from pdksh). The path ''F:/bin'' above
		2186	is set up automatically during the build to a correct value
		2187	on the builder machine, but is overridable at
		2188	runtime,
		2189
		2190
		2191	__Reasons:__ a consensus on perl5-porters was
		2192	that perl should use one non-overridable shell per platform.
		2193	The obvious choices for OS/2 are
		2194	''cmd.exe'' and ''sh.exe''. Having perl build itself
		2195	would be impossible with ''cmd.exe'' as a shell, thus I
		2196	picked up sh.exe. This assures almost 100%
		2197	compatibility with the scripts coming from *nix. As an added
		2198	benefit this works as well under DOS if you
		2199	use DOS-enabled port of pdksh (see
		2200	``Prerequisites'').
		2201
		2202
		2203	__Disadvantages:__ currently ''sh.exe'' of pdksh calls
		2204	external programs via ''fork()''/''exec()'', and there
		2205	is ''no'' functioning ''exec()'' on
		2206	OS/2 . ''exec()'' is emulated by
		2207	EMX by an asynchronous call while the caller
		2208	waits for child completion (to pretend that the pid
		2209	did not change). This means that 1 ''extra'' copy of
		2210	''sh.exe'' is made active via
		2211	''fork()''/''exec()'', which may lead to some
		2212	resources taken from the system (even if we do not count
		2213	extra work needed for ''fork()''ing).
		2214
		2215
		2216	Note that this a lesser issue now when we do not spawn
		2217	''sh.exe'' unless needed (metachars found).
		2218
		2219
		2220	One can always start ''cmd.exe'' explicitly
		2221	via
		2222
		2223
		2224	system 'cmd', '/c', 'mycmd', 'arg1', 'arg2', ...
		2225	If you need to use ''cmd.exe'', and do not want to hand-edit thousands of your scripts, the long-term solution proposed on p5-p is to have a directive
		2226
		2227
		2228	use OS2::Cmd;
		2229	which will override ''system()'', ''exec()'', ``, and open(,'...'). With current perl you may override only ''system()'', ''readpipe()'' - the explicit version of ``, and maybe ''exec()''. The code will substitute the one-argument call to ''system()'' by CORE::system('cmd.exe', '/c', shift).
		2230
		2231
		2232	If you have some working code for OS2::Cmd, please
		2233	send it to me, I will include it into distribution. I have
		2234	no need for such a module, so cannot test it.
		2235
		2236
		2237	For the details of the current situation with calling
		2238	external programs, see ``2 (and DOS )
		2239	programs under Perl'' in Starting OS . Set us
		2240	mention a couple of features:
		2241
		2242
		2243	External scripts may be called by their basename. Perl will
		2244	try the same extensions as when processing __-S__
		2245	command-line switch.
		2246
		2247
		2248	External scripts starting with #! or
		2249	extproc will be executed directly, without calling
		2250	the shell, by calling the program specified on the rest of
		2251	the first line.
		2252
		2253
		2254	__Memory allocation__
		2255
		2256
		2257	Perl uses its own ''malloc()'' under OS/2
		2258	- interpreters are usually malloc-bound for speed, but perl
		2259	is not, since its malloc is lightning-fast.
		2260	Perl-memory-usage-tuned benchmarks show that Perl's malloc
		2261	is 5 times quicker than EMX one. I do not
		2262	have convincing data about memory footprint, but a (pretty
		2263	random) benchmark showed that Perl's one is 5%
		2264	better.
		2265
		2266
		2267	Combination of perl's ''malloc()'' and rigid
		2268	DLL name resolution creates a special problem
		2269	with library functions which expect their return value to be
		2270	''free()''d by system's ''free()''. To facilitate
		2271	extensions which need to call such functions, system
		2272	memory-allocation functions are still available with the
		2273	prefix emx_ added. (Currently only
		2274	DLL perl has this, it should propagate to
		2275	''perl_.exe'' shortly.)
		2276
		2277
		2278	__Threads__
		2279
		2280
		2281	One can build perl with thread support enabled by providing
		2282	-D usethreads option to ''Configure''. Currently
		2283	OS/2 support of threads is very
		2284	preliminary.
		2285
		2286
		2287	Most notable problems:
		2288
		2289
		2290	COND_WAIT
		2291
		2292
		2293	may have a race condition. Needs a reimplementation (in
		2294	terms of chaining waiting threads, with the linked list
		2295	stored in per-thread structure?).
		2296
		2297
		2298	''os2.c''
		2299
		2300
		2301	has a couple of static variables used in OS/2-specific
		2302	functions. (Need to be moved to per-thread structure, or
		2303	serialized?)
		2304
		2305
		2306	Note that these problems should not discourage
		2307	experimenting, since they have a low probability of
		2308	affecting small programs.
		2309	!!AUTHOR
		2310
		2311
		2312	Ilya Zakharevich, ilya@math.ohio-state.edu
		2313	!!SEE ALSO
		2314
		2315
		2316	perl(1).
		2317	----