From 83a3813dd4dca0a912ee83b7b494e9e9b82f9913 Mon Sep 17 00:00:00 2001 From: Stefano Sanfilippo Date: Sun, 8 Mar 2015 13:56:06 +0100 Subject: [PATCH] Updating readme. --- README.md | 75 ++++++++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 63 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index 76ff2b9..721b2a2 100644 --- a/README.md +++ b/README.md @@ -12,8 +12,10 @@ Compilation =========== You will need `bison` version >= 3.0 (Bison 2.5 requires manual intervention), -`flex` >= 2.5 and any C++11 compiler. The build scripts are generated using -CMake. A typical Makefile-based build workflow would be: +`flex` >= 2.5, `LLVM` >= 3.5, `Boost` >= 1.48 and any C++11 compiler. +The build scripts are generated using CMake. + +A typical Makefile-based build workflow would be: mkdir build/ cd build/ @@ -36,12 +38,48 @@ is provided in `cmake/bison2.patch`. You will have to manually apply it with: However note that compilation with Bison 2.5 is not supported and the patch might be removed in the future. +###Building with LLVM on Debian/Ubuntu +Debian Testing and Ubuntu >= 14.04 distribute a LLVM 3.5 development package +**which is broken** (see [1](https://bugs.launchpad.net/ubuntu/+source/llvm/+bug/1365432) +and [2](https://bugs.launchpad.net/ubuntu/+source/llvm/+bug/1387011)). + +Luckly, LLVM.org directly provides an APT repo which works fine. +http://llvm.org/apt/ have all the relevant info for installing the repo. +After that, the package we need is `llvm-3.5-dev`. + +**This is only necessary for compilation, Debian/Ubuntu LLVM runtime libs +and utilities work just fine.** + Usage ===== -`mcc` is a source to source compiler, which reads Monicelli and outputs a -subset of C++. For those of you who want to get to the code ASAP, the `examples/` -folder contains a set of programs covering most of the features of the language. +###LLVM frontend +Monicelli emits LLVM bytecode in its default configuration. +A typical compilation workflow would be: + + $ ./mcc example.mc + $ llc example.bc + $ cc example.s libmcrt.a -o example + +In particular, note that the Monicelli runtime library must be linked to use +all of the I/O functions. Also note the use of the `llc` utility, which is +provided by LLVM, to produce native assembler from LLVM bitcode. + +As such, `llvm` utilities are needed for compiling. Only the "low level" +utilities (`opt` and `llc`) are needed, not the whole Clang/Clang++ suite. +Usually, the relevant package goes under the name `llvm`. + +`mcc` does not optimize the emitted bytecode to ensure readibility when +disassembling with `llvm-as`. However, you might want to optimize the code +using `opt` LLVM utility: + + $ opt example.bc | llc -o example.s + +in place of the simple `llc` compilation step. + +###C++ transpiler +`mcc` can be compiled as a source to source compiler, which reads Monicelli +and outputs a subset of C++. A good way to learn on the field is comparing the resulting C++ with the input. Well, mostly with the beautified version of the input, `*.beauty.mc`. @@ -75,6 +113,11 @@ Accented letters can be replaced by the non-accented letter followed by a backtick `` ` ``, although the use of the correct Italian spelling is strongly encouraged for maximizing the antani effect. +###Get started! +For those of you who want to get to the code ASAP, the `examples/` +folder contains a set of programs covering most of the features of the language. + + Main ---- @@ -110,6 +153,10 @@ They are directly mapped on usual operators as follows: So `2 più 4` means `2 + 4`. +When evaluating binary expressions whose operands have different types, +the type of the result will be the less restrictive between the two. +This ensures that no loss takes place when evaluating an expression. + ###Binary shift Binary shift operators have a slighly different @@ -159,18 +206,22 @@ A value can be assigned to a variable with the following statement: the alternate spelling `come se fosse` can be used as well. +The `` initializer is casted to the declared type of the variable, +even if the cast will cause some loss. This feature can be (ab)used to introduce +C-style casts too. + ###Declaration Variables can be declared in any scope. There are 5 variable types, which are directly mapped on C++/C99 types as follows: -| Type name | Mapped C type | -|-----------|---------------| -| Necchi | `int` | -| Mascetti | `char` | -| Perozzi | `float` | -| Melandri | `bool` | -| Sassaroli | `double` | +| Type name | Mapped C type | Size | +|-----------|---------------|-------| +| Necchi | `int` | 64bit | +| Mascetti | `char` | 8bit | +| Perozzi | `float` | 32bit | +| Melandri | `bool` | - | +| Sassaroli | `double` | 64bit | A variable is declared with the following statement: