Amiga: what changed

Revision 1 to 2. Removed lines have a minus sign; added lines have a plus sign.

Old	New		Line
1	1		(Amiga only)
2	2
3	3		This page is about the so called 'classic Amiga' version of Free Pascal, which means [[m68k\|Motorola 680x0]] CPU based systems running AmigaOS 3.x and below. For [[MorphOS]], [[AROS]] and [[AmigaOS\|AmigaOS4]] versions, see the relevant pages.
4	4
5	5		Please note, that the information detailed here is specific to version Free Pascal 2.x and above, and does not* apply** to the old 0.99.x and 1.0.x versions of Free Pascal for Amiga, still available on various Amiga download sites.*
6	6
7	7		After a long break, [[m68k\|Motorola 68k]] CPU series and classic Amiga is supported again in Free Pascal 3.0. Please note that to successfully use the compiler natively, a very fast 68k system is required, at least expanded with a Motorola 68060 processor and 128MB of memory or more and a Hard Disk controller with DMA support, or an emulator with a fast JIT-compiler like [WinUAE](http://winuae.net), or a next-gen Amiga-compatible system. Large parts of the classic Amiga support was developed under [[MorphOS]]. Cross compiling from other architectures and operating systems is supported.
8	8
9	9		## Requirements
10	10
11	11		By default, Free Pascal and its runtime library requires AmigaOS 3.0 (v39+ or newer). If you want to target older systems, please see [[Amiga Legacy Support]].
12	12
13	13		## Identification
14	14
15	15		To identify classic Amiga exclusively during compile-time, use {\$IFDEF AMIGA68K}. To identify classic Amiga or [[AmigaOS\|AmigaOS4]], use {\$IFDEF AMIGA}. To identify any Amiga-like system including [[AROS]] and [[MorphOS]], 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 AMIGA68K is only available in Free Pascal 3.0.2 and up.
16	16
17	17		## Stack
18	18
19	19		Under Amiga, the default stack is set to 256 KiB. Stack size can be set directly by the programmer with a compiler switch (-Cs), or with the {\$MEMORY} directive. The memory area for the stack is dynamically allocated on program startup, so if you set this value too high, in low memory situations your program may exit immediately on startup without any further notice.
20	20
21	21		Please note that increasing stack size with the 'stack' utility *will NOT* work** for your app, because the RTL startup code will replace the existing stack with the size specified by the directive, using the exec.library/StackSwap function.
22	22
23	23		## SysCalls
24	24
25	25		### Introduction to SysCalls
26	26
27	27		Free Pascal supports generating Amiga-style library calls. You don't need to use additional hand-written assembly to call any library function. However, you must declare every function you're going to use in the following way:
28	28
29	29		``` pascal
30	30		Var
31	31		my_LibBase: Pointer;
32	32
33	33		function my_OldCall(param1: LongInt location 'd0',
34	34		param2: LongInt location 'd1'): LongInt;
35	35		SysCall my_LibBase 1234; { Amiga-style call }
36	36		```
37	37
38	38		Where my_LibBase is the library base returned by exec's OpenLibrary() call, and 1234 is the call offset. Please note that offset values in Free Pascal must be specified as positive values, and not negative as shown in the Amiga SDK. my_LibBase can be a typed pointer, a dword or a void pointer. It's recommended to use PLibrary or the library's own type if one exists or possible.
39	39
40	40		### Other hints about libraries and Syscalls
41	41
42	42		MOST IMPORTANT: While creating your own interface units for libraries, you must open the libraries you're going to use explicitly before using any function from them. Don't forget to close all libraries before you exit. The interface units bundled with the compiler will auto open and close the respective libraries (unless otherwise noted).
43	43
44	44		## Naming conventions
45	45
46	46		This section describes the differences between the official Amiga SDK, which is for C and assembly language, and Amiga-specific units in FPC RTL.
47	47
48	48		### Constants
49	49
50	50		System constants are named exactly like in Amiga SDK.
51	51
52	52		### Structures
53	53
54	54		System structures are named similar to those in the Amiga SDK, but follow the Pascal convention about type naming, so:
55	55
56	56		- structure names has a T before the name
57	57		- each type has a pointer to the type with P before the name.
58	58
59	59		The following example should make things trivial to understand:
60	60
61	61		` struct Task is equal to TTask`\
62	62		` struct Task * is equal to PTask`
63	63
64	64		## Alignment
65	65
66	66		Record elements are aligned to WORD (2 bytes) under Amiga by default. Use {\$PACKRECORDS 4} if you need DWORD aligned structures. For byte aligned records, you can use a packed record, however this is not recommended when targeting the plain 68000, which has [[m68k\|special alignment requirements]].
67	67
68	68		## Threading
69	69
70	70		Threading is supported on Amiga since Free Pascal 3.0, using the [[AThreads]] unit. Read there for possible caveats and unsupported features.
71	71
72	72		## Hooks
73	73
74	74		Hook functions passed to some Amiga API calls must be declared with the cdecl modifier to be future proof. This is because differences in calling convention between some versions of the Free Pascal Compiler and the operating system. More specifically, recent versions of Free Pascal Compiler use the register calling convention by default on [[m68k]], while Hooks are expected to use stdcall or cdecl.
75	75
76	76		If you still want to use a function with the register calling convention, use the HookEntryPas helper function instead of HookEntry in the AmigaLib unit.
77	77
78	78		## Things good to know
79	79
80	80		Here are a few hints, which I think are good to remember, when using FPC on Amiga.
81	81
82	82		- A filesystem which supports file name length above 30 characters is highly recommended. Lack of it may cause unexpected results or compilation failures, especially in case of large projects like the compiler itself.
83	83		- On program exit, System unit will close all files opened via its own functions, so it's recommended to use them in most cases.
84	84		- 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.
85	85		- 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, unless you explicitly require memory areas which should stay in memory after your process has exited (like pointers passed to other processes).
86	86		- Do not mix FPC and OS memory functions on a pointer. It won't work and will only cause crashes and/or memory leaks.
87	87
88	88		## Linker
89	89
90	90		Some versions of Free Pascal on Amiga, including latest SVN trunk versions default to vlink by Frank Wille as the default linker, when running natively on Amiga. The cross-compilers still default to GNU ld. vlink is open source, and it is available [here](http://sun.hasenbraten.de/vlink). Binaries are available as part of the [vbcc compiler package](http://sun.hasenbraten.de/vbcc).
91	91
92	92		You can change the linker back to GNU ld by adding -XV- argument when compiling. For cross compilers -XV argument enables vlink.
93	93
94	94		Please make sure you use vlink version 0.16 or newer with Free Pascal on Amiga. Earlier versions might have issues when used with Free Pascal or might not have features the compiler now requires.
95	95
96	96		## Assembler
97	97
98	98		The Amiga 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. Please also note that linking vasm generated object files with GNU ld is not supported, as vasm outputs objects in ELF format, while GNU LD for Amiga only supports aout objects. This means using vasm with FPC, requires vlink as linker
99	99
100	100		vasm is open source, and it is available [here](http://sun.hasenbraten.de/vasm). Binaries are available as part of the [vbcc compiler package](http://sun.hasenbraten.de/vbcc). Only vasm versions 1.7h and newer were tested, older versions might not work.
101	101
102		-	<span style="color:red">WARNING: vasm versions between 1.9a and 1.9c - these versions inclusive - contain a bug, which makes it impossible to use these versions with Free Pascal on any [[m68k]] platform. Please stick to vasm versions 1.8 (any letter), 1.9 (no letter) or 1.9d, or newer.</span>
	102	+	WARNING: vasm versions between 1.9a and 1.9c - these versions inclusive - contain a bug, which makes it impossible to use these versions with Free Pascal on any [[m68k]] platform. Please stick to vasm versions 1.8 (any letter), 1.9 (no letter) or 1.9d, or newer.
103	103
104	104		#### Building vasm for FPC
105	105
106	106		Note that vasm for m68k needs to be built with the standard syntax module to work with FPC. This is not the default, as most coders and compilers (like vbcc itself) prefer the Motorola syntax module. A vasm version with the standard syntax module can be built with the following command, issued in the root of the vasm source tree:
107	107
108	108		``` bash
109	109		make CPU=m68k SYNTAX=std
110	110		```
111	111
112	112		The resulting vasmm68k_std executable file is the assembler is the one FPC needs.
113	113
114	114		## Building
115	115
116	116		To build an Amiga cross-compiler, use the following steps:
117	117
118	118		1. Install the latest stable FPC version for your host platform, at the time of the writing of this article this is FPC 3.0.2. This will be used as the startup compiler.
119	119		2. Check out FPC SVN trunk into a directory.
120	120		3. Make sure you have Amiga cross-binutils and/or vasm and vlink in the PATH.
121	121		4. Go to the trunk's main directory and use the following command to build an FPC cross-compiler:
122	122
123	123		``` bash
124	124		make clean crossall crossinstall OS_TARGET=amiga CPU_TARGET=m68k CROSSOPT="-Cp68020" INSTALL_PREFIX="<path/to/install>"
125	125		```
126	126
127	127		If you use vasm and vlink, the CROSSOPT option in the make line should additionally include the options "-Avasm -XV".
128	128
129	129		If your binutils has different prefix than m68k-amiga, you add the BINUTILSPREFIX parameter to the above command line, for example: BINUTILSPREFIX=m68k-amigaos-
130	130
131	131		If you've done everything right, you should find a working Amiga cross-compiler with all the prebuilt RTL and Packages units in the install path you've specified.
132	132
133	133		Now, lets create a default fpc.cfg for Amiga 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:
134	134
135	135		``` bash
136	136		#IFDEF CPUM68K
137	137		-Fu<path/to/install>/lib/fpc/$fpcversion/units/$FPCTARGET
138	138		-Fu<path/to/install>/lib/fpc/$fpcversion/units/$FPCTARGET/*
139	139		#IFDEF AMIGA
140	140		-FD</path/to/amiga-cross-binutils>
141	141		#ENDIF
142	142		#ENDIF
143	143		```
144	144
145	145		Optionally also add an -XP parameter, to specify the correct prefix of your cross-binutils, for example: -XPm68k-amigaos-
146	146
147	147		Optionally add \<path/to/install\>/lib/fpc/3.3.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 Amiga executables:
148	148
149	149		``` bash
150	150		ppcross68k -Tamiga <source.pas>
151	151		```
152	152
153	153		## See also
154	154
155	155		- [[List of Amiga software written in Free Pascal]]
156	156		- [[Amiga TagList]] - A proposal
157	157		- [[Amiga Legacy Support]] - special support for very old (1.2+/v33+) AmigaOS versions
158	158
159	159		## More information
160	160
161	161		More information regarding Free Pascal and Amiga can be read on the [Free Pascal 4 Amiga wiki](http://fpcamigawiki.alb42.de). This wiki also contains links to (unofficial) nightly downloads and other (additional) information for Amiga.
162	162
163	163		---
164	164		From the Free Pascal wiki, page "Amiga", as it stood on 2023-04-23 after a change by Chain-Q, out of the wiki's dump of 2024-05-26. Copyright stays with the author who wrote it, according to the old wiki's [[Licensing]] page. If you have concerns about this material, [message the admin](/wiki-contact).
165	165		Category: AmigaOS
166	166		Category: Operating Systems and Platforms

Back to history