Liberty Eiffel Wiki - User contributions [en]

Clean

2023-12-17T10:53:47Z

Tybor:

[[Category:Tool]]

= Usage =
se clean [options] <Root-Name> ...
Command clean removes all intermediate files produced by previous compile, or compile_to_c runs.
Names (<Root-Name> ...) can have the Eiffel suffix, no suffix at all, or the suffix used for Liberty Eiffel command files on your system (.make on UNIX or .BAT on Windows for example).

= Options =
-help:

Display a brief summary of the command-line syntax and a complete list of finder options.

-no_remove:

Print the name of files that would be removed, but do not remove them.e.

-verbose:

Print system information during the compilation (full path of loaded files, type inference score, removed files, etc.).

-version:

Show the number of the version of LibertyEiffel you're using.

= Examples =
== Example 1 ==
To remove intermediate files produced for the HELLO_WORLD program.
Type: clean hello_world
You can also type: clean hello_world.e
or you can also type: clean HELLO_WORLD
on Unix, you can type: clean hello_world.make
on Windows, you can do: clean hello_world.BAT

== Example 2 ==
Under Unix or Windows, remove all intermediates files in the current directory : clean *.e

If the root class file is not in the current directory, you can type (for Unix) : clean *.make

Option -verbose can be used to see which files are removed.

Release Notes (Versions history)

2022-07-05T06:13:36Z

Tybor: /* Curtiss (2022.dev, to be named after Glenn Curtiss) */

[[Category: Releases]]
== Liberty Eiffel (latest release first) ==
For other upcoming releases see the [[upcoming releases|list of names]].
=== Curtiss (2022.dev, to be named after [https://en.wikipedia.org/wiki/Glenn_Curtiss Glenn Curtiss]) ===
* not yet released (see next section for current release notes)
* User-visible changes:
** added support for assign (note: it applies to the setter, while ISE version applies to the getter)
** redesign of eiffeldoc generated HTML to reduce its size dramatically
** addition of a zsh completer for se
** updated dependency of BDW GC to version 8.x
** installation script (install.sh) now supports the latest libgc-dev library (external garbage collector)
** finally removed the obsolete classes GEN_RAND, MIN_STAND and STD_RAND
** removed support for some unused legacy platforms (OpenVMS, Amiga, Elate, BeOS, OS/2, Macintosh, HP RISC, IBM370, NS32000, MIPS, Pyramid 9810, SPARC, VAX, Motorola 68000) - in case you have a real use case for those we are happy to readd it
** removed support for some unused backend C-compilers (i.e. Watcom-C)
** removed obsolete feature "is_basic_expanded_type" from class ANY
** obsolete keyword 'creation' now generates an error
** obsolete class READY_DESCRIPTION removed from sequencer cluster
** 'is_prime' feature added to class INTEGER_GENERAL
** 'is_fibonacci' feature added to class INTEGER_GENERAL
** constants 'Tau', 'Sqr_tau' and 'Inv_tau' added to math_constants.e
** C-runtime now C99 compliant
** C-runtime now thread-safe
** C-code generator does not yet generate C99 compliant C-code, currently being worked on (likely for the Dennis-release).
** RUN_FEATUREs now have clear names (hopefully)
** to better support the user access rights model of the current Windows versions, the config file is no longer written to a root directory but rather to %ALLUSERSPROFILE% or %USERPROFILE%
* Known bugs:
** see [https://savannah.gnu.org/bugs/?group=liberty-eiffel] for the full list

=== Bell (2016.05, named after [https://en.wikipedia.org/wiki/Alexander_Graham_Bell Alexander Graham Bell]) ===
* released in May 2016
* first release since Liberty Eiffel has become the official GNU Eiffel compiler
* User-visible changes:
** changed Environment Variable name from SmartEiffel to LibertyEiffel (anyhow, normally it should not be necessary to set this one)
** new tool [[Mock]]
** removed linebreaks in compiler output
** many bugfixes
** GC call at exit is optional
** generic creation
** agents are now [https://en.wikipedia.org/wiki/Closure_(computer_programming) closures ]
** finder now finds all classes in the universe with the given name, not only the first one
** keyword '''is''' at the beginning of a feature is now deprecated
** Added support for alias "[]" and alias "()"
** constants are now visible in the eiffeldoc generated documentation
* Known bugs:
** there is still an issue in both GC implementations (classical SEGC and BDW), if it shows up, it often yields a "Bad target type" runtime error.
** for the full list see [https://savannah.gnu.org/bugs/?group=liberty-eiffel]

=== Adler (2013.11, named after [http://en.wikipedia.org/wiki/Charles_Adler,_Jr. Charles Adler, Jr.]) ===
* First release as Liberty Eiffel
* User-visible changes:
** Added [[library_class:NATURAL_8|<tt>NATURAL_8</tt>]], [[library_class:NATURAL_16|<tt>NATURAL_16</tt>]], [[library_class:NATURAL_32|<tt>NATURAL_32</tt>]], and [[library_class:NATURAL_64|<tt>NATURAL_64</tt>]] classes. See <tt>tutorial/natural.e</tt> for examples.
** Even low-level features (i.e. <tt>external "built_in"</tt>) are now checking their assertions. As an example, division by zero is now checked by assertions.
** Inlined dynamic dispatch for better performance
** A missing export clause is deprecated. Use <tt>{ANY}</tt> instead.
** New core libraries: cli, json, log, parse (beware, these libraries are not yet tuned to be used without GC)
** Improved libraries: string (with notably a new [[library_class:FIXED_STRING|<tt>FIXED_STRING</tt>]] class)
** Wrapper libraries: gtk, gdk, readline, ffi...
** A new tool that can generate mocks to help unit testing
** [http://hboehm.info/gc/ BDW] GC support
** Collections implementation of is_equal changed to compare the contained objects using their is_equal functions instead of = (which was formerly the functionality of is_equal_map). The old functionality of is_equal is available by fast_is_equal.
* Developer changes:
** The web site now belongs to the repository
** Automatic testing tools (ET on the web, and <tt>watch_eiffeltest.sh</tt> in the shell)
** Automatic Debian packages generation
* Known bugs:
** BDW GC is not well tested; currently weak references seem not to work properly; and the GC is not run at program exit (it should run all finalizers)
** Sometimes SmartEiffel's native GC behaves wrongly, analysis is welcome
** Some of the newer core libraries do not work very well when there is no GC
** See the [https://savannah.gnu.org/bugs/?group=liberty-eiffel bugs page]

Finder

2016-05-30T07:52:32Z

Tybor: /* Options */

[[Category:Tool]]
== Usage ==
se find [options] [<ACEfile.ace>] <Class>
The find command tells you which file is loaded when searching for an Eiffel <Class>.

When an Eiffel file is found, find prints the full path name on standard output.

The exit status is set to GENERAL.exit_success_code only when an existing file is found (thus allowing usage of the find command in shell scripts).
As for other commands, when the ACE file mode is used, only the content of the <ACEfile.ace> file is used to search the source file.
To see the loading path used by LibertyEiffel, you can for example type the find command using a bad (non-existent) class name.
In ACE file mode, the loading path can be updated by modifying the ACE file itself. In traditional mode (i.e. no ACE file), the default loading path may also be tailored (see below).

== Options ==
-help:
Display a brief summary of the command-line syntax and a complete list of find options.

-version:
Show the number of the version of LibertyEiffel you're using.

-verbose:
Print system information during the compilation (full path of loaded files, type inference score, removed files, etc.).

-loadpath <loadpath_file>:
Adds a loadpath file for class lookup. See below for details on the loading path constitution.

-raw:
Does not display the cluster name. Its only output is usually the path name of the class so it is useful in scripts.

== Where does Find search? ==

This is explained in detail in the [[class loading]] section. Note that finder will find all classes with a given name.

Tutorial tour

2016-04-01T23:04:51Z

Tybor: /* io cluster */

Welcome to the guided tour of the tutorial!

All the classes in the tutorial are provided with your LibertyEiffel installation, in the <code>tutorial</code> directory.

=== Easy starting: Hello World! ===

To compile the program, go to the <code>LibertyEiffel/tutorial</code> directory and execute the command:

se c HELLO_WORLD make -o hello

The meaning of the command is
{|
|-
|<code>se</code>
|the front-end tool for the LibertyEiffel compiler
|-
|<code>c</code>
|the tool invoked by <code>se</code> for compile into an executable
|-
|<code>HELLO_WORLD</code>
|the class of which an object is created (you may also write it in lower-case, or use its filename with the <code>.e</code> extension) we call it root class, as this is the root of the programs object tree
|-
|<code>make</code>
|the creation procedure of the <code>HELLO_WORLD</code> class to call
|-
|<code>-o hello</code>
|generates an executable with the name hello (linux) or hello.exe (windows)
|}

The command produces an executable, usually <code>hello</code> or <code>hello.exe</code> depending on the system. After compiling is finished, you can run the executable.

This unavoidable program is in the file <code>hello_world.e</code> and lets you grasp the basic concepts of Eiffel. Those concepts are:
* '''Everything is a class'''. In Eiffel, outside classes there is no salvation.
* The program starts by '''creating an object''' (of the root class) and initializing it by execution of the given root creation procedure. Here, the <code>make</code> feature in the class <code>HELLO_WORLD</code>.
* Each file is named after the name of the class it contains, in lower-case, with the <code>.e</code> extension.
* Each class comes with a set of '''features''', all its attributes and methods which come in form of functions (if they return a result) or procedures (in case they just 'do' something)
* Note the special object <code>io</code> that allows you to write text on the standard output. We will see that it also lets you read data.
* For the Eiffel syntax, look [[Syntax_diagrams|here]].

Please take a look at the following examples in the tutorial folder to see some classical example programs (some of them are in organized in folders for better overview)
* fibonacci.e
* knight.e
* pyramide.e and pyramide2.e
* hanoi
* parking
* triangle

To compile the other samples you must obviously modify the compiler command to give another root class .

== Some important concepts ==

=== Comments ===
As in every programming language there is the possibility to write comments into the source code, which do not have any effect for the final program, but are for the developer or reader of the source code to get an understanding of the ideas and algorithms behind the code.
A comment in Eiffel starts with the sequence of a couple of minus signs and is terminated by a newline (RETURN).
-- this is a comment in Eiffel
a := b + 3 -- comments are also allowed after some code

=== Manifest notations ===
LibertyEiffel comes with a big set of available datatypes. Famous examples as INTEGER, BOOLEAN, CHARACTER and STRING. For those (and also many collection types) there is the possibility to directly denote them in the program code, using the notations
123
True, False
'a'
"STRING"
See tutorial file manifest_notation.e for an example with nearly all options to define objects by manifest notations.

=== Everything is an Object ===
As mentioned above, in Eiffel every useful thing is an object. There are two different kinds of objects: expanded objects and referenced object. Expanded objects are passed by value, while reference objects are - who guesses - passed by reference. In case you write 7 in the source code this is a shorthand for an instance of the expanded type INTEGER and therefore it is an expanded object. Whenever you assign it to a variable or pass it to another feature it gets copied. A STRING object - e. g. denoted by "Hello World!" in the source code is a reference object, created implicitly by the compiler, allocated on the heap and passed by reference.

=== Local variables and Assignments ===
Every routine may define variables in a "local block" before its body (which start with the keyword do):
make
local
a: INTEGER
s: STRING
do
a := 5
a := a + 1
s := "Hello World!"
end

The visibility of these variables is limited to the method they are defined in and they do not keep their value from one execution of that routine to another. Assignment is done by the assignment operator ":=" which changes the variable (or let's say writable entity) on the left side to the value of the expression on the right side. In case of the "Hello World!" assignment a new object of type STRING is created on the heap, initialized to the text "Hello World!" and a link to this object is stored in the local variable s.

=== Loops ===
In Eiffel we have exactly one construct to do something repeatedly, so no need to learn about for, do-while, while, anyhow, one is sufficient:
from
-- initialization
invariant
-- what shall stay true during repetition
variant
-- non-negative, but decreasing numeric value
until
-- termination condition
loop
-- what to do several times
end

Note, that the termination condition is an expression of type BOOLEAN and the loop body is executed until the condition evaluates to True, which differs in the logic from e. g. the loop constructs in C.

The most strange things for newcomers are probably the [https://en.wikipedia.org/wiki/Loop_invariant invariant] and the [https://en.wikipedia.org/wiki/Loop_variant variant]. While the first is a BOOLEAN condition, that stays true for every iteration, the latter is an INTEGER value which decreases with every iteration and always stays positive and therefore shows that the loop terminates. Both are optional and are not used very often in practice, even though they are essential in case we want to prove a program to be totally correct (and therefore terminates). I fear, that these formal loop assertions stay more or less unused until a formal verification tool is able to take real benefit from them.

See tutorial/loops.e for an example of the Greatest Common Divider algorithm to show the usage of the loop.

=== Input-output ===

==== io cluster ====

The input-output cluster is made up of several parts.

The io/basic subcluster contains the staples of

* the definitions of standard input and output streams, [[library_class:STD_INPUT|STD_INPUT]] and [[library_class:STD_OUTPUT|STD_OUTPUT]] that are available to all classes. In fact [[library_class:ANY|ANY]] offers those features:
** io: [[library_class:STD_INPUT_OUTPUT|STD_INPUT_OUTPUT]] -- Handle to standard file setup.
** std_input: [[library_class:STD_INPUT|STD_INPUT]] -- The standard input stream
** std_output: [[library_class:STD_OUTPUT|STD_OUTPUT]] -- The standard output stream
** std_error: [[library_class:STD_ERROR|STD_ERROR]] -- The standard error stream
** standard_streams: [[library_class:STANDARD_STREAMS|STANDARD_STREAMS]], a singleton that allows to redirect std_input_stream, std_output_stream as well as std_error_stream.

Beyond this standards streams that are available to all processes you can get read files in the operative file system using an [[library_class:INPUT_STREAM|INPUT_STREAM]] using [[library_class:BINARY_FILE_READ|BINARY_FILE_READ]] to read a binary file or [[library_class:TEXT_FILE_READ|TEXT_FILE_READ]] to read a text file.
Similarly, to write a file you use an [[library_class:OUTPUT_STREAM|OUTPUT_STREAM]] such as [[library_class:BINARY_FILE_WRITE|BINARY_FILE_WRITE]] for binary files or [[library_class:TEXT_FILE_WRITE|TEXT_FILE_WRITE]] for text files.

[[library_class:READLINE_INPUT_STREAM|READLINE_INPUT_STREAM]] is an input stream where the data is read from Command Line Interface (CLI) using the GNU readline library. You probabily have already used this library without knowing as it is used by several programs as at the time this notes has been written almost nine hundred packages in Debian use a version of readline

You may have noticed that Eiffel uses streams to access files. This is a much more flexible way to access data. In fact when you use an [[library_class:INPUT_STREAM|INPUT_STREAM]] the actual data can come from plain files, or from a string with [[library_class:STRING_INPUT_STREAM|STRING_INPUT_STREAM]] or any classes that conforms to and INPUT_STREAM, or more properly any live type that is a proper heir of INPUT_STREAM, such as BINARY_INPUT_STREAM, EZMQ_SOCKET_INPUT (a sockect messaging library), FILTER_INPUT_STREAM{ (put references to filters and explaiin BASE64_INPUT_STREAM, HTTP_CLIENT_INPUT_STREAM, MONITORED_INPUT_STREAM, QUOTED_PRINTABLE_INPUT_STREAM, TEMPLATE_INPUT_STREAM
), TERMINAL_INPUT_STREAM.

Mostly for testing purposes there are also [[library_class:NULL_INPUT_STREAM|NULL_INPUT_STREAM]], a "null" stream provides an unbroken sequence of zero, like /dev/zero does on Unix and
[[library_class:NULL_OUTPUT_STREAM|NULL_OUTPUT_STREAM]] that swallows any character like /dev/null does on Unix.

* directory
* basic_directory?

=== Arguments ===
print_arguments.e

=== Feature calls ===

=== Contracts ===
Contracts are the main reason why Eiffel is superior to many other languages...
...

=== Garbage collection ===
Eiffel is garbage collected. That means, the objects created on the heap will automatically be freed after they lost reachability from the rest of the executing program.

=== ACE files ===

=== Collections ===
including iterator and sorting

=== Downcasting ===
downcasting.e

== To go further ==

=== Agents ===
... and tuples

=== external ===

=== cecil ===

=== Memory management ===
memory

== Extension libraries ==

=== Random ===

=== Date & time ===

=== Storable ===

=== Sequencer ===

=== Vision ===
visiopn, signal

=== Network ===

=== Execution ===

Tutorial tour

2016-04-01T21:14:14Z

Tybor: /* Input-output */

Welcome to the guided tour of the tutorial!

All the classes in the tutorial are provided with your LibertyEiffel installation, in the <code>tutorial</code> directory.

=== Easy starting: Hello World! ===

To compile the program, go to the <code>LibertyEiffel/tutorial</code> directory and execute the command:

se c HELLO_WORLD make -o hello

The meaning of the command is
{|
|-
|<code>se</code>
|the front-end tool for the LibertyEiffel compiler
|-
|<code>c</code>
|the tool invoked by <code>se</code> for compile into an executable
|-
|<code>HELLO_WORLD</code>
|the class of which an object is created (you may also write it in lower-case, or use its filename with the <code>.e</code> extension) we call it root class, as this is the root of the programs object tree
|-
|<code>make</code>
|the creation procedure of the <code>HELLO_WORLD</code> class to call
|-
|<code>-o hello</code>
|generates an executable with the name hello (linux) or hello.exe (windows)
|}

The command produces an executable, usually <code>hello</code> or <code>hello.exe</code> depending on the system. After compiling is finished, you can run the executable.

This unavoidable program is in the file <code>hello_world.e</code> and lets you grasp the basic concepts of Eiffel. Those concepts are:
* '''Everything is a class'''. In Eiffel, outside classes there is no salvation.
* The program starts by '''creating an object''' (of the root class) and initializing it by execution of the given root creation procedure. Here, the <code>make</code> feature in the class <code>HELLO_WORLD</code>.
* Each file is named after the name of the class it contains, in lower-case, with the <code>.e</code> extension.
* Each class comes with a set of '''features''', all its attributes and methods which come in form of functions (if they return a result) or procedures (in case they just 'do' something)
* Note the special object <code>io</code> that allows you to write text on the standard output. We will see that it also lets you read data.
* For the Eiffel syntax, look [[Syntax_diagrams|here]].

Please take a look at the following examples in the tutorial folder to see some classical example programs (some of them are in organized in folders for better overview)
* fibonacci.e
* knight.e
* pyramide.e and pyramide2.e
* hanoi
* parking
* triangle

To compile the other samples you must obviously modify the compiler command to give another root class .

== Some important concepts ==

=== Comments ===
As in every programming language there is the possibility to write comments into the source code, which do not have any effect for the final program, but are for the developer or reader of the source code to get an understanding of the ideas and algorithms behind the code.
A comment in Eiffel starts with the sequence of a couple of minus signs and is terminated by a newline (RETURN).
-- this is a comment in Eiffel
a := b + 3 -- comments are also allowed after some code

=== Manifest notations ===
LibertyEiffel comes with a big set of available datatypes. Famous examples as INTEGER, BOOLEAN, CHARACTER and STRING. For those (and also many collection types) there is the possibility to directly denote them in the program code, using the notations
123
True, False
'a'
"STRING"
See tutorial file manifest_notation.e for an example with nearly all options to define objects by manifest notations.

=== Everything is an Object ===
As mentioned above, in Eiffel every useful thing is an object. There are two different kinds of objects: expanded objects and referenced object. Expanded objects are passed by value, while reference objects are - who guesses - passed by reference. In case you write 7 in the source code this is a shorthand for an instance of the expanded type INTEGER and therefore it is an expanded object. Whenever you assign it to a variable or pass it to another feature it gets copied. A STRING object - e. g. denoted by "Hello World!" in the source code is a reference object, created implicitly by the compiler, allocated on the heap and passed by reference.

=== Local variables and Assignments ===
Every routine may define variables in a "local block" before its body (which start with the keyword do):
make
local
a: INTEGER
s: STRING
do
a := 5
a := a + 1
s := "Hello World!"
end

The visibility of these variables is limited to the method they are defined in and they do not keep their value from one execution of that routine to another. Assignment is done by the assignment operator ":=" which changes the variable (or let's say writable entity) on the left side to the value of the expression on the right side. In case of the "Hello World!" assignment a new object of type STRING is created on the heap, initialized to the text "Hello World!" and a link to this object is stored in the local variable s.

=== Loops ===
In Eiffel we have exactly one construct to do something repeatedly, so no need to learn about for, do-while, while, anyhow, one is sufficient:
from
-- initialization
invariant
-- what shall stay true during repetition
variant
-- non-negative, but decreasing numeric value
until
-- termination condition
loop
-- what to do several times
end

Note, that the termination condition is an expression of type BOOLEAN and the loop body is executed until the condition evaluates to True, which differs in the logic from e. g. the loop constructs in C.

The most strange things for newcomers are probably the [https://en.wikipedia.org/wiki/Loop_invariant invariant] and the [https://en.wikipedia.org/wiki/Loop_variant variant]. While the first is a BOOLEAN condition, that stays true for every iteration, the latter is an INTEGER value which decreases with every iteration and always stays positive and therefore shows that the loop terminates. Both are optional and are not used very often in practice, even though they are essential in case we want to prove a program to be totally correct (and therefore terminates). I fear, that these formal loop assertions stay more or less unused until a formal verification tool is able to take real benefit from them.

See tutorial/loops.e for an example of the Greatest Common Divider algorithm to show the usage of the loop.

=== Input-output ===

==== io cluster ====

The input-output cluster is made up of several parts.

The io/basic subcluster contains the staples of

* the definitions of standard input and output streams, [[library_class:STD_INPUT|STD_INPUT]] and [[library_class:STD_OUTPUT|STD_OUTPUT]] that are available to all classes. In fact [[library_class:ANY|ANY]] offers those features:
** io: [[library_class:STD_INPUT_OUTPUT|STD_INPUT_OUTPUT]] -- Handle to standard file setup.
** std_input: [[library_class:STD_INPUT|STD_INPUT]] -- The standard input stream
** std_output: [[library_class:STD_OUTPUT|STD_OUTPUT]] -- The standard output stream
** std_error: [[library_class:STD_ERROR|STD_ERROR]] -- The standard error stream
** standard_streams: [[library_class:STANDARD_STREAMS|STANDARD_STREAMS]], a singleton that allows to redirect std_input_stream, std_output_stream as well as std_error_stream.

Beyond this standards streams that are available to all processes you can get read files in the operative file system using an [[library_class:INPUT_STREAM|INPUT_STREAM]] using [[library_class:BINARY_FILE_READ|BINARY_FILE_READ]] to read a binary file or [[library_class:TEXT_FILE_READ|TEXT_FILE_READ]] to read a text file.
Similarly, to write a file you use an [[library_class:OUTPUT_STREAM|OUTPUT_STREAM]] such as [[library_class:BINARY_FILE_WRITE|BINARY_FILE_WRITE]] for binary files or [[library_class:TEXT_FILE_WRITE|TEXT_FILE_WRITE]] for text files.

[[library_class:READLINE_INPUT_STREAM|READLINE_INPUT_STREAM]] is an input stream where the data is read from Command Line Interface (CLI) using the GNU readline library. You probabily have already used this library without knowing as it is used by several programs like

* directory
* basic_directory?

=== Arguments ===
print_arguments.e

=== Feature calls ===

=== Contracts ===
Contracts are the main reason why Eiffel is superior to many other languages...
...

=== Garbage collection ===
Eiffel is garbage collected. That means, the objects created on the heap will automatically be freed after they lost reachability from the rest of the executing program.

=== ACE files ===

=== Collections ===
including iterator and sorting

=== Downcasting ===
downcasting.e

== To go further ==

=== Agents ===
... and tuples

=== external ===

=== cecil ===

=== Memory management ===
memory

== Extension libraries ==

=== Random ===

=== Date & time ===

=== Storable ===

=== Sequencer ===

=== Vision ===
visiopn, signal

=== Network ===

=== Execution ===

Tutorial tour

2016-03-31T09:17:54Z

Tybor: /* Comments */

Lib/kernel

2016-03-30T15:59:55Z

Tybor: Created page with "The classes in the kenel cluster are basic === ANY === The class ANY is the everpresent root of all your objects. All classes defined in a Liberty Ei..."

The classes in the kenel cluster are basic

=== ANY ===

[[library_class:ANY|The class ANY]] is the everpresent root of all your objects.

All classes defined in a Liberty Eiffel system implicitly insert all the features of class [[library_class:ANY|ANY]].

Wrapping C libraries

2016-03-24T15:56:54Z

Tybor: /* Text to be still reviewd */

[[Category: Interfacing]]
== Developer's guidelines ==
=== or how to write GNU-Eiffel wrappers for a C library ===

<cite>
"longum iter est per praecepta, breve et efficax per exempla" 
"The path of precept is long, that of example short and effectual." 
Seneca the Elder 
</cite>

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

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 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.

==== Prerequites ====

You should be proficient with:

* the C 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.

==== Software prerequisites ====

Make sure you have access on your machine to:

* 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

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.

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.

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.

Let's return to our wrapping/binding work after a due phylosophical digression

=== Preliminares ===

Most data structure in C are usually handled by reference, i.e. using pointers.

Passing objects by value is currently requires "expanded external classes" and will no be covered in this guide. Therefore if your library extensively pass structures around by value and not by reference (with a pointer), for example (TODO: put links to online example of passing structure by value) in function calls or contained in other structures our life will be quite hard. Fortunately enought most libraries handles most of its data structures by reference and zlib is no exception: in fact its basic functions takes pointers as first argument.

----
== Identifying types and classes ==

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.

A simplicistic rule-of-thumb specifically fitted to wrap libraries written in C is that when we have several functions that takes a pointer to a struct this struct is a good candidate for a class and those functions are good candidates to be wrapped as features usable by an Eiffel program.

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.

=== Code organization and class hierarchy. ===

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.

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)
**** 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

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:

* eiffel-glib/library/
** core
** data_types
** externals
*** generated
** fundamentals
** utilities

Let's fill <code>zlib/library/loadpath.se</code>. It lists two directories: those containing the high-level classes, the same of the loadpath.se file itself, i.e. the current directory (.) and the ./externals directory which will contain deferred classes that provide access to external features.

<pre>
./
./externals/
</pre>

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>:

<pre>
../common/loadpath.se
./library/loadpath.se
</pre>

=== Low-level access to functions ===

Writing the Eiffel source code to access external C code is an extremely long, tedious and verbose process so a tool named '''wrappers_generator''' has been created.

It was not included in binary form in the adler release since it was not ready for prime time.
Now it isn't robust as I would like but at least it processes sources like Gtk3, Glib, &slasho;mq and other libraries without crashing.

It will be included into bell and later releases; before it's relase I would suggest to rebuild the compiler and work from the Git repository.

You can get the sources from https://savannah.gnu.org/projects/liberty-eiffel/ or from https://github.com/LibertyEiffel/Liberty and build it with install.sh script which also build wrappers_generator.

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.

Given an XML file and a list of C files (headers or sources) to wrap wrappers_generator:

* for each source file create a deferred class containing all the wrappable functions found in that file; functions in foo.h are wrapped into FOO_EXTERNALS
* for each struct creates a deferred class containing queries and setters feature to manipulate all members which have an Eiffel wrapper type;
* the same is made for unions
* creates a deferred Eiffel class named like the xml file containing wrappers for all typedefs, so when you have to refer to C "long" which is notorious for change size on various platform you can use "like long" in Eiffel
* each enumeration is wrapped into expanded classes with proper queries and setters. That way they are as efficient as plain integers values but they can't assume arbitrary values; enum foobar is wrapped into FOOBAR_ENUM
* when the values of an enumeration are actually flags, i.e. they all are diffent powers of 2, it's wrapped as a "flag" enumeration with commands to set and unset each flag of the enum.
* C++ classes, namespaces and all its fineries are currently ignored
* macros, #defines and all cannot be handled since they are "preprocessed away" and their text is not preseted to gccxml or castxml
* variadic functions can't be wrapped in Eiffel
* it transform CamelCase into CAMEL_CASE for classes, camel_case for features (queries, commands and so on)
* 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.

=== 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
C function Eiffel feature
const char * zlibVersion (void); zlib_version: POINTER
int deflateInit (z_streamp strm, int level); deflate_init (a_stream: POINTER; a_level: INTEGER_32): INTEGER_32
int deflate (z_streamp strm, int flush); deflate (a_stream: POINTER;a_flush: INTEGER_32): INTEGER
int deflateEnd (z_streamp strm); deflate_end (a_stream: POINTER): INTEGER
int inflateInit (z_streamp strm); inflate_init (a_stream: POINTER): INTEGER
int inflate (z_streamp strm, int flush); inflate (a_stream: POINTER; a_flush: INTEGER): INTEGER
int inflateEnd (z_streamp strm); inflate_end (a_stream: POINTER): INTEGER

As you can see I have turned camelCaseFunction into camel_case_function which is far more in tune with Eiffel style. Int is actually an INTEGER_32 or only INTEGER (it still don't matter, even if I suspect that it will do soon: world is already filled with 64-bit machines and literally billion of devices with 4,8,16 bit CPU are in use today, not counting GPGPU)

Let's take a look at ZLIB_EXTERNALS. You'll see many entries like

inflate_init (a_stream: POINTER): INTEGER is -- int inflateInit (z_streamp strm);
external "plug_in"
alias "{
location: "${eiffel_libraries}/plugins"
module_name: "zlib"
feature_name: "inflateInit"
}"
end

this entry tells us that the Eiffel feature "inflate_init" refers to the symbol "inflateInit" in the module "zlib" of the plugins found in the directory.

Entries like this are the only "esoteric" Eiffel code you will see. All the details required to interface to C, to link to the actualy library and how to compile the code written in other languages is handled by the plugin part.

Without using plugins every Eiffel program should know all the details required to compile a C application with zlib. It would require to always use ACE files - even for simple examples - because you need to provide proper "c_compiler_options" and "linker_options"; for a single, simple library like Zlib it looks a tame task, only requiring to add -lzlib to the "linker_options" but when you start building real-world application things will get complicated really fast.

See SmartEiffel documentation on plugins.

All those functions returns an integer with standardized values #defined in the C header. We will wrap them in the deferred class ZLIB_CONSTANTS.

Deferred? Why deferred? We want to avoid the Eiffel programmer the burden to deal with all the details that C requires - otherwise we would have used plain C - so we do not want him/her to directly use that libraries. Deferred classes cannot have creation clauses so we are sure that no objects of type ZLIB_EXTERNALS and ZLIB_CONSTANTS will be created. They are helper classes that will be either inherited from or - more properly - inserted into ZLIB_STREAM and its effective heirs, ZLIB_INPUT_STREAM and ZLIB_OUTPUT_STREAM.

Making sure that the Eiffel developer will not use low-level features directly is the main reason why all the external features are not exported to anyone else, using the syntax feature {} -- External calls. This way only heirs - conforming or not - of that class can use them; for people coming from C++ it's like having private functions members.
C types

Here's a quick conversion table for various C types
C type Eiffel type
int INTEGER;
short int INTEGER_16
long int INTEGER_32 or 64
long long int INTEGER_64
int8_t (defined at stdint.h, ISO C 99) INTEGER_8
int16_t INTEGER_16
int32_t INTEGER_32
int64_t INTEGER_64
unsigned int NATURAL
unsigned short int NATURAL_16
unsigned long int NATURAL_32 on 32-bit, NATURAL_64 on 64.bit. See long int
unsigned long long int NATURAL_64
signed/unsigned char CHARACTER
float REAL_32
double REAL_64
long double REAL_EXTENDED
char BOOLEAN
void* or any other pointer POINTER

Some notes:

intXX_t are defined in GNU systems (Linux Glibc, CygWin and similar).
Currently INTEGER is mere alias for INTEGER_32 but this is bound to change in future version of SmartEiffel. Personally I think that it should be "the integer type with the same bit-lenght of C int".
A nice feature of long int is that is could be longer that int. So we can't really be sure whenever it is 32 or 64 bit. Usually it is an INTEGER_32 on 32-bit machines and INTEGER_64 on 64-bit machines. See this post on the SmartEiffel mailing list.
The same problem applies for long unsigned int: NATURAL_32 on 32-bits and NATURAL_64 on 64-bit. This mismatch can be quite problematic and it will be discussed-addressed later.
At the time of writing of this document SmartEiffel has some know issues regarding NATURALs types. If they actually do cause bugs there is an (unsatisfactory) workaround: use a bigger INTEGER. This implies a hidden conversion at C level and bargains correctness with a little waste of space and worse performance. Do not use an INTEGER of same size: it "usually" works nicely but this is a known source of nasty bugs since you will soon or later it will silently overflow.

An enlighting explanation about C variable types and declarations can be read on Wikipedia (I find particurarly confusing - expecially for the novice - that char is at the same time an 8-bit integer and an encoding for ASCII characters. Most programmers could always end up thinking about it only as a character. After more than 30 years they could have called it "byte". Yet this behaviour is fit the spirit of C very well. ).

The resulting ZLIB_CONSTANTS class is almost boring and undocumented. I maintained the documentation level found in the original documentation, since those are values that will be handled only by the implementation of the wrapper.

Have a look at WRAPPER_HANDLER. Eiffel has the ability to selectively export Any class that needs to access some of the
Access to structure field

Let's wrap the z_stream structure (the structure name is actually struct z_stream_s typedeffed to z_stream during its definition); the wrapper will have a similar two layer design: the low-level Z_STREAM_STRUCT will be a deferred class, with feature {} -- Hidden, low-level getters and setters. This class will also have a feature struct_size: INTEGER that will be the value of sizeof(z_stream)

Field named FooBar in the struct my_struct will be read with the Eiffel query my_struct_get_foo_bar and set with the command my_struct_set_foo_bar. Remember that those are low-level features; references to other objects will be pointers and its signature will be one of an external function: the first argument will be always the address of - a POINTER to - the wrapped struct.
Naming of placeholder arguments

Placeholder names should be chosen in a way that makes the documentation of the feature in English as smooth as possible for a proper argument placeholder for the Gnu-Eiffel language. "CamelCase" will be translated into "a_camel_case", "ENOO" is translated into "an_enoo". Eventual underscores in front of `a_name' are removed: "__foo" becomes "a_foo". The prefixed preposition is added to make clearer that the name refers to a generic value, not to a particular one. Always tries to use a placeholder that can be directly put in the feature's documentation without paraphrase.
ZLIB_STREAM, at last.

So let's write something that will be used in an actual Eiffel program! We start writing ZLIB_STREAM from file common/skeleton that provides us the usual LGPL-2.1-or-later headers. It inserts ZLIB_EXTERNALS and Z_STREAM_STRUCT.

TODO: finish this
The "common" cluster

The basic building blocks of a wrapper library have been put in the common cluster.

The WRAPPER class it the "fundamental" one even if embarassingly simple. Its only effective field (i.e.: stored, non-computed) is the handle POINTER. It shall handle the allocation and deallocation of the memory referred by handle so it is an heir of DISPOSABLE but it doesn't define dispose because there is no such a thing like a default memory handling in C.

C_STRUCT inherits from WRAPPER and provides default implementations for copy, is_equal and from_external_pointer features; it introduces the deferred "struct_size" query which should give the same result of C operator sizeof(MyStruct).

Note that there are - at least conceptually - other potentially heirs of WRAPPER, like pointers to functions

Many C libraries often return const char* strings. Those strings shall not be modified and their memory will be handled by the library; by all other means they actually are plain strings. A correct behaviour is to write foo: STRING is do create Result.from_external_copy(a_function_returning_a_const_char_pointer(handle)) end; a STRING is meant to be manipulated and changed and has control on the memory of its content. Here we are instead given a piece of memory holding some text that is "mostly read-only" whose control is held by the library. To provide correct behaviour STRING must copy the buffer, from_external can't be used. CONST_STRING is an effective heir of STRING that provides efficient wrapping of "const strings". It is usable like any other STRING but all the changes are made to a separe buffer preserving the original content - we are actually not allowed to change it. No further memory is allocated when a CONST_STRING is created: the buffer returned by the C library is used directly. For example, GTK+ has many calls like const gchar* gtk_entry_get_text (GtkEntry *entry); Memory efficiency is achieved making changing features slower. If you need to change its content consider using its feature string to get a new (non-const) STRING with the same content.

TODO: add proper description about:
CACHING_FACTORY
C_ARRAY
COMPARABLE_C_STRUCT
COMPARABLE_WRAPPER
CONST_STRING
C_OWNED
C_STRUCT
EIFFEL_OWNED
ENUM
EXPANDED_WRAPPER
GLOBAL_CACHE
GLOBALLY_CACHED
HASHABLE_WRAPPER
ITERATOR_ON_C_ARRAY
LINKED_STRING
MIXED_MEMORY_HANDLING
NULL_TERMINATED_C_ARRAY
NULL_TERMINATED_STRING_ARRAY
POINTER_HANDLING
REFERENCE_COUNTED
SHARED
STRING_ARRAY
STRING_ARRAY_ITERATOR
WRAPPER_COLLECTION
WRAPPER_DICTIONARY
WRAPPER
WRAPPER_FACTORY
WRAPPER_HANDLER
WRAPPERS_CACHE
Enumerations

There are two general tecnique to wrap an enum.

Put all the possible values of enumerations into a class as INTEGER constants accessibile to the user of your library. This is mostly similar to the actual usage of an enumeration. Each and every feature that accept an enum value as argument will need a precondition like is_valid_foo (a_foo_value)
Create a new type. In fact an enumeration is an INTEGER that can assume only precise and prestabilited values, so that its value is correct and consistent all the times. Class ENUM provides some facilities to achieve this. It shall be used in classes like this:

-- This file have been created by eiffel-gcc-xml.
-- Any change will be lost by the next execution of the tool.

expanded class PANGO_WEIGHT

insert ENUM

creation default_create
feature -- Validity
is_valid_value (a_value: INTEGER): BOOLEAN is
do
Result := ((a_value = pango_weight_ultralight) or else
(a_value = pango_weight_light) or else
(a_value = pango_weight_normal) or else
(a_value = pango_weight_semibold) or else
(a_value = pango_weight_bold) or else
(a_value = pango_weight_ultrabold) or else
(a_value = pango_weight_heavy))
end

feature -- Setters
default_create, set_ultralight is
do
value := pango_weight_ultralight
end

set_light is
do
value := pango_weight_light
end

set_normal is
do
value := pango_weight_normal
end

set_semibold is
do
value := pango_weight_semibold
end

set_bold is
do
value := pango_weight_bold
end

set_ultrabold is
do
value := pango_weight_ultrabold
end

set_heavy is
do
value := pango_weight_heavy
end

feature -- Queries
is_ultralight: BOOLEAN is
do
Result := (value=pango_weight_ultralight)
end

is_light: BOOLEAN is
do
Result := (value=pango_weight_light)
end

is_normal: BOOLEAN is
do
Result := (value=pango_weight_normal)
end

is_semibold: BOOLEAN is
do
Result := (value=pango_weight_semibold)
end

is_bold: BOOLEAN is
do
Result := (value=pango_weight_bold)
end

is_ultrabold: BOOLEAN is
do
Result := (value=pango_weight_ultrabold)
end

is_heavy: BOOLEAN is
do
Result := (value=pango_weight_heavy)
end

feature {WRAPPER, WRAPPER_HANDLER} -- Low level values
pango_weight_ultralight: INTEGER is
external "plug_in"
alias "{
location: "foo"
module: "bar"
feature_name: "PANGO_WEIGHT_ULTRALIGHT"
}"
end

pango_weight_light: INTEGER is
external "plug_in"
alias "{
location: "foo"
module: "bar"
feature_name: "PANGO_WEIGHT_LIGHT"
}"
end

pango_weight_normal: INTEGER is
external "plug_in"
alias "{
location: "foo"
module: "bar"
feature_name: "PANGO_WEIGHT_NORMAL"
}"
end

pango_weight_semibold: INTEGER is
external "plug_in"
alias "{
location: "foo"
module: "bar"
feature_name: "PANGO_WEIGHT_SEMIBOLD"
}"
end

pango_weight_bold: INTEGER is
external "plug_in"
alias "{
location: "foo"
module: "bar"
feature_name: "PANGO_WEIGHT_BOLD"
}"
end

pango_weight_ultrabold: INTEGER is
external "plug_in"
alias "{
location: "foo"
module: "bar"
feature_name: "PANGO_WEIGHT_ULTRABOLD"
}"
end

pango_weight_heavy: INTEGER is
external "plug_in"
alias "{
location: "foo"
module: "bar"
feature_name: "PANGO_WEIGHT_HEAVY"
}"
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.

Using eiffel-gcc-xml

Have a look at the manually written ZLIB_EXTERNALS. Eiffel is a language that is meant to be easy to the reader at the cost of being verbose. All that text of source to access a bunch of C functions. Think about serious libraries that have literally thousands of functions, structures, and enumeration! Writing the low level side of those wrappers is a really long, tedious task, the kind of task that people usually would leave to an unfaticable, astonishgly fast yet quite dumb worker, a computer. Andreas Leitner - who is surely quite smarter than myself - wrote a C parser for his Eiffel Wrapper Generator. I do not have neither the time neither the abilities of Andreas but it seems that I'm more lucky than him. In fact by the time I got serious with this project, people with the same problem, requiring tons of wrappers for Python, produced gcc-xml. These days parsing XML is a considered a common task, a task to be left to standard libraries, so SmartEiffel have an XML parser. So I wrote a little tool name "eiffel-gcc-xml" that takes the output of gcc-xml as input to produce the low-level "external" classes that we need to access functions, structures and enumerations.

Well, it actually requires a little more work since it breaks very often.
Memory handling
C_STRUCT is a wrapper for a data structure implemented in C programming language using a structure.
It does not make any assumption about memory handling; the developer of a SmartEiffel wrapper of a C library has to inherit to create a proper wrapper for it the developer shall inherit both from this class and from classes providing memory handling behavior, depending on how structure's memory shall be handled. This is decided case-by-case by C library.
Currently available memory handling classes are:

C_OWNED: memory is always handled by the underlying C library.
EIFFEL_OWNED: once created memory is fully handled by Eiffel runtime, usually with the Garbage Collector.
GLOBALLY_CACHED: Until disposed by Eiffel the wrapper registered in wrappers dictionary will be the unique wrapper used on the Eiffel side.
MIXED_MEMORY_HANDLING: whose memory can either by handled by the Eiffel library or by the underlying C code. Who handles memory is decided on a per-object based on the value of the flag `is_shared': handle will not be freed on dispose of the Eiffel wrapper object, when `is_shared' is true.
REFERENCE_COUNTED: memory is handled thought reference counting, i.e.GObject

Add proper examples of the various memory handling classes.
Implementing collections
Quite often objects are stored into containers or collections like arrays, linked lists, dictionaries, hashed-tables and so on. Many C libraries provides their own implementation of the classic containers, for example the GLib library provides GList, GSList, GHashTable and many others.
A WRAPPER_COLLECTION is a COLLECTION implemented wrapping some facilities offered by the wrapped C library, like GLib's linked list GList.
When you wrap those data structures you will encounter two kinds of problems:

Pointer returned by C containers could be newly allocated, not already wrapped by the Eiffel wrapper or already wrapper by the Eiffel wrapper. You can't naively create a new WRAPPER every time. Beside the obvious waste of memory and the stress you put on the garbage collector you will break most postconditions and invariant of a COLLECTION, since things that seems obvious like

do_stuff (my_collection: WRAPPER_COLLECTION[ITEM]) is require
my_collection/=Void not my_collection.is_empty local a,b: ITEM do a :=
my_collection.first b := my_collection.first check will_fail: a = b end end

In fact a and b will be different wrappers referring to the same underlying C structure. A WRAPPER_COLLECTION shall avoid this repeated, unnecessary and wrong creation of WRAPPERs, that will breaks invariants and post-conditions of a COLLECTION.
A solution is to inherit from WRAPPERS_CACHE, initializing cache at creation time and keeping it updated during usage. Cache's key is the address (pointer) to the wrapped C structure, value is the corresponding Eiffel wrapper. This way you can get back an already-created Eiffel wrapper.
Classes can implement different scheme; for example G_OBJECT_LIST retrieve the reference to the eventual WRAPPER directly from underlying GObject.

The container has no means to know how it shall create the wrapper for it, since C does not have the notion of generic, strongly typed container. The effective type of the containee is either not know by WRAPPER_COLLECTION or worse its conteinees could actually belong to different classes, sharing a common ancestor.
Since each library has its own idea on how the programmer shall handle �memory when dealing with containers an effective, non-deferred heir of WRAPPER_COLLECTION shall implement `wrapper' feature that given a pointer creates or retrieve a WRAPPER of the fittest class. Usually "plain" usage could return a fixed type; more elaborate type systems like GObject could provide the facilities necessary to pick a useful Eiffel type.

TODO: finish it.
Comparability and hashability
Some collections does not require anything in particular to their containee, like arrays or linked lists. Other collections needs either to compare their containee or to obtain an hash value from it. Therefore wrapper classes that are conceptually comparable or hashable shall inherit from COMPARABLE_WRAPPER and HASHABLE_WRAPPER respectively so they could be stored into collections that requires such abilities.
How to adapt old wrappers
(This is almost obsolete) Previous design was a black-or-white design: a class was either Eiffel-owned or not; C_STRUCT's are "owned" by the Eiffel code, and the Eiffel side should keep then longest lived reference to this struct; SHARED_C_STRUCT modelled the non-Eiffel-owned.
This approach is overly simplicistic since real-life libraries implement a wide spectrum of memory handling policies. One solutions does not fit all needs. Study the documentation of the library and pick the right memory handling Eiffel class.
The long int problem

Shortly it could be solved having two separate clusters one for 32bit, one for 64 bit where a deferred class defines a parameterless query for anchored declaration like

long_int: INTEGER_32 is do end

long_int: INTEGER_64 is do end

but this looks like an unfeasible hack to me, at least now. Currently it is the only available answer; a "proper" solution would require changes in both the compiler and the standard library. I would like to know how ISE solved this.

GObject-based libraries

Nowadays many libraries are based on the GLib Object System also known as Gobject. This library "provides a portable object system and transparent cross-language interoperability". It is used as the basic building block for literally hundeds of libraries and applications; in fact the command apt-cache rdepends libglib2.0-0 |wc -l told me that more than 2200 applications and libraries depend on either GLib or GObject.

GObject implement its own classed type system. With the exception of basic types (and some other subtleties I will write later) all objects are structures referred by pointer, i.e. non-expanded classes in Eiffellese; the type of each object is identified by a number, a GType which has an associated structure to describe the class - the type - itself. During startup of the Eiffel application the wrapper library will register for each type name (i.e. GtkWindow, GtkButton....) it wraps an agent that given a pointer creates an Eiffel wrapper object for the creation_agents dictionary, with a call similar to creation_agents.put (agent create_gtk_window, "GtkWindow"), given the feature create_gtk_window (p: POINTER): GTK_WINDOW is do create Result.from_external_pointer(p) end.

A Gobject can store arbitrary properties into itself. We use this to store a reference pointer to its Eiffel wrapper.

When we receive a pointer to a Gobject the G_OBJECT_FACTORY first looks if this Gobject already has an attacked wrapper (an effective heir of G_OBJECT). Otherwise it ask the Gobject its GType and the associated class-name. It this class-name has a creation agent the wrapper is created invoking the retrieved creation agent; otherwise we recursively look at its parent class until we find a type that has a corresponding creation agent.

When an effective G_OBJECT heir is actually created either explicitly because we know for sure its type or throught a creation agent the address of the wrapper is stored in the property "eiffel-wrapper" using the C function g_object_set_qdata (see store_eiffel_wrapper in G_OBJECT).

As usual this approach is both correct, memory efficient and collection-friendly (see "Implementing collections" earlier) at the cost of being computing intensive. There are times when the wrapper library has to create transient wrappers for shortly lived objects. Here enters secondary wrappers, or G_OBJECTs that are not referred-by the GOBject they refer to. Letting code speak: having a_gtk_window_ptr: POINTER; my_window: GTK_WINDOW; factory: G_OBJECT_EXPANDED_FACTORY check create my_window.secondary_wrapper_from(a_gtk_window_ptr) /= factory.wrapper(a_gtk_window_ptr) end will hold and also create my_window.main_wrapper_from(a_gtk_window_ptr); check my_window = factory.wrapper(a_gtk_window_ptr) end will be successfully passed. The difference is that the first is only an allocation of a smallish object (few bytes) while the latter could potentially require several looks-up into a dictionary plus an O(n) search into the GObject properties (during g_object_get_qdata used to see if a wrapper does actually exist)

TODO: show how to wrap a typical GObject-using library, like Gnome's GConf configuration system.
Commit's policy

There is no strict rule...
Ideally each commit should provide compilable code and working examples.
Provided examples and classes can be unfinished and uncomplete, can contain warnings, empty features and so on. My motto is "something is better than nothing".
it is nice to tell other developers what are you working on; anemail on eiffel-libraries-devel@gna.org suffice.
I promise I won't track you with a 9-tail cat to bash you if you commit uncompilable code.
Code that compiles is a good thing. Wisely designed code that compiles is better, since it has better performances; but I prefer published, working code even if has no state-of-the-art performances instead of

Various very old notes
Those notes are left here to be worked on.

Suggested
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.
Sketch difficoult features into comments.
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.
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.

=== Incoming tools ===

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

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

This will give us support for Gtk3, Glib, Cairo and many many other libraries in a much faster way that manually wrapping each one.

The tool that will generate such binding will be named '''leggow''', acronym for '''Liberty Eiffel Generator of GObject Wrappers''' and it currently lies in the leggow branch in repository https://github.com/tybor/Liberty but it is currently only an idea.

Wrapping C libraries

2016-03-24T15:56:25Z

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

[[Category: Interfacing]]
== Developer's guidelines ==
=== or how to write GNU-Eiffel wrappers for a C library ===

<cite>
"longum iter est per praecepta, breve et efficax per exempla" 
"The path of precept is long, that of example short and effectual." 
Seneca the Elder 
</cite>

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

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 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.

==== Prerequites ====

You should be proficient with:

* the C 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.

==== Software prerequisites ====

Make sure you have access on your machine to:

* 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

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.

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.

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.

Let's return to our wrapping/binding work after a due phylosophical digression

=== Preliminares ===

Most data structure in C are usually handled by reference, i.e. using pointers.

Passing objects by value is currently requires "expanded external classes" and will no be covered in this guide. Therefore if your library extensively pass structures around by value and not by reference (with a pointer), for example (TODO: put links to online example of passing structure by value) in function calls or contained in other structures our life will be quite hard. Fortunately enought most libraries handles most of its data structures by reference and zlib is no exception: in fact its basic functions takes pointers as first argument.

----
== Identifying types and classes ==

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.

A simplicistic rule-of-thumb specifically fitted to wrap libraries written in C is that when we have several functions that takes a pointer to a struct this struct is a good candidate for a class and those functions are good candidates to be wrapped as features usable by an Eiffel program.

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.

=== Code organization and class hierarchy. ===

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.

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)
**** 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

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:

* eiffel-glib/library/
** core
** data_types
** externals
*** generated
** fundamentals
** utilities

Let's fill <code>zlib/library/loadpath.se</code>. It lists two directories: those containing the high-level classes, the same of the loadpath.se file itself, i.e. the current directory (.) and the ./externals directory which will contain deferred classes that provide access to external features.

<pre>
./
./externals/
</pre>

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>:

<pre>
../common/loadpath.se
./library/loadpath.se
</pre>

=== Low-level access to functions ===

Writing the Eiffel source code to access external C code is an extremely long, tedious and verbose process so a tool named '''wrappers_generator''' has been created.

It was not included in binary form in the adler release since it was not ready for prime time.
Now it isn't robust as I would like but at least it processes sources like Gtk3, Glib, &slasho;mq and other libraries without crashing.

It will be included into bell and later releases; before it's relase I would suggest to rebuild the compiler and work from the Git repository.

You can get the sources from https://savannah.gnu.org/projects/liberty-eiffel/ or from https://github.com/LibertyEiffel/Liberty and build it with install.sh script which also build wrappers_generator.

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.

Given an XML file and a list of C files (headers or sources) to wrap wrappers_generator:

* for each source file create a deferred class containing all the wrappable functions found in that file; functions in foo.h are wrapped into FOO_EXTERNALS
* for each struct creates a deferred class containing queries and setters feature to manipulate all members which have an Eiffel wrapper type;
* the same is made for unions
* creates a deferred Eiffel class named like the xml file containing wrappers for all typedefs, so when you have to refer to C "long" which is notorious for change size on various platform you can use "like long" in Eiffel
* each enumeration is wrapped into expanded classes with proper queries and setters. That way they are as efficient as plain integers values but they can't assume arbitrary values; enum foobar is wrapped into FOOBAR_ENUM
* when the values of an enumeration are actually flags, i.e. they all are diffent powers of 2, it's wrapped as a "flag" enumeration with commands to set and unset each flag of the enum.
* C++ classes, namespaces and all its fineries are currently ignored
* macros, #defines and all cannot be handled since they are "preprocessed away" and their text is not preseted to gccxml or castxml
* variadic functions can't be wrapped in Eiffel
* it transform CamelCase into CAMEL_CASE for classes, camel_case for features (queries, commands and so on)
* 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.

==== Text to be still reviewd ====

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
C function Eiffel feature
const char * zlibVersion (void); zlib_version: POINTER
int deflateInit (z_streamp strm, int level); deflate_init (a_stream: POINTER; a_level: INTEGER_32): INTEGER_32
int deflate (z_streamp strm, int flush); deflate (a_stream: POINTER;a_flush: INTEGER_32): INTEGER
int deflateEnd (z_streamp strm); deflate_end (a_stream: POINTER): INTEGER
int inflateInit (z_streamp strm); inflate_init (a_stream: POINTER): INTEGER
int inflate (z_streamp strm, int flush); inflate (a_stream: POINTER; a_flush: INTEGER): INTEGER
int inflateEnd (z_streamp strm); inflate_end (a_stream: POINTER): INTEGER

As you can see I have turned camelCaseFunction into camel_case_function which is far more in tune with Eiffel style. Int is actually an INTEGER_32 or only INTEGER (it still don't matter, even if I suspect that it will do soon: world is already filled with 64-bit machines and literally billion of devices with 4,8,16 bit CPU are in use today, not counting GPGPU)

Let's take a look at ZLIB_EXTERNALS. You'll see many entries like

inflate_init (a_stream: POINTER): INTEGER is -- int inflateInit (z_streamp strm);
external "plug_in"
alias "{
location: "${eiffel_libraries}/plugins"
module_name: "zlib"
feature_name: "inflateInit"
}"
end

this entry tells us that the Eiffel feature "inflate_init" refers to the symbol "inflateInit" in the module "zlib" of the plugins found in the directory.

Entries like this are the only "esoteric" Eiffel code you will see. All the details required to interface to C, to link to the actualy library and how to compile the code written in other languages is handled by the plugin part.

Without using plugins every Eiffel program should know all the details required to compile a C application with zlib. It would require to always use ACE files - even for simple examples - because you need to provide proper "c_compiler_options" and "linker_options"; for a single, simple library like Zlib it looks a tame task, only requiring to add -lzlib to the "linker_options" but when you start building real-world application things will get complicated really fast.

See SmartEiffel documentation on plugins.

All those functions returns an integer with standardized values #defined in the C header. We will wrap them in the deferred class ZLIB_CONSTANTS.

Deferred? Why deferred? We want to avoid the Eiffel programmer the burden to deal with all the details that C requires - otherwise we would have used plain C - so we do not want him/her to directly use that libraries. Deferred classes cannot have creation clauses so we are sure that no objects of type ZLIB_EXTERNALS and ZLIB_CONSTANTS will be created. They are helper classes that will be either inherited from or - more properly - inserted into ZLIB_STREAM and its effective heirs, ZLIB_INPUT_STREAM and ZLIB_OUTPUT_STREAM.

Making sure that the Eiffel developer will not use low-level features directly is the main reason why all the external features are not exported to anyone else, using the syntax feature {} -- External calls. This way only heirs - conforming or not - of that class can use them; for people coming from C++ it's like having private functions members.
C types

Here's a quick conversion table for various C types
C type Eiffel type
int INTEGER;
short int INTEGER_16
long int INTEGER_32 or 64
long long int INTEGER_64
int8_t (defined at stdint.h, ISO C 99) INTEGER_8
int16_t INTEGER_16
int32_t INTEGER_32
int64_t INTEGER_64
unsigned int NATURAL
unsigned short int NATURAL_16
unsigned long int NATURAL_32 on 32-bit, NATURAL_64 on 64.bit. See long int
unsigned long long int NATURAL_64
signed/unsigned char CHARACTER
float REAL_32
double REAL_64
long double REAL_EXTENDED
char BOOLEAN
void* or any other pointer POINTER

Some notes:

intXX_t are defined in GNU systems (Linux Glibc, CygWin and similar).
Currently INTEGER is mere alias for INTEGER_32 but this is bound to change in future version of SmartEiffel. Personally I think that it should be "the integer type with the same bit-lenght of C int".
A nice feature of long int is that is could be longer that int. So we can't really be sure whenever it is 32 or 64 bit. Usually it is an INTEGER_32 on 32-bit machines and INTEGER_64 on 64-bit machines. See this post on the SmartEiffel mailing list.
The same problem applies for long unsigned int: NATURAL_32 on 32-bits and NATURAL_64 on 64-bit. This mismatch can be quite problematic and it will be discussed-addressed later.
At the time of writing of this document SmartEiffel has some know issues regarding NATURALs types. If they actually do cause bugs there is an (unsatisfactory) workaround: use a bigger INTEGER. This implies a hidden conversion at C level and bargains correctness with a little waste of space and worse performance. Do not use an INTEGER of same size: it "usually" works nicely but this is a known source of nasty bugs since you will soon or later it will silently overflow.

An enlighting explanation about C variable types and declarations can be read on Wikipedia (I find particurarly confusing - expecially for the novice - that char is at the same time an 8-bit integer and an encoding for ASCII characters. Most programmers could always end up thinking about it only as a character. After more than 30 years they could have called it "byte". Yet this behaviour is fit the spirit of C very well. ).

The resulting ZLIB_CONSTANTS class is almost boring and undocumented. I maintained the documentation level found in the original documentation, since those are values that will be handled only by the implementation of the wrapper.

Have a look at WRAPPER_HANDLER. Eiffel has the ability to selectively export Any class that needs to access some of the
Access to structure field

Let's wrap the z_stream structure (the structure name is actually struct z_stream_s typedeffed to z_stream during its definition); the wrapper will have a similar two layer design: the low-level Z_STREAM_STRUCT will be a deferred class, with feature {} -- Hidden, low-level getters and setters. This class will also have a feature struct_size: INTEGER that will be the value of sizeof(z_stream)

Field named FooBar in the struct my_struct will be read with the Eiffel query my_struct_get_foo_bar and set with the command my_struct_set_foo_bar. Remember that those are low-level features; references to other objects will be pointers and its signature will be one of an external function: the first argument will be always the address of - a POINTER to - the wrapped struct.
Naming of placeholder arguments

Placeholder names should be chosen in a way that makes the documentation of the feature in English as smooth as possible for a proper argument placeholder for the Gnu-Eiffel language. "CamelCase" will be translated into "a_camel_case", "ENOO" is translated into "an_enoo". Eventual underscores in front of `a_name' are removed: "__foo" becomes "a_foo". The prefixed preposition is added to make clearer that the name refers to a generic value, not to a particular one. Always tries to use a placeholder that can be directly put in the feature's documentation without paraphrase.
ZLIB_STREAM, at last.

So let's write something that will be used in an actual Eiffel program! We start writing ZLIB_STREAM from file common/skeleton that provides us the usual LGPL-2.1-or-later headers. It inserts ZLIB_EXTERNALS and Z_STREAM_STRUCT.

TODO: finish this
The "common" cluster

The basic building blocks of a wrapper library have been put in the common cluster.

The WRAPPER class it the "fundamental" one even if embarassingly simple. Its only effective field (i.e.: stored, non-computed) is the handle POINTER. It shall handle the allocation and deallocation of the memory referred by handle so it is an heir of DISPOSABLE but it doesn't define dispose because there is no such a thing like a default memory handling in C.

C_STRUCT inherits from WRAPPER and provides default implementations for copy, is_equal and from_external_pointer features; it introduces the deferred "struct_size" query which should give the same result of C operator sizeof(MyStruct).

Note that there are - at least conceptually - other potentially heirs of WRAPPER, like pointers to functions

Many C libraries often return const char* strings. Those strings shall not be modified and their memory will be handled by the library; by all other means they actually are plain strings. A correct behaviour is to write foo: STRING is do create Result.from_external_copy(a_function_returning_a_const_char_pointer(handle)) end; a STRING is meant to be manipulated and changed and has control on the memory of its content. Here we are instead given a piece of memory holding some text that is "mostly read-only" whose control is held by the library. To provide correct behaviour STRING must copy the buffer, from_external can't be used. CONST_STRING is an effective heir of STRING that provides efficient wrapping of "const strings". It is usable like any other STRING but all the changes are made to a separe buffer preserving the original content - we are actually not allowed to change it. No further memory is allocated when a CONST_STRING is created: the buffer returned by the C library is used directly. For example, GTK+ has many calls like const gchar* gtk_entry_get_text (GtkEntry *entry); Memory efficiency is achieved making changing features slower. If you need to change its content consider using its feature string to get a new (non-const) STRING with the same content.

TODO: add proper description about:
CACHING_FACTORY
C_ARRAY
COMPARABLE_C_STRUCT
COMPARABLE_WRAPPER
CONST_STRING
C_OWNED
C_STRUCT
EIFFEL_OWNED
ENUM
EXPANDED_WRAPPER
GLOBAL_CACHE
GLOBALLY_CACHED
HASHABLE_WRAPPER
ITERATOR_ON_C_ARRAY
LINKED_STRING
MIXED_MEMORY_HANDLING
NULL_TERMINATED_C_ARRAY
NULL_TERMINATED_STRING_ARRAY
POINTER_HANDLING
REFERENCE_COUNTED
SHARED
STRING_ARRAY
STRING_ARRAY_ITERATOR
WRAPPER_COLLECTION
WRAPPER_DICTIONARY
WRAPPER
WRAPPER_FACTORY
WRAPPER_HANDLER
WRAPPERS_CACHE
Enumerations

There are two general tecnique to wrap an enum.

Put all the possible values of enumerations into a class as INTEGER constants accessibile to the user of your library. This is mostly similar to the actual usage of an enumeration. Each and every feature that accept an enum value as argument will need a precondition like is_valid_foo (a_foo_value)
Create a new type. In fact an enumeration is an INTEGER that can assume only precise and prestabilited values, so that its value is correct and consistent all the times. Class ENUM provides some facilities to achieve this. It shall be used in classes like this:

-- This file have been created by eiffel-gcc-xml.
-- Any change will be lost by the next execution of the tool.

expanded class PANGO_WEIGHT

insert ENUM

creation default_create
feature -- Validity
is_valid_value (a_value: INTEGER): BOOLEAN is
do
Result := ((a_value = pango_weight_ultralight) or else
(a_value = pango_weight_light) or else
(a_value = pango_weight_normal) or else
(a_value = pango_weight_semibold) or else
(a_value = pango_weight_bold) or else
(a_value = pango_weight_ultrabold) or else
(a_value = pango_weight_heavy))
end

feature -- Setters
default_create, set_ultralight is
do
value := pango_weight_ultralight
end

set_light is
do
value := pango_weight_light
end

set_normal is
do
value := pango_weight_normal
end

set_semibold is
do
value := pango_weight_semibold
end

set_bold is
do
value := pango_weight_bold
end

set_ultrabold is
do
value := pango_weight_ultrabold
end

set_heavy is
do
value := pango_weight_heavy
end

feature -- Queries
is_ultralight: BOOLEAN is
do
Result := (value=pango_weight_ultralight)
end

is_light: BOOLEAN is
do
Result := (value=pango_weight_light)
end

is_normal: BOOLEAN is
do
Result := (value=pango_weight_normal)
end

is_semibold: BOOLEAN is
do
Result := (value=pango_weight_semibold)
end

is_bold: BOOLEAN is
do
Result := (value=pango_weight_bold)
end

is_ultrabold: BOOLEAN is
do
Result := (value=pango_weight_ultrabold)
end

is_heavy: BOOLEAN is
do
Result := (value=pango_weight_heavy)
end

feature {WRAPPER, WRAPPER_HANDLER} -- Low level values
pango_weight_ultralight: INTEGER is
external "plug_in"
alias "{
location: "foo"
module: "bar"
feature_name: "PANGO_WEIGHT_ULTRALIGHT"
}"
end

pango_weight_light: INTEGER is
external "plug_in"
alias "{
location: "foo"
module: "bar"
feature_name: "PANGO_WEIGHT_LIGHT"
}"
end

pango_weight_normal: INTEGER is
external "plug_in"
alias "{
location: "foo"
module: "bar"
feature_name: "PANGO_WEIGHT_NORMAL"
}"
end

pango_weight_semibold: INTEGER is
external "plug_in"
alias "{
location: "foo"
module: "bar"
feature_name: "PANGO_WEIGHT_SEMIBOLD"
}"
end

pango_weight_bold: INTEGER is
external "plug_in"
alias "{
location: "foo"
module: "bar"
feature_name: "PANGO_WEIGHT_BOLD"
}"
end

pango_weight_ultrabold: INTEGER is
external "plug_in"
alias "{
location: "foo"
module: "bar"
feature_name: "PANGO_WEIGHT_ULTRABOLD"
}"
end

pango_weight_heavy: INTEGER is
external "plug_in"
alias "{
location: "foo"
module: "bar"
feature_name: "PANGO_WEIGHT_HEAVY"
}"
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.

Using eiffel-gcc-xml

Have a look at the manually written ZLIB_EXTERNALS. Eiffel is a language that is meant to be easy to the reader at the cost of being verbose. All that text of source to access a bunch of C functions. Think about serious libraries that have literally thousands of functions, structures, and enumeration! Writing the low level side of those wrappers is a really long, tedious task, the kind of task that people usually would leave to an unfaticable, astonishgly fast yet quite dumb worker, a computer. Andreas Leitner - who is surely quite smarter than myself - wrote a C parser for his Eiffel Wrapper Generator. I do not have neither the time neither the abilities of Andreas but it seems that I'm more lucky than him. In fact by the time I got serious with this project, people with the same problem, requiring tons of wrappers for Python, produced gcc-xml. These days parsing XML is a considered a common task, a task to be left to standard libraries, so SmartEiffel have an XML parser. So I wrote a little tool name "eiffel-gcc-xml" that takes the output of gcc-xml as input to produce the low-level "external" classes that we need to access functions, structures and enumerations.

Well, it actually requires a little more work since it breaks very often.
Memory handling
C_STRUCT is a wrapper for a data structure implemented in C programming language using a structure.
It does not make any assumption about memory handling; the developer of a SmartEiffel wrapper of a C library has to inherit to create a proper wrapper for it the developer shall inherit both from this class and from classes providing memory handling behavior, depending on how structure's memory shall be handled. This is decided case-by-case by C library.
Currently available memory handling classes are:

C_OWNED: memory is always handled by the underlying C library.
EIFFEL_OWNED: once created memory is fully handled by Eiffel runtime, usually with the Garbage Collector.
GLOBALLY_CACHED: Until disposed by Eiffel the wrapper registered in wrappers dictionary will be the unique wrapper used on the Eiffel side.
MIXED_MEMORY_HANDLING: whose memory can either by handled by the Eiffel library or by the underlying C code. Who handles memory is decided on a per-object based on the value of the flag `is_shared': handle will not be freed on dispose of the Eiffel wrapper object, when `is_shared' is true.
REFERENCE_COUNTED: memory is handled thought reference counting, i.e.GObject

Add proper examples of the various memory handling classes.
Implementing collections
Quite often objects are stored into containers or collections like arrays, linked lists, dictionaries, hashed-tables and so on. Many C libraries provides their own implementation of the classic containers, for example the GLib library provides GList, GSList, GHashTable and many others.
A WRAPPER_COLLECTION is a COLLECTION implemented wrapping some facilities offered by the wrapped C library, like GLib's linked list GList.
When you wrap those data structures you will encounter two kinds of problems:

Pointer returned by C containers could be newly allocated, not already wrapped by the Eiffel wrapper or already wrapper by the Eiffel wrapper. You can't naively create a new WRAPPER every time. Beside the obvious waste of memory and the stress you put on the garbage collector you will break most postconditions and invariant of a COLLECTION, since things that seems obvious like

do_stuff (my_collection: WRAPPER_COLLECTION[ITEM]) is require
my_collection/=Void not my_collection.is_empty local a,b: ITEM do a :=
my_collection.first b := my_collection.first check will_fail: a = b end end

In fact a and b will be different wrappers referring to the same underlying C structure. A WRAPPER_COLLECTION shall avoid this repeated, unnecessary and wrong creation of WRAPPERs, that will breaks invariants and post-conditions of a COLLECTION.
A solution is to inherit from WRAPPERS_CACHE, initializing cache at creation time and keeping it updated during usage. Cache's key is the address (pointer) to the wrapped C structure, value is the corresponding Eiffel wrapper. This way you can get back an already-created Eiffel wrapper.
Classes can implement different scheme; for example G_OBJECT_LIST retrieve the reference to the eventual WRAPPER directly from underlying GObject.

The container has no means to know how it shall create the wrapper for it, since C does not have the notion of generic, strongly typed container. The effective type of the containee is either not know by WRAPPER_COLLECTION or worse its conteinees could actually belong to different classes, sharing a common ancestor.
Since each library has its own idea on how the programmer shall handle �memory when dealing with containers an effective, non-deferred heir of WRAPPER_COLLECTION shall implement `wrapper' feature that given a pointer creates or retrieve a WRAPPER of the fittest class. Usually "plain" usage could return a fixed type; more elaborate type systems like GObject could provide the facilities necessary to pick a useful Eiffel type.

TODO: finish it.
Comparability and hashability
Some collections does not require anything in particular to their containee, like arrays or linked lists. Other collections needs either to compare their containee or to obtain an hash value from it. Therefore wrapper classes that are conceptually comparable or hashable shall inherit from COMPARABLE_WRAPPER and HASHABLE_WRAPPER respectively so they could be stored into collections that requires such abilities.
How to adapt old wrappers
(This is almost obsolete) Previous design was a black-or-white design: a class was either Eiffel-owned or not; C_STRUCT's are "owned" by the Eiffel code, and the Eiffel side should keep then longest lived reference to this struct; SHARED_C_STRUCT modelled the non-Eiffel-owned.
This approach is overly simplicistic since real-life libraries implement a wide spectrum of memory handling policies. One solutions does not fit all needs. Study the documentation of the library and pick the right memory handling Eiffel class.
The long int problem

Shortly it could be solved having two separate clusters one for 32bit, one for 64 bit where a deferred class defines a parameterless query for anchored declaration like

long_int: INTEGER_32 is do end

long_int: INTEGER_64 is do end

but this looks like an unfeasible hack to me, at least now. Currently it is the only available answer; a "proper" solution would require changes in both the compiler and the standard library. I would like to know how ISE solved this.

GObject-based libraries

Nowadays many libraries are based on the GLib Object System also known as Gobject. This library "provides a portable object system and transparent cross-language interoperability". It is used as the basic building block for literally hundeds of libraries and applications; in fact the command apt-cache rdepends libglib2.0-0 |wc -l told me that more than 2200 applications and libraries depend on either GLib or GObject.

GObject implement its own classed type system. With the exception of basic types (and some other subtleties I will write later) all objects are structures referred by pointer, i.e. non-expanded classes in Eiffellese; the type of each object is identified by a number, a GType which has an associated structure to describe the class - the type - itself. During startup of the Eiffel application the wrapper library will register for each type name (i.e. GtkWindow, GtkButton....) it wraps an agent that given a pointer creates an Eiffel wrapper object for the creation_agents dictionary, with a call similar to creation_agents.put (agent create_gtk_window, "GtkWindow"), given the feature create_gtk_window (p: POINTER): GTK_WINDOW is do create Result.from_external_pointer(p) end.

A Gobject can store arbitrary properties into itself. We use this to store a reference pointer to its Eiffel wrapper.

When we receive a pointer to a Gobject the G_OBJECT_FACTORY first looks if this Gobject already has an attacked wrapper (an effective heir of G_OBJECT). Otherwise it ask the Gobject its GType and the associated class-name. It this class-name has a creation agent the wrapper is created invoking the retrieved creation agent; otherwise we recursively look at its parent class until we find a type that has a corresponding creation agent.

When an effective G_OBJECT heir is actually created either explicitly because we know for sure its type or throught a creation agent the address of the wrapper is stored in the property "eiffel-wrapper" using the C function g_object_set_qdata (see store_eiffel_wrapper in G_OBJECT).

As usual this approach is both correct, memory efficient and collection-friendly (see "Implementing collections" earlier) at the cost of being computing intensive. There are times when the wrapper library has to create transient wrappers for shortly lived objects. Here enters secondary wrappers, or G_OBJECTs that are not referred-by the GOBject they refer to. Letting code speak: having a_gtk_window_ptr: POINTER; my_window: GTK_WINDOW; factory: G_OBJECT_EXPANDED_FACTORY check create my_window.secondary_wrapper_from(a_gtk_window_ptr) /= factory.wrapper(a_gtk_window_ptr) end will hold and also create my_window.main_wrapper_from(a_gtk_window_ptr); check my_window = factory.wrapper(a_gtk_window_ptr) end will be successfully passed. The difference is that the first is only an allocation of a smallish object (few bytes) while the latter could potentially require several looks-up into a dictionary plus an O(n) search into the GObject properties (during g_object_get_qdata used to see if a wrapper does actually exist)

TODO: show how to wrap a typical GObject-using library, like Gnome's GConf configuration system.
Commit's policy

There is no strict rule...
Ideally each commit should provide compilable code and working examples.
Provided examples and classes can be unfinished and uncomplete, can contain warnings, empty features and so on. My motto is "something is better than nothing".
it is nice to tell other developers what are you working on; anemail on eiffel-libraries-devel@gna.org suffice.
I promise I won't track you with a 9-tail cat to bash you if you commit uncompilable code.
Code that compiles is a good thing. Wisely designed code that compiles is better, since it has better performances; but I prefer published, working code even if has no state-of-the-art performances instead of

Various very old notes
Those notes are left here to be worked on.

Suggested
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.
Sketch difficoult features into comments.
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.
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.

=== Incoming tools ===

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

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

This will give us support for Gtk3, Glib, Cairo and many many other libraries in a much faster way that manually wrapping each one.

The tool that will generate such binding will be named '''leggow''', acronym for '''Liberty Eiffel Generator of GObject Wrappers''' and it currently lies in the leggow branch in repository https://github.com/tybor/Liberty but it is currently only an idea.

Wrapping C libraries

2016-03-24T15:55:59Z

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

[[Category: Interfacing]]
== Developer's guidelines ==
=== or how to write GNU-Eiffel wrappers for a C library ===

<cite>
"longum iter est per praecepta, breve et efficax per exempla" 
"The path of precept is long, that of example short and effectual." 
Seneca the Elder 
</cite>

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

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 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.

==== Prerequites ====

You should be proficient with:

* the C 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.

==== Software prerequisites ====

Make sure you have access on your machine to:

* 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

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.

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.

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.

Let's return to our wrapping/binding work after a due phylosophical digression

=== Preliminares ===

Most data structure in C are usually handled by reference, i.e. using pointers.

Passing objects by value is currently requires "expanded external classes" and will no be covered in this guide. Therefore if your library extensively pass structures around by value and not by reference (with a pointer), for example (TODO: put links to online example of passing structure by value) in function calls or contained in other structures our life will be quite hard. Fortunately enought most libraries handles most of its data structures by reference and zlib is no exception: in fact its basic functions takes pointers as first argument.

----
== Identifying types and classes ==

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.

A simplicistic rule-of-thumb specifically fitted to wrap libraries written in C is that when we have several functions that takes a pointer to a struct this struct is a good candidate for a class and those functions are good candidates to be wrapped as features usable by an Eiffel program.

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.

=== Code organization and class hierarchy. ===

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.

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/
** 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

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:

* eiffel-glib/library/
** core
** data_types
** externals
*** generated
** fundamentals
** utilities

Let's fill <code>zlib/library/loadpath.se</code>. It lists two directories: those containing the high-level classes, the same of the loadpath.se file itself, i.e. the current directory (.) and the ./externals directory which will contain deferred classes that provide access to external features.

<pre>
./
./externals/
</pre>

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>:

<pre>
../common/loadpath.se
./library/loadpath.se
</pre>

=== Low-level access to functions ===

Writing the Eiffel source code to access external C code is an extremely long, tedious and verbose process so a tool named '''wrappers_generator''' has been created.

It was not included in binary form in the adler release since it was not ready for prime time.
Now it isn't robust as I would like but at least it processes sources like Gtk3, Glib, &slasho;mq and other libraries without crashing.

It will be included into bell and later releases; before it's relase I would suggest to rebuild the compiler and work from the Git repository.

You can get the sources from https://savannah.gnu.org/projects/liberty-eiffel/ or from https://github.com/LibertyEiffel/Liberty and build it with install.sh script which also build wrappers_generator.

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.

Given an XML file and a list of C files (headers or sources) to wrap wrappers_generator:

* for each source file create a deferred class containing all the wrappable functions found in that file; functions in foo.h are wrapped into FOO_EXTERNALS
* for each struct creates a deferred class containing queries and setters feature to manipulate all members which have an Eiffel wrapper type;
* the same is made for unions
* creates a deferred Eiffel class named like the xml file containing wrappers for all typedefs, so when you have to refer to C "long" which is notorious for change size on various platform you can use "like long" in Eiffel
* each enumeration is wrapped into expanded classes with proper queries and setters. That way they are as efficient as plain integers values but they can't assume arbitrary values; enum foobar is wrapped into FOOBAR_ENUM
* when the values of an enumeration are actually flags, i.e. they all are diffent powers of 2, it's wrapped as a "flag" enumeration with commands to set and unset each flag of the enum.
* C++ classes, namespaces and all its fineries are currently ignored
* macros, #defines and all cannot be handled since they are "preprocessed away" and their text is not preseted to gccxml or castxml
* variadic functions can't be wrapped in Eiffel
* it transform CamelCase into CAMEL_CASE for classes, camel_case for features (queries, commands and so on)
* 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.

==== Text to be still reviewd ====

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
C function Eiffel feature
const char * zlibVersion (void); zlib_version: POINTER
int deflateInit (z_streamp strm, int level); deflate_init (a_stream: POINTER; a_level: INTEGER_32): INTEGER_32
int deflate (z_streamp strm, int flush); deflate (a_stream: POINTER;a_flush: INTEGER_32): INTEGER
int deflateEnd (z_streamp strm); deflate_end (a_stream: POINTER): INTEGER
int inflateInit (z_streamp strm); inflate_init (a_stream: POINTER): INTEGER
int inflate (z_streamp strm, int flush); inflate (a_stream: POINTER; a_flush: INTEGER): INTEGER
int inflateEnd (z_streamp strm); inflate_end (a_stream: POINTER): INTEGER

As you can see I have turned camelCaseFunction into camel_case_function which is far more in tune with Eiffel style. Int is actually an INTEGER_32 or only INTEGER (it still don't matter, even if I suspect that it will do soon: world is already filled with 64-bit machines and literally billion of devices with 4,8,16 bit CPU are in use today, not counting GPGPU)

Let's take a look at ZLIB_EXTERNALS. You'll see many entries like

inflate_init (a_stream: POINTER): INTEGER is -- int inflateInit (z_streamp strm);
external "plug_in"
alias "{
location: "${eiffel_libraries}/plugins"
module_name: "zlib"
feature_name: "inflateInit"
}"
end

this entry tells us that the Eiffel feature "inflate_init" refers to the symbol "inflateInit" in the module "zlib" of the plugins found in the directory.

Entries like this are the only "esoteric" Eiffel code you will see. All the details required to interface to C, to link to the actualy library and how to compile the code written in other languages is handled by the plugin part.

Without using plugins every Eiffel program should know all the details required to compile a C application with zlib. It would require to always use ACE files - even for simple examples - because you need to provide proper "c_compiler_options" and "linker_options"; for a single, simple library like Zlib it looks a tame task, only requiring to add -lzlib to the "linker_options" but when you start building real-world application things will get complicated really fast.

See SmartEiffel documentation on plugins.

All those functions returns an integer with standardized values #defined in the C header. We will wrap them in the deferred class ZLIB_CONSTANTS.

Deferred? Why deferred? We want to avoid the Eiffel programmer the burden to deal with all the details that C requires - otherwise we would have used plain C - so we do not want him/her to directly use that libraries. Deferred classes cannot have creation clauses so we are sure that no objects of type ZLIB_EXTERNALS and ZLIB_CONSTANTS will be created. They are helper classes that will be either inherited from or - more properly - inserted into ZLIB_STREAM and its effective heirs, ZLIB_INPUT_STREAM and ZLIB_OUTPUT_STREAM.

Making sure that the Eiffel developer will not use low-level features directly is the main reason why all the external features are not exported to anyone else, using the syntax feature {} -- External calls. This way only heirs - conforming or not - of that class can use them; for people coming from C++ it's like having private functions members.
C types

Here's a quick conversion table for various C types
C type Eiffel type
int INTEGER;
short int INTEGER_16
long int INTEGER_32 or 64
long long int INTEGER_64
int8_t (defined at stdint.h, ISO C 99) INTEGER_8
int16_t INTEGER_16
int32_t INTEGER_32
int64_t INTEGER_64
unsigned int NATURAL
unsigned short int NATURAL_16
unsigned long int NATURAL_32 on 32-bit, NATURAL_64 on 64.bit. See long int
unsigned long long int NATURAL_64
signed/unsigned char CHARACTER
float REAL_32
double REAL_64
long double REAL_EXTENDED
char BOOLEAN
void* or any other pointer POINTER

Some notes:

intXX_t are defined in GNU systems (Linux Glibc, CygWin and similar).
Currently INTEGER is mere alias for INTEGER_32 but this is bound to change in future version of SmartEiffel. Personally I think that it should be "the integer type with the same bit-lenght of C int".
A nice feature of long int is that is could be longer that int. So we can't really be sure whenever it is 32 or 64 bit. Usually it is an INTEGER_32 on 32-bit machines and INTEGER_64 on 64-bit machines. See this post on the SmartEiffel mailing list.
The same problem applies for long unsigned int: NATURAL_32 on 32-bits and NATURAL_64 on 64-bit. This mismatch can be quite problematic and it will be discussed-addressed later.
At the time of writing of this document SmartEiffel has some know issues regarding NATURALs types. If they actually do cause bugs there is an (unsatisfactory) workaround: use a bigger INTEGER. This implies a hidden conversion at C level and bargains correctness with a little waste of space and worse performance. Do not use an INTEGER of same size: it "usually" works nicely but this is a known source of nasty bugs since you will soon or later it will silently overflow.

An enlighting explanation about C variable types and declarations can be read on Wikipedia (I find particurarly confusing - expecially for the novice - that char is at the same time an 8-bit integer and an encoding for ASCII characters. Most programmers could always end up thinking about it only as a character. After more than 30 years they could have called it "byte". Yet this behaviour is fit the spirit of C very well. ).

The resulting ZLIB_CONSTANTS class is almost boring and undocumented. I maintained the documentation level found in the original documentation, since those are values that will be handled only by the implementation of the wrapper.

Have a look at WRAPPER_HANDLER. Eiffel has the ability to selectively export Any class that needs to access some of the
Access to structure field

Let's wrap the z_stream structure (the structure name is actually struct z_stream_s typedeffed to z_stream during its definition); the wrapper will have a similar two layer design: the low-level Z_STREAM_STRUCT will be a deferred class, with feature {} -- Hidden, low-level getters and setters. This class will also have a feature struct_size: INTEGER that will be the value of sizeof(z_stream)

Field named FooBar in the struct my_struct will be read with the Eiffel query my_struct_get_foo_bar and set with the command my_struct_set_foo_bar. Remember that those are low-level features; references to other objects will be pointers and its signature will be one of an external function: the first argument will be always the address of - a POINTER to - the wrapped struct.
Naming of placeholder arguments

Placeholder names should be chosen in a way that makes the documentation of the feature in English as smooth as possible for a proper argument placeholder for the Gnu-Eiffel language. "CamelCase" will be translated into "a_camel_case", "ENOO" is translated into "an_enoo". Eventual underscores in front of `a_name' are removed: "__foo" becomes "a_foo". The prefixed preposition is added to make clearer that the name refers to a generic value, not to a particular one. Always tries to use a placeholder that can be directly put in the feature's documentation without paraphrase.
ZLIB_STREAM, at last.

So let's write something that will be used in an actual Eiffel program! We start writing ZLIB_STREAM from file common/skeleton that provides us the usual LGPL-2.1-or-later headers. It inserts ZLIB_EXTERNALS and Z_STREAM_STRUCT.

TODO: finish this
The "common" cluster

The basic building blocks of a wrapper library have been put in the common cluster.

The WRAPPER class it the "fundamental" one even if embarassingly simple. Its only effective field (i.e.: stored, non-computed) is the handle POINTER. It shall handle the allocation and deallocation of the memory referred by handle so it is an heir of DISPOSABLE but it doesn't define dispose because there is no such a thing like a default memory handling in C.

C_STRUCT inherits from WRAPPER and provides default implementations for copy, is_equal and from_external_pointer features; it introduces the deferred "struct_size" query which should give the same result of C operator sizeof(MyStruct).

Note that there are - at least conceptually - other potentially heirs of WRAPPER, like pointers to functions

Many C libraries often return const char* strings. Those strings shall not be modified and their memory will be handled by the library; by all other means they actually are plain strings. A correct behaviour is to write foo: STRING is do create Result.from_external_copy(a_function_returning_a_const_char_pointer(handle)) end; a STRING is meant to be manipulated and changed and has control on the memory of its content. Here we are instead given a piece of memory holding some text that is "mostly read-only" whose control is held by the library. To provide correct behaviour STRING must copy the buffer, from_external can't be used. CONST_STRING is an effective heir of STRING that provides efficient wrapping of "const strings". It is usable like any other STRING but all the changes are made to a separe buffer preserving the original content - we are actually not allowed to change it. No further memory is allocated when a CONST_STRING is created: the buffer returned by the C library is used directly. For example, GTK+ has many calls like const gchar* gtk_entry_get_text (GtkEntry *entry); Memory efficiency is achieved making changing features slower. If you need to change its content consider using its feature string to get a new (non-const) STRING with the same content.

TODO: add proper description about:
CACHING_FACTORY
C_ARRAY
COMPARABLE_C_STRUCT
COMPARABLE_WRAPPER
CONST_STRING
C_OWNED
C_STRUCT
EIFFEL_OWNED
ENUM
EXPANDED_WRAPPER
GLOBAL_CACHE
GLOBALLY_CACHED
HASHABLE_WRAPPER
ITERATOR_ON_C_ARRAY
LINKED_STRING
MIXED_MEMORY_HANDLING
NULL_TERMINATED_C_ARRAY
NULL_TERMINATED_STRING_ARRAY
POINTER_HANDLING
REFERENCE_COUNTED
SHARED
STRING_ARRAY
STRING_ARRAY_ITERATOR
WRAPPER_COLLECTION
WRAPPER_DICTIONARY
WRAPPER
WRAPPER_FACTORY
WRAPPER_HANDLER
WRAPPERS_CACHE
Enumerations

There are two general tecnique to wrap an enum.

Put all the possible values of enumerations into a class as INTEGER constants accessibile to the user of your library. This is mostly similar to the actual usage of an enumeration. Each and every feature that accept an enum value as argument will need a precondition like is_valid_foo (a_foo_value)
Create a new type. In fact an enumeration is an INTEGER that can assume only precise and prestabilited values, so that its value is correct and consistent all the times. Class ENUM provides some facilities to achieve this. It shall be used in classes like this:

-- This file have been created by eiffel-gcc-xml.
-- Any change will be lost by the next execution of the tool.

expanded class PANGO_WEIGHT

insert ENUM

creation default_create
feature -- Validity
is_valid_value (a_value: INTEGER): BOOLEAN is
do
Result := ((a_value = pango_weight_ultralight) or else
(a_value = pango_weight_light) or else
(a_value = pango_weight_normal) or else
(a_value = pango_weight_semibold) or else
(a_value = pango_weight_bold) or else
(a_value = pango_weight_ultrabold) or else
(a_value = pango_weight_heavy))
end

feature -- Setters
default_create, set_ultralight is
do
value := pango_weight_ultralight
end

set_light is
do
value := pango_weight_light
end

set_normal is
do
value := pango_weight_normal
end

set_semibold is
do
value := pango_weight_semibold
end

set_bold is
do
value := pango_weight_bold
end

set_ultrabold is
do
value := pango_weight_ultrabold
end

set_heavy is
do
value := pango_weight_heavy
end

feature -- Queries
is_ultralight: BOOLEAN is
do
Result := (value=pango_weight_ultralight)
end

is_light: BOOLEAN is
do
Result := (value=pango_weight_light)
end

is_normal: BOOLEAN is
do
Result := (value=pango_weight_normal)
end

is_semibold: BOOLEAN is
do
Result := (value=pango_weight_semibold)
end

is_bold: BOOLEAN is
do
Result := (value=pango_weight_bold)
end

is_ultrabold: BOOLEAN is
do
Result := (value=pango_weight_ultrabold)
end

is_heavy: BOOLEAN is
do
Result := (value=pango_weight_heavy)
end

feature {WRAPPER, WRAPPER_HANDLER} -- Low level values
pango_weight_ultralight: INTEGER is
external "plug_in"
alias "{
location: "foo"
module: "bar"
feature_name: "PANGO_WEIGHT_ULTRALIGHT"
}"
end

pango_weight_light: INTEGER is
external "plug_in"
alias "{
location: "foo"
module: "bar"
feature_name: "PANGO_WEIGHT_LIGHT"
}"
end

pango_weight_normal: INTEGER is
external "plug_in"
alias "{
location: "foo"
module: "bar"
feature_name: "PANGO_WEIGHT_NORMAL"
}"
end

pango_weight_semibold: INTEGER is
external "plug_in"
alias "{
location: "foo"
module: "bar"
feature_name: "PANGO_WEIGHT_SEMIBOLD"
}"
end

pango_weight_bold: INTEGER is
external "plug_in"
alias "{
location: "foo"
module: "bar"
feature_name: "PANGO_WEIGHT_BOLD"
}"
end

pango_weight_ultrabold: INTEGER is
external "plug_in"
alias "{
location: "foo"
module: "bar"
feature_name: "PANGO_WEIGHT_ULTRABOLD"
}"
end

pango_weight_heavy: INTEGER is
external "plug_in"
alias "{
location: "foo"
module: "bar"
feature_name: "PANGO_WEIGHT_HEAVY"
}"
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.

Using eiffel-gcc-xml

Have a look at the manually written ZLIB_EXTERNALS. Eiffel is a language that is meant to be easy to the reader at the cost of being verbose. All that text of source to access a bunch of C functions. Think about serious libraries that have literally thousands of functions, structures, and enumeration! Writing the low level side of those wrappers is a really long, tedious task, the kind of task that people usually would leave to an unfaticable, astonishgly fast yet quite dumb worker, a computer. Andreas Leitner - who is surely quite smarter than myself - wrote a C parser for his Eiffel Wrapper Generator. I do not have neither the time neither the abilities of Andreas but it seems that I'm more lucky than him. In fact by the time I got serious with this project, people with the same problem, requiring tons of wrappers for Python, produced gcc-xml. These days parsing XML is a considered a common task, a task to be left to standard libraries, so SmartEiffel have an XML parser. So I wrote a little tool name "eiffel-gcc-xml" that takes the output of gcc-xml as input to produce the low-level "external" classes that we need to access functions, structures and enumerations.

Well, it actually requires a little more work since it breaks very often.
Memory handling
C_STRUCT is a wrapper for a data structure implemented in C programming language using a structure.
It does not make any assumption about memory handling; the developer of a SmartEiffel wrapper of a C library has to inherit to create a proper wrapper for it the developer shall inherit both from this class and from classes providing memory handling behavior, depending on how structure's memory shall be handled. This is decided case-by-case by C library.
Currently available memory handling classes are:

C_OWNED: memory is always handled by the underlying C library.
EIFFEL_OWNED: once created memory is fully handled by Eiffel runtime, usually with the Garbage Collector.
GLOBALLY_CACHED: Until disposed by Eiffel the wrapper registered in wrappers dictionary will be the unique wrapper used on the Eiffel side.
MIXED_MEMORY_HANDLING: whose memory can either by handled by the Eiffel library or by the underlying C code. Who handles memory is decided on a per-object based on the value of the flag `is_shared': handle will not be freed on dispose of the Eiffel wrapper object, when `is_shared' is true.
REFERENCE_COUNTED: memory is handled thought reference counting, i.e.GObject

Add proper examples of the various memory handling classes.
Implementing collections
Quite often objects are stored into containers or collections like arrays, linked lists, dictionaries, hashed-tables and so on. Many C libraries provides their own implementation of the classic containers, for example the GLib library provides GList, GSList, GHashTable and many others.
A WRAPPER_COLLECTION is a COLLECTION implemented wrapping some facilities offered by the wrapped C library, like GLib's linked list GList.
When you wrap those data structures you will encounter two kinds of problems:

Pointer returned by C containers could be newly allocated, not already wrapped by the Eiffel wrapper or already wrapper by the Eiffel wrapper. You can't naively create a new WRAPPER every time. Beside the obvious waste of memory and the stress you put on the garbage collector you will break most postconditions and invariant of a COLLECTION, since things that seems obvious like

do_stuff (my_collection: WRAPPER_COLLECTION[ITEM]) is require
my_collection/=Void not my_collection.is_empty local a,b: ITEM do a :=
my_collection.first b := my_collection.first check will_fail: a = b end end

In fact a and b will be different wrappers referring to the same underlying C structure. A WRAPPER_COLLECTION shall avoid this repeated, unnecessary and wrong creation of WRAPPERs, that will breaks invariants and post-conditions of a COLLECTION.
A solution is to inherit from WRAPPERS_CACHE, initializing cache at creation time and keeping it updated during usage. Cache's key is the address (pointer) to the wrapped C structure, value is the corresponding Eiffel wrapper. This way you can get back an already-created Eiffel wrapper.
Classes can implement different scheme; for example G_OBJECT_LIST retrieve the reference to the eventual WRAPPER directly from underlying GObject.

The container has no means to know how it shall create the wrapper for it, since C does not have the notion of generic, strongly typed container. The effective type of the containee is either not know by WRAPPER_COLLECTION or worse its conteinees could actually belong to different classes, sharing a common ancestor.
Since each library has its own idea on how the programmer shall handle �memory when dealing with containers an effective, non-deferred heir of WRAPPER_COLLECTION shall implement `wrapper' feature that given a pointer creates or retrieve a WRAPPER of the fittest class. Usually "plain" usage could return a fixed type; more elaborate type systems like GObject could provide the facilities necessary to pick a useful Eiffel type.

TODO: finish it.
Comparability and hashability
Some collections does not require anything in particular to their containee, like arrays or linked lists. Other collections needs either to compare their containee or to obtain an hash value from it. Therefore wrapper classes that are conceptually comparable or hashable shall inherit from COMPARABLE_WRAPPER and HASHABLE_WRAPPER respectively so they could be stored into collections that requires such abilities.
How to adapt old wrappers
(This is almost obsolete) Previous design was a black-or-white design: a class was either Eiffel-owned or not; C_STRUCT's are "owned" by the Eiffel code, and the Eiffel side should keep then longest lived reference to this struct; SHARED_C_STRUCT modelled the non-Eiffel-owned.
This approach is overly simplicistic since real-life libraries implement a wide spectrum of memory handling policies. One solutions does not fit all needs. Study the documentation of the library and pick the right memory handling Eiffel class.
The long int problem

Shortly it could be solved having two separate clusters one for 32bit, one for 64 bit where a deferred class defines a parameterless query for anchored declaration like

long_int: INTEGER_32 is do end

long_int: INTEGER_64 is do end

but this looks like an unfeasible hack to me, at least now. Currently it is the only available answer; a "proper" solution would require changes in both the compiler and the standard library. I would like to know how ISE solved this.

GObject-based libraries

Nowadays many libraries are based on the GLib Object System also known as Gobject. This library "provides a portable object system and transparent cross-language interoperability". It is used as the basic building block for literally hundeds of libraries and applications; in fact the command apt-cache rdepends libglib2.0-0 |wc -l told me that more than 2200 applications and libraries depend on either GLib or GObject.

GObject implement its own classed type system. With the exception of basic types (and some other subtleties I will write later) all objects are structures referred by pointer, i.e. non-expanded classes in Eiffellese; the type of each object is identified by a number, a GType which has an associated structure to describe the class - the type - itself. During startup of the Eiffel application the wrapper library will register for each type name (i.e. GtkWindow, GtkButton....) it wraps an agent that given a pointer creates an Eiffel wrapper object for the creation_agents dictionary, with a call similar to creation_agents.put (agent create_gtk_window, "GtkWindow"), given the feature create_gtk_window (p: POINTER): GTK_WINDOW is do create Result.from_external_pointer(p) end.

A Gobject can store arbitrary properties into itself. We use this to store a reference pointer to its Eiffel wrapper.

When we receive a pointer to a Gobject the G_OBJECT_FACTORY first looks if this Gobject already has an attacked wrapper (an effective heir of G_OBJECT). Otherwise it ask the Gobject its GType and the associated class-name. It this class-name has a creation agent the wrapper is created invoking the retrieved creation agent; otherwise we recursively look at its parent class until we find a type that has a corresponding creation agent.

When an effective G_OBJECT heir is actually created either explicitly because we know for sure its type or throught a creation agent the address of the wrapper is stored in the property "eiffel-wrapper" using the C function g_object_set_qdata (see store_eiffel_wrapper in G_OBJECT).

As usual this approach is both correct, memory efficient and collection-friendly (see "Implementing collections" earlier) at the cost of being computing intensive. There are times when the wrapper library has to create transient wrappers for shortly lived objects. Here enters secondary wrappers, or G_OBJECTs that are not referred-by the GOBject they refer to. Letting code speak: having a_gtk_window_ptr: POINTER; my_window: GTK_WINDOW; factory: G_OBJECT_EXPANDED_FACTORY check create my_window.secondary_wrapper_from(a_gtk_window_ptr) /= factory.wrapper(a_gtk_window_ptr) end will hold and also create my_window.main_wrapper_from(a_gtk_window_ptr); check my_window = factory.wrapper(a_gtk_window_ptr) end will be successfully passed. The difference is that the first is only an allocation of a smallish object (few bytes) while the latter could potentially require several looks-up into a dictionary plus an O(n) search into the GObject properties (during g_object_get_qdata used to see if a wrapper does actually exist)

TODO: show how to wrap a typical GObject-using library, like Gnome's GConf configuration system.
Commit's policy

There is no strict rule...
Ideally each commit should provide compilable code and working examples.
Provided examples and classes can be unfinished and uncomplete, can contain warnings, empty features and so on. My motto is "something is better than nothing".
it is nice to tell other developers what are you working on; anemail on eiffel-libraries-devel@gna.org suffice.
I promise I won't track you with a 9-tail cat to bash you if you commit uncompilable code.
Code that compiles is a good thing. Wisely designed code that compiles is better, since it has better performances; but I prefer published, working code even if has no state-of-the-art performances instead of

Various very old notes
Those notes are left here to be worked on.

Suggested
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.
Sketch difficoult features into comments.
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.
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.

=== Incoming tools ===

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

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

This will give us support for Gtk3, Glib, Cairo and many many other libraries in a much faster way that manually wrapping each one.

The tool that will generate such binding will be named '''leggow''', acronym for '''Liberty Eiffel Generator of GObject Wrappers''' and it currently lies in the leggow branch in repository https://github.com/tybor/Liberty but it is currently only an idea.

Wrapping C libraries

2016-03-24T15:55:27Z

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

[[Category: Interfacing]]
== Developer's guidelines ==
=== or how to write GNU-Eiffel wrappers for a C library ===

<cite>
"longum iter est per praecepta, breve et efficax per exempla" 
"The path of precept is long, that of example short and effectual." 
Seneca the Elder 
</cite>

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

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 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.

==== Prerequites ====

You should be proficient with:

* the C 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.

==== Software prerequisites ====

Make sure you have access on your machine to:

* 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

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.

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.

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.

Let's return to our wrapping/binding work after a due phylosophical digression

=== Preliminares ===

Most data structure in C are usually handled by reference, i.e. using pointers.

Passing objects by value is currently requires "expanded external classes" and will no be covered in this guide. Therefore if your library extensively pass structures around by value and not by reference (with a pointer), for example (TODO: put links to online example of passing structure by value) in function calls or contained in other structures our life will be quite hard. Fortunately enought most libraries handles most of its data structures by reference and zlib is no exception: in fact its basic functions takes pointers as first argument.

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

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.

A simplicistic rule-of-thumb specifically fitted to wrap libraries written in C is that when we have several functions that takes a pointer to a struct this struct is a good candidate for a class and those functions are good candidates to be wrapped as features usable by an Eiffel program.

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.

=== Code organization and class hierarchy. ===

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.

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/
** 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

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:

* eiffel-glib/library/
** core
** data_types
** externals
*** generated
** fundamentals
** utilities

Let's fill <code>zlib/library/loadpath.se</code>. It lists two directories: those containing the high-level classes, the same of the loadpath.se file itself, i.e. the current directory (.) and the ./externals directory which will contain deferred classes that provide access to external features.

<pre>
./
./externals/
</pre>

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>:

<pre>
../common/loadpath.se
./library/loadpath.se
</pre>

=== Low-level access to functions ===

Writing the Eiffel source code to access external C code is an extremely long, tedious and verbose process so a tool named '''wrappers_generator''' has been created.

It was not included in binary form in the adler release since it was not ready for prime time.
Now it isn't robust as I would like but at least it processes sources like Gtk3, Glib, &slasho;mq and other libraries without crashing.

It will be included into bell and later releases; before it's relase I would suggest to rebuild the compiler and work from the Git repository.

You can get the sources from https://savannah.gnu.org/projects/liberty-eiffel/ or from https://github.com/LibertyEiffel/Liberty and build it with install.sh script which also build wrappers_generator.

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.

Given an XML file and a list of C files (headers or sources) to wrap wrappers_generator:

* for each source file create a deferred class containing all the wrappable functions found in that file; functions in foo.h are wrapped into FOO_EXTERNALS
* for each struct creates a deferred class containing queries and setters feature to manipulate all members which have an Eiffel wrapper type;
* the same is made for unions
* creates a deferred Eiffel class named like the xml file containing wrappers for all typedefs, so when you have to refer to C "long" which is notorious for change size on various platform you can use "like long" in Eiffel
* each enumeration is wrapped into expanded classes with proper queries and setters. That way they are as efficient as plain integers values but they can't assume arbitrary values; enum foobar is wrapped into FOOBAR_ENUM
* when the values of an enumeration are actually flags, i.e. they all are diffent powers of 2, it's wrapped as a "flag" enumeration with commands to set and unset each flag of the enum.
* C++ classes, namespaces and all its fineries are currently ignored
* macros, #defines and all cannot be handled since they are "preprocessed away" and their text is not preseted to gccxml or castxml
* variadic functions can't be wrapped in Eiffel
* it transform CamelCase into CAMEL_CASE for classes, camel_case for features (queries, commands and so on)
* 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.

==== Text to be still reviewd ====

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
C function Eiffel feature
const char * zlibVersion (void); zlib_version: POINTER
int deflateInit (z_streamp strm, int level); deflate_init (a_stream: POINTER; a_level: INTEGER_32): INTEGER_32
int deflate (z_streamp strm, int flush); deflate (a_stream: POINTER;a_flush: INTEGER_32): INTEGER
int deflateEnd (z_streamp strm); deflate_end (a_stream: POINTER): INTEGER
int inflateInit (z_streamp strm); inflate_init (a_stream: POINTER): INTEGER
int inflate (z_streamp strm, int flush); inflate (a_stream: POINTER; a_flush: INTEGER): INTEGER
int inflateEnd (z_streamp strm); inflate_end (a_stream: POINTER): INTEGER

As you can see I have turned camelCaseFunction into camel_case_function which is far more in tune with Eiffel style. Int is actually an INTEGER_32 or only INTEGER (it still don't matter, even if I suspect that it will do soon: world is already filled with 64-bit machines and literally billion of devices with 4,8,16 bit CPU are in use today, not counting GPGPU)

Let's take a look at ZLIB_EXTERNALS. You'll see many entries like

inflate_init (a_stream: POINTER): INTEGER is -- int inflateInit (z_streamp strm);
external "plug_in"
alias "{
location: "${eiffel_libraries}/plugins"
module_name: "zlib"
feature_name: "inflateInit"
}"
end

this entry tells us that the Eiffel feature "inflate_init" refers to the symbol "inflateInit" in the module "zlib" of the plugins found in the directory.

Entries like this are the only "esoteric" Eiffel code you will see. All the details required to interface to C, to link to the actualy library and how to compile the code written in other languages is handled by the plugin part.

Without using plugins every Eiffel program should know all the details required to compile a C application with zlib. It would require to always use ACE files - even for simple examples - because you need to provide proper "c_compiler_options" and "linker_options"; for a single, simple library like Zlib it looks a tame task, only requiring to add -lzlib to the "linker_options" but when you start building real-world application things will get complicated really fast.

See SmartEiffel documentation on plugins.

All those functions returns an integer with standardized values #defined in the C header. We will wrap them in the deferred class ZLIB_CONSTANTS.

Deferred? Why deferred? We want to avoid the Eiffel programmer the burden to deal with all the details that C requires - otherwise we would have used plain C - so we do not want him/her to directly use that libraries. Deferred classes cannot have creation clauses so we are sure that no objects of type ZLIB_EXTERNALS and ZLIB_CONSTANTS will be created. They are helper classes that will be either inherited from or - more properly - inserted into ZLIB_STREAM and its effective heirs, ZLIB_INPUT_STREAM and ZLIB_OUTPUT_STREAM.

Making sure that the Eiffel developer will not use low-level features directly is the main reason why all the external features are not exported to anyone else, using the syntax feature {} -- External calls. This way only heirs - conforming or not - of that class can use them; for people coming from C++ it's like having private functions members.
C types

Here's a quick conversion table for various C types
C type Eiffel type
int INTEGER;
short int INTEGER_16
long int INTEGER_32 or 64
long long int INTEGER_64
int8_t (defined at stdint.h, ISO C 99) INTEGER_8
int16_t INTEGER_16
int32_t INTEGER_32
int64_t INTEGER_64
unsigned int NATURAL
unsigned short int NATURAL_16
unsigned long int NATURAL_32 on 32-bit, NATURAL_64 on 64.bit. See long int
unsigned long long int NATURAL_64
signed/unsigned char CHARACTER
float REAL_32
double REAL_64
long double REAL_EXTENDED
char BOOLEAN
void* or any other pointer POINTER

Some notes:

intXX_t are defined in GNU systems (Linux Glibc, CygWin and similar).
Currently INTEGER is mere alias for INTEGER_32 but this is bound to change in future version of SmartEiffel. Personally I think that it should be "the integer type with the same bit-lenght of C int".
A nice feature of long int is that is could be longer that int. So we can't really be sure whenever it is 32 or 64 bit. Usually it is an INTEGER_32 on 32-bit machines and INTEGER_64 on 64-bit machines. See this post on the SmartEiffel mailing list.
The same problem applies for long unsigned int: NATURAL_32 on 32-bits and NATURAL_64 on 64-bit. This mismatch can be quite problematic and it will be discussed-addressed later.
At the time of writing of this document SmartEiffel has some know issues regarding NATURALs types. If they actually do cause bugs there is an (unsatisfactory) workaround: use a bigger INTEGER. This implies a hidden conversion at C level and bargains correctness with a little waste of space and worse performance. Do not use an INTEGER of same size: it "usually" works nicely but this is a known source of nasty bugs since you will soon or later it will silently overflow.

An enlighting explanation about C variable types and declarations can be read on Wikipedia (I find particurarly confusing - expecially for the novice - that char is at the same time an 8-bit integer and an encoding for ASCII characters. Most programmers could always end up thinking about it only as a character. After more than 30 years they could have called it "byte". Yet this behaviour is fit the spirit of C very well. ).

The resulting ZLIB_CONSTANTS class is almost boring and undocumented. I maintained the documentation level found in the original documentation, since those are values that will be handled only by the implementation of the wrapper.

Have a look at WRAPPER_HANDLER. Eiffel has the ability to selectively export Any class that needs to access some of the
Access to structure field

Let's wrap the z_stream structure (the structure name is actually struct z_stream_s typedeffed to z_stream during its definition); the wrapper will have a similar two layer design: the low-level Z_STREAM_STRUCT will be a deferred class, with feature {} -- Hidden, low-level getters and setters. This class will also have a feature struct_size: INTEGER that will be the value of sizeof(z_stream)

Field named FooBar in the struct my_struct will be read with the Eiffel query my_struct_get_foo_bar and set with the command my_struct_set_foo_bar. Remember that those are low-level features; references to other objects will be pointers and its signature will be one of an external function: the first argument will be always the address of - a POINTER to - the wrapped struct.
Naming of placeholder arguments

Placeholder names should be chosen in a way that makes the documentation of the feature in English as smooth as possible for a proper argument placeholder for the Gnu-Eiffel language. "CamelCase" will be translated into "a_camel_case", "ENOO" is translated into "an_enoo". Eventual underscores in front of `a_name' are removed: "__foo" becomes "a_foo". The prefixed preposition is added to make clearer that the name refers to a generic value, not to a particular one. Always tries to use a placeholder that can be directly put in the feature's documentation without paraphrase.
ZLIB_STREAM, at last.

So let's write something that will be used in an actual Eiffel program! We start writing ZLIB_STREAM from file common/skeleton that provides us the usual LGPL-2.1-or-later headers. It inserts ZLIB_EXTERNALS and Z_STREAM_STRUCT.

TODO: finish this
The "common" cluster

The basic building blocks of a wrapper library have been put in the common cluster.

The WRAPPER class it the "fundamental" one even if embarassingly simple. Its only effective field (i.e.: stored, non-computed) is the handle POINTER. It shall handle the allocation and deallocation of the memory referred by handle so it is an heir of DISPOSABLE but it doesn't define dispose because there is no such a thing like a default memory handling in C.

C_STRUCT inherits from WRAPPER and provides default implementations for copy, is_equal and from_external_pointer features; it introduces the deferred "struct_size" query which should give the same result of C operator sizeof(MyStruct).

Note that there are - at least conceptually - other potentially heirs of WRAPPER, like pointers to functions

Many C libraries often return const char* strings. Those strings shall not be modified and their memory will be handled by the library; by all other means they actually are plain strings. A correct behaviour is to write foo: STRING is do create Result.from_external_copy(a_function_returning_a_const_char_pointer(handle)) end; a STRING is meant to be manipulated and changed and has control on the memory of its content. Here we are instead given a piece of memory holding some text that is "mostly read-only" whose control is held by the library. To provide correct behaviour STRING must copy the buffer, from_external can't be used. CONST_STRING is an effective heir of STRING that provides efficient wrapping of "const strings". It is usable like any other STRING but all the changes are made to a separe buffer preserving the original content - we are actually not allowed to change it. No further memory is allocated when a CONST_STRING is created: the buffer returned by the C library is used directly. For example, GTK+ has many calls like const gchar* gtk_entry_get_text (GtkEntry *entry); Memory efficiency is achieved making changing features slower. If you need to change its content consider using its feature string to get a new (non-const) STRING with the same content.

TODO: add proper description about:
CACHING_FACTORY
C_ARRAY
COMPARABLE_C_STRUCT
COMPARABLE_WRAPPER
CONST_STRING
C_OWNED
C_STRUCT
EIFFEL_OWNED
ENUM
EXPANDED_WRAPPER
GLOBAL_CACHE
GLOBALLY_CACHED
HASHABLE_WRAPPER
ITERATOR_ON_C_ARRAY
LINKED_STRING
MIXED_MEMORY_HANDLING
NULL_TERMINATED_C_ARRAY
NULL_TERMINATED_STRING_ARRAY
POINTER_HANDLING
REFERENCE_COUNTED
SHARED
STRING_ARRAY
STRING_ARRAY_ITERATOR
WRAPPER_COLLECTION
WRAPPER_DICTIONARY
WRAPPER
WRAPPER_FACTORY
WRAPPER_HANDLER
WRAPPERS_CACHE
Enumerations

There are two general tecnique to wrap an enum.

Put all the possible values of enumerations into a class as INTEGER constants accessibile to the user of your library. This is mostly similar to the actual usage of an enumeration. Each and every feature that accept an enum value as argument will need a precondition like is_valid_foo (a_foo_value)
Create a new type. In fact an enumeration is an INTEGER that can assume only precise and prestabilited values, so that its value is correct and consistent all the times. Class ENUM provides some facilities to achieve this. It shall be used in classes like this:

-- This file have been created by eiffel-gcc-xml.
-- Any change will be lost by the next execution of the tool.

expanded class PANGO_WEIGHT

insert ENUM

creation default_create
feature -- Validity
is_valid_value (a_value: INTEGER): BOOLEAN is
do
Result := ((a_value = pango_weight_ultralight) or else
(a_value = pango_weight_light) or else
(a_value = pango_weight_normal) or else
(a_value = pango_weight_semibold) or else
(a_value = pango_weight_bold) or else
(a_value = pango_weight_ultrabold) or else
(a_value = pango_weight_heavy))
end

feature -- Setters
default_create, set_ultralight is
do
value := pango_weight_ultralight
end

set_light is
do
value := pango_weight_light
end

set_normal is
do
value := pango_weight_normal
end

set_semibold is
do
value := pango_weight_semibold
end

set_bold is
do
value := pango_weight_bold
end

set_ultrabold is
do
value := pango_weight_ultrabold
end

set_heavy is
do
value := pango_weight_heavy
end

feature -- Queries
is_ultralight: BOOLEAN is
do
Result := (value=pango_weight_ultralight)
end

is_light: BOOLEAN is
do
Result := (value=pango_weight_light)
end

is_normal: BOOLEAN is
do
Result := (value=pango_weight_normal)
end

is_semibold: BOOLEAN is
do
Result := (value=pango_weight_semibold)
end

is_bold: BOOLEAN is
do
Result := (value=pango_weight_bold)
end

is_ultrabold: BOOLEAN is
do
Result := (value=pango_weight_ultrabold)
end

is_heavy: BOOLEAN is
do
Result := (value=pango_weight_heavy)
end

feature {WRAPPER, WRAPPER_HANDLER} -- Low level values
pango_weight_ultralight: INTEGER is
external "plug_in"
alias "{
location: "foo"
module: "bar"
feature_name: "PANGO_WEIGHT_ULTRALIGHT"
}"
end

