Free Pascal Wiki

Note

This is a basic initial idea for the official Free Pascal online wiki regarding the AROS port. Please feel free to comment and/or improve, especially on the developer and technical paragraphs.

TODO: add more information, this is merely initial commit

NOTE: if wanted we can use this page for editing in which case i'm willing to keep it in sync with fpc-wiki if/when going online.

Please note that all information detailed here is specific to Free Pascal 3.x and above. It does not apply to the older AROS Free Pascal 1.x port, nor does it apply to the even older 0.99.x and 1.0.x versions of Free Pascal for classic Amiga/m68k.

However, this port is very closely related to the recent supported classic Amiga/m68k and MorphOS platforms as they share some of the same code with AROS in an attempt to unify the support in Free Pascal for these platforms.

AROS Port

This port is aimed at AROS (AROS Research Operating System), the open source implementation of the "classic Amiga" operating system, which runs on modern processors like x86-32/x86-64/arm and PPC. Currently x86-32 ABIv0 is the only supported target for Free Pascal.

Because AROS is API compatible with Amiga (and binary compatible with Amiga/m68k), there is much similarity when addressing classic Amiga, MorphOS and AROS (all of which are now supported by Free Pascal).

Free Pascal for AROS has its own Wiki page here (under slow and continues development).

History

A first port of Free Pascal, version 1.x at the time, was contributed to AROS by Sasu Purola in 2002. This port only targeted m68k and was based on the Amiga/m68k port of Free Pascal which in itself was mostly done by Nils Sjöholm and Carl Eric Codère. Further development of this port for AROS ceased quickly thereafter.

A freshly restarted port was initiated in 2010 by Marcus Sackrow based on Free Pascal 2.5.1 and, was announced in the first half of 2011 at aros-exec. This port was also (partially) based on the Amiga/m68k port by Nils and Carl.

In August 2014, Károly Balogh (who brought us the MorphOS and classic Amiga(OS) ports) started the integration and unification of all three supported amiga-noid platforms into the FPC 2.7.1 trunk. Karoly and Marcus have been improving on that ever since.

With the release of FPC 3.0, AROS/i386 is officially supported as a target.

Important dates with regards to Free Pascal

• 2002-02-19 - Free Pascal 1.1 was committed into AROS Contrib repo [1]
• 2007-01-02 - Not being actively developed and for saving build time and space, Free Pascal was removed from AROS Contrib. [2]
• 2011-04-18 - First official announcement of a working port of FPC 2.5 for AROS. [3]
• 2011-05-30 - Initial release of Free Pascal 2.5.1 for AROS available to public. [4]
• 2011-06-18 - Start of a native LCL implementation for AROS. [5]
• 2011-08-06 - Revision 18107 added a fresh new AROS branch in the FPC source-tree. [6]
• 2014-08-18 - Revision 28445 transferred AROS RTL from the AROS branch into FPC trunk [7]
• 2014-08-31 - Revision 28547 transferred the AROS Units package units from branch AROS to trunk, effectively adding support for AROS to experimental FPC 2.7.1 compiler. [8]
• 2015-11-13 - Revision 32319 marked the release of Free Pascal 3.0.0 The AROS/i386 target is now officially supported. [9]
• 2016-01-24 - Revision 32996 changed usage of "array of const" to "array of PtrUInt". [10]
• 2016-09-03 - Revision 34416 Refactoring of SysCalls (for all our supported platforms). Calling convention EAXBASE for AROS was added (usage: {$SYSCALL EAXBASE}). [11]
• 2016-11-06 - Revision 34827 marked the support for AROS-ARM. The AROS/arm target is now supported in trunk. Previous commits added support for SysCall mechanism for ARM [12]

TODO: Add more dates, e.g. gadgets/LCL, fpGUI, fpGUI/LCL, Zune/LCL, AThreads and search + add relevant links. [Goal is to fill the holes between 2011-2014 and 2014-2015 a bit more]

Important dates with regards to Lazarus

Support for Lazarus is an ongoing effort which started several years ago, mainly done by ALB42. ALB42's work includes a (incomplete but ongoing progress) MUI widgetset implementation (amongst others) but is not supported in Lazarus trunk. Recently support was added for NoGUI widgetset.

• 2017-03-03 - Revision 53853 adds Lazarus supporting NoGUI for Amiga-like platforms. [13]

