Creating bindings for C libraries: what changed

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

Old	New		Line
1	1		# Introduction
2	2
3	3		This page describes how to create Pascal bindings for C libraries. In order to use C libraries in Pascal, you have to create a pascal translation for every C function, type and variable. To do that one can either utilized an automated tool, like h2pas or do a manual headers conversion
4	4
5	5		# H2PAS
6	6
7	7		## Overview
8	8
9	9		The [[H2Pas]] tool that automatically translates many common C things. A GUI for Lazarus using h2pas and other tools additionally automates the creation. It helps to create a rule set, which can be used to update the bindings. So the next version of the c library can be converted far more easier. A nice feature of the h2pas wizard is that it uses temporary files, so the c header files remain unchanged.
10	10
11	11		## Work flow
12	12
13	13		- Fetch the C header files you want to translate.
14	14		- Create a working directory and give your bindings a name
15	15		- Create a new h2pas project with the h2pas wizard.
16	16		- Add the .h files to the project.
17	17		- Setup the h2pas options.
18	18		- Run the wizard.
19	19		- Fix errors by adding text tools and run the wizard again.
20	20		- When h2pas runs without errors, test compilation and add optional tools to beautify the output.
21	21		- Write some test programs to test your bindings.
22	22		- Publish your bindings on lazarus-ccr or the FreePascal website.
23	23
24	24		## Install tools
25	25
26	26		The h2pas tool comes with every normal fpc installation.
27	27
28	28		Install the h2paswizard package in the Lazarus IDE. Go to "Package-\>Install/Uninstall Packages", select from the right list the H2PasWizard package and click 'Install selection', then 'Save and rebuild IDE'. Restart the IDE and you get a new menu entry: Tools -\> h2pas
29	29
30	30		## Fetch C header files
31	31
32	32		The C header files .h describes the interface of a C library. They are normally not provided with the library. You have to get the sources or the development package of the library. For example the C header files of the gtk libraries are in the package gtk+-devel.
33	33
34	34		### Example: MPICH2
35	35
36	36		Download the mpich2-1.0.3.tar.gz from <http://www-unix.mcs.anl.gov/mpi/mpich2/> and unpack them. The .h files are under mpich2-1.0.3/src/include.
37	37
38	38		You can find more information about MPICH for FPC [[MPICH\|here]].
39	39
40	40		## Create a working directory and name your bindings
41	41
42	42		Create a directory with a useful name. A name should not contain special characters, like spaces, umlaute, points or commas. Copy the .h files.
43	43
44	44		### Example: MPICH2
45	45
46	46		The h2p directory will be used for the pascal files. The h2p/c_sources directory will be used for the .h files.
47	47
48	48		``` bash
49	49		mkdir -p h2p/c_sources
50	50		cp mpich2-1.0.3/src/include/*.h h2p/c_sources/
51	51		```
52	52
53	53		## Create a new h2pas project with the h2pas wizard
54	54
55	55		Open the h2pas wizard: "Tools -\> h2pas". This will open a window. You can switch between this window and the other IDE windows. Your last h2pas project will be loaded automatically. To create a new project click on "Settings -\> New/Clear settings". Then click on the bottom button "Save settings" and choose a filename.
56	56
57	57		Note: If this is the first time you have used the h2pas wizard, you need to use the wizard's "Settings" tab to tell the wizard where to find the h2pas.exe converter program. The h2pas.exe converter lives in the same directory as the FreePascal compiler fpc.exe - if you downloaded FPC as part of Lazarus it will be in ...\Lazarus\fpc\version\bin. Then save the settings so you don't have to do this again.
58	58
59	59		### Example: MPICH2
60	60
61	61		Click on "Settings -\> New/Clear settings". Then click on the bottom button "Save settings" and save it as h2p/mpi2.h2p.
62	62
63	63		## Add the .h files to the h2pas-project
64	64
65	65		In the "C header files" page you can add/delete the .h files. You can enable/disable .h files to convert only part of the files.
66	66
67	67		### Example: MPICH2
68	68
69	69		Click on "C header files -\> Add .h files ..." and select "mpi.h" and "mpio.h". They will be enabled automatically. Select the mpi.h file and click "Merge all but this", so that the wizard combines all header files into one unit (mpi.pas).
70	70
71	71		## Setup the h2pas options
72	72
73	73		Under "h2pas Options" you can set the parameters for the h2pas program.
74	74
75	75		### Example: MPICH2
76	76
77	77		- Enable -e, -D, -p, -w and disable all others.
78	78		- The -l library path is "mpich".
79	79		- Output extension is ".pas"
80	80		- Output directory is h2pas/, which is the default, so leave it empty
81	81
82	82		## Run the wizard
83	83
84	84		Click on the bottom button "Run h2pas". This will copy the \<example\>.h file to a temporary \<example\>.tmp.h file and run the tools listed under "Before h2pas". Then it runs h2pas to convert the \<example\>.tmp.h into \<example\>.inc or \<example\>.pas or whatever output extension you setup on the h2pas page. Then it runs the tools listed under "After h2pas" on the output files.
85	85
86	86		If h2pas finds a syntax error, the IDE will open the example.tmp.h file and jumps to the error line. h2pas often only reports 'syntax error', which is very unspecific. See [[Common problems when converting C header files]].
87	87
88	88		### Example: MPICH2
89	89
90	90		The h2pas wizard already contains all tools to convert all the specials of this header file, so h2pas runs without errors. But the created unit is not yet ready. Read further.
91	91
92	92		Go to the After H2Pas tab and add the Reduce compiler directives in pascal file tool.
93	93
94	94		Add the following to the Undefines property:
95	95
96		-	~~` MPI_INCLUDED`\~~
97		-	~~` MPIO_INCLUDE`\~~
98		-	~~` NEEDS_MPI_FINT`\~~
99		-	~~` MPI_BUILD_PROFILING`\~~
100		-	~~` MPICH_SUPPRESS_PROTOTYPES`\~~
101		-	~~` MPI_Wtime`\~~
102		-	~~` HAVE_MPICH2G2`\~~
103		-	~~` FOO`\~~
104		-	~~` HAVE_PRAGMA_HP_SEC_DEF`~~
	96	+	```text
	97	+	MPI_INCLUDED
	98	+	MPIO_INCLUDE
	99	+	NEEDS_MPI_FINT
	100	+	MPI_BUILD_PROFILING
	101	+	MPICH_SUPPRESS_PROTOTYPES
	102	+	MPI_Wtime
	103	+	HAVE_MPICH2G2
	104	+	FOO
	105	+	HAVE_PRAGMA_HP_SEC_DEF
	106	+	```