pango_weight_light: INTEGER is
external "plug_in"
alias "{
location: "foo"
module: "bar"
feature_name: "PANGO_WEIGHT_LIGHT"
}"
end

pango_weight_normal: INTEGER is
external "plug_in"
alias "{
location: "foo"
module: "bar"
feature_name: "PANGO_WEIGHT_NORMAL"
}"
end

pango_weight_semibold: INTEGER is
external "plug_in"
alias "{
location: "foo"
module: "bar"
feature_name: "PANGO_WEIGHT_SEMIBOLD"
}"
end

pango_weight_bold: INTEGER is
external "plug_in"
alias "{
location: "foo"
module: "bar"
feature_name: "PANGO_WEIGHT_BOLD"
}"
end

pango_weight_ultrabold: INTEGER is
external "plug_in"
alias "{
location: "foo"
module: "bar"
feature_name: "PANGO_WEIGHT_ULTRABOLD"
}"
end

pango_weight_heavy: INTEGER is
external "plug_in"
alias "{
location: "foo"
module: "bar"
feature_name: "PANGO_WEIGHT_HEAVY"
}"
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.

Using eiffel-gcc-xml

Have a look at the manually written ZLIB_EXTERNALS. Eiffel is a language that is meant to be easy to the reader at the cost of being verbose. All that text of source to access a bunch of C functions. Think about serious libraries that have literally thousands of functions, structures, and enumeration! Writing the low level side of those wrappers is a really long, tedious task, the kind of task that people usually would leave to an unfaticable, astonishgly fast yet quite dumb worker, a computer. Andreas Leitner - who is surely quite smarter than myself - wrote a C parser for his Eiffel Wrapper Generator. I do not have neither the time neither the abilities of Andreas but it seems that I'm more lucky than him. In fact by the time I got serious with this project, people with the same problem, requiring tons of wrappers for Python, produced gcc-xml. These days parsing XML is a considered a common task, a task to be left to standard libraries, so SmartEiffel have an XML parser. So I wrote a little tool name "eiffel-gcc-xml" that takes the output of gcc-xml as input to produce the low-level "external" classes that we need to access functions, structures and enumerations.

