# MorphOS

This page contains platform specific notes about the MorphOS port of Free Pascal. MorphOS is a massively enhanced, independent AmigaOS-clone, featuring ABI and API compatibility with classic Amiga, running on various PowerPC platforms. For more information, see its homepage.

## Identification

To identify MorphOS exclusively during compile-time, use {$IFDEF MORPHOS}. To identify any Amiga-like systems, use {$IFDEF HASAMIGA}. This is similar to HASUNIX which is defined across Unix systems. Please note that HASAMIGA define is only available in Free Pascal 3.0 and up, and the AMIGA define is *NOT* defined on MorphOS.

## Stack

#### SysV

SysV calling convention stores arguments according to SysV.4 ABI, then jumps to address stored at (LibBase - Offset). This calling convention is often used where no LibBase is needed.

#### BaseSysV

BaseSysV is a variation of SysV. It stores LibBase as first argument according to SysV.4 ABI, then puts all other arguments, then jumps to address stored at (LibBase - Offset). This calling convention also can be considered as legacy, R12Base convention replaced it, but still many libraries using it.

#### SysVBase

SysVBase is a variation of SysV. It stores all arguments according to SysV.4 ABI, then stores LibBase as last argument, then jumps to address stored at (LibBase - Offset). This calling convention also can be considered as legacy, as R12Base convention replaced it. This one is rare, not many libraries using it.

#### R12Base

R12Base is a variation of SysV. It stores all arguments according to SysV.4 ABI, then stores LibBase into register r12, then jumps to address stored at (LibBase - Offset). This calling convention superseeded BaseSysV and SysVBase, and should be used in new libraries.

### Other hints about libraries and Syscalls

MOST IMPORTANT: You must open the libraries you're going to use explicitly before using any function from them, because the compiler will not do it for you. Don't forget to close all libraries before you exit.

Before declaring a SysCall function, please check the units provided with FPC, the function you want to use might already be declared in one of the units, ready to be used.

## Naming conventions

This section describes the differences between the official MorphOS SDK, which is for C language, and MorphOS-specific units in FPC RTL.

### Constants

System constants are named exactly like in MorphOS SDK.

### Structures

System structures are named similar like in MorphOS SDK, but follows the Pascal convention about type naming, so structure names has a T before, and each type has a pointer to type with P before the name. The following example should make things trivial:

 struct Task equals to TTask


### Function calls

System calls are named like in MorphOS SDK, but there are a few exceptions. Unfortunately MorphOS legacy (Amiga compatible) API has some name conflicts with Free Pascal RTL functions, and this issue cannot be solved with function overloading. These calls are available with a name prefixed by their library's name. So for example, exec.library's FreeMem() is available under the name execFreeMem(), and FreeMem() means the FreeMem() call of FPC's own heap manager. The following functions are known to be affected:

• exec.library
• AllocMem() (only causes trouble inside System unit),
• FreeMem()
• Insert()
• dos.library
• Close()
• Write()
• Input()
• Output()
• Seek()
• Rename()
• Exit()
• Flush()
• System()
• DeleteFile() (conflicts with SysUtils)
• CreateDir() (conflicts with SysUtils)
• graphics.library
• Move() (conflicts with Video)

Be prepared for more...

#### MUI

In the following section there are a few hints about using MUI with Free Pascal.

1. set() and get() MUI macros available under name MUIset() and MUIget(), to avoid name conflicts with Pascal language. These are wrappers to the appropriate Intuition functions just like in C.
2. To avoid unnecessary typecasting, MUI_TRUE and MUI_FALSE declared instead of plain True and False. Using these is recommended.
3. There are various helper functions in MUIHelper unit, to make Pascal code using MUI much simpler and more readable. Use them.
4. Pascal preprocessor won't preparse strings like C does. So text formatting sequences widely used in MUI applications like \033c and so won't work. You have to use the defined constants instead. Example:

C version:

"\033cCentered \033bBold Text"

Pascal version:

MUIX_C+'Centered '+MUIX_B+'Bold Text'

or

#27'cCentered '#27'bBold Text'
• Note: these constants are there in official mui.h includes as well, they're just rarely used.

## Alignment

