Difference between revisions of "Specifics"

From Freepascal Amiga wiki
Jump to navigation Jump to search
(ThreadBase Added)
(→‎Compiler defines: Alphabetical tree)
 
(22 intermediate revisions by 2 users not shown)
Line 1: Line 1:
−
== Specialities of AROS Freepascal ==
+
== Specific implementations/changes for Free Pascal on Amiga systems==
  
−
in Relation to other Freepascal implementations.
+
=== in Relation to other Free Pascal implementations ===
 
----
 
----
−
The compiler:
+
==== Compiler defines ====
−
 
+
There are several [//www.freepascal.org/docs-html/prog/progap7.html#x329-344000G compiler defines (table G.4)] available for Free Pascal. More on multiplatform programming can be found [//wiki.freepascal.org/Multiplatform_Programming_Guide here].
−
has additional features:
 
 
{| class="wikitable"
 
{| class="wikitable"
 +
|-
 +
!Definition HASAMIGA
 +
|With this definition you can can determine if you are on any of the Amiga platforms (also future proof for future Amiga platforms). Use it to encapsulate code parts (or uses) for all Amiga-style systems {$ifdef HASAMIGA} {$endif} or disable parts which does not work on all Amiga-style systems via {$ifndef HASAMIGA} {$endif}
 +
|-
 +
!Definition AMIGA
 +
|This definition exists in FreePascal for Amiga m68k and Amiga PowerPC (OS4) only. Do separate Amiga m68k and OS4 you can use the processor defines '''M68K''' and '''POWERPC''' or the specialized defines '''AMIGA68k''' and '''AMIGAOS4'''.
 +
|-
 +
!Definition MORPHOS
 +
|This definition exists in FreePascal for MorphOS.
 
|-
 
|-
 
!Definition AROS
 
!Definition AROS
−
|There are several [//www.freepascal.org/docs-html/prog/progap7.html#x329-344000G compiler defines (table G.4)] available for Freepascal. The AROS version of FPC adds the definition AROS to that list. This enables you to determine if your program is compiled/targeted for AROS or not. You can use {$IFDEF AROS} or {$IFNDEF AROS} to make use of this define. This would also aid in porting platform specific sources and/or writing FreePascal programs that could be compiled using the [//aminet.net/package/dev/lang/fpc110aami old FPC 1.10 compiler for classic amiga's], [//aminet.net/package/dev/lang/fpc-2.0.4.powerpc-mos MorphOS] and/or [//aminet.net/package/dev/lang/fpc-20060820-powerpc-amiga AmigaOS 4]. More on multiplatform programming can be found [//wiki.freepascal.org/Multiplatform_Programming_Guide here].
+
| This definition exists in FreePascal for AROS. This enables you to determine if your program is compiled/targeted for AROS or not. You can use {$IFDEF AROS} or {$IFNDEF AROS} to make use of this define. ABI define '''AROS_ABIv0''' and '''AROS_ABIv1'''
−
|-
+
NOTE: There is no dedicated AROS m68k Version, the released Version is the Amiga m68k version because AROS m68k is binary compatible to Amiga classic.
−
|
 
 
|}
 
|}
  
 +
Tree structure of Amiga related platform defines:
  
−
System unit:
+
* '''HASAMIGA''' (defined since FPC 3.0)
 +
** '''AMIGA''' (Classic and new)
 +
*** '''AMIGA68K''' (Classic Amiga OS, defined since FPC 3.0.2)
 +
*** '''AMIGAOS4''' (Amiga OS4)
 +
** '''AROS''' (AROS)
 +
*** '''AROS_ABIv0''' (AROS v0 ABI)
 +
*** '''AROS_ABIv1''' (AROS v1 ABI)
 +
** '''MORPHOS''' (MorphOS)
  
−
has some additional functions and variables:
+
==== Additional System unit contents ====
 +
'''System''' unit has some additional functions and variables:
  
 
Be warned if you change any of the variables then your program will crash and most likely your computer as well.
 
Be warned if you change any of the variables then your program will crash and most likely your computer as well.
Line 23: Line 39:
 
{| class="wikitable"
 
{| class="wikitable"
 
|-
 
|-
−
!Debug(Msg: string); DebugLn(Msg: string);
+
!SysDebug(Msg: ShortString); SysDebugLn(Msg: ShortString);
−
|Write a message to debug out put of AROS, in hosted mode you can find this output in the shell you started AROS from. if you want to read the messages in AROS (or you have a native installation) you can use Sashimi to catch the output. DebugLn() adds a return after the message, Debug() does not.
+
|Write a message to debug output of the system. To read this debug messages you need a special tool to catch the messages (AROS: sashimi, hosted AROS: consoleoutput; MorphOS/AmigaOS4: LogTool)  SysDebugLn() adds a return after the message, SysDebug() does not. '''NOTE''': The ''Msg'' parameter is a ShortString, so must not be longer than 255 chars.
−
|-
 
−
!function GetLibAdress(Base: Pointer; Offset: LongInt): Pointer;
 
−
|Function to calculate the function pointer from the library base and the offset. Needed to call AROS library functions. For an example see [[Call Library]]
 
 
|-
 
|-
 
!AOS_WbMsg: Pointer;
 
!AOS_WbMsg: Pointer;
Line 43: Line 56:
 
!AOS_heapPool: Pointer;
 
!AOS_heapPool: Pointer;
 
|Its a Pool Header created with (CreatePool from exec), all memory allocations are created in this pool, could be used to AllocPooled memory as well (even AllocMem, New and so on do it automatically)
 
|Its a Pool Header created with (CreatePool from exec), all memory allocations are created in this pool, could be used to AllocPooled memory as well (even AllocMem, New and so on do it automatically)
 +
|}
 +
 +
==== Threading ====
 +
{| class="wikitable"
 +
|-
 +
!athreads
 +
|This unit is needed if the program wants to use threads. It must be added as very first uses in the main source file. it is comparable to the ''cthreads'' units of freepascal for linux.
 +
|}
 +
 +
==== Syscalls ====
 +
 +
For all Amiga systems a special calling convention for calls into a Amiga-style (.library) with the keyword ''syscall''. A typical Library call looks like this:
 +
<source lang="pascal">
 +
procedure FktName(parameters); syscall Base Offset;
 +
</source>
 +
{| class="wikitable"
 +
|-
 +
|''Parameter''
 +
|'''AROS(i386, x86_64, ARM), AmigaOS4''': Parameter of the function with type: '''param: type'''
 +
'''AmigaOS3, MorphOS''': Parameter of the function with type and location: '''param: type location 'register' ''' register is a standard m68k register 'd0'-'d7','a0'-'a6'
 +
|-
 +
|''Base''
 +
|'''AmigaOS3, AROS, MorphOS''': LibraryBase from OpenLibrary();
 +
'''AmigaOS4:''' Interface of the Library from GetInterface();
 +
|-
 +
|''Offset''
 +
|'''AmigaOS3, MorphOS, AmigaOS4''': Offset relative to the ''Base''
 +
'''AROS''': Offset relative to the ''Base'' divided by the size of a Pointer (therefore its the same value for 64 bit and 32bit)
 +
|}
 +
[[Call Library]] shows how to create syscalls for the different platforms and how to gather the needed informations
 +
 +
Further informations about syscalls: [http://wiki.freepascal.org/Amiga#SysCalls AmigaOS3], [http://wiki.freepascal.org/AmigaOS#Library_interfaces_and_Syscalls AmigaOS4], [http://wiki.freepascal.org/MorphOS#SysCalls MorphOS]
 +
 +
=== Relation to other languages on AROS/Amiga ===
 +
----
 +
Not really compiler related, but more about how ones program should behave, look and act on an amiganoid system.
 +
 +
 +
There is a document called "Amiga User Interface Style Guide" [http://amigaos.pl/amiga_user_interface_style_guide/index.html] that cover some of the basic techniques that should be practised when programming for amiganoid systems. Of course, it would be impossible to follow them all (if even for the GUI differences) but there are a couple of interesting topics in there:
 +
{| class="wikitable"
 +
|-
 +
!Embedded version IDs: [http://amigaos.pl/amiga_user_interface_style_guide/embedded_version_ids.html]
 +
|Gives the programmer the ability to let the system 'interrogate' your program (executable) and displays version information (from either commandline tool version or by using the icon information menu from the workbench).<br>
 +
To put it simply, add a const string in generic version format:
 +
$VER: <name> <version>.<revision> (<d>.<m>.<y>)
 +
|}
 +
----
 +
==== Changed Unit Names ====
 +
{| class="wikitable"
 +
|+
 +
!Library name in AROS !! corresponding Free Pascal Unit !! Collision with
 +
|-
 +
|graphics.libray || agraphics || Graphics unit from LCL
 +
|-
 +
|dos.library || amigados || Dos unit from RTL
 +
|}
 +
 +
Also note that the usage of unit amigalib is deprecated. The functions that resided in this unit can now be found in their respective counterpart units e.g. graphic related function can now be found inside unit AGraphics, Intuition related functions can now be found inside unit Intuition, etc.
 +
 +
==== Changed constants/function Names ====
 +
{| class="wikitable"
 +
|+
 +
!type !! Original Name !! Free Pascal Name !! Collision with
 +
|-
 +
| colspan=4 | '''Exec.Library (exec) '''
 +
|-
 +
|function || AllocMem || ExecAllocMem || AllocMem() in System
 +
|-
 +
|procedure || FreeMem || ExecFreeMem || FreeMem() in System
 +
|-
 +
|procedure || Insert || ExecInsert || Insert() in System
 +
|-
 +
|procedure || Exception || ExecException || Exception keyword
 +
|-
 +
| colspan=4 | '''dos.Library (amigados)'''
 +
|-
 +
|procedure || Close      || DOSClose              || Collides with Close() function in unit System
 +
|-
 +
| function || CreateDir  || DOSCreateDir          || Collides with CreateDir() function in unit SysUtils
 +
|-
 +
| function || DateToStr  || DOSDateToStr          || Collides with DateToStr() function in unit SysUtils
 +
|-
 +
|procedure || Delay      || DOSDelay              || Collides with Delay() function in unit CRT
 +
|-
 +
|procedure || DeleteFile || DOSDeleteFile        || Collides with DeleteFile() function in unit SysUtils
 +
|-
 +
|procedure || Exit      || DOSExit              || Collides with Exit() function in unit System
 +
|-
 +
|procedure || Flush      || DOSFlush              || Collides with Flush() function in unit System
 +
|-
 +
| function || Format    || DOSFormat            || Collides with Format() function in unit SysUtils
 +
|-
 +
|variable  || Input      || DOSInput              || Collides with Input() variable in unit System
 +
|-
 +
|procedure || Open      || DOSOpen              || For consistency with other dos functions
 +
|-
 +
|variable  || Output    || DOSOutput            || Collides with Output() variable in unit System
 +
|-
 +
|procedure || Read      || DOSRead              || Collides with Read() function in unit System
 +
|-
 +
|procedure || Rename    || DOSRename            || Collides with Rename() function in unit System
 +
|-
 +
|procedure || Seek      || DOSSeek              || Collides with Seek() function in unit System
 +
|-
 +
| function || StrToDate  || DOSStrToDate          || Collides with StrToDate() function in unit SysUtils
 +
|-
 +
| function || System    || DOSSystem            || For consistency with other dos functions
 +
|-
 +
|procedure || Write      || DOSWrite              || Collides with Write() function in unit System
 +
|-
 +
| colspan=4 | '''Graphics.Library (agraphics)'''
 +
|-
 +
|procedure || Move || GfxMove || Move() in System
 +
|-
 +
|procedure || Text || GfxText || Text type
 +
|-
 +
| colspan=4 | '''Intuition.Library (intuition)'''
 +
|-
 +
|const || SINGLE || SINGLE_PT || Single type
 +
|-
 +
|const || FANFOLD || FANFOLD_PT || (renamed because of Single renaming)
 +
|-
 +
|const || WBENCHSCREEN || WBENCHSCREEN_f ||
 +
|-
 +
|const || PUBLICSCREEN || PUBLICSCREEN_f ||
 +
|-
 +
|const || CUSTOMSCREEN || CUSTOMSCREEN_f ||
 +
|-
 +
|const || SCREENTYPE || SCREENTYPE_f ||
 +
|-
 +
|const || SHOWTITLE || SHOTITLE_f ||
 +
|-
 +
|const || BEEPING || BEEPING_f ||
 +
|-
 +
|const || CUSTOMBITMAP || CUSTOMBITMAP_f ||
 
|-
 
|-
−
!AOS_ThreadBase: Pointer;
+
|const || SCREENBEHIND || SCREENBEHIND_f ||
−
|Real type is: PLibrary can be used to call all thread.library calls WARNING: can be nil if the Thread.library does not exist.
 
 
|}
 
|}

Latest revision as of 20:45, 11 February 2018

Specific implementations/changes for Free Pascal on Amiga systems

in Relation to other Free Pascal implementations

Compiler defines

There are several compiler defines (table G.4) available for Free Pascal. More on multiplatform programming can be found here.

Definition HASAMIGA With this definition you can can determine if you are on any of the Amiga platforms (also future proof for future Amiga platforms). Use it to encapsulate code parts (or uses) for all Amiga-style systems {$ifdef HASAMIGA} {$endif} or disable parts which does not work on all Amiga-style systems via {$ifndef HASAMIGA} {$endif}
Definition AMIGA This definition exists in FreePascal for Amiga m68k and Amiga PowerPC (OS4) only. Do separate Amiga m68k and OS4 you can use the processor defines M68K and POWERPC or the specialized defines AMIGA68k and AMIGAOS4.
Definition MORPHOS This definition exists in FreePascal for MorphOS.
Definition AROS This definition exists in FreePascal for AROS. This enables you to determine if your program is compiled/targeted for AROS or not. You can use {$IFDEF AROS} or {$IFNDEF AROS} to make use of this define. ABI define AROS_ABIv0 and AROS_ABIv1

NOTE: There is no dedicated AROS m68k Version, the released Version is the Amiga m68k version because AROS m68k is binary compatible to Amiga classic.

Tree structure of Amiga related platform defines:

  • HASAMIGA (defined since FPC 3.0)
    • AMIGA (Classic and new)
      • AMIGA68K (Classic Amiga OS, defined since FPC 3.0.2)
      • AMIGAOS4 (Amiga OS4)
    • AROS (AROS)
      • AROS_ABIv0 (AROS v0 ABI)
      • AROS_ABIv1 (AROS v1 ABI)
    • MORPHOS (MorphOS)

Additional System unit contents

System unit has some additional functions and variables:

Be warned if you change any of the variables then your program will crash and most likely your computer as well.

SysDebug(Msg: ShortString); SysDebugLn(Msg: ShortString); Write a message to debug output of the system. To read this debug messages you need a special tool to catch the messages (AROS: sashimi, hosted AROS: consoleoutput; MorphOS/AmigaOS4: LogTool) SysDebugLn() adds a return after the message, SysDebug() does not. NOTE: The Msg parameter is a ShortString, so must not be longer than 255 chars.
AOS_WbMsg: Pointer; Real Type is PWBStartup (from "Workbench" unit) can be used to determine if the program was started from WB (if this pointer is Nil then it was started from CLI)
AOS_ExecBase: Pointer; Real type is: PExecBase (from "Exec" Unit) can be used to call all exec.library calls, or to inspect system basic features
AOS_DOSBase: Pointer; Real type is: PDOSBase (from "AmigaDos" Unit) can be used to call all dos.library calls
AOS_UtilityBase: Pointer; Real type is: PUtilityBase (from "Utility" Unit) can be used to call all utility.library calls
AOS_heapPool: Pointer; Its a Pool Header created with (CreatePool from exec), all memory allocations are created in this pool, could be used to AllocPooled memory as well (even AllocMem, New and so on do it automatically)

Threading

athreads This unit is needed if the program wants to use threads. It must be added as very first uses in the main source file. it is comparable to the cthreads units of freepascal for linux.

Syscalls

For all Amiga systems a special calling convention for calls into a Amiga-style (.library) with the keyword syscall. A typical Library call looks like this: 

procedure FktName(parameters); syscall Base Offset;
Parameter AROS(i386, x86_64, ARM), AmigaOS4: Parameter of the function with type: param: type

AmigaOS3, MorphOS: Parameter of the function with type and location: param: type location 'register' register is a standard m68k register 'd0'-'d7','a0'-'a6'

Base AmigaOS3, AROS, MorphOS: LibraryBase from OpenLibrary();

AmigaOS4: Interface of the Library from GetInterface();

Offset AmigaOS3, MorphOS, AmigaOS4: Offset relative to the Base

AROS: Offset relative to the Base divided by the size of a Pointer (therefore its the same value for 64 bit and 32bit)

Call Library shows how to create syscalls for the different platforms and how to gather the needed informations

Further informations about syscalls: AmigaOS3, AmigaOS4, MorphOS

Relation to other languages on AROS/Amiga

Not really compiler related, but more about how ones program should behave, look and act on an amiganoid system.


There is a document called "Amiga User Interface Style Guide" [1] that cover some of the basic techniques that should be practised when programming for amiganoid systems. Of course, it would be impossible to follow them all (if even for the GUI differences) but there are a couple of interesting topics in there:

Embedded version IDs: [2] Gives the programmer the ability to let the system 'interrogate' your program (executable) and displays version information (from either commandline tool version or by using the icon information menu from the workbench).

To put it simply, add a const string in generic version format: 

$VER: <name> <version>.<revision> (<d>.<m>.<y>)

Changed Unit Names

Library name in AROS corresponding Free Pascal Unit Collision with
graphics.libray agraphics Graphics unit from LCL
dos.library amigados Dos unit from RTL

Also note that the usage of unit amigalib is deprecated. The functions that resided in this unit can now be found in their respective counterpart units e.g. graphic related function can now be found inside unit AGraphics, Intuition related functions can now be found inside unit Intuition, etc.

Changed constants/function Names

type Original Name Free Pascal Name Collision with
Exec.Library (exec)
function AllocMem ExecAllocMem AllocMem() in System
procedure FreeMem ExecFreeMem FreeMem() in System
procedure Insert ExecInsert Insert() in System
procedure Exception ExecException Exception keyword
dos.Library (amigados)
procedure Close DOSClose Collides with Close() function in unit System
function CreateDir DOSCreateDir Collides with CreateDir() function in unit SysUtils
function DateToStr DOSDateToStr Collides with DateToStr() function in unit SysUtils
procedure Delay DOSDelay Collides with Delay() function in unit CRT
procedure DeleteFile DOSDeleteFile Collides with DeleteFile() function in unit SysUtils
procedure Exit DOSExit Collides with Exit() function in unit System
procedure Flush DOSFlush Collides with Flush() function in unit System
function Format DOSFormat Collides with Format() function in unit SysUtils
variable Input DOSInput Collides with Input() variable in unit System
procedure Open DOSOpen For consistency with other dos functions
variable Output DOSOutput Collides with Output() variable in unit System
procedure Read DOSRead Collides with Read() function in unit System
procedure Rename DOSRename Collides with Rename() function in unit System
procedure Seek DOSSeek Collides with Seek() function in unit System
function StrToDate DOSStrToDate Collides with StrToDate() function in unit SysUtils
function System DOSSystem For consistency with other dos functions
procedure Write DOSWrite Collides with Write() function in unit System
Graphics.Library (agraphics)
procedure Move GfxMove Move() in System
procedure Text GfxText Text type
Intuition.Library (intuition)
const SINGLE SINGLE_PT Single type
const FANFOLD FANFOLD_PT (renamed because of Single renaming)
const WBENCHSCREEN WBENCHSCREEN_f
const PUBLICSCREEN PUBLICSCREEN_f
const CUSTOMSCREEN CUSTOMSCREEN_f
const SCREENTYPE SCREENTYPE_f
const SHOWTITLE SHOTITLE_f
const BEEPING BEEPING_f
const CUSTOMBITMAP CUSTOMBITMAP_f
const SCREENBEHIND SCREENBEHIND_f
Retrieved from "http://fpcamigawiki.alb42.de/index.php?title=Specifics&oldid=880"