fpc/rtl/freebsd/bsdport.txt

$Id: bsdport.txt,v 1.5 2003/11/18 21:47:19 marco Exp $

$Revision$

The Free Pascal *BSD port.

Comments, mistakes and suggestions to Marco@freepascal.org


In 1.1.x/1.9.x/2.0.x branch, the  BSD RTLs are merged into one, for easier
maintaining, NetBSD and OpenBSD are dropped due to lack of feedback and
interest, Darwin has been added.

1 *BSD status and notes. (kept on CVS because I work on several places)
-----------------------------------------------------------------------------

Please read these before running a *BSD snapshot/release

1.1  Supported OS versions.
---

   FREEBSD
	    6.x	   : roughly same as 4.x
	    5.x    : Used to develop and maintain port. Should work, all
			 versions. Best *BSD platform.
            4.x    : Should work mostly. Maybe some updates to prt0.as/cprt0.as
			needed.

            3.x    : _not_ supported,  (3.2, 3.4, 3.6 would probably work
   		     with some very minor changes to the signalhandling. The
   		     syscall numbers changed)

(all these are deprecated in 1.0.x

  (NON-ELF) 2.x    : _not_ supported, but it might be doable. (the
   		     OpenBSD port works on a.out)
   
            5.0DP1 : simple testing seemed to work without changes. Nearly
		      no package tests tried though.

   NetBSD   1.5.x  : Most stuff should work.
	    Rest   : status unknown, though some NetBSD developper said
		     he didn't expect problems for 1.6.x
  
   OpenBSD  3.1    : This version should work somewhat. Needs an assembler
		      from the ports tree (devel/binutils) to function
		      properly. Linker of the ports tree is easier,
		      but that one doesn't want to make shared files.
)
The IDE also is starting to work quite nicely on FreeBSD, so it is included
in the releases since 1.0.6. I didn't check the fixes for *BSD on the other
two OSes yet.

1.2 Known bugs
---

The FreeBSD/FPC port is now more or less a tested distro. There are several
 known bugs, but I can now only remember one:

-  Recover from Delphi exceptions that originate as processor exceptions
    will go wrong. (see texception4 in the test suite)

   (recovering from several processor
   exceptions in one proc will have unpredictable results (breakable hang
   probably))

1.3 Possible issues.

Some things are not really bugs, but status is unknown, or there is
something dodgy about the implementation:

- The NetBSD and OpenBSD ports are barely tested, they build on the stable
   FreeBSD base though. Most packages (and the FCL) have been tested with
   FreeBSD, quite some with NetBSD, nearly none with OpenBSD.

-  IMPORTANT:
     !!! An explicite warning: Not all procedures and structures in Linux are
   checked, so even if they are not commented out, they can be not implemented!!!
   This specially applies to linux specific stuff. In case of doubt, use a
   scratch system, view the source, or mail the maintainer.
   I fixed a bug in truncate just a few months ago, that had gone unnoticed
   for the near two years that the port works now.!!! 

- The absence of kernel READDIR support has been fixed with a "hack", which
    means that searchpath (-Fx) and FindFirst/FindNext are more or less
    working.     This "hacked" readdir implementation is now 1 1/2 year
    bugfree now (and no anomolies detected), and works on the other two BSDs
    too. Be careful with usage on "special" filesystems and files though. 
    (devfs, tmpfs hardlinks)
   Together with Sebastian I developped a port of the libc routines, but
    they don't work yet (NOTE to self: retest, am a lot better with debugger
    now)

3 How to build a *BSD compiler/RTL ?
-----------------------------------------------------------------------------

To rebuild the compiler, you need a starting compiler which is either the
last releaseversion, or the release you are building itself (but e.g. on
other OS)

Preparation:
- make sure your tree is up to date and cleaned of stale object and unit files.
- I assume ppc386 is the name of your compiler. Append PP=<compilername> and
   replace ppc386 with your compilername if it is different on your system.
- I'll assume we are building openbsd on one of the other systems.

- Start compiler on other OS? (tested is Linux) -> check 3.1
   (crosscompiling)
- Already a suitable 1.0.x startcompiler on *BSD  -> 3.2 is much
    easier.

Trying to build with snapshot compiler binaries is no problem mosttimes, but
release compilers _ought_ to work.

3.1 How to build a *BSD system starting on (another *BSD, Linux, or Linux
    emu on any of them).
---

The procedure here is verbose, and for the most akward case. If you have
linux support on on your FreeBSD machine, or operate on NFS or Samba share
(so that copying and using the sources in two systems is easier) some steps
can be omitted or simplified. Just play with it.

create the RTL:

1. go to the target RTL directory. (if you want to build for OpenBSD, to
	rtl/openbsd).
2. If your binary format is the same (both are ELF), simply run 
     (g)make OS_TARGET=openbsd  

  this will be called "case A" from now on.
  Otherwise we need to build via assembler files; (CASE B) and you'll
    need to execute:
 
    (g)make OS_TARGET=openbsd OPT='-a'

compile the compiler:

3. Go to the compiler/ directory
   Case A:
 
   make OS_TARGET=openbsd OPT='-Fu../rtl/openbsd -kdontlink'

   Case B:

   make OS_TARGET=openbsd OPT='-Fu../rtl/openbsd -kdontlink -a'

4 Collect all necessary files, put them in one directory on the target
   computer. 

   Case A:  - all *.o and *.ppu files in compiler/ and rtl/openbsd/
	    - compiler/link.res and 
	    - compiler/ppas.sh

   Case B:  - All *.s and *.ppu files in compiler/ and rtl/openbsd/
	    - the prt0.as file in rtl/openbsd/i386, rename this file to prt0.s
	    - compiler/link.res and compiler/ppas.sh

Creating the final compiler:

5 edit link.res, and fix all paths (it will include ../rtl/openbsd, simply
   remove all paths in the INPUT() section, so filenames only)
  Remove "dontlink" from the commandline of the linker in the ppas.sh file,
  and make the ppas.sh file executable with chmod.

6 Make sure you are in the right dir.
  Case A: run ppas.sh
  Case B: run the do_s script in the appendix (which will assembler all *.s
           files to *.o on the target system), THEN run ppas.sh

7 Test your compiler with pp -?, brandelf if necessary. (NetBSD ident code is
   already in the prt0.s file. Will be for ELF OpenBSD too)

Rebuild everything (compiler+RTL+FCL+pkgs) on the host system: 

8 Go to the toplevel directory fpc/

9 Enter:
   gmake all
 
Install the system

10 gmake install   
   (will install into $PREFIX=/usr/local)



3.2 How to build a *BSD system if you have a suitable compiler on the
targetsystem.
---

Rebuild everything (compiler+RTL+FCL+pkgs) on the host system: 

1 Go to the toplevel directory fpc/

2 Enter:
   gmake all
 
Install the system

3 gmake install   
   (will install into $PREFIX=/usr/local)


------------------
Appendix A:   The DO_S script. (C) El Znorro
------------------
#!/bin/sh

for i in *.s; do
 flup=`basename $i .s`
 as $i -o $flup.o
 echo $i
 echo $flup
 done