Free Pascal Compiler Files

                            Free Pascal Compiler

                        Version 1.9.8 aka 2.0.0-Rc2

                  Readme for targets netware and netwlibc

*******************************************************************************

1. Install FreePascal 1.9.8
2. Install Units for Netware
3. Change your fpc.cfg
4. Install Binutils for netware
5. Compiling for Netware
6. Netware Targets
7. Netware specifics for FreePascal
8. Debugging
9. Running the compiler on the Server



-------------------------------------------------------------------------------
1. Install FreePascal 1.9.8
-------------------------------------------------------------------------------

Netware is designed to be a cross target. It is possible to run the compiler on
a netware server but this is not a recommended configuration.

Install FreePascal 1.9.6 for your platform. Netware cross compiling was tested
under i386-win32 and i386-linux. Other platforms supported by FreePascal should
also work as long as current binutils for target netware can be compiled on
that platform.

-------------------------------------------------------------------------------
2. Install Units for Netware
-------------------------------------------------------------------------------

Download fpc-1.9.8-i386-netware-units.zip (for clib target) and 
fpc-1.9.8-i386-netwlibc-units.zip (for libc target) and unpack the zips under
your FreePascal path (where the directory units exists).
A sample structure could look like:

/usr/lib/fpc/1.9.8/units/--:
                           :--i386-linux
			   :--i386-netware
			   :--i386-netwlibc

-------------------------------------------------------------------------------
3. Change your fpc.cfg
-------------------------------------------------------------------------------

Add lines for the netware units and imp-files to your fpc.cfg. This 
is needed for the target netware and netwlibc (replace (fpcdir) with 
the directory where FreePascal is installed):