Record elements are aligned to DWORD (4 bytes) under MorphOS by default. Use {PACKRECORDS 2} if you need word aligned structures. For byte aligned records, use a packed record. ## Threading Threading is supported on MorphOS since Free Pascal 3.0, using the AThreads unit. Read there for possible caveats and unsupported features. ## Things good to know Here are a few hints, which I think are good to remember, when using FPC on MorphOS. • On program exit, System unit will close all files opened via its own functions, so it's recommended to use them in most cases. • Do not mix FPC and OS file functions on a single file. It may work in some cases, but that's purely a coincidence. It's bad programming and can stop working anytime without notice. • On program exit, the heap manager will free all memory allocated via its own functions. It uses a memory pool to avoid fragmentation. It also makes debugging easier when using heaptrc unit. Using OS memory functions directly is not recommended. • Scribble, which is a programmer's editor based on Scintilla is included in MorphOS SDK 2.x and part of MorphOS 3.x itself, and supports Pascal syntax highlighting out of box. • Another option for syntax highlighted editing is GoldEd, also known as Cubic IDE (or the lite version MorphEd, which was available as part of older MorphOS SDKs). A very nice Pascal syntax highlight addon was made for it by Rafal Zabdyr. The original site is down, but a backup is available here: http://obligement.free.fr/files/ged5morphed_pas075.lha ## Cross compiling Cross compiling to MorphOS is supported since version 3.0.0 and up. ### Cross compiling from Linux It's possible to cross-build the MorphOS compiler from Linux/i386 and Linux/x86-64 (probably other CPUs too, but it was not tested). To do that, you need Linux to MorphOS cross-binutils, mainly GNU as, ld, and optionally ar and strip. It's best if you build these from GNU sources, along with the rest of cross-build GNU toolchain. Mark "bigfoot" Olsen kindly provided a script for this, available here. Optionally, the binutils required by FPC are available here as binary for Linux/i386 (works on Linux/x86-64 too, if you install the required 32 bit environment). It was only tested on Ubuntu and Debian Linuxes, but may work on other distributions too. This package is provided "as-is" without any kind of support. Use it at your own risk. To build a MorphOS cross-compiler, use the following steps: 1. Install FPC the latest stable compiler, at the time of the writing of this article this is FPC 3.0.0. This will be used as the startup compiler. 2. Check out FPC SVN trunk into a directory (see version info above) 3. Make sure the aforementioned cross-binutils are actually in the PATH. 4. Go to the trunk's main directory and use the following command to build an FPC to MorphOS cross-compiler running on Linux:  make clean crossall crossinstall OS_TARGET=morphos CPU_TARGET=powerpc INSTALL_PREFIX="<path/to/install>" If you've done everything right, you should find a working MorphOS cross-compiler in the install path you've specified. Now, lets create a default fpc.cfg for MorphOS cross compiling. Create a file called <path/to/install>/lib/fpc/etc/fpc.cfg. Put the following lines into that file, and fix up the paths: #IFDEF CPUPOWERPC -Fu<path/to/install>/lib/fpc/fpcversion/units/$FPCTARGET -Fu<path/to/install>/lib/fpc/$fpcversion/units/\$FPCTARGET/*
#IFDEF MORPHOS
-FD</path/to/morphos-cross-binutils>
-XPpowerpc-morphos-
#ENDIF
#ENDIF


Optionally add <path/to/install>/lib/fpc/3.1.1/ directory to the PATH, so you'll have direct access to the cross compiler. If you've done everything right, you now should be able to build MorphOS executables from Pascal source on Linux the following way:

ppcrossppc -Tmorphos <source.pas>


Copy the resulting executable to MorphOS, and that's it!

### Cross compiling from OSX

In general, the same rules and steps apply as for Linux cross compiling. To build the binutils from sources using Mark Olsen's script (see in the previous section) some slight modifications to the script and/or additional GNU tools might be required.

For convenience, a binutils package required by FPC are available here as binary for Darwin/i386. This package is provided "as-is" without any kind of support. Use it at your own risk.

### Cross compiling from Windows

In general, the same rules and steps apply as for Linux cross compiling. It's also possible to cross-build the binutils with Cygwin using Mark Olsen's script, as linked in the previous section.

For convenience, a binutils package required by FPC are available here as binary for Windows/x86 (Cygwin/i686). This package is provided "as-is" without any kind of support. Use it at your own risk.

As FPC on Windows use a bit different directory structure the place to put our fpc.cfg is: <path/to/install>/bin/i386-win32/fpc.cfg. Also, for easy access, make sure directory <path/to/install>/bin/i386-win32/ is part of the PATH.

The cross-build from Windows/x64 was not tested, but should work with the obvious differences in paths and tools.

## Bootstrapping a compiler from Linux

To bootstrap a Free Pascal Compiler from Linux to MorphOS, first please complete the previous section. In order to have all the tools available, it's easiest to install the latest FPC compiler archive available here.

After you have a working cross compiler, go to the SVN trunk/compiler directory, and issue the following command:

make compiler OS_TARGET=morphos CPU_TARGET=powerpc FPC="<path/to/install>/lib/fpc/2.7.1/ppcrossppc"

Copy the resulting ppcppc executable to MorphOS. On the MorphOS box, try to cycle a compiler the following way in the SVN's trunk/compiler directory:

make cycle FPC=/path/to/ppcppc


Congratulations, you've just successfully bootstrapped Free Pascal on MorphOS! Now, copy everything in place by hand to your FPC: assign, build more stuff, etc... :)

Some version of Free Pascal on MorphOS, including latest SVN trunk versions default to vlink by Frank Wille as the default linker, when running natively on MorphOS. The cross-compilers still default to GNU ld. vlink is open source, and it is available here. Binaries are available as part of the vbcc compiler package.

You can change the linker back to GNU ld by adding -XV- argument when compiling. For cross compilers -XV argument enables vlink.

## Assembler

The MorphOS port supports both GNU as assembler and vasm. Advanced features like named sections support are only available with vasm. To compile with vasm, you need to specify the argument -Avasm compile time. Please note that mixing GNU as and vasm compiled objects might cause issues during linking.

vasm is open source, and it is available here. Binaries are available as part of the vbcc compiler package. Only vasm versions 1.7h and newer were tested, older versions might not work.

If -Avasm is set as default, for example in the config file, one can switch back to GNU as by using the -Aas-legacy command line argument. Please note that since the MorphOS SDK has a very old GNU as bundled, there could be problems with some of the assembly code generated by using the normal GNU as argument -Aas.