FPMake: what changed

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

Old	New		Line
1	1		FPMake is a build-system for Pascal code specifically. It can be compared with other build systems like Make, cons, scons, etc.
2	2
3	3		With FPMake the code is split up into packages. A FPMake-package can contain units, binaries, examples and documentation. Each package can depend on other packages, in which case a package can use the units of it's dependences. FPMake uses two different locations to search for packages, a system-wide (global) and a local location. By default the global location points to the location of the fpc-installation, while the local location is user-specific.
4	4
5	5		Some parts of fpc itself are compiled using FPMake. (The packages fastcgi and fcl-web in fpc 2.6 and all packages, utilities and the ide in fpc 2.7 and up)
6	6
7	7		The packages-manager [[fppkg]] can be used to manage the FPMake packages and to install them from a remote repository.
8	8
9	9		## How does it work
10	10
11	11		FPMake works with Pascal-applications called fpmake, of which each can compile and install one or more FPMake-packages. All settings, location of the sources and instructions are defined inside the source of this fpmake-executable. This source-file is normally saved with the name fpmake.pp. The fpmake.pp is compiled into the fpmake-executable, and this executable can build and install the final packages.
12	12
13	13		## Building FPMake packages
14	14
15	15		The easiest is to use [[fppkg]] to build a FPMake package. But it can also be done manually. Locate the sources of the package you want to install and the fpmake.pp file. Now compile the fpmake.pp file:
16	16
17		-	~~`fpc fpmake.pp`~~
	17	+	```text
	18	+	fpc fpmake.pp
	19	+	```
18	20
19	21		Typical output looks like:
20	22
21		-	~~`Free Pascal Compiler version 2.7.1 [2014/11/26] for i386`\~~
22		-	~~`Copyright (c) 1993-2014 by Florian Klaempfl and others`\~~
23		-	~~`Target OS: Darwin for i386`\~~
24		-	~~`Compiling fpmake.pp`\~~
25		-	~~`Assembling (pipe) fpmake.s`\~~
26		-	~~`Linking fpmake`\~~
27		-	~~`203 lines compiled, 3.6 sec`~~
	23	+	```text
	24	+	Free Pascal Compiler version 2.7.1 [2014/11/26] for i386
	25	+	Copyright (c) 1993-2014 by Florian Klaempfl and others
	26	+	Target OS: Darwin for i386
	27	+	Compiling fpmake.pp
	28	+	Assembling (pipe) fpmake.s
	29	+	Linking fpmake
	30	+	203 lines compiled, 3.6 sec
	31	+	```
28	32
29	33		Now run the new fpmake(.exe)-executable to build the package(s). This example only contains one package.
30	34
31	35		On unices or alike:
32	36
33		-	~~`./fpmake build --globalunitdir=/usr/local/lib/fpc/2.7.1`~~
	37	+	```text
	38	+	./fpmake build --globalunitdir=/usr/local/lib/fpc/2.7.1
	39	+	```
34	40
35	41		On Windows or alike:
36	42
37		-	~~`fpmake.exe build --globalunitdir=c:\pp`~~
	43	+	```text
	44	+	fpmake.exe build --globalunitdir=c:\pp
	45	+	```
38	46
39	47		Typical output looks like:
40	48
41		-	~~`Start compiling package fcl-base for target i386-darwin.`\~~
42		-	~~` Compiling src/ascii85.pp`\~~
43		-	~~` Compiling src/avl_tree.pp`\~~
44		-	~~` Compiling src/base64.pp`\~~
45		-	~~` Compiling src/fpmimetypes.pp`\~~
46		-	~~`[100%] Compiled package fcl-base`~~
	49	+	```text
	50	+	Start compiling package fcl-base for target i386-darwin.
	51	+	Compiling src/ascii85.pp
	52	+	Compiling src/avl_tree.pp
	53	+	Compiling src/base64.pp
	54	+	Compiling src/fpmimetypes.pp
	55	+	[100%] Compiled package fcl-base
	56	+	```
47	57
48	58		The --globalunitdir parameter gives the location of the already installed global packages. This way FPMake can find the packages that this package depends on. When there is a second location where packages are installed, in addition the --localunitdir parameter can be used.
49	59
50	60		If you want to know which path you have to use for the --global(local)unitdir parameter, it's the directory which contains a directory called 'fpmkinst'.
51	61
52	62		To remove all files generated during the build and to be able to do a 'clean' build, perform a clean.
53	63
54	64		On unices or alike:
55	65
56		-	~~`./fpmake clean`~~
	66	+	```text
	67	+	./fpmake clean
	68	+	```