Well, it actually requires a little more work since it breaks very often.
Memory handling
C_STRUCT is a wrapper for a data structure implemented in C programming language using a structure.
It does not make any assumption about memory handling; the developer of a SmartEiffel wrapper of a C library has to inherit to create a proper wrapper for it the developer shall inherit both from this class and from classes providing memory handling behavior, depending on how structure's memory shall be handled. This is decided case-by-case by C library.
Currently available memory handling classes are:

C_OWNED: memory is always handled by the underlying C library.
EIFFEL_OWNED: once created memory is fully handled by Eiffel runtime, usually with the Garbage Collector.
GLOBALLY_CACHED: Until disposed by Eiffel the wrapper registered in wrappers dictionary will be the unique wrapper used on the Eiffel side.
MIXED_MEMORY_HANDLING: whose memory can either by handled by the Eiffel library or by the underlying C code. Who handles memory is decided on a per-object based on the value of the flag `is_shared': handle will not be freed on dispose of the Eiffel wrapper object, when `is_shared' is true.
REFERENCE_COUNTED: memory is handled thought reference counting, i.e.GObject

Add proper examples of the various memory handling classes.
Implementing collections
Quite often objects are stored into containers or collections like arrays, linked lists, dictionaries, hashed-tables and so on. Many C libraries provides their own implementation of the classic containers, for example the GLib library provides GList, GSList, GHashTable and many others.
A WRAPPER_COLLECTION is a COLLECTION implemented wrapping some facilities offered by the wrapped C library, like GLib's linked list GList.
When you wrap those data structures you will encounter two kinds of problems:

