Amiga: what changed

Revision 3 to 4. 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	+	```text
62	62		struct Task is equal to TTask
63	63		struct Task * is equal to PTask
64	64		```
65	65
66	66		## Alignment
67	67
68	68		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]].
69	69
70	70		## Threading
71	71
72	72		Threading is supported on Amiga since Free Pascal 3.0, using the [[AThreads]] unit. Read there for possible caveats and unsupported features.
73	73
74	74		## Hooks
75	75
76	76		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.
77	77
78	78		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.
79	79
80	80		## Things good to know
81	81
82	82		Here are a few hints, which I think are good to remember, when using FPC on Amiga.
83	83
84	84		- 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.
85	85		- On program exit, System unit will close all files opened via its own functions, so it's recommended to use them in most cases.
86	86		- 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.
87	87		- 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).
88	88		- Do not mix FPC and OS memory functions on a pointer. It won't work and will only cause crashes and/or memory leaks.
89	89
90	90		## Linker
91	91
92	92		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).
93	93
94	94		You can change the linker back to GNU ld by adding -XV- argument when compiling. For cross compilers -XV argument enables vlink.
95	95
96	96		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.
97	97
98	98		## Assembler
99	99
100	100		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
101	101
102	102		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.
103	103
104	104		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.
105	105
106	106		#### Building vasm for FPC
107	107
108	108		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:
109	109
110	110		``` bash
111	111		make CPU=m68k SYNTAX=std
112	112		```
113	113
114	114		The resulting vasmm68k_std executable file is the assembler is the one FPC needs.
115	115
116	116		## Building
117	117
118	118		To build an Amiga cross-compiler, use the following steps:
119	119
120	120		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.
121	121		2. Check out FPC SVN trunk into a directory.
122	122		3. Make sure you have Amiga cross-binutils and/or vasm and vlink in the PATH.
123	123		4. Go to the trunk's main directory and use the following command to build an FPC cross-compiler:
124	124
125	125		``` bash
126	126		make clean crossall crossinstall OS_TARGET=amiga CPU_TARGET=m68k CROSSOPT="-Cp68020" INSTALL_PREFIX="<path/to/install>"
127	127		```
128	128
129	129		If you use vasm and vlink, the CROSSOPT option in the make line should additionally include the options "-Avasm -XV".
130	130
131	131		If your binutils has different prefix than m68k-amiga, you add the BINUTILSPREFIX parameter to the above command line, for example: BINUTILSPREFIX=m68k-amigaos-
132	132
133	133		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.
134	134
135	135		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:
136	136
137	137		``` bash
138	138		#IFDEF CPUM68K
139	139		-Fu<path/to/install>/lib/fpc/$fpcversion/units/$FPCTARGET
140	140		-Fu<path/to/install>/lib/fpc/$fpcversion/units/$FPCTARGET/*
141	141		#IFDEF AMIGA
142	142		-FD</path/to/amiga-cross-binutils>
143	143		#ENDIF
144	144		#ENDIF
145	145		```
146	146
147	147		Optionally also add an -XP parameter, to specify the correct prefix of your cross-binutils, for example: -XPm68k-amigaos-
148	148
149	149		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:
150	150
151	151		``` bash
152	152		ppcross68k -Tamiga <source.pas>
153	153		```
154	154
155	155		## See also
156	156
157	157		- [[List of Amiga software written in Free Pascal]]
158	158		- [[Amiga TagList]] - A proposal
159	159		- [[Amiga Legacy Support]] - special support for very old (1.2+/v33+) AmigaOS versions
160	160
161	161		## More information
162	162
163	163		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.
164	164
165	165		---
166	166		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).
167	167		Category: AmigaOS
168	168		Category: Operating Systems and Platforms

Back to history