57	69
58	70		On Windows or alike:
59	71
60		-	~~`fpmake.exe clean`~~
	72	+	```text
	73	+	fpmake.exe clean
	74	+	```
61	75
62	76		Use the -h parameter to get an overview of all other available commands and options.
63	77
64	78		## Installing FPMake packages
65	79
66	80		Just like building packages, using [[fppkg]] to install FPMake packages is the easiest. But it canbe done manually. First compile the package and then call the fpmake executable to install the package.
67	81
68	82		On unices or alike:
69	83
70		-	~~`./fpmake install --globalunitdir=/usr/local/lib/fpc/2.7.1 --prefix=/usr/local --baseinstalldir=/usr/local/lib/fpc/2.7.1`~~
	84	+	```text
	85	+	./fpmake install --globalunitdir=/usr/local/lib/fpc/2.7.1 --prefix=/usr/local --baseinstalldir=/usr/local/lib/fpc/2.7.1
	86	+	```
71	87
72	88		On Windows or alike:
73	89
74		-	~~`fpmake.exe install --globalunitdir=c:\pp --prefix=c:\pp --baseinstalldir=c:\pp`~~
	90	+	```text
	91	+	fpmake.exe install --globalunitdir=c:\pp --prefix=c:\pp --baseinstalldir=c:\pp
	92	+	```
75	93
76	94		Typical output looks like:
77	95
78		-	~~`Installing package fcl-base`\~~
79		-	~~`Installation package fcl-base for target i386-darwin succeeded`~~
	96	+	```text
	97	+	Installing package fcl-base
	98	+	Installation package fcl-base for target i386-darwin succeeded
	99	+	```
