Wrapping C libraries - Revision history

Ramack: /* Low-level access to functions */

2018-09-15T18:08:54Z

Low-level access to functions

← Older revision		Revision as of 20:08, 15 September 2018
Line 110:		Line 110:
	wrappers_generator does not parses C code directly but reads the output of gccxml or its successor, castxml. Those tools provides an XML description of the source code analyzed that greatly ease the task of generating glue code. In fact they were created for that purpose.		wrappers_generator does not parses C code directly but reads the output of gccxml or its successor, castxml. Those tools provides an XML description of the source code analyzed that greatly ease the task of generating glue code. In fact they were created for that purpose.

−	<pre>gccxml</pre> is available in Debian ~~stable~~ while <pre>castxml</pre> is available in Debian ~~testing~~. Both are also available for Ubuntu, Redhat et cetera.	+	<pre>gccxml</pre> is available in Debian oldstable while <pre>castxml</pre> is available in Debian stable. Both are also available for Ubuntu, Redhat et cetera.

	Given an XML file and a list of C files (headers or sources) to wrap wrappers_generator:		Given an XML file and a list of C files (headers or sources) to wrap wrappers_generator:
Line 126:		Line 126:
	* if it doesn't exist it creates a directory plugin/c that will contain all the C code that will be compiled by liberty eiffel when using the library		* if it doesn't exist it creates a directory plugin/c that will contain all the C code that will be compiled by liberty eiffel when using the library

−	It does not try to give high-level, directly usable wrappers but it writes fairly verbose low-level wrappers that hopefully will save you quite a lot of typing.	+	It does not try to give high-level, directly usable wrappers but it writes fairly verbose low-level wrappers that hopefully will save you quite a lot of typing.
−

	=== The rest of this document still needs to be adapted. ===		=== The rest of this document still needs to be adapted. ===

Hzwakenberg: /* The rest of this document still needs to be adapted. */

2018-09-09T13:14:34Z

The rest of this document still needs to be adapted.

← Older revision		Revision as of 15:14, 9 September 2018
Line 507:		Line 507:
	Start copying original documentation into an Eiffel class and comment it out entirely.		Start copying original documentation into an Eiffel class and comment it out entirely.
	Add proper indexing clauses, then progressively convert it into Eiffel from top to bottom.		Add proper indexing clauses, then progressively convert it into Eiffel from top to bottom.
−	Sketch ~~difficoult~~ features into comments.	+	Sketch difficult features into comments.
	This behaviour is not meant to pile rubbish, but to quickly know how much work we still have to do.		This behaviour is not meant to pile rubbish, but to quickly know how much work we still have to do.
−	This means that the resulting Eiffel classes will be a derivative work of the original documentation of the library. This is usally not a problem these days because documentation is often automatically extracted from sources, so the Eiffel wrapper will end up having the same license of the wrapper library; for example our GTK+ wrapper being a derivative work of the actual GTK+ C library must abide its LGPL license.	+	This means that the resulting Eiffel classes will be a derivative work of the original documentation of the library. This is usally not a problem these days because documentation is often automatically extracted from sources, so the Eiffel wrapper will end up having the same license of the wrapper library; for example our GTK+ wrapper being a derivative work of the actual GTK+ C library must abide its LGPL license.
−	All the infrastructure of GTK+, including GObject are - in my humble opinion - explicitly designed to make the life easy for people writing wrappers for loosely-typed languages such as Python, Perl and other scriptiong languages. This (sadly) means that life for heavily/strongly-typed languages such as Eiffel are ~~make~~ annoying.	+	All the infrastructure of GTK+, including GObject are - in my humble opinion - explicitly designed to make the life easy for people writing wrappers for loosely-typed languages such as Python, Perl and other scriptiong languages. This (sadly) means that life for heavily/strongly-typed languages such as Eiffel are made annoying.
	Objects like closures and other amenities like that won't be wrapped until the rest is done and working.		Objects like closures and other amenities like that won't be wrapped until the rest is done and working.

Hzwakenberg: /* Incoming tools */

2018-09-09T13:12:34Z

Incoming tools

← Older revision		Revision as of 15:12, 9 September 2018
Line 515:		Line 515:
	=== Incoming tools ===		=== Incoming tools ===