#IFDEF Netwlibc
-Fu(fpcdir)/units/i386-netwlibc/rtl
-Fu(fpcdir)/units/i386-netwlibc/*
-XPi386-netware-
#ENDIF

#IFDEF Netware_clib
-Fu(fpcdir)/units/i386-netware/rtl
-Fu(fpcdir)/units/i386-netware/*
-XPi386-netware-
#ENDIF

-------------------------------------------------------------------------------
4. Install Binutils for netware
-------------------------------------------------------------------------------

Precompiled versions for i386-Linux and i386-win32 can be downloaded
from

win32:  ftp://ftp.freepascal.org/fpc/contrib/cross/mingw/binutils-2.15-win32-i386-netware.zip
linux:  ftp://ftp.freepascal.org/fpc/contrib/cross/linux/binutils-netware-fpc-2.15.90.0.3-2.i386.rpm

After installation, make sure that a path to the installed binutils is set, i.e.

>i386-netware-ld -V
GNU ld version 2.15.90.0.3 20040415
  Supported emulations:
     i386nw
>

You can also specify the path to the netware binutils in you fpc.cfg. (-FU)

If you want to compile binutils, i compiled it with the following options:

./configure --prefix=/usr --disable-shared --target=i386-netware

-------------------------------------------------------------------------------
5. Compiling for Netware
-------------------------------------------------------------------------------

Create a hello.pp like:

Program Hello;

{$Description Fpc-1.9.8-Test}
{$Version 1,0,0}
{$Copyright (c) 2005 me}
{$Screenname FPC-TEST1}

{$if defined(netware_libc)}
uses libc;
{$endif}

begin
  {$if defined(netware_libc)}
  setscreenmode(0);  // to avoid auto screen destruction
  {$endif}
  Writeln ('Hello Netware');
  Writeln (stderr,'Hello logger screen or console');
end.
 
and execute the compiler:
 fpc -Tnetware hello.pp
 
or for libc:
 
 fpc -Tnetwlibc hello.pp
 
This will (hopefully) create the file hello.nlm.

-------------------------------------------------------------------------------
6. Netware Targets
-------------------------------------------------------------------------------

The compiler supports two different targets for netware. Both targets are 
using the same compiler and binutils but different runtime libraries.

Netware
-------

This target is based on the classic netware c-library (clib.nlm). 
The nlm should work on netware versions from 4.00 on. I think it will 
not work on 3.x but this may be changed in the runtime library.
The resulting nlm is a uni-processor nlm (no xdc-data support).
There are some netware specific support modules included in the rtl:

aio     - Serial port support, aio.h in ndk
nwnit   - Definitions from the following ndk-files: nwaccntg.h, nwafp.h, 
          nwbindry.h, nwdatamg.h, nwdir.h, nwenvrn.h, nwenvrn1.h, 
          nwextatt.h, nwmsg.h, nwnit.h, nwqueue.h, nwserial.h, 
          nwservst.h, nwsync.h, nwtts.h
nwprot  - netware server protocol library (streams and tli)
nwserv  - Contains definitions from the follwing header files: string.h 
          dirent.h errno.h fcntl.h limits.h locale.h nwaudnlm.h nwbitops.h 
          nwcntask.h nwconio.h nwconn.h nwdebug.h nwdfs.h nwdos.h nwerrno.h 
          nwfattr.h nwfileio.h nwfileng.h nwfinfo.h nwfshook.h nwipx.h nwlib.h 
          nwlocale.h nwmalloc.h nwncpx.h nwnspace.h nwproc.h nwsemaph.h 
          nwserv.h nwsignal.h nwstring.h nwtoolib.h stdio.h stdlib.h unistd.h 
          time.h utime.h nwthread.h nwmediam.h ioctl.h sys/socket.h sys/time.h 
          sys/filio.h syys/ioctl.h sys/stat.h sys/time.h sys/timeval.h 
          sys/uio.h sys/utsname.h
nwsnut  - Netware utility text interface (same as in ndk)
winsock - Netware winsock2 interface
nwcalls - nwcalls library for netware (untested)

Netwlibc
--------

This target is based on the modern netware libc (libc.nlm). The nlm should work 
on netware versions from 5.10 on (current service packs and libc fixes may be 
required). Older versions of netware are not supported because no libc is 
available on these versions.
Threads within the generated nlm can run on any cpu by default (xdc-data 
is generated by the compiler).
There are some netware specific support modules included in the rtl:

libc    - Interface to netware libc
winsock - Netware winsock2 interface


-------------------------------------------------------------------------------
7. Netware specifics for FreePascal
-------------------------------------------------------------------------------

Compiler Switches
=================
The following additional compiler switches are supported for Netware:

{$Description TEXT}
Sets the NLM Description displayed while loading the NLM

{$Version x,y,z}
Sets the nlm version to x.y.z, x,y, and z has to be numeric, z=1 will
be interpreted as rev a, z=1 as rev b ...

{$Screenname}
Sets the clib screenname, the following special Screennames will be supported
by netware:
default      no own screen, stdout and errout are active (console for Nw < 6,
             Logger Screen on newer Versions)
none         No screen and no stdout/errout at all. You should not use this
             mode with FreePascal because in case a runtime error will be
             generated, FreePascal prints the error to stdout and that will
             fail and generate another runtime error (and so on ...)
             This will result in a nice abend (even when loaded protected)

{$Threadname}
Sets the thread name. Make sure the names are not to long for netware because
this will prevent your nlm from loading.

{$Memory Stacksize}
{$Memory Stacksize,Heapsize}
Specifies the stacksize, the heapsize will be ignored.

Exports
=======

Exports will be handled like in win32:

procedure bla; CDECL; EXPORT;
begin
end;

exports bla name 'bla';

Be aware that without Name 'bla' this will be exported in upper-case.

Imports and Netware .imp Files
==============================

The standard way for importing public symbols on netware is via a .imp
file. The file is a simple text file containing the symbol names. This
file will be processed by nlmconv (the final linker for netware, part
of binutils)
FreePascal installes the standard .imp files in the unit directory.
The imp files are searched via the specified library path. If you plan
to use own imp files, make shure that linefeeds are LF only and not
CR LF as on Dos and Windows.

The following declaration needs nlmlib.imp and sets nlmlib.nlm as autoload:

FUNCTION rmdir (path : PCHAR) : LONGINT; CDECL; EXTERNAL 'nlmlib' NAME 'rmdir';
	
while the following declaration only imports the symbol without autoloading:
	      
FUNCTION rmdir (path : PCHAR) : LONGINT; CDECL; EXTERNAL;

but this will result in a linker warning because no .imp file is used. To
avoid that warning, you can use (currently only supported for target
netwlibc, not for target netware):

FUNCTION rmdir (path : PCHAR) : LONGINT; CDECL; EXTERNAL '!nlmlib' NAME 'rmdir';
		      
This specifies the .imp file but does not add an autoload for nlmlib.


Writing NLMs that can be cleanly unloaded
=========================================

The rtl takes care that unload will work in most cases. Netware will trigger
the unload from the console process. In case the nlm would not unload,
the console process may hang.
To make sure, unload also works when your program waits in a socket call,
the rtl first deinitializes winsock which will release your blocking socket
call and allow a thread to terminate. This is not always what you want to do
on unloading your nlm. To prevent winsock from beeing released before your
threads are terminated, you can register an unload procedure that will be
called by the netware console process. Only do simple things (like signaling
a semaphore or setting a global variable) in that procedure because the owning
process calling this is the console process.

For a sample see demo/netware/nutmon.pp in the source tree.


Current Netware support packs
=============================

Especially early libc-versions have serious bugs on netware. For example
netware 6.5 < sp3 will abend in Dos.Exec and will truncate the environment
in protected space. I would suggest to try with a current netware support pack
before submitting bug reports.

-------------------------------------------------------------------------------
8. Debugging
-------------------------------------------------------------------------------

Remote debugging is possible with gdb on Netware 4.11, 5, 6 and 6.5. This
will be done by a converter (gdb2ndi) running on linux or win32. The 
converter will translate the gdb remote debugging protocol to the netware 
debug interface (ndi).

      TCP/IP             UDP
gdb <--------> gdb2ndi <-----> netware server

See http://home.arcor.de/armin.diehl/fpcnw/gdbnw.html for details


-------------------------------------------------------------------------------
9. Running the compiler on the Server
-------------------------------------------------------------------------------

Not really a supported configuration but you may try.

ALWAYS LOAD THE COMPILER PROTECTED, RUNNING A COMPILER IN RING 0 IS
NOT A GOOD IDEA

You need to download and install binutils as nlm's, they are available
as part of the gcc package on http://sourceforge.novell.com.

Copy the FreePascal tree to your server. Set the environment variable
PPC_CONFIG_PATH to point to your fpc.cfg and add the binutils and
fpc binary directory to your search path.
After changing your fpc.cfg, you may try to load fpc for ppc386.