80	100
81	101		The globalunitdir contains the location where to look for packages that the FPMake package can depend on, just like when building the package. The baseinstalldir is the location where the package should be installed to. In general this is the same path as is used for the global- or local-unitdir. Some packages also installs files outside of the baseinstalldir. like configuration files. These packages most often also need a prefix, so providing one is advisable.
82	102
83	103		## How to create FPMake-packages
84	104
85	105		### Simple example fpmake.pp
86	106
87	107		``` pascal
88	108		program fpmake;
89	109
90	110		uses fpmkunit;
91	111
92	112		Var
93	113		P: TPackage;
94	114		T: TTarget;
95	115
96	116		begin
97	117		With Installer do
98	118		begin
99	119		P := AddPackage('my-nice-program');
100	120		P.OSes := [win32,openbsd,netbsd,freebsd,darwin,linux];
101	121		T := P.Targets.AddUnit('myunit');
102	122		T.ResourceStrings := True;
103	123		T := P.Targets.AddUnit('myprogram');
104	124		T.Dependencies.Add('myunit');
105	125		Run;
106	126		end;
107	127		end.
108	128		```
109	129
110	130		### More complex example fpmake.pp
111	131
112	132		``` pascal
113	133		program fpmake;
114	134
115	135		uses fpmkunit;
116	136
117	137		type TWidgetSet = (wsGDI, wsX, wsCarbon);
118	138
119	139		var WidgetSet : TWidgetSet;
120	140		P : TPackage;
121	141
122	142		procedure DetermineWidgetSet;
123	143		Var
124	144		I : Integer;
125	145		begin
126	146		if Defaults.OS in AllWindowsOSes then
127	147		WidgetSet := wsGDI else
128	148		if Defaults.OS = MacOS then
129	149		WidgetSet := wsCarbon else
130	150		if Defaults.OS in AllUnixOSes then
131	151		Widgetset := wsX;
132	152
133	153		// Check paramstr() to see if the widgetset was overriden on the commandline;
134	154		For I := 1 to ParamCount do
135	155		If ParamStr(i) = '--widgetset=X' then
136	156		WidgetSet := wsX;
137	157		end;
138	158
139	159		begin
140	160		DetermineWidgetSet;
141	161		With Installer do
142	162		begin
143	163		// ...
144	164		Case WidgetSet of
145	165		wsGDI : P.UnitPath.Add('corelib/gdi');
146	166		wsX : P.UnitPath.Add('corelib/x11');
147	167		// etc.
148	168		end;
149	169		// ...
150	170		Run;
151	171		end;
152	172		end.
153	173		```
154	174
155	175		### Changing Working Directory
156	176
157	177		If working with units in a subfolder relative to ./fpmake, then "Directory" can be changed.
158	178
159	179		``` pascal
160	180		With Installer do
161	181		begin
162	182		...
163	183		Directory:='some/subdir';
164	184		T:= Targets.AddUnit('unitinfolder');
165	185		...
166	186		end;
167	187		```
168	188
169	189		### Adding directories
170	190
171	191		You can add directories with the unit path:
172	192
173	193		``` pascal
174	194		Case Defaults.OS of
175	195		Win32, Win64:
176	196		begin
177	197		T.UnitPath.Add('corelib/gdi');
178	198		T.Dependencies.Add('gfx_gdi');
179	199		end;
180	200		Linux:
181	201		begin
182	202		T.UnitPath.Add('corelib/x11');
183	203		T.Dependencies.Add('gfx_x11');
184	204		end;
185	205		end;
186	206		```
187	207
188	208		Often, it's more comfortable to use set constants like AllWindowsOSes, AllUnixOSes instead of specific OS names.
189	209
190	210		### Appending Compiler Options
191	211
192	212		Additional custom compiler options (i.e. compiler command line parameters) can be appended by using TTarget.Options, TPackage.Options, or Defaults.Options.
193	213
194	214		``` pascal
195	215		var T : TTarget;
196	216		...
197	217		T.Options.Append('-dSOMEDEFINE');
198	218		T.Options.Append('-xyzAnythingYouNeed');
199	219		```
200	220
201	221		Or
202	222
203	223		``` pascal
204	224		var P : TPackage;
205	225		...
206	226		P.Options.Append('-dSOMEDEFINE');
207	227		```
208	228
209	229		Or
210	230
211	231		``` pascal
212	232		Defaults.Options.Append('-dSOMEDEFINE');
213	233		```
214	234
215	235		Note: Before FPC 2.4.0, Options property was a simple string, and it seems it supported passing only one parameter to the compiler. Since FPC 2.4.0 (more precisely, since svn revision 13223) Options is a TStrings instance, so it's much more flexible. This also means that you should use \$ifdefs if you want to use Options and want your fpmake.pp be compatible with both FPC \< 2.4.0 and \>= 2.4.0.
216	236
217	237		## Common error messages
218	238
219	239		A few common error messages are explained here
220	240
221	241		### Unknown target for unit "\[unitname\]" in dependencies for \[targetname\] in package \[packagename\]
222	242
223	243		This indicates a problem in the fpmake.pp file. There is a dependency on a unit, added using Target.Dependencies.AddUnit('unitname'). But there is no corresponding target added to the package with the same unitname.
224	244
225	245		In other words: for every dependency on a unit, there must be a corresponding target within the same package. When there is a dependency on a unit in another package, add a dependency on that package. A dependency on a single file within a different package will not work.
226	246
227	247		Also note that the unit name has to be without the extension of the corresponding file. (Target.Dependencies.AddUnit('unitnams.pas') will not work, while Targets.Addunit requires the extension to be present)
228	248
229	249		### Could not find unit directory for dependency package "rtl"
230	250
231	251		In general the fpmake system scans the places typically used for fpc installations. In the case that fpmake doesn't find the FPC directory, you'll get the above mentioned error. In such case, set the FPCDIR environment variable to the base dir of the FPC installation, e.g.:
232	252
233		-	~~` export FPCDIR=~/src/lib/fpc/2.6.4`~~
	253	+	```text
	254	+	export FPCDIR=~/src/lib/fpc/2.6.4
	255	+	```
234	256
235	257		or
236	258
237		-	~~` set FPCDIR=C:\lazarus\fpc\2.6.4\`~~
	259	+	```text
	260	+	set FPCDIR=C:\lazarus\fpc\2.6.4\
	261	+	```
238	262
239	263		This can also be useful if you have to disambiguate over multiple FPC installations.
240	264
241	265		---
242	266		From the Free Pascal wiki, page "FPMake", as it stood on 2020-02-16 after a change by Trev, 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).

Back to history