Pointer returned by C containers could be newly allocated, not already wrapped by the Eiffel wrapper or already wrapper by the Eiffel wrapper. You can't naively create a new WRAPPER every time. Beside the obvious waste of memory and the stress you put on the garbage collector you will break most postconditions and invariant of a COLLECTION, since things that seems obvious like

do_stuff (my_collection: WRAPPER_COLLECTION[ITEM]) is require
my_collection/=Void not my_collection.is_empty local a,b: ITEM do a :=
my_collection.first b := my_collection.first check will_fail: a = b end end

In fact a and b will be different wrappers referring to the same underlying C structure. A WRAPPER_COLLECTION shall avoid this repeated, unnecessary and wrong creation of WRAPPERs, that will breaks invariants and post-conditions of a COLLECTION.
A solution is to inherit from WRAPPERS_CACHE, initializing cache at creation time and keeping it updated during usage. Cache's key is the address (pointer) to the wrapped C structure, value is the corresponding Eiffel wrapper. This way you can get back an already-created Eiffel wrapper.
Classes can implement different scheme; for example G_OBJECT_LIST retrieve the reference to the eventual WRAPPER directly from underlying GObject.

The container has no means to know how it shall create the wrapper for it, since C does not have the notion of generic, strongly typed container. The effective type of the containee is either not know by WRAPPER_COLLECTION or worse its conteinees could actually belong to different classes, sharing a common ancestor.
Since each library has its own idea on how the programmer shall handle �memory when dealing with containers an effective, non-deferred heir of WRAPPER_COLLECTION shall implement `wrapper' feature that given a pointer creates or retrieve a WRAPPER of the fittest class. Usually "plain" usage could return a fixed type; more elaborate type systems like GObject could provide the facilities necessary to pick a useful Eiffel type.

TODO: finish it.
Comparability and hashability
Some collections does not require anything in particular to their containee, like arrays or linked lists. Other collections needs either to compare their containee or to obtain an hash value from it. Therefore wrapper classes that are conceptually comparable or hashable shall inherit from COMPARABLE_WRAPPER and HASHABLE_WRAPPER respectively so they could be stored into collections that requires such abilities.
How to adapt old wrappers
(This is almost obsolete) Previous design was a black-or-white design: a class was either Eiffel-owned or not; C_STRUCT's are "owned" by the Eiffel code, and the Eiffel side should keep then longest lived reference to this struct; SHARED_C_STRUCT modelled the non-Eiffel-owned.
This approach is overly simplicistic since real-life libraries implement a wide spectrum of memory handling policies. One solutions does not fit all needs. Study the documentation of the library and pick the right memory handling Eiffel class.
The long int problem

Shortly it could be solved having two separate clusters one for 32bit, one for 64 bit where a deferred class defines a parameterless query for anchored declaration like

long_int: INTEGER_32 is do end

long_int: INTEGER_64 is do end

but this looks like an unfeasible hack to me, at least now. Currently it is the only available answer; a "proper" solution would require changes in both the compiler and the standard library. I would like to know how ISE solved this.

GObject-based libraries

Nowadays many libraries are based on the GLib Object System also known as Gobject. This library "provides a portable object system and transparent cross-language interoperability". It is used as the basic building block for literally hundeds of libraries and applications; in fact the command apt-cache rdepends libglib2.0-0 |wc -l told me that more than 2200 applications and libraries depend on either GLib or GObject.

GObject implement its own classed type system. With the exception of basic types (and some other subtleties I will write later) all objects are structures referred by pointer, i.e. non-expanded classes in Eiffellese; the type of each object is identified by a number, a GType which has an associated structure to describe the class - the type - itself. During startup of the Eiffel application the wrapper library will register for each type name (i.e. GtkWindow, GtkButton....) it wraps an agent that given a pointer creates an Eiffel wrapper object for the creation_agents dictionary, with a call similar to creation_agents.put (agent create_gtk_window, "GtkWindow"), given the feature create_gtk_window (p: POINTER): GTK_WINDOW is do create Result.from_external_pointer(p) end.

A Gobject can store arbitrary properties into itself. We use this to store a reference pointer to its Eiffel wrapper.

When we receive a pointer to a Gobject the G_OBJECT_FACTORY first looks if this Gobject already has an attacked wrapper (an effective heir of G_OBJECT). Otherwise it ask the Gobject its GType and the associated class-name. It this class-name has a creation agent the wrapper is created invoking the retrieved creation agent; otherwise we recursively look at its parent class until we find a type that has a corresponding creation agent.

When an effective G_OBJECT heir is actually created either explicitly because we know for sure its type or throught a creation agent the address of the wrapper is stored in the property "eiffel-wrapper" using the C function g_object_set_qdata (see store_eiffel_wrapper in G_OBJECT).

As usual this approach is both correct, memory efficient and collection-friendly (see "Implementing collections" earlier) at the cost of being computing intensive. There are times when the wrapper library has to create transient wrappers for shortly lived objects. Here enters secondary wrappers, or G_OBJECTs that are not referred-by the GOBject they refer to. Letting code speak: having a_gtk_window_ptr: POINTER; my_window: GTK_WINDOW; factory: G_OBJECT_EXPANDED_FACTORY check create my_window.secondary_wrapper_from(a_gtk_window_ptr) /= factory.wrapper(a_gtk_window_ptr) end will hold and also create my_window.main_wrapper_from(a_gtk_window_ptr); check my_window = factory.wrapper(a_gtk_window_ptr) end will be successfully passed. The difference is that the first is only an allocation of a smallish object (few bytes) while the latter could potentially require several looks-up into a dictionary plus an O(n) search into the GObject properties (during g_object_get_qdata used to see if a wrapper does actually exist)

TODO: show how to wrap a typical GObject-using library, like Gnome's GConf configuration system.
Commit's policy

There is no strict rule...
Ideally each commit should provide compilable code and working examples.
Provided examples and classes can be unfinished and uncomplete, can contain warnings, empty features and so on. My motto is "something is better than nothing".
it is nice to tell other developers what are you working on; anemail on eiffel-libraries-devel@gna.org suffice.
I promise I won't track you with a 9-tail cat to bash you if you commit uncompilable code.
Code that compiles is a good thing. Wisely designed code that compiles is better, since it has better performances; but I prefer published, working code even if has no state-of-the-art performances instead of

Various very old notes
Those notes are left here to be worked on.

Suggested
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.
Sketch difficoult features into comments.
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.
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.

=== Incoming tools ===

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

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

This will give us support for Gtk3, Glib, Cairo and many many other libraries in a much faster way that manually wrapping each one.

The tool that will generate such binding will be named '''leggow''', acronym for '''Liberty Eiffel Generator of GObject Wrappers''' and it currently lies in the leggow branch in repository https://github.com/tybor/Liberty but it is currently only an idea.

Upcoming release names

2016-02-27T22:14:27Z

Tybor:

The Liberty releases are named after famous engineers names starting by A for the first release, B for the second, and so on.
Here is a list of name suggestions for future releases:
* Alexander Graham Bell ('''"bell"''')
* Glenn Curtiss ('''"curtiss"''')
* Jack Dennis ('''"dennis"''')
* Gustave Eiffel ('''"eiffel"''') -- or is it too obvious?
* John Ambrose Fleming ('''"fleming"''')
* G?
* Grace Hopper ('''"hopper"''')
* I?

Feel free to suggest any further names. You may read the lists of engineers on WikiPedia:

* [https://en.wikipedia.org/wiki/Lists_of_engineers Lists of engineers]
* [https://en.wikipedia.org/wiki/List_of_civil_engineers List of civil engineers]
* [https://en.wikipedia.org/wiki/List_of_structural_engineers List of structural engineers]

Each "released release" (sic) will also have a numeric tag in the form of "year.month" which is more simple to remember.

Already released versions are listed in [[Versions history]].

Tools

2016-02-27T21:13:06Z

Tybor: /* Compiling */

[[Category: Tool]]
LibertyEiffel provides many tools besides the [[compile|compiler]].

All those tools use the [[configuration file]].

== The tools ==

=== Tool box ===

* [[se]]: a facade to all those tools

=== Compiling ===

* [[clean]]: remove the useless C files
* [[compile]]: the compiler (calls [[compile_to_c]])
* [[compile_to_c]]: the C compiler core
* [[extract_internals]]: the tentative inter-program object sharing tool
* [[wrappers_generator]]: a tools to generate low-level Eiffel wrappers for C code

=== Searching and documenting ===

* [[eiffeldoc]]: generates the whole documentation of a project
* [[finder]]: find a class
* [[pretty]]: make your source file pretty
* [[short]]: generates the interface documentation of a single class

=== Debugging ===

* [[ace_check]]: check an [[ACE|ACE file]]
* [[class_check]]: check the [[parsing|syntax]] and the [[semantics]] of a source code
* [[eiffeltest]]: the LibertyEiffel testing tool

=== Installing ===

* [[install]]: installs the LibertyEiffel tools

== The system core ==

If you are interested by how the system works, either by sheer curiosity, either because you want to modify it, here are some explanations.

If you want to create a new LibertyEiffel-oriented tool, this information is important too; also look at [[tool_class:EXTERNAL_TOOL|<tt>EXTERNAL_TOOL</tt>]].

* [[class loading]]
* [[parsing|syntactic analysis]]
* [[semantics|semantic analysis]]
* the [[optimizer]]
* the [[visitor|visitors]]
* code generation
** [[compile_to_c#Generation|compile_to_c]]
** [[compile_to_jvm#Generation|compile_to_jvm (obsolete)]]

GSoC - Google's Summer of Code

2016-02-14T23:32:05Z

Tybor:

This year we as LibertyEiffel want to participate in [https://developers.google.com/open-source/gsoc/ Google's Summer of Code Program]. On this site we collect idea for projects. But let's give it all in correct order:

= What is the Google Summer of Code? =
Summer of Code is Google's program to give students stipends for a 3 months programming task in an open source. Every participating student gets a mentor assigned (early birds might even have a chance to select ;-) who supports with his experience from the community.

= When will all this happen? =
The [https://developers.google.com/open-source/gsoc/timeline timeline] is quite terse but the most important dates are application before 25th of March and free time between May 23 and August 23 to work on coding.

= Why choosing LibertyEiffel for the Google Summer of Code? =
LibertyEiffel is the GNU compiler for the programming language Eiffel. It is based on the academic project SmartEiffel but evolved with the scope of being usable to real world programs. Eiffel in general is a very nice object oriented programming language which includes the specification of the program's functionality within the code. This is nice for debugging but also a step to be able to prove the program correct.

= What could I do? =
We are open to your ideas, as we are convinced that you will perform best in case you what your heart burns for. Feel free to suggest a project on the mailing list an we will find a mentor or subtasks to add or remove to make it appropriate. In case you just want to do something great for LibertyEiffel you can choose from the following ideas.

= Ideas =
== Windows Support ==
'''suggested by: '''ramack
 '''summary: '''LibertyEiffel in theory is running several platforms, but recent development was limited to a GNU/Linux environment and for Microsoft Windows no compiler is known to work. Target is to integrate a free C compiler (e. g. PellesC), including necessary fixes to generate accepted C code, add missing implementations for plugins (exec, net), create an installer, run test suite on MS Windows.
 '''difficulty: '''Easy
 '''skills: '''Experience with C programming on Windows, basic Eiffel knowledge
 '''potential mentors: '''ramack, Hans Zwakenberg
 '''notes: '''

== Eclipse integration ==
'''suggested by: '''ramack
 '''summary: '''Integrate LibertyEiffel into Eclipse with Syntax highlighting, compilation (and parsing the output) and the sedb debugger
 '''difficulty: '''Easy
 '''skills: '''Java knowledge, Eiffel knowledge, experience with Eclipse (plugin development) would be good
 '''potential mentors: '''ramack
 '''notes: '''

== Standard C11 conform C code ==
'''suggested by: '''ramack
 '''summary: '''Make the LibertyEiffel compiler emit C11 compatible C code.
 '''difficulty: '''Advanced
 '''skills: '''Deep experience in C programming, basic Eiffel knowledge
 '''potential mentors: '''ramack, Hans Zwakenberg
 '''notes: '''can be extended to apply additional static checkers like pclint, MISRA rules, high C compiler warning levels

== ECMA conformance ==
'''suggested by: '''ramack
 '''summary: '''many ECMA features are already supported, implement the missing ones (beside No-variant agent conformance, which is not planned to be included in LibertyEiffel)
 '''difficulty: '''Advanced
 '''skills: '''Deep Eiffel knowledge, willingness to dig into the ECMA standard document
 '''potential mentors: '''ramack,Cadrian
 '''notes: '''obviously test cases shall also be derived for the new features

== EiffelTest-NG ==
'''suggested by: '''ramack
 '''summary: '''Implement a new version of the tool eiffeltest, to execute the test suite
 '''difficulty: '''None/Easy/Advanced/Hard/Unmanageable
 '''skills: '''Good Eiffel knowledge, interest in Software testing
 '''potential mentors: '''ramack,Cadrian
 '''notes: '''the features should include: parallel test execution, time/progress monitoring and estimation, improved test status (ET integration), Coverage measurement (different criteria like Branch, MC/DC)

== Embedded Systems Readiness / Static Memory Allocation ==
'''suggested by: '''ramack
 '''summary: '''Improve the applicability of LibertyEiffel programs to small embedded systems, by introduction of a mechanism to prevent dynamic memory allocation.
 '''difficulty: '''Hard
 '''skills: '''Deep understanding of Memory Managment, Eiffel experience
 '''potential mentors: '''ramack
 '''notes: '''

== Resurrect the compile_to_jvm compiler ==
'''suggested by: '''ramack
 '''summary: '''Back in the SmartEiffel times there was a JVM backend, which compiled Eiffel to Java bytecode. This should be made working again with an example to build an Android App in Eiffel.
 '''difficulty: '''Hard
 '''skills: '''Good Eiffel experience, Knowledge of Java Bytecode and Compiler technology.
 '''potential mentors: '''ramack
 '''notes: '''

== Verification backend ==
'''suggested by: '''ramack
 '''summary: '''generate proof obligations from contracts for formal verification, e. g. by generationg of ACSL specifications from the Eiffel contracts to use Frama-C as "verification backend"
 '''difficulty: '''Hard
 '''skills: '''background in formal verification, Eiffel experience
 '''potential mentors: '''ramack
 '''notes: '''

== C++ support wrappers-generator ==
'''suggested by: '''Tybor
 '''summary: '''Add c++ support to wrappers-generator
 '''difficulty: '''Advanced
 '''skills: '''Good c++ knowledge, Good Eiffel experience.
 '''potential mentors: '''Tybor
 '''notes: '''C++ support could be a boon yet it would pose quite a few tricky problems as C++ object modeldiffers from Eiffel's in some ways.

== Scientific wrappers ==
'''suggested by: '''Tybor
 '''summary: '''Add wrappers for scientific purposes: complexes, intervals, arbitrary precision integers and floats. Interesting libraries could be:
* The GNU Multiple Precision Arithmetic Library https://gmplib.org/
* MPFR: multiple-precision floating-point computations with correct rounding. http://www.mpfr.org/
* Mpc: complex numbers with arbitrarily high precision and correct rounding of the result.
* Multi precision intervals http://mpfi.gforge.inria.fr/ https://gforge.inria.fr/projects/mpfi/

 '''difficulty: '''Advanced
 '''skills: '''Good Eiffel experience.
 '''potential mentors: '''Tybor
 '''notes: ''' Several GNU libraries would be a nice addition to Liberty yet their wrappers should be expanded types to be really useful.

== JavaScript backend ==
'''suggested by: '''Tybor
 '''summary: '''Implement an Eiffel to Javascript transcompiler
 '''difficulty: '''Easy/Advanced
 '''skills: '''Medium Eiffel knowledge, good knowledge of Javascript
 '''potential mentors: '''ybor,
 '''notes: '''Javascript is the new "write once run everywhere as it is quickly becoming the new lingua franca of the web. Having an Eiffel to Javascript compielr would widen the usage fields available to Eiffel. A naive compiler would be easy; something that don't require writing tons of glue Eiffel libraries would be quite a harder task. Think about what's to provide "usable" wrappers for libraries such as RaphaelJS or Angular. Their design is all but strongly-typed.

== Idea Template Title ==
'''suggested by: '''ramack
 '''summary: '''Summary of Project Idea (a few sentences)
 '''difficulty: '''None/Easy/Advanced/Hard/Unmanageable
 '''skills: '''what skills shall a student bring to do this?
 '''potential mentors: '''ramack,Tybor,Cadrian
 '''notes: '''anything further needs to be mentioned?

= How can I participate =
First you should register to the [[Get_in_touch|mailing list]]. Last you should add a page here in this wiki to present your project proposal and communicate the following:
* your name and contact data
* your background (other projects you are/have been involved
* list of known programming languages (rate with a scale of 3-10, omit the ones you know less)
* your background and interests (hobbies?)
* your motivation
* your timeline (idea is to have 12 week full time, but some planned absence for vacation or exams is acceptable, include milestones and project subtasks, duration of subtask should be in granularity of 1-2 weeks each)
* your project (what you want to do, why, how, etc. - This is THE main thing we are talking about)
In between (first and last) feel free to discuss ideas and details on list or privately with potential mentors.

Afterwards we will decide which project to accept, based on the subjective estimation of the LibertyEiffel-GSoC-Ratio (benefit for LibertyEiffel * success rate / amount of mentor effort). Note: amount of mentor effort is not linear! Of course the mentors will support you as much as possible, but an Eiffel-newbie working on a compiler-core redesign is just no feasible...

Of course it would be great if you could continue to maintain the project you worked on during GSoC even after the program.

= What about additional questions? =
See our [[Get_in_touch]] page for contact data to the LibertyEiffel community or check the [https://developers.google.com/open-source/gsoc/faq FAQ] provided by Google for this program.

Wrapping C libraries

2014-01-09T09:28:14Z

Tybor: Created page with " == Developer's guidelines == === or how to write GNU-Eiffel wrappers for a C library === <cite> "longum iter est per praecepta, breve et efficax per exempla" "The path ..."

== Developer's guidelines ==
=== or how to write GNU-Eiffel wrappers for a C library ===

<cite>
"longum iter est per praecepta, breve et efficax per exempla" 
"The path of precept is long, that of example short and effectual." 
Seneca the Elder 
</cite>

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

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 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.

==== Prerequites ====

You should be proficient of:

* the C 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.

==== Software prerequisites ====

Make sure you have access on your machine to:

* 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

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.

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.

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.

Let's return to our wrapping/binding work after a due phylosophical digression

=== Preliminares ===

Most data structure in C are usually handled by reference, i.e. using pointers.

Passing objects by value is currently requires "expanded external classes" and will no be covered in this guide. Therefore if your library extensively pass structures around by value and not by reference (with a pointer), for example (TODO: put links to online example of passing structure by value) in function calls or contained in other structures our life will be quite hard. Fortunately enought most libraries handles most of its data structures by reference and zlib is no exception: in fact its basic functions takes pointers as first argument.

----
== The rest of this document still needs to be adapted. ==
== TODO: add proper usage of wrappers-generator ==

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.

A simplicistic rule-of-thumb specifically fitted to wrap libraries written in C is that when we have several functions that takes a pointer to a struct this struct is a good candidate for a class and those functions are good candidates to be wrapped as features usable by an Eiffel program.

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.
Code organization and class hierarchy.

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.

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:

eiffel-glib/library/
|-- core
|-- data_types
|-- externals
|-- fundamentals
`-- utilities