−	Libraries using gobject-introspection and typelib provides much more ~~informations~~ to write wrappers and binding for other languages.	+	Libraries using gobject-introspection and typelib provides much more information to write wrappers and binding for other languages.

	The metadata of a typelib file allows to directly produce high-level wrappers.		The metadata of a typelib file allows to directly produce high-level wrappers.

Hzwakenberg: /* or how to write GNU-Eiffel wrappers for a C library */

2016-06-15T11:10:00Z

or how to write GNU-Eiffel wrappers for a C library

Tybor: /* Text to be still reviewd */

2016-03-24T15:56:54Z

Text to be still reviewd

← Older revision		Revision as of 17:56, 24 March 2016
Line 129:		Line 129:


−	==== ~~Text~~ to be ~~still~~ ~~reviewd~~ ====	+	=== The rest of this document still needs to be adapted. ===

	Let's write some low-level classes. We will put the functions found in the include file /usr/include/zlib.h in the class ZLIB_EXTERNALS and the low-level getters and setters features for the structure z_stream structure in the class Z_STREAM_STRUCT (this scheme is also used by eiffel-gcc-xml tool; I know it is simplicistic and that it could produce name-clashes but it has worked fine until now. ). Here's some examples		Let's write some low-level classes. We will put the functions found in the include file /usr/include/zlib.h in the class ZLIB_EXTERNALS and the low-level getters and setters features for the structure z_stream structure in the class Z_STREAM_STRUCT (this scheme is also used by eiffel-gcc-xml tool; I know it is simplicistic and that it could produce name-clashes but it has worked fine until now. ). Here's some examples
Line 512:		Line 512:
	All the infrastructure of GTK+, including GObject are - in my humble opinion - explicitly designed to make the life easy for people writing wrappers for loosely-typed languages such as Python, Perl and other scriptiong languages. This (sadly) means that life for heavily/strongly-typed languages such as Eiffel are make annoying.		All the infrastructure of GTK+, including GObject are - in my humble opinion - explicitly designed to make the life easy for people writing wrappers for loosely-typed languages such as Python, Perl and other scriptiong languages. This (sadly) means that life for heavily/strongly-typed languages such as Eiffel are make annoying.
	Objects like closures and other amenities like that won't be wrapped until the rest is done and working.		Objects like closures and other amenities like that won't be wrapped until the rest is done and working.
−

	=== Incoming tools ===		=== Incoming tools ===

Tybor: /* Code organization and class hierarchy. */

2016-03-24T15:56:25Z

Code organization and class hierarchy.

← Older revision		Revision as of 17:56, 24 March 2016
Line 61:		Line 61:

	We usually place each wrapper library in its own directory following this organization:		We usually place each wrapper library in its own directory following this organization:
−
−	<pre>
−	zlib/
−	\|-- examples -- Examples on how to use the Zlib wrappers
−	\|-- library -- Contains the high-level classes, those used directly in Eiffel programs
−	\| \|-- externals -- Contains the low-level classes to interface with C (externals, macros, enumeration and so on)
−	\| \| `- generated -- Contains the low-level classes automatically generated with a tool such as wrappers_generator
−	\| `-- loadpath.se -- Lists the clusters of the library itself, i.e. which directories contains its classes
−	\|-- loadpath.se -- Lists the clusters used by the library, i.e. its dependencies
−	`-- tests -- Contains the tests to be used with eiffeltest tool
−	</pre>

	* zlib/		* zlib/

Tybor: /* The rest of this document still needs to be adapted. */

2016-03-24T15:55:59Z

The rest of this document still needs to be adapted.

← Older revision		Revision as of 17:55, 24 March 2016
Line 47:		Line 47:

	----		----
−	== The rest of this document still needs to be adapted. ==
	== Identifying types and classes ==		== Identifying types and classes ==

Tybor: /* TODO: add proper usage of wrappers-generator */

2016-03-24T15:55:27Z

TODO: add proper usage of wrappers-generator

@@ Line 48: / Line 48: @@
 ----
 == The rest of this document still needs to be adapted.  ==
 Now you will wonder how to identify the types used in Zlib. This is quite an extensive argument that people smarter than me already handled in great details here.
@@ Line 56: / Line 55: @@
 Zlib has many functions taking a z_streamp which is nothing more than a typedef-fed pointer to structure z_stream_s. We will wrap those facilities in the Eiffel's (non-expanded) class ZLIB_STREAM.
 Before diving into code writing let's spend some words on how to cleanly organize our work. We want to provide the user of our library a pretty object-oriented API; since he/she will look at the sources directly soon-or-later it is useful to separate the high-level features and classes, those that will be used directly in other Eiffel projects from the low-level details, like external features or plugins.
@@ Line 62: / Line 63: @@
 We usually place each wrapper library in its own directory following this organization:
 zlib/
 |-- examples -- Examples on how to use the Zlib wrappers
 |-- library -- Contains the high-level classes, those used directly in Eiffel programs
 |   |-- externals -- Contains the low-level classes to interface with C (externals, macros, enumeration and so on)
 |   `-- loadpath.se -- Lists the clusters of the library itself, i.e. which directories contains its classes
 |-- loadpath.se -- Lists the clusters used by the library, i.e. its dependencies
 `-- tests -- Contains the tests to be used with eiffeltest tool
 If the library is conceptually separated into different areas, subsystems or if it is simple too wide to put cleanly every public class into a single directory we can split the content of the directory library into several sub-directory, like GLib wrapper. See its directory layout:
  ./
 ./externals/
 zlib/loadpath.se will list the clusters used by the library itself, i.e. its dependencies. Like the previous it is a plain text file containing directories or other loadpaths file (Ok... I'm not assuming proficiency with GNU-Eiffel here). Zlib is quite a "plain" library and does not have dependencies - here we are speaking of dependencies of the Eiffel wrappers - so he only shall list only the base cluster of a wrapper library, ../common/loadpath.se and the soad-path of the library itself <./library/loadpath.se/code>:
  ../common/loadpath.se
 ./library/loadpath.se
 Let's write some low-level classes. We will put the functions found in the include file /usr/include/zlib.h in the class ZLIB_EXTERNALS and the low-level getters and setters features for the structure z_stream structure in the class Z_STREAM_STRUCT (this scheme is also used by eiffel-gcc-xml tool; I know it is simplicistic and that it could produce name-clashes but it has worked fine until now. ). Here's some examples
@@ Line 473: / Line 524: @@
 All the infrastructure of GTK+, including GObject are - in my humble opinion - explicitly designed to make the life easy for people writing wrappers for loosely-typed languages such as Python, Perl and other scriptiong languages. This (sadly) means that life for heavily/strongly-typed languages such as Eiffel are make annoying.
 Objects like closures and other amenities like that won't be wrapped until the rest is done and working.

Hzwakenberg at 19:15, 12 September 2014

2014-09-12T19:15:09Z

← Older revision		Revision as of 21:15, 12 September 2014
Line 385:		Line 385:
	end		end

−	As you can see each possible value has a setter command (set_light, set_normal and so on) and a boolean query (is_light, is_normal). As usual low-level values are accessible only by a WRAPPER or a WRAPPER_HANDLER.	+	As you can see each possible value has a setter command<br>(set_light, set_normal and so on) and a boolean<br>query (is_light, is_normal). As usual low-level values are accessible<br>only by a WRAPPER or a WRAPPER_HANDLER.

	Using eiffel-gcc-xml		Using eiffel-gcc-xml

Hzwakenberg: /* Prerequites */

2014-09-07T13:54:28Z

Prerequites

← Older revision		Revision as of 15:54, 7 September 2014
Line 17:		Line 17:
	==== Prerequites ====		==== Prerequites ====

−	You should be proficient of:	+	You should be proficient with:

	* the C language,		* the C language,

← Older revision		Revision as of 13:10, 15 June 2016
Line 9:		Line 9:
	</cite>		</cite>

−	So instead of giving rules I guide you on my path of wrapping the ZLib library, one of the most widespread compression ~~library~~.	+	So instead of giving rules I guide you on my path of wrapping the ZLib library, one of the most widespread compression libraries.

−	I deliberately chose a "low-level" library with very precise and narrow aims which lets to show basic wrapping techniques: a wider, properly designed library has infrastructures and details that requires to know some tricks from the beginning of the work, otherwise the resulting wrapper should be heavily re-worked on many times.	+	I deliberately chose a "low-level" library with very precise and narrow aims which lets me show basic wrapping techniques: a wider, properly designed library has infrastructures and details that requires to know some tricks from the beginning of the work, otherwise the resulting wrapper should be heavily re-worked many times.

	I usually work with Debian and Ubuntu GNU/Linux, so all the system commands and the package names listed in this tutorial/how-to should apply without changes on Debian and Debian-derived machines. Other distributions, like Fedora, RedHat, Suse, Mandriva shall have similarly named packages. People using BSD OSes could have those libraries available in their package manager. As a last resort you can always download the sources, compile and install them manually. I hope you know how to do it, otherwise the rest of this document would be quite useless for you.		I usually work with Debian and Ubuntu GNU/Linux, so all the system commands and the package names listed in this tutorial/how-to should apply without changes on Debian and Debian-derived machines. Other distributions, like Fedora, RedHat, Suse, Mandriva shall have similarly named packages. People using BSD OSes could have those libraries available in their package manager. As a last resort you can always download the sources, compile and install them manually. I hope you know how to do it, otherwise the rest of this document would be quite useless for you.
Line 21:		Line 21:
	* the C language,		* the C language,
	* the Eiffel language,		* the Eiffel language,
−	* the C library you want to wrap; you ~~shall~~ known how to use it in a C program; take some time to read the documentation ~~of the library~~ and to study the provided ~~example~~ in order to make yourself familiar with the style required to use the library. You will need them to provide extensive, readable documentation of your classes.	+	* the C library you want to wrap; you should known how to use it in a C program; take some time to read the library documentation and to study the example provided in order to make yourself familiar with the style required to use the library. You will need them to provide extensive, readable documentation of your classes.

	==== Software prerequisites ====		==== Software prerequisites ====
Line 28:		Line 28:

	* Liberty Eiffel, you may download the Debian packages from		* Liberty Eiffel, you may download the Debian packages from
−	* The C headers of the library to wrap; you ~~shall~~ be able to compile the examples of the library you're wrapping; so I issued	+	* The C headers of the library to wrap; you should be able to compile the examples of the library you're wrapping; so I issued

	sudo apt-get install zlib1g-dev		sudo apt-get install zlib1g-dev

−	* Documentation of the library. Even if it is not absolutely necessary to make working wrappers they are indeed necessary to provide properly documented, therefore usable classes; (GNU) Eiffel has standard rules on how to document code and we shall abide to that; adapting the original C documentation while we ~~wraps~~ various features is a good style to handle documentation. Please do not leave any part of your code undocumented. Spend some time reading the documentation. It is always worth the effort.	+	* Documentation of the library. Even if it is not absolutely necessary to make working wrappers they are indeed necessary to provide properly documented, therefore usable classes; (GNU) Eiffel has standard rules on how to document code and we shall abide to that; adapting the original C documentation while we wrap various features is a good style to handle documentation. Please do not leave any part of your code undocumented. Spend some time reading the documentation. It is always worth the effort.

−	I would like to repeat the concept: even if source-code in general is intented to be read by a compiler to produce binary modules its readability and understandability for people is of the utmost importance. Code is not meant to be written-once and never re-read. It actually happens that good code will be read again and again by many people. The fact that programs are covered and protected by copyright laws is not incidental. It means that source code is the expression of an author, like a novel or poetry; I like to think that this fact includes in itself, in-nuce that source text will be read by people several ~~time~~. And this reading does occour when the source-code text is well-written, well-documentated, useful for study and reuse if its license does allow it.	+	I would like to repeat the concept: even if source-code in general is intented to be read by a compiler to produce binary modules, its readability and understandability for people is of the utmost importance. Code is not meant to be written-once and never re-read. It actually happens that good code will be read again and again by many people. The fact that programs are covered and protected by copyright laws is not incidental. It means that source code is the expression of an author, like a novel or poetry; I like to think that this fact includes in itself, in-nuce that source text will be read by people several times. And this reading does occour when the source-code text is well-written, well-documentated, useful for study and reuse if its license does allow it.

	This approach does resemble Knuth's Literate Programming and indeed many design choices made by Bertrand Meyer during the conception of Eiffel regarding readability and understandability of source-code, expecially those exposed in Object-Oriented Software Construction are strikingly similar to Knut's ideas.		This approach does resemble Knuth's Literate Programming and indeed many design choices made by Bertrand Meyer during the conception of Eiffel regarding readability and understandability of source-code, expecially those exposed in Object-Oriented Software Construction are strikingly similar to Knut's ideas.