README.md

Introduction
============

This Directory contains various examples for working with the LLVM tools.

All interesting files are from the LLVM project -
See http://llvm.org and in particular http://www.llvm.org/docs/
for more information.

This collection was prepared by Prof. R. C. Moore, fbi.h-da.de
in May 2017 for the Compiler Construction course. No warranty implied or expressed.
See LICENSE.TXT for the original license.

This code assumes you have clang and the LLVM library installed -- see below.

It is generally up-to-date with the latest LLVM release:
 *  The current version was updated in Summer 2020 and worked with the LLVM 10 at that time.
 *  Small changes have been made in 2021 to get it to work with LLVM 11.
 *  LLVM 12 was released in April 2021 (!) and this code has **not** been updated for it (yet),
    since as of this writing, not even Arch Linux makes this available.  
 *  However, **be warned**, this code will eventually be updated to LLVM 12! 


All of the example files (fibonacci.cpp, ModuleMaker.cpp and toy*.cpp):
 -  are available in the LLVM source tree, for example at <https://github.com/llvm/llvm-project/releases/tag/llvmorg-11.1.0>.
 -  the directory structure has been simplified, some files have been renamed,
    and a new Makefile is provided which is much simpler than the original cmake
    system (but not guarenteed to work outside Linux).  
 -  Test files have also been added. See below. 

Still, it should be emphasized that there is nothing really new here -- apart 
from the packaging, everything here is from the LLVM project!


Manifest ("Table of Contents")
===============================

You should have received the following files:

 * `fibonacci.cpp`  
This is a compiler without a front-end, so to speak,
but with an interpreter built in - see ModuleMaker for
an even simpler example.
 * `LICENSE.TXT`         
The LLVM Release Open Source License
(taken verbatim from the University of Illinois/NCSA,
https://github.com/llvm/llvm-project/blob/master/llvm/LICENSE.TXT).
 * `Makefile`  
A Makefile, not supplied by LLVM but written instead
by R. Moore - to make this collection work without the
rest of the LLVM source tree.  You will (of course)
need the LLVM tool set installed (clang, clang++ &
llvm-config and the llvm libs, at the very least).
 * `ModuleMaker.cpp`   
Another example provided in the LLVM source tree.
This file produces binary LLVM bit code for a program
which does nothing but return a status of 5. LLVM
bit code can be run using the LLVM "lli" tool.
Thus, you should be able to do the following:

```sh
$ make ModuleMaker  
$ ./ModuleMaker >status5.bc  
$ lli status5.bc  
$ echo $? # should print "5"  
```

"Hello World" doesn't get much simpler than this!
(Running "make testModuleMaker" does this, by the way).
 * `README.md`            
This file.
 * `KaleidoscopeJIT.h`   
A header file used by some of the toy4.cpp - toy9.cpp.
This version works with LLVM 10. 
 * `tests`            
A directory containing files in the Kaleidoscope
language, taken from the LLVM Tutorial, see
https://llvm.org/docs/tutorial/MyFirstLanguageFrontend/index.html
Some, but not all, of these are used by "make tests".
 * `toy2.cpp` - `toy9.cpp`          
The source code from the Tutorial, Chapters 2 through 9.

All of the above Chapters are available at
https://llvm.org/docs/tutorial/MyFirstLanguageFrontend/index.html

Building
=========

1.  Install clang and the llvm tool kit.  You can either compile from source
    (see above) or install binaries that you find elsewhere. 
    In any case, be careful about the verison of LLVM you install (again, see above)!

2.  Run `make` (or perhaps `make clean` and then `make`).

3.  If you wish, run `make tests` to run (almost) all the programs delivered
    in this colleciton.  
    The output from `make tests` is very long.
    Each program can also be tested individually, for example with
    `make testFibonacci` or `make testModuleMaker` or `make test5` 
    (read the Makefile to see all alternatives).  
    
    **Note**: `make test9` is broken. This is a known problem.
    That's why it's not included in `make tests`.   
    Please feel free to help me fix it.

Further Reading
===============

These files are only provided to illustrate how LLVM can be used.  The code from
the tutorial should be read together with the tutorial.

More information is available:

 * Overview of the LLVM Documentation:
http://llvm.org/releases/10.0.0/docs/index.html
 * The LLVM ("Kaledeiscope") Tutorial:
https://llvm.org/docs/tutorial/MyFirstLanguageFrontend/index.html
 * Guide for Programmers:
http://llvm.org/releases/10.0.0/docs/ProgrammersManual.html
 * Guide to the LLVM IR (LLVM Intermediate Representation):
http://llvm.org/releases/10.0.0/docs/LangRef.html