Let's fill zlib/library/loadpath.se. It lists two directories: those containing the high-level classes, the same of the loadpath.se file itself, i.e. the current directory (.) and the ./externals directory which will contain deferred classes that provide access to external features.

./
./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

Low-level access to functions

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
C function Eiffel feature
const char * zlibVersion (void); zlib_version: POINTER
int deflateInit (z_streamp strm, int level); deflate_init (a_stream: POINTER; a_level: INTEGER_32): INTEGER_32
int deflate (z_streamp strm, int flush); deflate (a_stream: POINTER;a_flush: INTEGER_32): INTEGER
int deflateEnd (z_streamp strm); deflate_end (a_stream: POINTER): INTEGER
int inflateInit (z_streamp strm); inflate_init (a_stream: POINTER): INTEGER
int inflate (z_streamp strm, int flush); inflate (a_stream: POINTER; a_flush: INTEGER): INTEGER
int inflateEnd (z_streamp strm); inflate_end (a_stream: POINTER): INTEGER

As you can see I have turned camelCaseFunction into camel_case_function which is far more in tune with Eiffel style. Int is actually an INTEGER_32 or only INTEGER (it still don't matter, even if I suspect that it will do soon: world is already filled with 64-bit machines and literally billion of devices with 4,8,16 bit CPU are in use today, not counting GPGPU)

Let's take a look at ZLIB_EXTERNALS. You'll see many entries like

inflate_init (a_stream: POINTER): INTEGER is -- int inflateInit (z_streamp strm);
external "plug_in"
alias "{
location: "${eiffel_libraries}/plugins"
module_name: "zlib"
feature_name: "inflateInit"
}"
end

this entry tells us that the Eiffel feature "inflate_init" refers to the symbol "inflateInit" in the module "zlib" of the plugins found in the directory.

Entries like this are the only "esoteric" Eiffel code you will see. All the details required to interface to C, to link to the actualy library and how to compile the code written in other languages is handled by the plugin part.

Without using plugins every Eiffel program should know all the details required to compile a C application with zlib. It would require to always use ACE files - even for simple examples - because you need to provide proper "c_compiler_options" and "linker_options"; for a single, simple library like Zlib it looks a tame task, only requiring to add -lzlib to the "linker_options" but when you start building real-world application things will get complicated really fast.

See SmartEiffel documentation on plugins.

All those functions returns an integer with standardized values #defined in the C header. We will wrap them in the deferred class ZLIB_CONSTANTS.

Deferred? Why deferred? We want to avoid the Eiffel programmer the burden to deal with all the details that C requires - otherwise we would have used plain C - so we do not want him/her to directly use that libraries. Deferred classes cannot have creation clauses so we are sure that no objects of type ZLIB_EXTERNALS and ZLIB_CONSTANTS will be created. They are helper classes that will be either inherited from or - more properly - inserted into ZLIB_STREAM and its effective heirs, ZLIB_INPUT_STREAM and ZLIB_OUTPUT_STREAM.

Making sure that the Eiffel developer will not use low-level features directly is the main reason why all the external features are not exported to anyone else, using the syntax feature {} -- External calls. This way only heirs - conforming or not - of that class can use them; for people coming from C++ it's like having private functions members.
C types

