Getting Started

This simple tutorial demonstrates the lossless translation facility in Jekyll. In the future this tutorial will be augmented with other tutorials that explore the language in more detail.

The first thing you need to do is install the Jekyll translator on your machine. To do this, go to the download page, and follow the instructions given there.

Translation from Jekyll to C

Once you have the Jekyll compiler installed, enter the following command:

$ jekyll --jekyll2c examples/prelude.jkl -o examples/prelude2.c -I examples/

This creates a C file called "prelude2.c" that is a C version of the Jekyll file "prelude.jkl". "prelude.jkl" is a simplified Jekyll version of a subset of the Haskell Prelude. Amongst other things, "prelude.jkl" demonstrates generic types, Haskell-style type-classes, and tagged unions.

If you look at "prelude2.c" you will see that the generated C code is quite readable, preserving all of the layout and commenting of the original Jekyll file.

Translation from C to Jekyll

Now for the magic. Enter the following command:

$ jekyll --c2jekyll examples/prelude2.c -o examples/prelude2.jkl -I examples/

This translates the C file back into a Jekyll file. Moreover, this Jekyll file will be exactly the same as the original Jekyll file. We can verify this using diff:

$ diff examples/prelude.jkl examples/prelude2.jkl

Editing C files

What happens if I edit a C file? Lets try it. In the C file insert a call to "printf" before the "return" statement on line 119. Now convert the file back to Jekyll. Let's see how the Jekyll file changes:

$ diff examples/prelude.jkl examples/prelude2.jkl
118a119
> printf("hello");

The change in the C file is reflected exactly into the Jekyll file. Most changes to a C file will transfer smoothly into the Jekyll version of the file.

Malformed C files

Those of you who looked at the C file will have noticed that the C file contains some special boilerplate code that is generated to implement some of the more complex Jekyll features. This boilerplate code uses special Jekyll macros that have special meaning to Jekyll but which are ignored by C compilers. What happens if we edit this boilerplate code so that it no longer corresponds to a correct use of a Jekyll feature?

Let's try it and see. On line 129 of "prelude2.c" replace "Show" with "Sphow". This boilerplate code will now be invalid, since it makes reference to a non-existant Jekyll interface. Now lets try translating this broken file to Jekyll:

$ ./jekyll --c2jekyll examples/prelude2.c -o examples/prelude2.jkl -I examples/
File examples/prelude2.c : 129 characters 28 - 32
Malformed input file: expected Show but given Sphow
    string(*show) (_dictenv(Sphow, List), _tagged List _p(_v( a)) *x);
                            ^^^^^

Jekyll spots the invalid input file and highlights where the boilerplate code was modified incorrectly.

Existing C files

So, Jekyll can compile programs written in Jekyll, but what about existing programs written in C?

Since Jekyll is a superset of C, most C files should work as Jekyll files. One may have to add "unsafe" in a few places to avoid safety warnings, and one may have to give Jekyll types for complex macros, but most existing code should go through with relatively little effort.

As a small example of how a C program can be ported to Jekyll, have a look at the file "gtktest.jkl" in the examples directory. This is a slightly modified version of the "hello world" example from the GTK. The only modification we have made from the original is that we have told Jekyll the types for some of the more complex GTK macros.

We can translate this file back to C as follows:

 $ ./jekyll --jekyll2c examples/gtktest.jkl -o examples/gtktest.c 
	`pkg-config --cflags gtk+-2.0`