Chelper: what changed

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

Old	New		Line
1	1		### About
2	2
3	3		Chelper is Lazarus extension tool, that helps converting C headers to Pascal. Yes, it's yet another C-to-Pascal converting tool like lot of similar ([[H2Pas]], ToPas), but one might find it more useful.
4	4
5	5		The extension doesn't try to convert a header for the user, instead it's a tool to help with manual translation, doing almost all of "dirty work" for the user.
6	6
7	7		Chelper also supports converting Objective-C declarations into Objective-P.
8	8
9	9		### Author
10	10
11	11		Dmitry 'skalogryz' Boyarintsev
12	12
13	13		### License
14	14
15	15		[modified](http://svn.freepascal.org/svn/lazarus/trunk/COPYING.modifiedLGPL) [LGPL](http://svn.freepascal.org/svn/lazarus/trunk/COPYING.LGPL) (same as the FPC RTL and the Lazarus LCL). You can contact the author if the modified LGPL doesn't work with your project licensing.
16	16
17	17		### Download
18	18
19	19		There's no "downloadable" package yet, you can access the tool from SVN:
20	20
21	21		<https://sourceforge.net/p/lazarus-ccr/svn/HEAD/tree/components/chelper/>
22	22
23		-	~~`svn checkout `[`https://svn.code.sf.net/p/lazarus-ccr/svn/components/chelper/`](https://svn.code.sf.net/p/lazarus-ccr/svn/components/chelper/)~~
	23	+	```
	24	+	svn checkout https://svn.code.sf.net/p/lazarus-ccr/svn/components/chelper/
	25	+	```
24	26
25	27		### Change Log
26	28
27	29		- Version 0.8, 8 Aug 2010
28	30
29	31		### Dependencies / System Requirements
30	32
31	33		- Lazarus 0.9.29 or Higher
32	34
33	35		Status: Beta
34	36
35	37		### Issues
36	38
37	39		- No complete expression parser to construct the expression tree.
38	40
39	41		If you find a bug in the converter please report it to [bugs.freepascal.org](http://bugs.freepascal.org) for Lazarus-CCR project. Please attach the C-header text and the explanation what doesn't work as expected.
40	42
41	43		### Installation
42	44
43	45		- Get the package from SVN
44	46		- Install Chelper.lpk package to the Lazarus.
45	47		- Go to Tools-\>C to Pascal Options-\>Converter, uncheck Use external converter if you want to use the package built-in converter.
46	48
47	49		Using built-in converter has an advantage of the performance. However, if you'll need to update converter, you'll need to rebuild the whole IDE. It's also possible that converter might cause crashes or hangs. You should bug report it, but you're risking to loose all of your data.
48	50
49	51		It's much safer to use the external cconvert tool. It's also easier to update the converter if a new features are added or bugs fixed. All you need is to rebuild the cconverter executable a lot of faster than rebuilding Lazarus.
50	52
51	53		To use the external tool, you need to do the following:
52	54
53	55		- Open and build cconvert.lpi project (located at the package directory). You should get "cconvert" executable file.
54	56		- Open Tools-\>C to Pascal Options-\>Converter, press Select and choose cconvert executable file.
55	57		- Check Use external converter at Tools-\>C to Pascal Options-\>Converter
56	58
57	59		### How to use
58	60
59	61		#### Shortkeys
60	62
61	63		- ctrl+b - convert a single C declaration to Pascal
62	64		- ctrl+shift+b - convert all C declarations to Pascal from the current cursor position to the end of the file.
63	65
64	66		#### General
65	67
66	68		- Open a file with C declarations in Lazarus IDE or start a new file copying declarations there
67	69		- Place the cursor at the line where C declaration and press Ctrl+B (the shortcut would be modifiable in future).
68	70
69	71		for example:
70	72
71		-	~~`int c;`\~~
72		-	~~`int b; `~~
	73	+	```
	74	+	int c;
	75	+	int b;
	76	+	```
73	77
74	78		if the cursor placed at 'inc c;' line and ctrl+b pressed the result would be:
75	79
76		-	~~`var`\~~
77		-	~~` c : Integer;`\~~
78		-	~~`int b;`~~
	80	+	``` pascal
	81	+	var
	82	+	c : Integer;
	83	+	int b;
	84	+	```
79	85
80	86		exactly one definition is converted. The cursor would be place right after the converted definition. You can press ctrl+b again, and the result would be:
81	87
82		-	~~`var`\~~
83		-	~~` c : Integer;`\~~
84		-	~~`var `\~~
85		-	~~` b : Integer;`~~
	88	+	``` pascal
	89	+	var
	90	+	c : Integer;
	91	+	var
	92	+	b : Integer;
	93	+	```
86	94
87	95		Parsing definitions one-by-one will get your C headers ready with a very short period of time, as well as keeping it clean and correct from Pascal point of view.
88	96
89	97		- If you're sure your defines (explained below) are configured well enough. You can try to convert the rest of the file in one call by pressing ctrl+shift+b
90	98
91	99		i.e. you have 2 declarations in the file:
92	100
93		-	~~`int fn(int, float);`\~~
94		-	~~`extern int v;`~~
	101	+	```
	102	+	int fn(int, float);
	103	+	extern int v;
	104	+	```
95	105
96	106		placing the cursor before them and pressing ctrl+shift+b, would generate.
97	107
98		-	~~`function fn(par0: Integer; par1: Single): Integer; cdecl; external;`\~~
	108	+	``` pascal
	109	+	function fn(par0: Integer; par1: Single): Integer; cdecl; external;
99	110
100		-	~~`var`\~~
101		-	~~` v : Integer; external;`~~
	111	+	var
	112	+	v : Integer; external;
	113	+	```
102	114
103	115		You must be careful, because it's common to use macros in C headers. Leaving any of macros undefined might produce wrong pascal declaration. The next section explains how to define a macro for the chelper.
104	116
105	117		#### Defines
106	118
107	119		In most cases parameterless macro definitions, like
108	120
109		-	~~`#define VALUE 1 << 2;`~~
	121	+	```
	122	+	#define VALUE 1 << 2;
	123	+	```
110	124
111	125		are used like constant values. Chelper translates them as constants trying to convert the define expression.
112	126
113		-	~~`const`\~~
114		-	~~` VALUE = 1 shr 2;`~~
	127	+	``` pascal
	128	+	const
	129	+	VALUE = 1 shr 2;
	130	+	```
115	131
116	132		In other cases defines are used for some "special" markings or additional information for external tools.
117	133
118		-	~~`#define LIB_DEPRECATED `\~~
119		-	~~`LIB_DEPRECATED int somefunc(int p);`~~
	134	+	```
	135	+	#define LIB_DEPRECATED
	136	+	LIB_DEPRECATED int somefunc(int p);
	137	+	```
120	138
121	139		without the knowledge of LIB_DEPRECATED being the macro (of nothing), it's impossible to parse function declaration correctly. You can specify macros used by Chelper in the special defines file.
122	140
123	141		Select Tools-\>C to Pascal options-\>Main select the defines file and press Edit.
124	142
125	143		This would open the custom defines file in Lazarus IDE. All macros declared at this file are used by Chelper. After adding/editing macro defines save the file and you can return to the C header converting.
126	144
127	145		Chelper handles parameter macros as well.
128	146
129		-	~~`int somefunc SAFE_PARAMS( (int i))`~~
	147	+	```
	148	+	int somefunc SAFE_PARAMS( (int i))
	149	+	```
130	150
131	151		adding the the following declaration into defines file
132	152
133		-	~~`#define SAFE_PARAMS(x) x`~~
	153	+	```
	154	+	#define SAFE_PARAMS(x) x
	155	+	```
134	156
135	157		will allow to parse the declaration correctly
136	158
137		-	~~`function somefunc(i: Integer): Integer;`~~
	159	+	``` pascal
	160	+	function somefunc(i: Integer): Integer;
	161	+	```
138	162
139	163		#### Configuration File
140	164
141	165		Configuration file represents itself a simple .ini file. Following section are used in the file:
142	166
143	167		- Main - for general declarations, that effects
144	168
145	169		- Types - custom type conversion section. Name=Value, where Name is the c-type name, Value is resulting pascal type
146	170
147	171		example:
148	172
149		-	~~`[Types]`\~~
150		-	~~`int=integer`\~~
151		-	~~`int*=PInteger`\~~
152		-	~~`float=single`\~~
153		-	~~`float*=PSingle`~~
	173	+	```
	174	+	[Types]
	175	+	int=integer
	176	+	int*=PInteger
	177	+	float=single
	178	+	float*=PSingle
	179	+	```
154	180
155	181		---
156	182		From the Free Pascal wiki, page "Chelper", as it stood on 2022-04-30 after a change by E-ric, 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