Here's a quick conversion table for various C types
C type Eiffel type
int INTEGER;
short int INTEGER_16
long int INTEGER_32 or 64
long long int INTEGER_64
int8_t (defined at stdint.h, ISO C 99) INTEGER_8
int16_t INTEGER_16
int32_t INTEGER_32
int64_t INTEGER_64
unsigned int NATURAL
unsigned short int NATURAL_16
unsigned long int NATURAL_32 on 32-bit, NATURAL_64 on 64.bit. See long int
unsigned long long int NATURAL_64
signed/unsigned char CHARACTER
float REAL_32
double REAL_64
long double REAL_EXTENDED
char BOOLEAN
void* or any other pointer POINTER

Some notes:

intXX_t are defined in GNU systems (Linux Glibc, CygWin and similar).
Currently INTEGER is mere alias for INTEGER_32 but this is bound to change in future version of SmartEiffel. Personally I think that it should be "the integer type with the same bit-lenght of C int".
A nice feature of long int is that is could be longer that int. So we can't really be sure whenever it is 32 or 64 bit. Usually it is an INTEGER_32 on 32-bit machines and INTEGER_64 on 64-bit machines. See this post on the SmartEiffel mailing list.
The same problem applies for long unsigned int: NATURAL_32 on 32-bits and NATURAL_64 on 64-bit. This mismatch can be quite problematic and it will be discussed-addressed later.
At the time of writing of this document SmartEiffel has some know issues regarding NATURALs types. If they actually do cause bugs there is an (unsatisfactory) workaround: use a bigger INTEGER. This implies a hidden conversion at C level and bargains correctness with a little waste of space and worse performance. Do not use an INTEGER of same size: it "usually" works nicely but this is a known source of nasty bugs since you will soon or later it will silently overflow.

An enlighting explanation about C variable types and declarations can be read on Wikipedia (I find particurarly confusing - expecially for the novice - that char is at the same time an 8-bit integer and an encoding for ASCII characters. Most programmers could always end up thinking about it only as a character. After more than 30 years they could have called it "byte". Yet this behaviour is fit the spirit of C very well. ).

The resulting ZLIB_CONSTANTS class is almost boring and undocumented. I maintained the documentation level found in the original documentation, since those are values that will be handled only by the implementation of the wrapper.

Have a look at WRAPPER_HANDLER. Eiffel has the ability to selectively export Any class that needs to access some of the
Access to structure field

Let's wrap the z_stream structure (the structure name is actually struct z_stream_s typedeffed to z_stream during its definition); the wrapper will have a similar two layer design: the low-level Z_STREAM_STRUCT will be a deferred class, with feature {} -- Hidden, low-level getters and setters. This class will also have a feature struct_size: INTEGER that will be the value of sizeof(z_stream)

Field named FooBar in the struct my_struct will be read with the Eiffel query my_struct_get_foo_bar and set with the command my_struct_set_foo_bar. Remember that those are low-level features; references to other objects will be pointers and its signature will be one of an external function: the first argument will be always the address of - a POINTER to - the wrapped struct.
Naming of placeholder arguments

Placeholder names should be chosen in a way that makes the documentation of the feature in English as smooth as possible for a proper argument placeholder for the Gnu-Eiffel language. "CamelCase" will be translated into "a_camel_case", "ENOO" is translated into "an_enoo". Eventual underscores in front of `a_name' are removed: "__foo" becomes "a_foo". The prefixed preposition is added to make clearer that the name refers to a generic value, not to a particular one. Always tries to use a placeholder that can be directly put in the feature's documentation without paraphrase.
ZLIB_STREAM, at last.

So let's write something that will be used in an actual Eiffel program! We start writing ZLIB_STREAM from file common/skeleton that provides us the usual LGPL-2.1-or-later headers. It inserts ZLIB_EXTERNALS and Z_STREAM_STRUCT.

TODO: finish this
The "common" cluster

The basic building blocks of a wrapper library have been put in the common cluster.

The WRAPPER class it the "fundamental" one even if embarassingly simple. Its only effective field (i.e.: stored, non-computed) is the handle POINTER. It shall handle the allocation and deallocation of the memory referred by handle so it is an heir of DISPOSABLE but it doesn't define dispose because there is no such a thing like a default memory handling in C.

C_STRUCT inherits from WRAPPER and provides default implementations for copy, is_equal and from_external_pointer features; it introduces the deferred "struct_size" query which should give the same result of C operator sizeof(MyStruct).

Note that there are - at least conceptually - other potentially heirs of WRAPPER, like pointers to functions

Many C libraries often return const char* strings. Those strings shall not be modified and their memory will be handled by the library; by all other means they actually are plain strings. A correct behaviour is to write foo: STRING is do create Result.from_external_copy(a_function_returning_a_const_char_pointer(handle)) end; a STRING is meant to be manipulated and changed and has control on the memory of its content. Here we are instead given a piece of memory holding some text that is "mostly read-only" whose control is held by the library. To provide correct behaviour STRING must copy the buffer, from_external can't be used. CONST_STRING is an effective heir of STRING that provides efficient wrapping of "const strings". It is usable like any other STRING but all the changes are made to a separe buffer preserving the original content - we are actually not allowed to change it. No further memory is allocated when a CONST_STRING is created: the buffer returned by the C library is used directly. For example, GTK+ has many calls like const gchar* gtk_entry_get_text (GtkEntry *entry); Memory efficiency is achieved making changing features slower. If you need to change its content consider using its feature string to get a new (non-const) STRING with the same content.

TODO: add proper description about:
CACHING_FACTORY
C_ARRAY
COMPARABLE_C_STRUCT
COMPARABLE_WRAPPER
CONST_STRING
C_OWNED
C_STRUCT
EIFFEL_OWNED
ENUM
EXPANDED_WRAPPER
GLOBAL_CACHE
GLOBALLY_CACHED
HASHABLE_WRAPPER
ITERATOR_ON_C_ARRAY
LINKED_STRING
MIXED_MEMORY_HANDLING
NULL_TERMINATED_C_ARRAY
NULL_TERMINATED_STRING_ARRAY
POINTER_HANDLING
REFERENCE_COUNTED
SHARED
STRING_ARRAY
STRING_ARRAY_ITERATOR
WRAPPER_COLLECTION
WRAPPER_DICTIONARY
WRAPPER
WRAPPER_FACTORY
WRAPPER_HANDLER
WRAPPERS_CACHE
Enumerations

There are two general tecnique to wrap an enum.

Put all the possible values of enumerations into a class as INTEGER constants accessibile to the user of your library. This is mostly similar to the actual usage of an enumeration. Each and every feature that accept an enum value as argument will need a precondition like is_valid_foo (a_foo_value)
Create a new type. In fact an enumeration is an INTEGER that can assume only precise and prestabilited values, so that its value is correct and consistent all the times. Class ENUM provides some facilities to achieve this. It shall be used in classes like this:

-- This file have been created by eiffel-gcc-xml.
-- Any change will be lost by the next execution of the tool.

expanded class PANGO_WEIGHT

insert ENUM

creation default_create
feature -- Validity
is_valid_value (a_value: INTEGER): BOOLEAN is
do
Result := ((a_value = pango_weight_ultralight) or else
(a_value = pango_weight_light) or else
(a_value = pango_weight_normal) or else
(a_value = pango_weight_semibold) or else
(a_value = pango_weight_bold) or else
(a_value = pango_weight_ultrabold) or else
(a_value = pango_weight_heavy))
end

feature -- Setters
default_create, set_ultralight is
do
value := pango_weight_ultralight
end

set_light is
do
value := pango_weight_light
end

set_normal is
do
value := pango_weight_normal
end

set_semibold is
do
value := pango_weight_semibold
end

set_bold is
do
value := pango_weight_bold
end

set_ultrabold is
do
value := pango_weight_ultrabold
end

set_heavy is
do
value := pango_weight_heavy
end

feature -- Queries
is_ultralight: BOOLEAN is
do
Result := (value=pango_weight_ultralight)
end

is_light: BOOLEAN is
do
Result := (value=pango_weight_light)
end

is_normal: BOOLEAN is
do
Result := (value=pango_weight_normal)
end

is_semibold: BOOLEAN is
do
Result := (value=pango_weight_semibold)
end

is_bold: BOOLEAN is
do
Result := (value=pango_weight_bold)
end

is_ultrabold: BOOLEAN is
do
Result := (value=pango_weight_ultrabold)
end

is_heavy: BOOLEAN is
do
Result := (value=pango_weight_heavy)
end

feature {WRAPPER, WRAPPER_HANDLER} -- Low level values
pango_weight_ultralight: INTEGER is
external "plug_in"
alias "{
location: "foo"
module: "bar"
feature_name: "PANGO_WEIGHT_ULTRALIGHT"
}"
end

pango_weight_light: INTEGER is
external "plug_in"
alias "{
location: "foo"
module: "bar"
feature_name: "PANGO_WEIGHT_LIGHT"
}"
end

pango_weight_normal: INTEGER is
external "plug_in"
alias "{
location: "foo"
module: "bar"
feature_name: "PANGO_WEIGHT_NORMAL"
}"
end

pango_weight_semibold: INTEGER is
external "plug_in"
alias "{
location: "foo"
module: "bar"
feature_name: "PANGO_WEIGHT_SEMIBOLD"
}"
end

pango_weight_bold: INTEGER is
external "plug_in"
alias "{
location: "foo"
module: "bar"
feature_name: "PANGO_WEIGHT_BOLD"
}"
end

pango_weight_ultrabold: INTEGER is
external "plug_in"
alias "{
location: "foo"
module: "bar"
feature_name: "PANGO_WEIGHT_ULTRABOLD"
}"
end

pango_weight_heavy: INTEGER is
external "plug_in"
alias "{
location: "foo"
module: "bar"
feature_name: "PANGO_WEIGHT_HEAVY"
}"
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.

Using eiffel-gcc-xml

Have a look at the manually written ZLIB_EXTERNALS. Eiffel is a language that is meant to be easy to the reader at the cost of being verbose. All that text of source to access a bunch of C functions. Think about serious libraries that have literally thousands of functions, structures, and enumeration! Writing the low level side of those wrappers is a really long, tedious task, the kind of task that people usually would leave to an unfaticable, astonishgly fast yet quite dumb worker, a computer. Andreas Leitner - who is surely quite smarter than myself - wrote a C parser for his Eiffel Wrapper Generator. I do not have neither the time neither the abilities of Andreas but it seems that I'm more lucky than him. In fact by the time I got serious with this project, people with the same problem, requiring tons of wrappers for Python, produced gcc-xml. These days parsing XML is a considered a common task, a task to be left to standard libraries, so SmartEiffel have an XML parser. So I wrote a little tool name "eiffel-gcc-xml" that takes the output of gcc-xml as input to produce the low-level "external" classes that we need to access functions, structures and enumerations.

Well, it actually requires a little more work since it breaks very often.
Memory handling
C_STRUCT is a wrapper for a data structure implemented in C programming language using a structure.
It does not make any assumption about memory handling; the developer of a SmartEiffel wrapper of a C library has to inherit to create a proper wrapper for it the developer shall inherit both from this class and from classes providing memory handling behavior, depending on how structure's memory shall be handled. This is decided case-by-case by C library.
Currently available memory handling classes are:

C_OWNED: memory is always handled by the underlying C library.
EIFFEL_OWNED: once created memory is fully handled by Eiffel runtime, usually with the Garbage Collector.
GLOBALLY_CACHED: Until disposed by Eiffel the wrapper registered in wrappers dictionary will be the unique wrapper used on the Eiffel side.
MIXED_MEMORY_HANDLING: whose memory can either by handled by the Eiffel library or by the underlying C code. Who handles memory is decided on a per-object based on the value of the flag `is_shared': handle will not be freed on dispose of the Eiffel wrapper object, when `is_shared' is true.
REFERENCE_COUNTED: memory is handled thought reference counting, i.e.GObject

Add proper examples of the various memory handling classes.
Implementing collections
Quite often objects are stored into containers or collections like arrays, linked lists, dictionaries, hashed-tables and so on. Many C libraries provides their own implementation of the classic containers, for example the GLib library provides GList, GSList, GHashTable and many others.
A WRAPPER_COLLECTION is a COLLECTION implemented wrapping some facilities offered by the wrapped C library, like GLib's linked list GList.
When you wrap those data structures you will encounter two kinds of problems:

Pointer returned by C containers could be newly allocated, not already wrapped by the Eiffel wrapper or already wrapper by the Eiffel wrapper. You can't naively create a new WRAPPER every time. Beside the obvious waste of memory and the stress you put on the garbage collector you will break most postconditions and invariant of a COLLECTION, since things that seems obvious like

do_stuff (my_collection: WRAPPER_COLLECTION[ITEM]) is require
my_collection/=Void not my_collection.is_empty local a,b: ITEM do a :=
my_collection.first b := my_collection.first check will_fail: a = b end end

In fact a and b will be different wrappers referring to the same underlying C structure. A WRAPPER_COLLECTION shall avoid this repeated, unnecessary and wrong creation of WRAPPERs, that will breaks invariants and post-conditions of a COLLECTION.
A solution is to inherit from WRAPPERS_CACHE, initializing cache at creation time and keeping it updated during usage. Cache's key is the address (pointer) to the wrapped C structure, value is the corresponding Eiffel wrapper. This way you can get back an already-created Eiffel wrapper.
Classes can implement different scheme; for example G_OBJECT_LIST retrieve the reference to the eventual WRAPPER directly from underlying GObject.

