FPC Version Switcher: what changed

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

Title: FPC Version Switcher

New		Line
1	+	## About
2	+
3	+	The FPC version switcher package integrates with the Lazarus IDE in order to allow easy switching of fpc versions.
4	+
5	+	<figure>
6	+	<img src="fpcversion.jpg" title="fpcversion.jpg" />
7	+	<figcaption>fpcversion.jpg</figcaption>
8	+	</figure>
9	+
10	+	## Background
11	+
12	+	### Actual compiler naming convention
13	+
14	+	The actual FPC compiler / cross-compiler is usually ppcxxx or ppcrossxxx where xxx denotes the cpu target.
15	+
16	+	For an i386 (32 bit) system:
17	+
18	+	- ppc386 is the actual compiler
19	+	- ppcrossx64 is the actual x86_64 cross compiler (produces 64 bit binaries)
20	+	- ppcrossarm is the actual arm cross compiler (produces arm binaries)
21	+
22	+	etc...
23	+
24	+	For an x86_64 (64 bit) system:
25	+
26	+	- ppcx64 is the actual compiler
27	+	- ppcross386 is the actual i386 cross compiler (produces 32 bit binaries)
28	+	- ppcrossarm is the actual arm cross compiler (produces arm binaries)
29	+
30	+	etc...
31	+
32	+	### The fpc frontend executable
33	+
34	+	Rather than letting one guess the actual compiler name for a certain target cpu and call it directly, FPC provides the fpc front end executable, which takes care of calling the right actual compiler for the required target cpu. To do that, 3 things are needed:
35	+
36	+	- The OS should be able to locate the fpc executable by either:
37	+	- adding the fpc executable path to the environment PATH variable (eg export PATH=/usr/bin;\$PATH) and just calling "fpc".
38	+	- providing a fully qualified path (eg /usr/bin/fpc).
39	+
40	+	- The fpc executable should be told what the target cpu is by using the -P\<target_cpu\> switch so that it can deduce by itself the actual compiler name.
41	+
42	+	- The fpc executable should be able to locate the actual compiler by either:
43	+	- adding the actual compiler (ppcxxx) path to the environment PATH variable (eg export PATH=/usr/lib/fpc;\$PATH)
44	+	- calling fpc with the -Xp\<ppcxxx_path\> switch to inform it about the location of the actual compiler (eg: fpc -Xp/usr/lib/fpc)
45	+
46	+	Some users opt to create in one folder symlinks with the fpc version suffixed (eg ppc386-3.1.1), and pointing to the actual compilers. The -V\<version\> switch lets the fpc executable append \<version\> to the actual compiler name (eg fpc -V3.1.1 on a 386 system will look for ppc386-3.1.1).
47	+
48	+	To sum up, calling fpc can take different forms:
49	+
50	+	- fpc -P\<cpu_target\>
51	+	- /usr/bin/fpc -Xp/usr/lib/fpc -P\<cpu_target\>
52	+	- /usr/bin/fpc -Xp/usr/lib/fpc -V3.1.1 -P\<cpu_target\>
53	+
54	+	etc...
55	+
56	+	### Checking fpc's mechanism
57	+
58	+	#### Processor name
59	+
60	+	The -PP switch just displays the processor name.
61	+
62	+	- On an i386 system (32 bit), the output of fpc -PP is i386
63	+	- On an x86_64 system (64 bit), the output of fpc -PP is x86_64
64	+
65	+	#### Actual compiler name name
66	+
67	+	The -PB switch will make fpc just display the actual compiler name for a target cpu.
68	+
69	+	On an i386 system (32 bit):
70	+
71	+	- fpc -PB will output ppc386 (default cpu target)
72	+	- fpc -Pi386 -PB will output ppc386
73	+	- fpc -Px86_64 -PB will output ppcrossx64
74	+	- fpc -Parm -PB will output ppcrossarm
75	+
76	+	etc...
77	+
78	+	On an x86_64 system (64 bit):
79	+
80	+	- fpc -PB will output ppcx64 (default cpu target)
81	+	- fpc -Px86_64 -PB will output ppcx64
82	+	- fpc -Pi386 -PB will output ppcross386
83	+	- fpc -Parm -PB will output ppcrossarm
84	+
85	+	etc...
86	+
87	+	One can even use it as follows:
88	+
89	+	\<path_to_fpc_bin\>/fpc -Xp\<\<path_to_fpc_lib\> -V\<fpc_version\> -P\<cpu_target\> -PB
90	+
91	+	### Compiler utilities
92	+
93	+	The actual compiler, once called, may need to locate some utilities. The path can be specified by either:
94	+
95	+	- Adding the compiler utilities path to the environment PATH variable (eg export PATH=/usr/local/bin/compiler_utilities;\$PATH)
96	+	- Adding the -FD\<compiler_utilities_path\> switch to fpc.cfg (eg: -FD/usr/local/bin/compiler_utilities)
97	+	- Calling fpc with the -FD\<compiler_utilities_path\> switch (eg: fpc -FD/usr/local/bin/compiler_utilities)
98	+
99	+	### Cross binutils
100	+
101	+	For cross compiling, the cross binutils (cross assembler, cross linker, ...) folder should be in the environment PATH variable.
102	+
103	+	## FPC Version Switcher
104	+
105	+	The FPC version switcher package allows tweaking all the above options and even providing a dropdown list in the IDE Tools/Options/Compiler Version in order to select the required fpc version, and set the \$(UseFPCVersion) macro accordingly.
106	+
107	+	Now, if the installations of the different fpc versions differ only by the version number (eg /usr/lib/fpc/2.6.4 and /usr/lib/fpc/3.1.1), then one can specify paths based on that macro (eg /usr/lib/fpc/\$(UseFPCVersion)). Moreover, any IDE macro other than \$(FPCVER) and that doesn't depend on it can be used in the paths (eg \$Env(HOME)/fpc/lib/\$(UseFPCVersion)).
108	+
109	+	### Pre-requisites
110	+
111	+	1. Having multiple fpc versions installed
112	+	2. Having a homogeneous directory structure (paths for different fpc versions should differ only by version number)
113	+	3. Modifying all paths in fpc.cfg to depend on FPC's \$FPCVERSION macro (where applicable)
114	+	4. Not having fpc related paths in the environment PATH variable (except as outlined in #Setting the fpc frontend executable path)
115	+	5. Having "fpc" as compiler executable in the IDE's Tools/Options/Files
116	+
117	+	### Installation
118	+
119	+	Open fpcversionswitcher.lpk in the lazarus/components/fpcversionswitcher folder, compile and install it and restart the IDE. A new frame will be available in Tools/Options/Compiler Version.
120	+
121	+	### FPC version selection
122	+
123	+	Enter or select the required FPC version using the dropdown list. This will set the \$(UseFPCVersion) macro accordingly. Note that this macro is different from the IDE's \$(FPCVER) macro.
124	+
125	+	### Setting the fpc frontend executable path
126	+
127	+	Enter or locate the absolute path of the fpc frontend executable. You can use \$(UseFPCVersion) and/or any IDE macro other than and doesn't depend on \$(FPCVER).
128	+
129	+	Select how the IDE should locate the fpc frontend:
130	+
131	+	- By adding the path to the environment PATH variable
132	+	- By calling the fpc executable with a fully qualified path
133	+	- By doing nothing and assuming that the path has been predefined in the environment PATH variable
134	+
135	+	### Setting the actual compiler executable path
136	+
137	+	Enter or locate the absolute path of the actual compiler executable. You can use \$(UseFPCVersion) and/or any IDE macro other than and doesn't depend on \$(FPCVER).
138	+
139	+	Select how the IDE should locate the actual compiler:
140	+
141	+	- By adding the path to the environment PATH variable
142	+	- By calling the fpc executable with the Xp switch and a fully qualified path
143	+
144	+	### Setting the compiler utilities path
145	+
146	+	Enter or locate the absolute path of the compiler utilities. You can use \$(UseFPCVersion) and any IDE macro other than and/or doesn't depend on \$(FPCVER).
147	+
148	+	Select how the IDE should locate the actual compiler:
149	+
150	+	- By adding the path to the environment PATH variable
151	+	- By calling the fpc executable with the FD switch and a fully qualified path
152	+	- By doing nothing and assuming that the FD switch is used in fpc.cfg
153	+
154	+	### Enabling the version suffix for the actual compiler
155	+
156	+	Check "ppc executable has suffix" if the actual compilers or symlinks pointing to them have the fpc version suffixed (eg ppc386-3.1.1)
157	+
158	+	### Mechanism
159	+
160	+	- FPC Version Switcher modifies the environment PATH variable for settings that require it to do so
161	+	- FPC Version Switcher passes to the IDE a prefix (the fpc frontend path or empty) which the IDE should prepend to "fpc"
162	+	- FPC Version Switcher passes to the IDE a suffix (the -Xp, -FD, and -V switches if any) which the IDE should append to "fpc"
163	+
164	+	### Verifying the settings
165	+
166	+	The check button will display:
167	+
168	+	- If the fpc frontend path should exist in the environment PATH variable before launching the IDE
169	+	- Which paths will be added to the environment PATH variable
170	+	- How the IDE should call the fpc frontend
171	+
172	+	### Usage
173	+
174	+	To change the fpc version, it is enough to go to Tools/Options/Compiler version and select the required FPC version. You can then compile your projects or the IDE with that version.
175	+
176	+	### Use cases with different fpc and ppc folders setups
177	+
178	+	For the sake of brevity, the fpc frontend executable folder and the actual compiler folder will be denoted as the bin and lib folders respectively,
179	+
180	+	#### Common bin folder and separate lib folders
181	+
182	+	- fpc executable path: /usr/local/bin
183	+	- ppcxxx executable path: /usr/local/lib/fpc/\$(UseFPCVersion)
184	+
185	+	#### Separate bin folders and separate lib folders
186	+
187	+	- fpc executable path: \$Env(HOME)/fpc/\$(UseFPCVersion)/bin
188	+	- ppcxxx executable path: \$Env(HOME)/fpc/\$(UseFPCVersion)/lib/fpc/\$(UseFPCVersion)
189	+
190	+	#### Common bin folder (fpc executable + ppcxxx-XYZ symlinks) and separate lib folders using symlinks /usr/local/bin/ppcxxx-\$(UseFPCVersion) -\> /usr/local/lib/fpc/\$(UseFPCVersion)/ppcxxx
191	+
192	+	- fpc executable path: /usr/local/bin
193	+	- ppcxxx executable path: /usr/local/bin
194	+	- ppc executable has suffix: Yes
195	+
196	+	### Known issues
197	+
198	+	This is a work in progress and therefore not all options are functional. What needs to be completed is the prefix/suffix link between FPC Version Switcher and the IDE. Therefore options that pass paths or switches to the IDE should not be used for now.
199	+
200	+	### Wishlist
201	+
202	+	- To have a dropdown button next to the Run button so that switching FPC versions is done without even going into Tools/Options
203	+	- To have separate FPC versions for projects and the IDE
204	+
205	+	---
206	+	From the Free Pascal wiki, page "FPC Version Switcher", as it stood on 2015-02-27 after a change by Stephano, 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).
207	+	Category: FPC
208	+	Category: IDE
209	+	Category: Lazarus
210	+	Category: Packages

Back to history