105	107
106	108		Add the following to the Defines property:
107	109
108		-	~~` MPICH2`\~~
109		-	~~` MPICH_NEW_MPIIO`~~
	110	+	```text
	111	+	MPICH2
	112	+	MPICH_NEW_MPIIO
	113	+	```
110	114
111	115		## Writing your own converter tools
112	116
113	117		### Using the tool "Search and replace"
114	118
115	119		Many things like renaming a variable can be done by the Search and replace tool. Add the tool via the Add new tool button on either the 'Before h2pas' or the 'After h2pas' page. Then set the SearchFor, ReplaceWith, Options and Caption property.
116	120
117	121		#### Option: trtRegExpr
118	122
119	123		If you set this option to True, it means that you want to use [[IDE regular expressions\|regular expressions]]. This allows for plenty of possibilities to adapt and/or beautify the source code by metacharacters and quantifiers. A list of the metacharacters and quantifiers and examples are found in this article: [[IDE regular expressions]].
120	124
121	125		### Example: rename an identifier Tguint to guint
122	126
123	127		\| Property \| Value \|
124	128		\|-------------\|-------------------------------\|
125	129		\| Caption \| Rename Tguint to guint \|
126	130		\| SearchFor \| Tguint \|
127	131		\| ReplaceWith \| guint \|
128	132		\| Options \| \[trtMatchCase,trtWholeWord\] \|
129	133
130	134		### Example: rename several identifiers
131	135
132	136		Rename Tguint to guint, Tgulong to gulong, Tgint to gint:
133	137
134	138		Property
135	139
136	140		Value
137	141
138	142		Caption
139	143
140	144		Rename Tguint to guint
141	145
142	146		SearchFor
143	147
144	148		T(guint\|gint\|gulong)
145	149
146	150		ReplaceWith
147	151
148	152		\$1
149	153
150	154		Options
151	155
152	156		\[trtMatchCase,trtWholeWord,trtRegExpr\]
153	157
154	158		### Example: MPICH2
155	159
156	160		#### Removing Makro MPI_DUP_FN
157	161
158	162		The MPI_DUP_FN is defined two times in the mpi C headers. Once as a macro to something that does not exist, and later to a real function. So, the first should be deleted.
159	163
160	164		Add a 'Search and replace' tool to the before H2Pas tools (at the end) with the following settings:
161	165
162	166		Property
163	167
164	168		Value
165	169
166	170		Caption
167	171
168	172		Remove dummy define MPI_DUP_FN
169	173
170	174		Name
171	175
172	176		RemoveDummyDefineMPI_DUP_FN
173	177
174	178		SearchFor
175	179
176	180		^#define\s+MPI_DUP_FN\s+MPIR_Dup_fn
177	181
178	182		ReplaceWith
179	183
180	184		Options
181	185
182	186		\[trtMatchCase,trtRegExpr\]
183	187
184	188		#### Removing typecasts to MPI_DUP_FN
185	189
186	190		Add a 'Search and replace' tool to the before H2Pas tools (at the end) with the following settings:
187	191
188	192		Property
189	193
190	194		Value
191	195
192	196		Caption
193	197
194	198		Remove MPI_DUP_FN Makros
195	199
196	200		Name
197	201
198	202		Remove_MPI_DUP_Func
199	203
200	204		SearchFor
201	205
202	206		^#define .MPI_DUP_FN\).$
203	207
204	208		ReplaceWith
205	209
206	210		Options
207	211
208	212		\[trtMatchCase,trtRegExpr\]
209	213
210	214		#### Removing functions MPIO_Test, PMPIO_Test, MPIO_Wait and PMPIO_Wait
211	215
212	216		The MPIO_Test, PMPIO_Test, MPIO_Wait and PMPIO_Wait functions are defined twice and redefined via macro. So, the functions can be removed:
213	217
214	218		Add a 'Search and replace' tool to the before H2Pas tools (at the end) with the following settings:
215	219
216	220		Property
217	221
218	222		Value
219	223
220	224		Caption
221	225
222	226		Remove Func P?MPIO_(Test\|Wait)
223	227
224	228		Name
225	229
226	230		RemoveFuncP_MPIO_Test_Wait
227	231
228	232		SearchFor
229	233
230	234		^int P?MPIO_(Test\|Wait).*$
231	235
232	236		ReplaceWith
233	237
234	238		Options
235	239
236	240		\[trtMatchCase,trtRegExpr\]
237	241
238	242		## Improving an existing tool
239	243
240	244		You found a bug and want to fix it or you want to extend one of the above tools. Great!
241	245
242	246		Most of the above tools are defined in the h2pasconvert unit, which is part of the h2paswizard package. Basically a tool needs a classname, a description and an Execute method. To test/debug a tool outside the IDE and save a lot of compilation time, see the project components/simpleideintf/examples/testh2pastool.lpi. Compile it and start it on a console/terminal with the filename of a .h file as first command parameter. For example:
243	247
244	248		``` bash
245	249		./testh2pastool files/h2pastest.pas
246	250		```
247	251
248	252		## Writing a custom tool
249	253
250	254		You can write your own conversion tools and register them in the IDE easily. Start a package and a add a new unit (say unit1) for your new class. See the existing tools as example and read the prior section. When you wrote a new tool and tested it with the above simpleideintf project, then register it in the IDE: Add a register procedure to your unit (unit1), like the following (pseudo code):
251	255
252	256		``` pascal
253	257		uses
254	258		Classes, ..., IDETextConverter;
255	259
256	260		type
257	261		TYourToolClass = class(TCustomTextConverterTool)
258	262		public
259	263		class function ClassDescription: string; override;
260	264		function Execute(aText: TIDETextConverter): TModalResult; override;
261	265		end;
262	266
263	267		procedure Register;
264	268
265	269		implementation
266	270
267	271		procedure Register;
268	272		begin
269	273		TextConverterToolClasses.RegisterClass(TYourToolClass);
270	274		end;
271	275		```
272	276
273	277		Do not forget to enable the register checkbox of the unit in the package editor, otherwise the Register procedure will not be called by the IDE. Then install your package in the IDE.
274	278
275	279		## Future work / Missing stuff
276	280
277	281		- A tool to convert static linked procedures to dynamic linked procedure variables
278	282		- A tool to fix functions without parameter names by searching the .c files. This could also add a comment, in which c file it found the function.
279	283		- Find missing identifiers and let the user check which one to comment or replace with base types.
280	284		- Create a list of macro functions, which were half translated.
281	285
282	286		C:
283	287
284	288		``` c
285	289		typedef struct page
286	290		{
287	291		u32int present : 1; // Page present in memory
288	292		u32int rw : 1; // Read-only if clear, readwrite if set
289	293		u32int user : 1; // Supervisor level only if clear
290	294		u32int accessed : 1; // Has the page been accessed since last refresh?
291	295		u32int dirty : 1; // Has the page been written to since last refresh?
292	296		u32int unused : 7; // Amalgamation of unused and reserved bits
293	297		u32int frame : 20; // Frame address (shifted right 12 bits)
294	298		} page_t;
295	299		```
296	300
297	301		Pascal:
298	302
299	303		``` pascal
300	304		type
301	305		Unsigned_7 = 0 .. (1 shl 7) - 1;
302	306		Unsigned_20 = 0 .. (1 shl 20) - 1;
303	307
304	308		type
305	309		page_t = bitpacked record
306	310		present : boolean;
307	311		rw : boolean;
308	312		user : boolean;
309	313		accessed : boolean;
310	314		dirty : boolean;
311	315		unused : Unsigned_7;
312	316		frame : Unsigned_20;
313	317		end;
314	318		```
315	319
316	320		# Convert C to Pascal with lua script
317	321
318	322		I'm impressed by the power of the lua scripting language and how easy it is to do funny things with it.
319	323
320	324		``` lua
321	325		--
322	326		-- Please send any improvement to mingodadATgmailDOTcom.
323	327		--
324	328
325	329		inFileName = arg[1] or 'g:\\tmp\\plua\\clua\\lvm.c'
326	330
327	331		fh = assert(io.open(inFileName))
328	332		cbody = fh:read('*a')
329	333		fh:close()
330	334
331	335		pasbody = cbody
332	336
333	337		function split(str, pat)
334	338		local t = {} -- NOTE: use {n = 0} in Lua-5.0
335	339		local fpat = '(.-)' .. pat
336	340		local last_end = 1
337	341		local s, e, cap = str:find(fpat, 1)
338	342		while s do
339	343		if s ~= 1 or cap ~= '' then
340	344		table.insert(t, cap)
341	345		end
342	346		last_end = e+1
343	347		s, e, cap = str:find(fpat, last_end)
344	348		end
345	349		if last_end <= #str then
346	350		cap = str:sub(last_end)
347	351		table.insert(t, cap)
348	352		end
349	353		return t
350	354		end
351	355
352	356		function trim(s)
353	357		-- from PiL2 20.4
354	358		return (s:gsub('^%s(.-)%s$', '%1'))
355	359		end
356	360
357	361		function trimChars(str, c1, c2)
358	362		return str:gsub('^%' .. c1 .. '(.-)%' .. c2 .. '$', '%1')
359	363		end
360	364
361	365		function getPascalType(cType)
362	366		if cType == 'void' then
363	367		return 'pointer'
364	368		elseif cType == 'int' then
365	369		return 'integer'
366	370		elseif cType == 'short' then
367	371		return 'Shortint'
368	372		elseif cType == 'define' then
369	373		return 'is_define'
370	374		else
371	375		return cType
372	376		end
373	377		end
374	378
375	379		--check var name and type
376	380		--if var starts with a capital letter
377	381		-- add 'T' informt of it
378	382		--if var is preceded by * then add a 'P' for type
379	383
380	384		function checkVarType(aType, aVar)
381	385		aType = getPascalType(aType)
382	386		aType = aType:gsub('^(%u)', 'T%1')
383	387		aVar = aVar:gsub('^(%*)', function(m)
384	388		aType = 'P' .. aType
385	389		return ''
386	390		end)
387	391		aVar = aVar:gsub('(%[[^]]+%])', function(m)
388	392		aType = 'array' .. m .. ' of ' .. aType
389	393		return ''
390	394		end)
391	395		return aType, aVar
392	396		end
393	397
394	398		function varDeclaration(aType, aVar)
395	399		aType, aVar = checkVarType(aType, aVar)
396	400		return aVar .. ' : ' .. aType
397	401		end
398	402
399	403		function checkDeclarationOrGoto(m1, m2, m3)
400	404		if m2 ~= 'goto' then
401	405		return '\n' .. m1 .. varDeclaration(m2, m3) .. ';'
402	406		else
403	407		return '\n' .. m1 .. m2 .. ' ' .. m3 .. ';'
404	408		end
405	409		end
406	410
407	411		function addProcFunc(mtype, mname, mparams, mbody)
408	412		local str, isFunc, rType, k, v
409	413		if mtype == 'void' then
410	414		str = '\nprocedure '
411	415		isFunc = false
412	416		else
413	417		str = '\nfunction '
414	418		isFunc = true
415	419		end
416	420		mtype, mname = checkVarType(mtype, mname)
417	421		local vparams = split(trimChars(mparams, '(',')'), ',')
418	422		str = str .. mname .. '('
419	423
420	424		local tparams = {}
421	425		for k, v in pairs(vparams) do
422	426		local vparam = split(trim(v), ' ')
423	427		if #vparam > 2 then
424	428		table.insert(tparams, vparam[1] .. ' ' .. varDeclaration(vparam[2], vparam[3]))
425	429		else
426	430		--print(vparam[1], vparam[2])
427	431		table.insert(tparams, varDeclaration(vparam[1], vparam[2] or 'is_define'))
428	432		end
429	433		end
430	434
431	435		str = str .. table.concat(tparams, '; ') .. ')'
432	436		if isFunc then
433	437		if mtype == 'int' then
434	438		rType = 'integer'
435	439		else
436	440		rType = mtype
437	441		end
438	442		str = str .. ':' .. rType
439	443		end
440	444
441	445		if mbody then
442	446		local tblLabels = {}
443	447		for v in mbody:gmatch('\n[\t ]([%w_]+)[\t ]:[^=]') do
444	448		if v ~= 'default' then
445	449		table.insert(tblLabels, v)
446	450		end
447	451		end
448	452
449	453		if #tblLabels > 0 then
450	454		str = str .. ';\nlabel\n '.. table.concat(tblLabels, ', ')
451	455		end
452	456
453	457		local declarations = {}
454	458
455	459		mbody = mbody:gsub('(\n[\t ])const[\t ]+([%w_]+)[\t ]+(%?[%w_]+)[\t ]:%=[\t ]([^;\n]+;)','%1 %2 %3 := %4')
456	460
457	461		mbody = mbody:gsub('(\n[\t ])([%w_]+)[\t ]+(%?[%w_]+)[\t ]:%=[\t ]([^;\n]+;)', function(m1, m2, m3, m4)
458	462		table.insert(declarations, varDeclaration(m2, m3) .. ';' )
459	463		return m1 .. m3 .. ' := ' .. m4
460	464		end)
461	465
462	466		mbody = mbody:gsub('\n[\t ]const[\t ]([%w_]+)[\t ]+(%?[%w_]+)[\t ];', function(m1,m2)
463	467		table.insert(declarations, varDeclaration(m1, m2) .. ';')
464	468		return ''
465	469		end)
466	470
467	471		mbody = mbody:gsub('\n([\t ])([%w_]+)[\t ]+(%?[%w_ ,]+);', function(m1,m2,m3)
468	472		if m2 ~= 'goto' then
469	473		table.insert(declarations, varDeclaration(m2, m3) .. ';')
470	474		return ''
471	475		else
472	476		return '\n' .. m1 .. m2 .. ' ' .. m3 .. ';'
473	477		end
474	478		end)
475	479
476	480		if #declarations > 0 then
477	481		local unique_decl = {}
478	482		table.sort(declarations)
479	483		local lastV = ''
480	484		local k2, v2
481	485		for k2,v2 in pairs(declarations) do
482	486		if v2 ~= lastV then
483	487		lastV = v2
484	488		table.insert(unique_decl, v2)
485	489		end
486	490		end
487	491		str = str .. ';\nvar\n '.. table.concat(unique_decl, '\n ') .. '\n'
488	492		else
489	493		str = str .. ';\n'
490	494		end
491	495
492	496		str = str .. 'begin' .. trimChars(mbody, '{','}') .. 'end'
493	497		end
494	498		return str .. ';'
495	499		end
496	500
497	501		--*************************************
498	502		--
499	503		-- Order of substitutions are important
500	504		--
501	505		--*************************************
502	506
503	507		--=assignements statements
504	508		pasbody = pasbody:gsub("([\t ])([%w_]+)[\t ]=[\t ]*([^=;\n]+);", '%1%2 := %3;')
505	509
506	510		--return
507	511		pasbody = pasbody:gsub('([\t ]*)return[\t ]+([^;]+);', '%1exit(%2);')
508	512
509	513		--NULL
510	514		pasbody = pasbody:gsub('([^%w]+)NULL([^%w]+)', '%1nil%2')
511	515
512	516		--void functions to procedure declaratios
513	517		pasbody = pasbody:gsub('([%w_]+)[\t ]+([%w_]+)[\t ](%b())[%s](%b{})', addProcFunc)
514	518		--pasbody = pasbody:gsub('\n([%w_]+)%s+([^%s]+)%s*(%b());', addProcFunc)
515	519
516	520		--const/static
517	521		tblLeaveCommented = {
518	522		'const', 'static'
519	523		}
520	524		for k,v in pairs(tblLeaveCommented) do
521	525		pasbody = pasbody:gsub('([\t ])(' .. v .. ')([\t ])', '%1{%2}%3')
522	526		end
523	527
524	528		--defines to const
525	529		isConstEmmited = false
526	530		function addConst(m1,m2)
527	531		local sm
528	532		sm = ''
529	533		if not isConstEmmited then
530	534		isConstEmmited = true
531	535		sm = '\nconst'
532	536		end
533	537		return sm .. '\n\t' .. m1 .. ' = ' .. m2 .. ';'
534	538		end
535	539
536	540		isConstEmmited = false
537	541		pasbody = pasbody:gsub('\n#define%s+([^%s]+)%s+(%b())', '\nconst %1 = %2;')
538	542		isConstEmmited = false
539	543		pasbody = pasbody:gsub('\n#define%s+([^%s]+)[ \t]+([^%s]+)', '\nconst %1 = %2;')
540	544
541	545		--includes
542	546		tblUses = {}
543	547		pasbody = pasbody:gsub('\n#[ \t]*(include)%s+([^\n]+)', function(m1,m2)
544	548		for w in m2:gmatch('"([^.]+)%..+"') do
545	549		table.insert(tblUses, w)
546	550		end
547	551		return '\n//#' .. m1 .. ' ' .. m2
548	552		end)
549	553		pasbody = '//uses ' .. table.concat(tblUses, ', ') .. ';\n' .. pasbody
550	554
551	555		--defines to compiler directives
552	556		pasbody = pasbody:gsub('\n#([^\n]+)', '\n{$%1}')
553	557
554	558		--comments
555	559		pasbody = pasbody:gsub('\n#', '\n//#')
556	560		pasbody = pasbody:gsub('/%', '(')
557	561		pasbody = pasbody:gsub('%/', ')')
558	562
559	563		--declarations
560	564		pasbody = pasbody:gsub('\n([\t ]*)([%w_]+)[\t ]+([%w_ ,]+);', checkDeclarationOrGoto)
561	565
562	566		--structs
563	567		function parseStruct(m1, m2)
564	568		return '\n' .. m1 .. ' = record\n' .. trimChars(m2, '{', '}') .. '\nend'
565	569		end
566	570		pasbody = pasbody:gsub('\n[\t ]struct[\t ]+([%w_]+)[\t ](%b{})', parseStruct)
567	571
568	572		--if statements
569	573		parseStatementCalled = false
570	574
571	575		function parseStatement(mSpace, mStatement, mCond, mBody)
572	576		parseStatementCalled = true
573	577		local vStatement
574	578		if mStatement == 'if' then
575	579		vStatement = mStatement .. ' ' .. mCond .. ' then'
576	580		elseif mStatement == 'else' then
577	581		return mSpace .. mStatement .. ' begin' .. trimChars(mCond, '{', '}') .. ' end;'
578	582		elseif (mStatement == 'while') then
579	583		vStatement = mStatement .. ' ' .. mCond .. ' do'
580	584		elseif (mStatement == 'for') then
581	585		vStatement = mStatement .. ' ' .. mCond .. ' do'
582	586		--local forArgs = split(trimChars(mCond, '(', ')'), ';')
583	587		--return mSpace .. (forArgs[1] or '') .. ';' .. mSpace ..'while (' ..
584	588		-- (forArgs[2] or 'true') .. ') do' .. mSpace .. 'begin' .. mSpace .. trimChars(mBody, '{', '}') .. '\n' .. mSpace ..
585	589		-- (forArgs[3] or '') .. ';\n' .. mSpace .. 'end;'
586	590		else
587	591		vStatement = mStatement .. ' ' .. mCond .. '\n'
588	592		end
589	593		return mSpace .. vStatement .. ' begin' .. trimChars(mBody, '{', '}') .. 'end;'
590	594		end
591	595
592	596		-- for nested blocks
593	597		parseStatementCalled = true
594	598		while(parseStatementCalled) do
595	599		parseStatementCalled = false
596	600		pasbody = pasbody:gsub('([^%w_])(if)[\t ](%b())[\t ](%b{})', parseStatement)
597	601		end
598	602
599	603		-- else
600	604		pasbody = pasbody:gsub('([\t ]+)(else)[\t ]*(%b{})', parseStatement)
601	605
602	606		pasbody = pasbody:gsub("([^%w_])if[\t ](%b())[\t ]([^;\n]+);", '%1if %2 then %3;')
603	607
604	608		--?: short if
605	609		pasbody = pasbody:gsub("([^?])?([^:;\n]):[\t ]*([^%s;]+);", ' iff(%1, %2, %3) ')
606	610
607	611		--while loop
608	612		-- for nested blocks
609	613		parseStatementCalled = true
610	614		while(parseStatementCalled) do
611	615		parseStatementCalled = false
612	616		pasbody = pasbody:gsub('([^%w_])(while)[\t ](%b())[\t ](%b{})', parseStatement)
613	617		end
614	618
615	619		--for loop
616	620		-- for nested blocks
617	621		parseStatementCalled = true
618	622		while(parseStatementCalled) do
619	623		parseStatementCalled = false
620	624		pasbody = pasbody:gsub('([^%w_])(for)[\t ](%b())%s(%b{})', parseStatement)
621	625		end
622	626
623	627		--do/while
624	628		-- for nested blocks
625	629		parseStatementCalled = true
626	630		while(parseStatementCalled) do
627	631		parseStatementCalled = false
628	632		pasbody = pasbody:gsub("([^%w_])do[\t ](%b{})[\t ]while([^;\n]+);",
629	633		function(m1, m2, m3)
630	634		parseStatementCalled = true
631	635		return m1 .. 'repeat ' .. trimChars(m2, '{', '}') .. 'until not' .. m3
632	636		end)
633	637		end
634	638
635	639		--switch/case statements
636	640
637	641		--begin/end enclose blocks around
638	642		-- for nested blocks
639	643		parseStatementCalled = true
640	644		while(parseStatementCalled) do
641	645		parseStatementCalled = false
642	646		pasbody = pasbody:gsub("([^%w_]case[\t ]+[^:]+)[\t ]:[%s](%b{})",
643	647		function(m1, m2, m3)
644	648		parseStatementCalled = true
645	649		return m1 .. ': begin' .. trimChars(m2, '{', '}') .. 'end;'
646	650		end)
647	651		pasbody = pasbody:gsub("([^%w_]default[\t ]):[%s](%b{})",
648	652		function(m1, m2, m3)
649	653		parseStatementCalled = true
650	654		return m1 .. ': begin' .. trimChars(m2, '{', '}') .. 'end;'
651	655		end)
652	656		end
653	657
654	658		--breaks remove
655	659		pasbody = pasbody:gsub("([^%w_]case[\t ]+[^:]+)[\t ]:[%s](.-)break;", '%1: %2')
656	660
657	661		--case
658	662		pasbody = pasbody:gsub("([^%w_])case[\t ]+([^:]+):", '%1%2:')
659	663
660	664		-- for nested blocks
661	665		parseStatementCalled = true
662	666		while(parseStatementCalled) do
663	667		parseStatementCalled = false
664	668		pasbody = pasbody:gsub("([^%w_])switch[\t ](%b())[\t ](%b{})",
665	669		function(m1, m2, m3)
666	670		parseStatementCalled = true
667	671		return m1 .. 'case ' .. m2 .. ' of ' .. trimChars(m3, '{', '}') .. 'end;'
668	672		end)
669	673		end
670	674
671	675		--pasbody = pasbody:gsub("([\t ])case[\t ]+('.')[\t ]:\n", '%1%2:\n')
672	676		--pasbody = pasbody:gsub("([\t ])case[\t ]+(%d+)[\t ]:\n", '%1%2:\n')
673	677		--pasbody = pasbody:gsub("([\t ])(case)[\t ]+('.')[\t ]:[\t ]*(%b{})", '%1%2 : %3')
674	678
675	679		--pre/pos increments
676	680		-- (n)++ -> PosInc(n)
677	681		pasbody = pasbody:gsub("(%([^%s+]+%))%+%+", 'PosInc%1')
678	682		-- n++ -> PosInc(n)
679	683		pasbody = pasbody:gsub("([^%s*+]+)%+%+", 'PosInc(%1)')
680	684		-- ++(n) -> PreInc(n)
681	685		pasbody = pasbody:gsub("%+%+(%([^%s;+]+%))", 'PreInc%1')
682	686		-- ++*n -> PreInc(n)
683	687		pasbody = pasbody:gsub("%+%+([^%s*;+]+)", 'PreInc(%1)')
684	688
685	689		-- (n)--
686	690		pasbody = pasbody:gsub("(%([^%s-]+%))%-%-", 'PosDec%1')
687	691		-- n*--
688	692		pasbody = pasbody:gsub("([^%s*-]+)%-%-", 'PosDec(%1)')
689	693		-- --(n)
690	694		pasbody = pasbody:gsub("%-%-(%([^%s;-]+%))", 'PreDec%1')
691	695		-- --n
692	696		pasbody = pasbody:gsub("%-%-([^%s;-]+)", 'PreDec(%1)')
693	697
694	698		--boolean operators
695	699		tblBooleanOperators = {
696	700		{'\|\|', 'or'},
697	701		{'&&', 'and'},
698	702		}
699	703		for k,v in pairs(tblBooleanOperators) do
700	704		pasbody = pasbody:gsub('([\t ])' .. v[1] .. '([\t ])', '%1) ' .. v[2] .. ' (%2')
701	705		end
702	706
703	707		--pointers
704	708		pasbody = pasbody:gsub("%->", '.')
705	709		pasbody = pasbody:gsub("%(%*([%w_]+)", '(%1^')
706	710		pasbody = pasbody:gsub("%%([%w_]+)", '%1^^')
707	711		pasbody = pasbody:gsub("&([%w_]+)", '@%1')
708	712		pasbody = pasbody:gsub("%([%w_]+)[\t ]:[\t ]*([%w_]+);", '%1 : ^%2;')
709	713		pasbody = pasbody:gsub("%^char", 'pchar')
710	714		--pasbody = pasbody:gsub("%([%w_]+)[\t ]:=[\t ]*([^;\n]+);", '%1^ := %2;')
711	715
712	716		--bit operators
713	717		tblBitOperators = {
714	718		{'<<', 'shl'},
715	719		{'>>', 'shr'},
716	720		{'\|', 'or'},
717	721		{'&', 'and'},
718	722		{'~', 'not'},
719	723		}
720	724
721	725		for k,v in pairs(tblBitOperators) do
722	726		pasbody = pasbody:gsub('([\t ])' .. v[1] .. '([\t ])', '%1 ' .. v[2] .. ' %2')
723	727		end
724	728
725	729		--==eq operator
726	730		pasbody = pasbody:gsub("([\t ])%=%=([\t ])", '%1 = %2')
727	731
728	732		--!= not eq operator
729	733		pasbody = pasbody:gsub("([\t ])!%=([\t ])", '%1 <> %2')
730	734
731	735		--! unary
732	736		pasbody = pasbody:gsub('([\t ])!([\t ])', '%1 not %2')
733	737
734	738		--blocks
735	739		--pasbody = pasbody:gsub("(%b{})", function(m1) return 'begin' .. trimChars(m1, '{', '}') .. 'end;' end)
736	740		--pasbody = pasbody:gsub("(%b{})", function(m1) return 'begin' .. trimChars(m1, '{', '}') .. 'end;' end)
737	741
738	742		--strings and escaped characters
739	743		tblEscapedCahrs = {
740	744		{'\\"', '"'},
741	745		{'\\\\', '\\'},
742	746		{'\\t', "'#9"},
743	747		{'\\n', "'#10'"},
744	748		{'\\f', "'#12'"},
745	749		}
746	750		pasbody = pasbody:gsub('%b""', function(m1)
747	751		return "'" .. trimChars(m1:gsub("'", "''") , '"', '"') .. "'"
748	752		end)
749	753		for k,v in pairs(tblEscapedCahrs) do
750	754		pasbody = pasbody:gsub(v[1], v[2])
751	755		end
752	756
753	757		--common functions/procedure
754	758		tblOrigFuncNewFunc = {
755	759		{'printf', 'format'},
756	760		{'malloc', 'GetMem'},
757	761		{'free', 'Dispose'},
758	762		{'memcpy', 'Move'},
759	763		}
760	764
761	765		for k,v in pairs(tblOrigFuncNewFunc) do
762	766		pasbody = pasbody:gsub('([\t ]+)' .. v[1] .. '%(', '%1' .. v[2] .. '(')
763	767		end
764	768
765	769		--typedefs
766	770		isTypeEmmited = false
767	771		function addType(m1,m2)
768	772		local sm
769	773		sm = ''
770	774		if not isTypeEmmited then
771	775		isTypeEmmited = true
772	776		sm = '\ntype'
773	777		end
774	778		return sm .. '\n\t' .. m2 .. ' = ' .. m1 .. ';'
775	779		end
776	780		--pasbody = pasbody:gsub('\ntypedef%s+struct%s+([^%s]+)%s+([^;]+)', addType)
777	781		--pasbody = pasbody:gsub('\ntypedef%s+([^%s]+)%s+([^;]-)', addType)
778	782		pasbody = pasbody:gsub('\n[\t ]*typedef[\t ]+struct[\t ]+([%w_]+)[\t ]+([^;]+)', '\n%2 = %1')
779	783		pasbody = pasbody:gsub('\n[\t ]*typedef[\t ]+struct%s+(%b{})%s+([%w_]+);',
780	784		function(m1, m2) return m2 .. ' = record' .. trimChars(m1, '{', '}') .. 'end;' end)
781	785
782	786		-- print the results
783	787		print(pasbody)
784	788		```
785	789
786	790		Here is an example of a c file converted.
787	791
788	792		``` pascal
789	793		//uses lua, llimits, lmem, lstate, lzio;
790	794		(*
791	795		** $Id: lzio.c,v 1.31.1.1 2007/12/27 13:02:25 roberto Exp $
792	796		** a generic input stream interface
793	797		** See Copyright Notice in lua.h
794	798		*)
795	799
796	800		//#include <string.h>
797	801
798	802		{$define lzio_c}
799	803		{$define LUA_CORE}
800	804
801	805		//#include 'lua.h'
802	806
803	807		//#include 'llimits.h'
804	808		//#include 'lmem.h'
805	809		//#include 'lstate.h'
806	810		//#include 'lzio.h'
807	811
808	812		function luaZ_fill(z : PTZIO):integer;
809	813		var
810	814		L : Plua_State;
811	815		buff : Pchar;
812	816		size : size_t;
813	817		begin
814	818		*L := z.L;
815	819		lua_unlock(L);
816	820		buff := z.reader(L, z.data, @size);
817	821		lua_lock(L);
818	822		if (buff = nil ) or ( size = 0) then exit(EOZ);
819	823		z.n := size - 1;
820	824		z.p := buff;
821	825		exit(char2int(PosInc^((z.p))));
822	826		end;
823	827
824	828		function luaZ_lookahead(z : PTZIO):integer;
825	829		begin
826	830		if (z.n = 0) then begin
827	831		if (luaZ_fill(z) = EOZ)
828	832		exit(EOZ);
829	833		else begin
830	834		PosInc(z.n); (* luaZ_fill removed first byte; put back it *)
831	835		z-PosDec(>p);
832	836		end;
833	837		end;
834	838		exit(char2int(z^.p));
835	839		end;
836	840
837	841		procedure luaZ_init(L : Plua_State; z : PTZIO; reader : lua_Reader; data : Ppointer);
838	842		begin
839	843		z.L := L;
840	844		z.reader := reader;
841	845		z.data := data;
842	846		z.n := 0;
843	847		z.p := nil;
844	848		end;
845	849
846	850		(* --------------------------------------------------------------- read --- *)
847	851
848	852		function luaZ_read(z : PTZIO; b : Ppointer; n : size_t):size_t;
849	853		var
850	854		m : size_t;
851	855		begin
852	856		while (n) do begin
853	857		if (luaZ_lookahead(z) = EOZ)
854	858		exit(n); (* exit(number of missing bytes *)
855	859		m = (n <= z.n) ? n : z.n); (* min. between n and z.n *)
856	860		Move(b, z.p, m);
857	861		z.n -= m;
858	862		z.p += m;
859	863		b := (char *)b + m;
860	864		n -= m;
861	865		end;
862	866		exit(0);
863	867		end;
864	868
865	869		(* ------------------------------------------------------------------------ *)
866	870
867	871		function luaZ_openspace(L : Plua_State; buff : PTMbuffer; n : size_t):Pchar;
868	872		begin
869	873		if (n > buff.buffsize) then begin
870	874		if (n < LUA_MINBUFFER) then n := LUA_MINBUFFER;
871	875		luaZ_resizebuffer(L, buff, n);
872	876		end;
873	877		exit(buff.buffer);
874	878		end;
875	879		```
876	880
877	881		# Manual conversion of C headers to Pascal
878	882
879	883		In this case one should utilize ones knowledge of C and Pascal together to make the headers. One can learn how to do the conversion by looking at examples.
880	884
881	885		## Converting constants
882	886
883	887		C:
884	888
885	889		``` c
886	890		#define SOME_CONSTANT 5
887	891		#define ANOTHER_CONSTANT 6
888	892		```
889	893
890	894		Pascal:
891	895
892	896		``` pascal
893	897		const
894	898		SOME_CONSTANT = 5;
895	899		ANOTHER_CONSTANT = 6;
896	900		```
897	901
898	902		## Converting exported routines
899	903
900	904		The most basic routines can be translated like this:
901	905
902	906		C:
903	907
904	908		``` c
905	909		int somekind_of_method(int* param_first, int* param_second)
906	910		void another_method(char*)
907	911		```
908	912
909	913		Pascal:
910	914
911	915		``` pascal
912	916		uses ctypes;
913	917
914	918		const
915	919		MyLib = 'mylib';
916	920
917	921		function somekind_of_method(param_first, param_second: pcint): cint; external MyLib;
918	922		procedure another_method_renamed(param1: PChar); external MyLib name 'another_method';
919	923		```
920	924
921	925		Note that one should use the ctypes unit together with the types that it declares to convert C headers instead of trying to use the basic Pascal types directly. This ensures that the bindings are correct in all platforms, as the C types might have different sizes on different architectures and operating systems.
922	926
923	927		Also, note that pointers to basic C types can be converted to types declared in ctypes, for example, int* is a pointer to a C int, so we can use the type pcint (pointer to a c integer). The C type int can be converted to cint and in Pascal we can shorten the declaration of parameters which are declared one after as folows: "param_first, param_second: pcint".
924	928
925	929		Finally, note that if the return value is void, then we should use a procedure instead of function.
926	930
927	931		[Creating Pascal bindings for C](https://github.com/williamhunter/pascal-bindings-for-c) is a tutorial with source code that explains in detail how to create manual bindings for C libraries. It deals with various data types (strings, arrays, etc). The tutorial also demonstrates how to create static (.a) and shared/dynamic libraries (.so or *.dll) libraries using the MinGW C compiler. Using this approach in combination with h2pas can be quite efficient.
928	932
929	933		See also the [[http://www.freepascal.org/docs-html/ref/refse85.html External Functions]] section of the reference guide.
930	934
931	935		# Publish your bindings on Lazarus-CCR or Free Pascal
932	936
933	937		You can submit your binding code to the Lazarus CCR repository (see e.g. [[Using the Lazarus-ccr SVN repository]]) so others can use (and maintain) it, too. If the bindings are useful for general, cross-platform work, they could be included in the FreePascal distribution as well.
934	938
935	939		# See also
936	940
937	941		- G. Marcou, E. Engler, A. Varnek, How to use C code in Free Pascal projects, Université de Strasbourg, 2009, [Link 1](http://ftp.psu.ru/programming/fpc/docs-pdf/CinFreePascal.pdf), [Link 2](https://www.scribd.com/document/370417404/CinFreePascal-pdf), Short description: Short tutorial that describes the process of using C and C++ code in Free Pascal, including writing of wrapper code.
938	942		- \[<https://github.com/williamhunter/pascal-bindings-for-c/blob/master/docs/Creating%20Pascal%20bindings%20for%20C%20(v1.0>).pdf Another tutorial\] showing how to use object-code and libraries created in C.
939	943		- [[Common problems when converting C header files]]
940	944		- [[Pascal for C users]]
941	945		- [[Lazarus/FPC Libraries]]
942	946		- [[SWIG]]
943	947
944	948		---
945	949		From the Free Pascal wiki, page "Creating bindings for C libraries", as it stood on 2023-08-28 after a change by Myrmidon, 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