The container has no means to know how it shall create the wrapper for it, since C does not have the notion of generic, strongly typed container. The effective type of the containee is either not know by WRAPPER_COLLECTION or worse its conteinees could actually belong to different classes, sharing a common ancestor.
Since each library has its own idea on how the programmer shall handle �memory when dealing with containers an effective, non-deferred heir of WRAPPER_COLLECTION shall implement `wrapper' feature that given a pointer creates or retrieve a WRAPPER of the fittest class. Usually "plain" usage could return a fixed type; more elaborate type systems like GObject could provide the facilities necessary to pick a useful Eiffel type.

TODO: finish it.
Comparability and hashability
Some collections does not require anything in particular to their containee, like arrays or linked lists. Other collections needs either to compare their containee or to obtain an hash value from it. Therefore wrapper classes that are conceptually comparable or hashable shall inherit from COMPARABLE_WRAPPER and HASHABLE_WRAPPER respectively so they could be stored into collections that requires such abilities.
How to adapt old wrappers
(This is almost obsolete) Previous design was a black-or-white design: a class was either Eiffel-owned or not; C_STRUCT's are "owned" by the Eiffel code, and the Eiffel side should keep then longest lived reference to this struct; SHARED_C_STRUCT modelled the non-Eiffel-owned.
This approach is overly simplicistic since real-life libraries implement a wide spectrum of memory handling policies. One solutions does not fit all needs. Study the documentation of the library and pick the right memory handling Eiffel class.
The long int problem

Shortly it could be solved having two separate clusters one for 32bit, one for 64 bit where a deferred class defines a parameterless query for anchored declaration like

long_int: INTEGER_32 is do end

long_int: INTEGER_64 is do end

but this looks like an unfeasible hack to me, at least now. Currently it is the only available answer; a "proper" solution would require changes in both the compiler and the standard library. I would like to know how ISE solved this.

GObject-based libraries

Nowadays many libraries are based on the GLib Object System also known as Gobject. This library "provides a portable object system and transparent cross-language interoperability". It is used as the basic building block for literally hundeds of libraries and applications; in fact the command apt-cache rdepends libglib2.0-0 |wc -l told me that more than 2200 applications and libraries depend on either GLib or GObject.

GObject implement its own classed type system. With the exception of basic types (and some other subtleties I will write later) all objects are structures referred by pointer, i.e. non-expanded classes in Eiffellese; the type of each object is identified by a number, a GType which has an associated structure to describe the class - the type - itself. During startup of the Eiffel application the wrapper library will register for each type name (i.e. GtkWindow, GtkButton....) it wraps an agent that given a pointer creates an Eiffel wrapper object for the creation_agents dictionary, with a call similar to creation_agents.put (agent create_gtk_window, "GtkWindow"), given the feature create_gtk_window (p: POINTER): GTK_WINDOW is do create Result.from_external_pointer(p) end.

A Gobject can store arbitrary properties into itself. We use this to store a reference pointer to its Eiffel wrapper.

When we receive a pointer to a Gobject the G_OBJECT_FACTORY first looks if this Gobject already has an attacked wrapper (an effective heir of G_OBJECT). Otherwise it ask the Gobject its GType and the associated class-name. It this class-name has a creation agent the wrapper is created invoking the retrieved creation agent; otherwise we recursively look at its parent class until we find a type that has a corresponding creation agent.

When an effective G_OBJECT heir is actually created either explicitly because we know for sure its type or throught a creation agent the address of the wrapper is stored in the property "eiffel-wrapper" using the C function g_object_set_qdata (see store_eiffel_wrapper in G_OBJECT).

As usual this approach is both correct, memory efficient and collection-friendly (see "Implementing collections" earlier) at the cost of being computing intensive. There are times when the wrapper library has to create transient wrappers for shortly lived objects. Here enters secondary wrappers, or G_OBJECTs that are not referred-by the GOBject they refer to. Letting code speak: having a_gtk_window_ptr: POINTER; my_window: GTK_WINDOW; factory: G_OBJECT_EXPANDED_FACTORY check create my_window.secondary_wrapper_from(a_gtk_window_ptr) /= factory.wrapper(a_gtk_window_ptr) end will hold and also create my_window.main_wrapper_from(a_gtk_window_ptr); check my_window = factory.wrapper(a_gtk_window_ptr) end will be successfully passed. The difference is that the first is only an allocation of a smallish object (few bytes) while the latter could potentially require several looks-up into a dictionary plus an O(n) search into the GObject properties (during g_object_get_qdata used to see if a wrapper does actually exist)

TODO: show how to wrap a typical GObject-using library, like Gnome's GConf configuration system.
Commit's policy

There is no strict rule...
Ideally each commit should provide compilable code and working examples.
Provided examples and classes can be unfinished and uncomplete, can contain warnings, empty features and so on. My motto is "something is better than nothing".
it is nice to tell other developers what are you working on; anemail on eiffel-libraries-devel@gna.org suffice.
I promise I won't track you with a 9-tail cat to bash you if you commit uncompilable code.
Code that compiles is a good thing. Wisely designed code that compiles is better, since it has better performances; but I prefer published, working code even if has no state-of-the-art performances instead of

Various very old notes
Those notes are left here to be worked on.

Suggested
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.
Sketch difficoult features into comments.
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.
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.
Enumeration classes will be automatically created by the incoming eiffel-gcc-xml tool.
General

Plugins

2013-08-08T10:51:33Z

Tybor: /* C Generation */

[[Category:Smarteiffel]]

Plugins are a means to augment in a spectactular manner the capabilities of SmartEiffel, by incorporating libraries which have the color, smell, and taste of the standard libraries. In fact, it's an extension of the standard Eiffel mechanism, [[externals]].

The goal of plugins is independence from the [[Glossary#BackEnd|back-end]]. This means that, potentially, the ''same'' library could be used simultaneously by [[compile_to_c]] and [[compile_to_jvm]]. Note that in the future we want to provide other [[Glossary#BackEnd|back-ends]]. In this case, the plugin system will become more important.

== How does it work ? ==

A plugin is made up of two interdependent parts :

* the Eiffel side, which provides an interface usable by other Eiffel objects ;
* the external side, which implements the plugin's interface for one or several [[Glossary#BackEnd|back-ends]] (for example, C and Java).

The Eiffel side is 100% Eiffel code, and it uses ''external'' features that allow crossing the barrier to the other side of the plugin. The barrier is managed by SmartEiffel : the compiler associates external functions with the ''external'' features using configuration files furnished by the plugin.

== Eiffel Side ==

The Eiffel side uses ''external'' features. The syntax is as follows:

feature
my_plugin_feature is
external "plug_in"
alias "{
location: "/path/to/my/plugins"
module_name: "my_plugin"
feature_name: "feature"
}"

Of course, a feature can take arguments and return a result ! (after all, it's an ''external'') ;-)

'''Beware''' however, it is necessary to only pass and return only basic ''expanded'' base types :
([[library_class:INTEGER|<TT>INTEGER</TT>]], [[library_class:BOOLEAN|<TT>BOOLEAN</TT>]], etc.) or use [[library_class:POINTER|<TT>POINTER</TT>]] (common usage: <TT>a_string.to_external</TT>).

* '''location''' indicates the directory where you store one or many of your plugins. This path can contain environment variables (either true system environment variables, or variables definined in the <TT>[Environment]</TT> section of your [[Configuration file|configuration file]]).
For example, the standard SmartEiffel libraries are defined by using the following ''location'':
location: "${sys}plugins"

* '''module_name''' contains the plugin name itself. This must be the name of a sub-directory of ''location'' that contains a directory for a specific [[Glossary#BackEnd|back-end]] (for example, <TT>c</TT> for the C generator, <TT>java</TT> for the Java generator). The content of each of these sub-repositories depends on the generator, and is specified below.

* '''feature_name''' is the name of the feature, function, method etc. named by the [[Glossary#BackEnd|back-end]] (for example, C calls functions, Java calls methods). What they're called is not important : they're all features ;-)

== Dark side ==

=== C Generation ===

The C [[Glossary#BackEnd|back-end]] uses a sub-directory of your plugin named <TT>c</TT>. the files used are:

* all the <TT>.c</TT> files, which are included in the compiler-generated C files
* all the <TT>.h</TT> files, which are included in the compiler-generated header file
* the <TT>libs</TT> file, which contains a description of the native libraries to link
* the <TT>paths</TT> file, which contains a description of the paths used to find the libraries
* the <TT>includes</TT> file, which contains a description of the paths used to find header files
* the <TT>auto_init</TT> file, which contains a description of a possible initialization function called at the very start of the program
* the <TT>cecil.se</TT> file, which is a [[cecil]] description automatically taken into account
* the <TT>compiler_options</TT> and the <TT>linker_options</TT> files which are passed verbatim to the underlying strata of compiling chain, usually a C compiler where they are parsed with a shell. They usually contains invocation of tools that gives the mutable correct flags to compile and link the library, i.e. pkg-config.

The '''<TT>.c</TT> and <TT>.h</TT>''' files are included in alphabetic order.

The '''<TT>includes</TT>, <TT>libs</TT> and <TT>paths</TT>''' files use an identical syntax to that of the [[configuration file]], but with different keys:
* The sections carry the operating system name, the ''flavor'' from the configuration file and finally the C compiler used, in that order and separated by a period. If the plugin doesn't depend on one of these elements, it can be omitted.
* The keys in these files are only informative; however, the values are used to generate command line calls to the C compiler.

The '''<TT>auto_init</TT>''' file uses the same syntax as the [[configuration file]], but with yet other keys:
* The default section (i.e. the first one, without a name between square brackets) contains one key, <TT>function</TT> which value gives the name of the initialization function to call at the start of the system
* Any other section describes plugin dependencies. The must have two keys: <TT>location</TT> and <TT>module_name</TT> which have the same meaning as in the Eiffel alias. Those dependencies describe initialization order (initialize dependencies first).

The '''<TT>cecil.se</TT>''' file is automatically included as it were specified by the <TT>-cecil</TT> option.

For examples, you can examine the configurations files for Vision or ncurses. There is also a tutorial called '''mini_gtk''' (in the <TT>SmartEiffel/tutorial/plugin</TT> directory).

'''Note''': when there are no arguments, names are generated without parentheses. This permits to attributes, variables and to macros. The absence of parentheses is not then a bug but a desired behavior. In the case where one wants access to a function without an argument, it suffices to use a macro to replace a name without parentheses with the name of the function to call.

=== Java Generation===

For the Java [[Glossary#BackEnd|back-end]], the plugin sub-directory must be named <TT>java</TT>.
The compiler uses the following files :

* the <TT>.java</TT> files are compiled using the command line options and/or from the configuration file (see [[compile_to_jvm]] for more detail). The <TT>.class</TT> files so generated are automatically copied in the compilation directory of the program.
* the <TT>.class</TT> files, if they are present and if they are more recent than the corresponding <TT>.java</TT> files are utilized in place of a compilation of the <TT>.java</TT> files, in the same manner as the <TT>make</TT> command under UNIX.

To shorten the compilation time of a program dependent on plugins supplied with the compiler (like for example the <TT>io</TT> plugin), the installer will compile the <TT>.java</TT> plugin files during installation.

Introduction

2013-04-05T22:30:34Z

Tybor:

= Liberty Eiffel is a compiler for the Eiffel programming language =

It '''continues''' the development of SmartEiffel, the GNU Eiffel Compiler.

It is a complete, small and fast, Eiffel compiler, including an Eiffel to C compiler, documentation tools, a pretty printer, a debugger and various other tools.

It also includes a large library of classes distributed under the terms of the MIT/X Consortium License and a comprehensive set of wrappers/bindings for widespread Free-Software libraries.

Eiffel is an advanced object-oriented programming language that emphasizes the design and construction of high-quality and reusable software.

= TODO =
on this page the following shall be done:
* rework content from SmartEiffel Wiki (below Origins of the SmartEiffel project)
* update links to Liberty plan and Documentation, after those pages are moved from github wiki to Mediawiki

= Liberty's roots =

== Origins ==

Liberty has its origin in the [http://en.wikipedia.org/wiki/Statue_of_Liberty Statue of Liberty]. The structure of the Statue was designed and built by [http://en.wikipedia.org/wiki/Gustave_Eiffel Gustave Eiffel], a famous French engineer.

The origins of the language is [http://www.eiffel.com Eiffel] and more specifically [http://smarteiffel.loria.fr SmartEiffel].

== Manifesto ==

We want to retain from SmartEiffel its rigour; but not its rigidity. Think of Liberty as ''SmartEiffel down from its ivory tower''.

Liberty is free as in ''freedom''. We want people to contribute to Liberty from the start.

So please, do join us to give Eiffel the leading position it should have won twenty years ago :-)

== Foundation documents ==

Those documents were published by the SmartEiffel team:

* [http://www.jot.fm/issues/issue_2004_04/article7/ Conformance of agents in the Eiffel language]
* [http://www.loria.fr/~colnet/publis/icsr9.pdf Reconciling Subtyping and Code Reuse in Object-Oriented Languages]

= Liberty's future =

== The grand plan ==

Liberty is at its beginnings. Have a look at the [[Liberty plan]].

== Release names ==
See [[Versions history|list of released versions]] and [[Upcoming releases]].

== Documentation ==
[[Liberty language specification]]
[[Liberty compiler design notes]]

= Community =

You may join us via our mailing list by simply e-mailing to [mailto:libertyeiffel@librelist.com libertyeiffel@librelist.com] The archives are available on [http://librelist.com/browser/libertyeiffel/].

[[Category:Smarteiffel]]
==Origins of the SmartEiffel project==

During the course of his work on his thesis, [[User:Colnet|Dominique Colnet]], principal author of SmartEiffel, discovered the Eiffel language while editing an encyclopedic work on object oriented languages
([[Bibliography#MNCLT 1989|[MNCLT 1989]]], [[Bibliography#MNCLT 1991|[MNCLT 1991]]]).

Holding the post of Assistant Professor of Computer Science in 1989, the Powers That Be at his educational institution at the time decided, in 1990, to use the Eiffel language for introductory computer science.
It is amusing to mention here that Dominique Colnet was at the time a fervent defender of Smalltalk.
As everyone knows, it's a pretty good thing that it's not up to a young Assistant Professor of Computer Science to decide which programming language is the best to use.
So, it is amusing to note that Dominique Colnet was forced to use Eiffel against his will in 1990!

In order to reconcile his teaching and research work on the compilation of object oriented languages, Dominique Colnet decided therefore to abandon
Smalltalk for Eiffel and to establish a project to kill two birds with one stone: combine interesting research with a free product that would also be useful for teaching.

The SmartEiffel project, originally named ''SmallEiffel'' actually commenced
during the year 1994 when Dominique Colnet decided to write his own Eiffel compiler.

Writing an Eiffel compiler is no small undertaking.
Before making this decision, Dominique Colnet had begun to write a new Eiffel class library whose architecture simply corresponded nearly word for word with the base classes one could find at that time in Smalltalk-80 libraries ([[Bibliography#GR 1983|[GR 1983]]],
[[Bibliography#Goldberg 1984|[Goldberg 1984]]]).
Because of the very bad quality of the commercial Eiffel compilers available at that time the decision was taken to write a new one from scratch.
The new compiler was named ''SmallEiffel'' to make reference to both Smalltalk
and Eiffel ([[Bibliography#OOSC 1988|[OOSC 1988]]], [[Bibliography#ETL 1992|[ETL 1992]]]).
An entire year was necessary to write the first version of SmallEiffel and it was not until July 1995 that SmallEiffel was able to compile itself.
Since that time, more than ten years have passed and more than
[[versions_history|thirty versions]] have seen the light of day.

==Little SmartEiffel developing into something big?==
Starting out as simple research prototype and teaching aid, SmartEiffel has seen its capabilities steadily increase from version to version since 1995.

In 1998, on the occasion of a visit to LORIA by Richard Stallman, president and founder of the FSF (Free Software Foundation), the GNU designation was added to the project's name.

<div id="EcmaEiffel">
From 2002 and up to 2005, Dominique Colnet participated actively in meetings with the initial objective of standardizing the Eiffel language
('''ECMA''' standards committee TC39-TG4, ECMA standard number 367).
Of course it goes without saying that the entire SmartEiffel team is associated with the standards work and its many long discussions...

Finally, in May 2005, the SmartEiffel project announced that it was going to continue to work on the ''true Eiffel language''.
In reality, the language described by the ECMA TC39-TG4 working group clearly diverges from what is conventionally called Eiffel.
ECMA-Eiffel is a very different language, and above all, not yet experimented.
The SmartEiffel team will never implement ECMA TC39-TG4.
</div>

At July 2005, at the time when we write these lines, after more than 10 years of work not only on the compiler but also on the Eiffel language itself, we, the SmartEiffel project, consider that the Eiffel language as we know it today, now contains nearly all desirable features.
Therefore, version 2.2 of SmartEiffel marks the debut of a new level of stability and corresponds to what we think of as being the ''true Eiffel language''.

==Objectives of the SmartEiffel project==
The language is entering into a period of stability.
In fact, in version 2.2, the only important thing that is still missing is distributed programming, the [[FAQ#SCOOP|SCOOP]] mechanism.
Needless to say, the implementation of SCOOP will not negatively affect any existing software.
In our opinion, it is evident that one must truly move towards a
'''stable and validated language''' experimentally through work on a large palette of programs.

We anticipate in the short term an important effort which began in version 2.2 concerning the implementation of libraries.
We are also going to '''more fully open up the project''' in order to augment the dynamics around SmartEiffel: to work on a Wiki for consolidation of documentation and to increase the number of people authorized to contribute to the source code of the project.

Without modifying the language, we will work on novel tools in the domain of [[Glossary#TypePrediction|dynamic type prediction]] and on static assertion validation.
In fact, we think that '''the Eiffel language should remain simple'''.
The tools that we are going to integrate will, without any change to the language, focus on the following objectives:
* better predict [[FAQ#StaticVsDynamicType|dynamic types]] and obtain better execution performance,
* statically validate assertions as well as detect calls without a target (calls on [[Void|<code>Void</code>]]),
* statically resolve all typing problems tied to [[Glossary#Covariance|covariance]] and to change of export status ([[FAQ#CATCALL|CATCALLs]]).
Another way to describe the objectives of the SmartEiffel project is to give here our point of view on Eiffel, or more precisely on the spirit of Eiffel.

==Eiffel, the spirit of Eiffel or the Eiffel method?==
Strictly speaking, Eiffel is a language and not truly a method.
That being said, after more than ten years of work on Eiffel and for Eiffel, we cannot help but notice that Eiffel is a good vehicle for a particular way of thinking and therefore as a way of working with computer software. 
We assert here, without fear of contradiction, that Eiffel is most probably the best current language for doing what is commonly called '''software engineering'''. 
This is no surprise when one knows that ''software engineering'' was our guiding principle from the start when we were making choices concerning the Eiffel language.

Before presenting other aspects that we take into account after each evolution of the language, it is good to keep in mind that the perfect universal computer language for all kinds of applications does not exist and will probably never exist. 
Today and probably for some time to come, the concepts of computer programming languages remain empirical and any given language is only effective for only a given spectrum of applications. 
We will try to give below the principal guides that influenced our choice.

Software engineering is the principal guide in the conception and the choices made concerning the Eiffel language. 
The following fundamental points flow from this guideline:
* Eiffel is designed especially for large and even '''very large programs''',
* Eiffel should facilitate working on a team, '''communication and documentation''',
* Eiffel should facilitate '''maintenance and test''' of software components.

Of course, the '''security''' aspect is also one of our primary concerns.
Moreover, as for the software engineering aspect, we propose to set the bar even higher: to put forth a language capable of fully exploiting all machine resources, a language and set of tools to truly generate [[Performance|'''high performance programs''']].

User:Tybor

2013-04-04T22:31:28Z

Tybor: Created page with "I'm Paolo Redaelli, who began programming on a Commodore 64 and then on Amiga. I discovered GNU and freedom in information technology when I bought GeekGadgets for Amiga, a port…"

I'm Paolo Redaelli, who began programming on a Commodore 64 and then on Amiga.
I discovered GNU and freedom in information technology when I bought GeekGadgets for Amiga, a port of the most popular development tools and utilities from the Free Software Foundation (FSF), BSD and other sources.
During IPISA (Incontro Programmatori Italiani Sistemi Amiga, italian amiga programmers meeting) in 1997 I met Richard Stallman; with his talk he taught us what means to seek freedom in IT
Rudi Chiarito was working on the Amiga port of SmallEiffel; at MIPSA he suggested me to study Eiffel and Meyer's "Object Oriented Software Construction".
I'm now a structural civil engineer with a strong toward Quality Management Systems so I found the cleanness of Eiffel and its Design by contract tecnique really useful to write bugfree correct software.
My efforts in Liberty are to provide access to the widest possible set of wrappers and binding to widespread libraries: one of the main reasons Eiffel didn't become widespread is that there weren't enought libraries.

Generated c code

2013-04-04T19:49:11Z

Tybor:

[[Category:Smarteiffel]]
*** I have partially updated the examples here: the hello_world.id file was generated by se2.2beta5 and I
*** have noted some statements that are now obsolete in view of recent compiler changes.
*** This article and its French counterpart need revising by the development team.

*** You can also use [http://SmartEiffel.loria.fr/man/c_code.html the original article]

People who want to interface with applications and/or libraries written in C should as far as possible limit themselves to the interfaces provided by [[Cecil]], [[externals|external]] and [[plugins]]. This page gives details about the generated C code, but these details ought not to be of any use to you. ;-)

== The type identifiers ==

=== Description ===

SmartEiffel generates one unique identifying number for each active type in the Eiffel code[[Generated c code#note1|1]]. A lot of symbols in the generated C code depend on that identifier.

'''Don't depend on those identifiers!''' The mangling table is only valid for one specific compilation of one specific application with one specific compiler version, for one compiler [[compile_to_c]] in one specific version and libraries in one specific version... We do not guarantee the stabbility of these identifiers.

If ''27'' is an identifier, then:

* The C type of an Eiffel object is '''T27''';
* The corresponding C structure is '''struct S27'''; in that structure, the names of the attributes are prefixed with an underscore (there may be some other fields used by SmartEiffel, in particular, the <TT>id</TT> field, which in this case has the value 27). Each reference type can be cast to <TT>T0</TT> (although some reference types may not have the <TT>id</TT> field).
* Each method is called '''r27''method_name''()'''
* Each prefix method is called '''r27_px_''method_name''()'''
* Each infix method is called '''r27_ix_''method_name''()'''
* Each late-binding method is called '''X27''method_name''()'''
* The object's creation method (when the [[Garbage collector|garbage collector]] is used) is called '''new27()'''
* The type model is a variable called '''M27'''. Models are used for initialisation. For example:
T27 M27 = {27,NULL,NULL,0,0};
...
{T27*n=((T27*)se_malloc(sizeof(*n)));
*n=M27;
r27make(n);
...

Some characters in method names, such as <TT>"<"</TT> or <TT>"+"</TT>, will be replaced by their corresponding ASCII code in decimal.

=== An example ===

For example: [[library_class:STRING|<TT>STRING</TT>]] has the identifier '''7'''[[Generated c code#note2|2]]. So:

* The object type is '''T7'''.
typedef struct S7 T7;
* The structure is defined in '''struct S7'''.
struct S7{Tid id;T9 _storage;t2 _count;t2 _capacity;};
* The <TT>append</TT> method becomes:
void r7append(se_dump_stack*caller,T7* C,T0* a1)
(See below for details on the ''dump stack'' execution stack.)

=== The <TT>.id</TT> file ===

When the application is compiled, the list of identifiers is stored in a file whose name is suffixed <TT>.id</TT>. The file is reread in incremental compilations (which allows some stability in the identifiers, so long as the whole project is not recompiled).

This file is structured in ''entries'', each entry being separated from others by a hash character (<TT>#</TT>). This file looks like this:

5 "REAL"
class-path: "/SmartEiffel/lib/numeric/real.e"
class-name: REAL
assertion-level: all
parent-count: 1 inherit: 49
#
72 "FAST_ARRAY"
class-path: "/SmartEiffel/lib/storage/collection/fast_array.e"
class-name: FAST_ARRAY
assertion-level: all
parent-count: 1 inherit: 58
#
62 "STD_ERROR"
class-path: "/SmartEiffel/lib/io/terminal/std_error.e"
class-name: STD_ERROR
assertion-level: all
parent-count: 1 inherit: 39
c-type: T62 reference: yes
ref-status: live id-field: yes
destination-graph-nodes: ->OUTPUT_STREAM
run-time-set-count: 1
run-time-set:
STD_ERROR (62)
#
. . .

You should never depend on these identifiers. In any case, when an identifier is computed, collisions may occur, and affect the process. Thus, the identifier and name of each type depends not only on the type name, but also on the order in which the types are compiled. That is, on the order of ''application'' and ''library'' types combined... They also depend on the compilation mode used (since that can change the list of active types), and the version of the compiler you're using. So what is <TT>T145</TT> today may be <TT>T234</TT> tomorrow[[Generated c code#note3|3]]!

Consequently, '''do not ever rely on the generated identifiers, because they are not constant!''' Do not try to write in your own C code horrible things like <TT>new123</TT> or <TT>T456</TT>, because the only thing we can guarantee is that this code will not work.

== Naming convention ==

The preceding section has explained how methods are generated.

The function prototype <TT>r7append()</TT> from the example above is presented as
v7append(se_dump_stack*caller,T7* C,T0* a1);
This shows how ''Current'' and the arguments are passed. The rules are as follows:

* ''Current'' is called <TT>C</TT> and is always strongly typed (with its own exact type). This parameter may be omitted if Current is not used by the method. In some cases (when code is inlined), ''Current'' can be copied in local variables named <TT>C1</TT>, <TT>C2</TT>...
* The arguments are called <TT>a1</TT>, <TT>a2</TT>... and are typed <TT>T0*</TT> for reference types or given their exact type for expanded types (e.g. <TT>T2</TT> for an integer)
* Inside functions, a local variable <TT>R</TT> is defined. This is ''Result''.
* Local variable keep their Eiffel name, prefixed by an underscore.

=== Agent routines ===

Functions of the form _T111C222l333c444 are agent creations.

222 is the id of the class where the agent creation was written (look it up in
the .id file);
333 is the line number;
444 is the column number.

111 is a little more difficult to explain. It is the id of the type from which
this agent creation will be executed. It can be the same as 222, but it will
be different if 222 corresponds to a generic class, and it can also be
different if a class inherits from 222.

For example, function _T832C832l1362c106
was declared in class #832, on
line 1362 column 106.

== The mangling table ==

OK, now you understand why you cannot use type numbers, but you still want to know what those fields in the mangling table mean (in the <TT>.id</TT> file)>..

First, a big caveat. Although it may have been very stable for quite some time now, '''the mangling table coding may change'''! We currently have no plans to change it, and we prefer keeping it the way it is. But once again, we do not commit ourselves to the current representation.

Let's look again at the extract of a <TT>.id</TT> file. The part shown covers nearly all the possible cases:

5 "REAL"
class-path: "/SmartEiffel/lib/numeric/real.e"
class-name: REAL
assertion-level: all
parent-count: 1 inherit: 49
#
72 "FAST_ARRAY"
class-path: "/SmartEiffel/lib/storage/collection/fast_array.e"
class-name: FAST_ARRAY
assertion-level: all
parent-count: 1 inherit: 58
#
62 "STD_ERROR"
class-path: "/SmartEiffel/lib/io/terminal/std_error.e"
class-name: STD_ERROR
assertion-level: all
parent-count: 1 inherit: 39
c-type: T62 reference: yes
ref-status: live id-field: yes
destination-graph-nodes: ->OUTPUT_STREAM
run-time-set-count: 1
run-time-set:
STD_ERROR (62)
#
. . .

There is one entry per type (active or not); each entry spans many lines and is terminated by a hash symbol (<TT>#</TT>).

Each entry contains a lot of information. Not all of it is always present; missing entries take default values.

Only the first line is compulsory. It contains the type identifier, and its name (as would be returned by <TT>generating_type</TT>).

The following lines contain different fields, marked by a keyword, a colon and a value. There may be one or more fields on a single line. Those fields are:

{|
|-
| '''class-path'''
| The path to the file containing the source code. May be omitted if the class has no associated file (uncommon).
|-
| '''class-name'''
| The name of the class, as returned by <TT>generator</TT>.
|-
| '''parent-count'''
| Le number of parents.
|-
| '''inherit'''
| On the same line as '''parent-count''' if the latter is not null; it gives the list of parent class identifiers.
|-
| '''c-type'''
| The C type, usually in the form '''T27'''. If it is omitted, the class has no runnable type.
In that case, the following fields do not appear either.
|-
| '''reference'''
| On the same line as '''c-type''', <TT>yes</TT> for a reference type or <TT>no</TT> for an expanded type.
|-
| '''ref-status'''
| Either <TT>live</TT> for an active type (i.e. instances of this type are created at run-time), or <TT>dead</TT> otherwise.
|-
| '''id-field'''
| On the same line as '''ref-status''', <TT>yes</TT> if the <TT>id</TT> field has to be generated in the C structure (as its first element), <TT>no</TT> otherwise. This field is present if one of these confitions is true:
* some late binding may occur on targets of that type,
* or the structure may be accessed by an [[external]] or by [[cecil]].
Note that a lot of calls are statically computed; the type inference algorithm used in SmartEiffel increases the number of such types that do not need the id field.

|-
| '''destination-graph-nodes'''
| ????? 
|-
| '''run-time-set-count'''
| The number of concrete, active descendants of the type (including itself). This is the number of items in '''run-time-set''' below.
|-
| '''run-time-set'''
| The concrete, active heirs of this type (including itself). One class per line, tab-indented.
|}

== The dump stack ==

'''When not in boost mode''', a stack is managed by the runtime environment generated by SmartEiffel. This stack is displayed when an uncaught exception is raised. It is also used by the debugger [[sedb]].

Technically, the SmartEiffel stack is built upon the native (C) stack. Each stack element is a <TT>se_dump_stack</TT>[[Generated c code#note4|4]] usually allocated on the stack[[Generated c code#note5|5]]. It is made up of several parts:

* a frame descriptor, of type <TT>se_frame_descriptor</TT>[[Generated c code#note4|4]] which is a static description of the feature, as follows:
** run type,
** does it use Current,
** number and type of the local variables, and
** an anti-recursion flag (for contracts)...
* a dynamic part:
** a pointer to ''Current'' (i.e. either a pointer to an expanded object, or else a pointer to a reference object, it being a pointer to the object itself). That is why the type of the <TT>current</TT> field is <TT>Void**</TT>. This field will be <TT>NULL</TT> if ''Current'' is not used by the ''feature'',o
** the position (used mainly by [[sedb]]),
** a pointer to the caller (i.e. the <TT>se_dump_stack</TT> of the calling function),
** a pointer to the exception origin: if not <TT>NULL</TT>, it means that this <TT>se_dump_stack</TT> ''is not'' in the stack, but was malloc'ed to preserve the exception stack trace,
** an array of local variables (with double indirection as for ''Current''), hence the type void***.

Macros handle the linking between the <TT>se_dump_stack</TT> frames.

* Normally, the top of the dump stack is the global variable <TT>se_dst</TT> defined in <TT>SmartEiffel/sys/runtime/no_check.c</TT>. The macro <TT>set_dump_stack_top</TT> accomplishes the assignment of its argument in this variable.
* In [[SCOOP]] mode, each processor has its own stack. So the <TT>set_dump_stack_top</TT> macro has two arguments: the processor and the new dump stack top.

----
<div id="note1">1. There is a bijection (a one to one relationship) between the number and the ''name'' of the type (including the value of its generic parameters in the case of generic types). </div>

<div id="note2">2. There are some identifiers that are reserved for "basic" types. They are:

* '''0''': the type any other can be cast to
* '''1''': [[library_class:INTEGER_8|<TT>INTEGER_8</TT>]]
* '''2''': [[library_class:INTEGER|<TT>INTEGER</TT>]] (or [[library_class:INTEGER_32|<TT>INTEGER_32</TT>]])
* '''3''': [[library_class:CHARACTER|<TT>CHARACTER</TT>]]
* '''4''': [[library_class:REAL_32|<TT>REAL_32</TT>]]
* '''5''': [[library_class:REAL_64|<TT>REAL_64</TT>]] (or [[library_class:REAL|<TT>REAL</TT>]])
* '''6''': [[library_class:BOOLEAN|<TT>BOOLEAN</TT>]]
* '''7''': [[library_class:STRING|<TT>STRING</TT>]]
* '''8''': [[library_class:POINTER|<TT>POINTER</TT>]]
* '''9''': [[library_class:NATIVE_ARRAY|<TT>NATIVE_ARRAY</TT>]]<TT>[</TT>[[library_class:CHARACTER|<TT>CHARACTER</TT>]]<TT>]</TT>
* '''10''': [[library_class:INTEGER_16|<TT>INTEGER_16</TT>]]
* '''11''': [[library_class:INTEGER_64|<TT>INTEGER_64</TT>]]
* '''12''': [[library_class:REAL_EXTENDED|<TT>REAL_EXTENDED</TT>]]

So it is likely that the root class of the system may have the identifier '''12'''. But do not rely on that too much (before all the changes to INTEGERs, it was '''11''').

All [[liberty_class:NATURAL|<tt>NATURAL</TT>]] classes (NATURAL, NATURAL_8, NATURAL_16, NATURAL_32, NATURAL_64 and NATURAL_GENERAL) does not have a fixed id.

</div>

<div id="note3">3. The compiler will do its best not to change the identifiers uselessly. The <TT>.id</TT> file is loaded at the beginning of the compilation process, and saved again at its end. But [[clean]], for example, erases that file.</div>

<div id="note4">4. You can find the definition of these structures in the <TT>SmartEiffel/sys/runtime/c/no_check.h</TT> file.</div>

<div id="note5">5. The exception is when an exception is raised: in that case, part of the stack is allocated onto the heap before the <TT>longjmp</TT>. </div>