Status

• Most FPC RTL functions are supported (see also missing features for more detailed information)
• AROS' support units and implementations are as much source compatible to Amiga/m68k as possible, so theoretically any program you write which uses functionality from these units could therefor be cross-compiled for Amiga/m68k and/or MorphOS (if not using AROS specific functionality).
• The (cross) compiler is available for multiple platforms, including AROS/i386, Windows32/64 and linux32/64
• AROS Binutils are available -> Need to prepare archives + Readme's, add links to sources, etc. Note: available ARM binutils for Windows in aros-archives do not offer aros-arm emulation support

Missing features:

• Support for AROS ABIv1 is not implemented yet. see classic Amiga/m68k for now.
• No WideStrings manager. Will it ever ?
• Dynamic Libraries (in the sense of how Free Pascal implements this functionality). Normal dynamic loading of native .library files is of course supported, using Exec LoadLibrary() and CloseLibrary() functions. Reason for missing is that AROS does not officially supports retrieving Function offsets using symlinks and function names are missing from AROS native libraries.

Future enhancements (requires FPC 3.1.1. Not available in trunk, see also ALB42's blog):

• Support for fpGUI (native and LCL) was started by ALB42 in 2014 (working for most parts)
• Support for Lazarus/MUI widgets was (re)started in 2014 by ALB42 (currently in development, already very usable).
• Support for AROS/X86-64 (ABI-v1) was started in June 2015 by ALB42 and expanded by Chain-Q (seems successful, under development/testing)

ToDo Items:

• ExecuteProcess() is not supported yet -> yes it is, made available by ALB42, need to lookup revision (future functionality?)

A more elaborating status pages can be viewed on the Free Pascal for AROS wiki - Status Page.

Port Notes

The current (cross) compiler is able to create AROS executables for AROS/i386 (abiv0).

Filenames

Every operating system derived from or based upon classic Amiga/m68k, is neither Windows nor Linux. This results in a somewhat different used filename-scheme. Amiga/AROS/MorphOS uses the format "Drive Name:Directory 1/Subdirectory/Name of a file.extention" (without the quotes). Please keep this in mind when developing software that is intended to run cross-platform. Also note that executables do not have a file-extension.

File pattern matching (wildcards)

By default, AROS uses different (in relation to the usual asterisk usage) symbols for pattern matching. The native AmigaDos parsePattern() function explains them in detail.

During porting great effort was put into Free Pascal's DOS functions, to support both Amiga-style and the more known asterisk symbol to be used as wild-card for pattern matching.

Requirements to start developing for AROS

• An AROS ABIv0 i386 installation in case testing of the executables is required.
• Free Pascal for AROS, or (cross)compiler for a supported platform (Windows, Linux, Others ?)
• The AROS binutils (standard installed by most AROS distros)
• No other dependencies required, but for completeness the AROS NDK.

Native development and/or testing executables is possible by installing AROS into a virtual machine, running AROS hosted (as single application) under Linux/Windows or on a dedicated AROS machine. All of which require minimal i386 processor.

Documentation/Reference

• AROS homepage
• AROS wikibook
• AROS Support forums
• Free Pascal for AROS wiki
• Free Pascal for AROS wiki - Introduction to AROS (A Short Introduction for those unfamiliar with AROS).
• Free Pascal for AROS Online reference (not up to date, we could use some help)

Technical information

Identification

System Defines

• AROS - To identify AROS exclusively
• HASAMIGA - To identify any Amiga-like system (Amiga/m68k, MorphOS and AROS), similar to HASUNIX which is defined across Unix systems.

Supported User Defines

• LCL_MUI (use LCL/MUI widgetset implementation), if omitted use fpGUI//LCL implementation.

Stack

Programs compiled for AROS, uses an initial default stack size of 256 kB. The size of the stack can be set directly by the programmer with the compiler switch -Cs, or with the {$MEMORY} directive.

A program initially uses the stack it retrieves from either shell or Workbench (or replacement), but in case the program was compiled using larger stack size settings, then the program will automatically use the compiler settings and allocates its own stack.

In case of a stack-overflow, one could simply increase the size of the shell-stack, to see how much stack is required to run the program properly without stack overflow, and later adjust the compiler settings in order to recompile the program to use these new (better) settings.

Do note that setting the stack-size too high could result in memory related issues, especially when your configuration is low on memory.

SysCalls

Free Pascal supports generating AROS-style library calls, which means that it isn't necessary to use additional hand-written assembly in order top call a library function.

However, every function available in the library that you want to use/expose should be declared in a similar matter as shown:

Var 
  MyLibraryBase  : Pointer;
Const
  FunctionOffset = 1234;

  function  NameOfLibraryFunction(parameter1: LongInt; parameter2: PChar): LongWord; SysCall MyLibraryBase FunctionOffset;

In this example, MyLibraryBase is the base address of the library as returned by a call the exec's OpenLibrary() function, and FunctionOffset is the call Offset. Offset values for AROS libraries are positive numbers, as declared by the AROS SDK. The MyLibraryBase variable can be a typed pointer, a dword or a nil pointer. It's recommended to use PLibrary or the library's own type (if one exists or possible).

Note that you need to initialize the MyLibraryBase explicitly, before being able to use any function from the library. Please don't forget to use exec's CloseLibrary() function to release system resources again, when exiting your program. The interface units provided by the compiler will auto open and close respective libraries (unless otherwise noted).

Threading

Threading is supported on AROS since Free Pascal 3.0, using the AThreads unit. Read there for possible caveats and unsupported features.

Developer information

Binutils

AROS support in Free Pascal does not initiate the linker tool ld directly but, instead uses a tool named collect-aros which will complete the last compilation stage with calling the right binutil tools in order to create an valid AROS executable.

Compilation of the binutils and the collect-aros tool require a shell such as bash on Linux and/or MingW.

Requirements:

• A working GCC environment (tested on Linux and MingW32) that is capable of compiling gnu binutils.
• AROS source archive from the AROS nightly download page.
• gnu binutils sources from the gnu ftp archive that matches one (or all if you prefer) of the .diff files found in the AROS source archive

Compile binutils from source:

• extract one of the binutils directories from the AROS source archive (or if you prefer, all of them). Each directory contains a .diff file which corresponds with the binutils version it applies to.
• extract corresponding matching version of the gnu binutils archive.
• apply the .diff patch.
• ./configure
• make

TODO: replace with bash script

Compile collect-aros tool from source:

• extract the collect-aros directory from the AROS source archive.
• ./configure
• make

TODO: replace with bash script

Cross Compiling

In order to be able to cross-compile you should first create the binutils for your host platform.

Cross compiling from Linux

Create the binutils

Cross compiling from Windows

• Make sure you have the required binutils + collect-aros tool
• Place the binutils + collect-aros in a directory of your choice. f.e. G:\WinDev\BinUtils

Now, it needs to be decided whether the BinUtils directory is placed into the path environment variable, or alternatively use the COMPILER_PATH environment variable. This is needed to let collect-aros tool be able to locate the correct binutils.

If you are using the binutils _only_ for Free Pascal then it would be easier to use the COMPILER_PATH environment variable, but be warned that this can interfere with an existing GCC setup. In case you are using the same binutils for other compilers (for instance GCC), then using the Path environment variable would most probably be a better solution.

Setting either environment variable depends on the Windows version you are actually using, so please consult your operating system's manual in order to accomplish this task.

Note: You can always use the path to FPC to copy the binutils into, as most people have Free Pascal in their PATH environment variable already

• Install the AROS target archive in your existing FPC installation

How, when, where ?

• configure fpc by modifying your fpc.cfg configuration file (note that something similar needs to be done for fp-IDE).

Make sure you have the following lines present in your fpc.cfg file in order to use the correct filenames for the binutils.

 #IFNDEF WIN32
 #DEFINE NEEDCROSSBINUTILS
 #ENDIF

 #IFDEF FPC_CROSSCOMPILING
 #IFDEF NEEDCROSSBINUTILS
   -XP$FPCTARGET-
 #ENDIF
 #ENDIF

Add the following lines to fpc.cfg if you have used the COMPILER_PATH environment variable.

 -FD$COMPILER_PATH$

Make sure the following line is present in your fpc.cfg file to make sure the aros units can be found (niote that you need to replace the "D:\WinDev\FPC301" part to match the location of your personal FPC installation.

 -FuD:\WinDev\FPC301\units\$FPCTARGET\*

You should now be able to successfully target AROS by using the -Taros compiler switch