README.md 9.8 KB
Newer Older
1 2 3

# Table of Contents

Noric Couderc's avatar
Noric Couderc committed
4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27
1.  [Building](#org56015e8)
2.  [Structure](#org1f65d63)
    1.  [Layers of Teal](#org650148f)
    2.  [Documentation](#org28194be)
    3.  [Teal Intermediate Language (Teal IR)](#org53b8a2c)
    4.  [Test files](#orgc26f11c)
3.  [Using Teal](#org1dc34a0)
4.  [Running Teal programs](#orgbd9eecb)
    1.  [Adding your own Teal actions](#orgcbffe99)
    2.  [Logging](#org14d6025)
5.  [Notes on the implementation](#org9cbc93d)
6.  [Git FAQ](#org2aa4ef8)
    1.  [What's Git?](#org81662cd)
    2.  [I Can't Clone the Repository](#orge832457)
    3.  [How Do I Update My Fork with Changes the Instructors Made?](#org7dc3950)
        1.  [TL;DR](#orge5951eb)
        2.  [List Remotes](#orgc124a66)
        3.  [Specify a Remote Upstream](#orgc5e6ef5)
        4.  [Get the Changes](#org6f1c095)
        5.  [Merging Changes](#org43e5eb7)
        6.  [Pushing to Gitlab](#org3497367)


<a id="org56015e8"></a>
28 29 30 31 32 33 34

# Building

To build Teal-0 (the default) run:

    ./gradlew jar test

Noric Couderc's avatar
Noric Couderc committed
35 36 37 38
If you want to build without running the tests, run:

    ./gradlew jar

39 40 41 42 43 44 45 46
For other layers of Teal, set suitable parameters; e.g., for Teal-3, run:

    ~./gradlew -PlangVersion=teal-3 jar test

If you are using Teal as part of a course, you may be using a distribution of Teal that does not
include all Teal layers (possibly only Teal-0).


Noric Couderc's avatar
Noric Couderc committed
47
<a id="org1f65d63"></a>
48 49 50 51 52 53 54 55 56 57 58 59

# Structure

The `compiler` directory contains the implementation of the compiler.
It is divided into the following parts:

1.  `compiler/<teal-variant>/frontend`: A compiler frontend that parses code, creates an AST, runs name and type analyses (where available).
2.  `compiler/<teal-variant>/ast/*.ast`: The three parts of the Teal AST: Programs and Modules (`toplevel.ast`), Types (`type.ast`), and declarations, expressions, and statements (`teal0.ast`)
3.  `compiler/<teal-variant>/backend`: A compiler backend that takes an AST and generates Teal IR code (the intermediate representation for Teal).
4.  `ir/`: An interpreter that takes Teal IR code and executes it (via interpretation)(. All variants of Teal currently use the same interpreter.


Noric Couderc's avatar
Noric Couderc committed
60
<a id="org650148f"></a>
61 62 63 64 65 66 67 68

## Layers of Teal

Depending on your distribution, the `compiler` directory may contain multiple subdirectories,
from `compiler/teal0` to `compiler/teal3`.
Lower layers of Teal contain fewer language features.


Noric Couderc's avatar
Noric Couderc committed
69
<a id="org28194be"></a>
70 71 72 73 74 75 76 77 78 79

## Documentation

The `docs/` directory contains a description of the Teal language
(possibly limited to your current Teal distribution).  This
definition takes precedence over the implementation; if the
implementation disagrees with the documentation, you should assume
that this is a bug in the implementation.


Noric Couderc's avatar
Noric Couderc committed
80
<a id="org53b8a2c"></a>
81 82 83 84 85 86 87 88 89 90 91

## Teal Intermediate Language (Teal IR)

Intermediate representations are simplified representations of a programming langauge
that make it easier to analyse and/or optimise the program.
The IR tends to be more verbose than the source code, since it isn't intended for humans to read
but only for the machine to analyse and execute.

Teal IR is most closely related to register transfer IRs such as GIMPLE, LLVM bitcode, or WebAssembly


Noric Couderc's avatar
Noric Couderc committed
92
<a id="orgc26f11c"></a>
93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109

## Test files

The `testfiles` directory contains test files for various parts of the compiler and interpreter.
Each file in these directories can have the following extensions:

-   `.in`: A TEAL file that is loaded in a test
-   `.expected`: The expected output of the test (not necessary TEAL, depending on what we test).
-   `.out`: The actual output we got when running the part of the compiler we're testing.
    -   Tests compare `.expected` and `.out` files.
-   `.teal`: A TEAL file that is usually imported by some other file, usually used for library code.

These files are loaded and tested by the various test classes in:

-   `compiler/teal0/test/lang`


Noric Couderc's avatar
Noric Couderc committed
110
<a id="org1dc34a0"></a>
111 112 113 114 115 116 117 118 119 120

# Using Teal

The Teal compiler and runtime use the same entry point.  You can start
them with the following, which will print out help:
`java -jar build/teal-0.jar`

You can find this main entry point in: `teal/compiler/teal0/java/lang/Compiler.java`


Noric Couderc's avatar
Noric Couderc committed
121
<a id="orgbd9eecb"></a>
122 123 124 125 126 127 128 129

# Running Teal programs

`java -jar build/teal-0.jar program.teal --run arg1 arg2 ...`
The arguments to the program can be integers or strings. This will call the `main` function (which must
take matching formal parameters) and print out the `main` function's return value.


Noric Couderc's avatar
Noric Couderc committed
130
<a id="orgcbffe99"></a>
131 132 133 134 135 136 137 138 139 140

## Adding your own Teal actions

You can find two predefined entry points in `teal/compiler/teal0/java/lang/Compiler.java` that you can
use to get started:

-   `Compiler.customASTAction()`, which you can run with `java -jar build/teal-0.jar program.teal -Y`, can process the AST
-   `Compiler.customIRAction()`, which you can run with `java -jar build/teal-0.jar program.teal -Z`, can process the IR


Noric Couderc's avatar
Noric Couderc committed
141
<a id="org14d6025"></a>
142 143 144 145 146 147 148 149 150 151

## Logging

Can be enabled by the `TEAL_DEBUG` environment variable:

-   `export TEAL_DEBUG=interp` enables interpreter debugging
-   `export TEAL_DEBUG=irgen` enables IR generation debugging
-   `export TEAL_DEBUG=interp,irgen` enables both interpreter and IR generation debugging


Noric Couderc's avatar
Noric Couderc committed
152
<a id="org9cbc93d"></a>
153 154 155 156 157

# Notes on the implementation

See [the implementation notes](notes.md) (if available in your distribution).

Noric Couderc's avatar
Noric Couderc committed
158

Noric Couderc's avatar
Noric Couderc committed
159
<a id="org2aa4ef8"></a>
Noric Couderc's avatar
Noric Couderc committed
160 161 162 163 164 165

# Git FAQ

Here are answers to some questions you may ask yourself when using Git.


Noric Couderc's avatar
Noric Couderc committed
166
<a id="org81662cd"></a>
Noric Couderc's avatar
Noric Couderc committed
167 168 169 170

## What's Git?

Git is what's called a version control system.
Noric Couderc's avatar
Noric Couderc committed
171 172 173 174 175 176 177 178 179 180 181 182
But what does that mean? Let's look at each word:

-   Version: A version is a snapshot of code, it's like a picture of the state of code at a given point.
-   Control: We want to manage versions, that is, we want to do things like:
    -   Change version easily (for instance, going back to an older version)
    -   Compare two versions
    -   Merge versions together
    -   etc.
-   System: Well, that's just a program that allows you to do something, in this case, version control.

In other words, git is a piece of software that helps you track and
compare changes you (and other people!) make to your code.
Noric Couderc's avatar
Noric Couderc committed
183 184 185 186

Have you ever made a million changes to a program, only
to realize your idea doesn't work and now you have to get
fifteen files back to the state they were in? Well,
Noric Couderc's avatar
Noric Couderc committed
187
git's job is to make this task easy.
Noric Couderc's avatar
Noric Couderc committed
188 189 190 191 192 193

Git is very useful, and used *everywhere*, but it's also
a bit difficult to learn. Some git commands will seem
very mysterious as you start, and that's normal,
if you need help, please contact us!

Noric Couderc's avatar
Noric Couderc committed
194 195 196 197
If you want to get a rough idea of the commands, you can use this [cheat sheet](https://about.gitlab.com/images/press/git-cheat-sheet.pdf).

For a more detailed introduction, you may look at [Gitlab's documentation](https://docs.gitlab.com/ee/gitlab-basics/start-using-git.html).

Noric Couderc's avatar
Noric Couderc committed
198 199
Lastly, if you prefer videos with rainbows and unicorns, you may be
interested in [this series of videos by Daniel Shiffman](https://thecodingtrain.com/beginners/git-and-github/).
Noric Couderc's avatar
Noric Couderc committed
200

Noric Couderc's avatar
Noric Couderc committed
201

Noric Couderc's avatar
Noric Couderc committed
202
<a id="orge832457"></a>
Noric Couderc's avatar
Noric Couderc committed
203 204 205 206 207 208 209 210 211 212 213 214

## I Can't Clone the Repository

You probably need to upload a SSH public key to the Gitlab server.
You generate those on your computer, two files will be created,
you upload the contents of of these files to the Gitlab, so it knows who you are.

The file you didn't upload (the private key) is not to be shared with anyone.

[Here](https://docs.gitlab.com/ee/ssh) is a tutorial on how to do that.


Noric Couderc's avatar
Noric Couderc committed
215
<a id="org7dc3950"></a>
Noric Couderc's avatar
Noric Couderc committed
216 217 218 219 220 221 222 223 224

## How Do I Update My Fork with Changes the Instructors Made?

Sometimes, Noric or Christoph might update the exercises, you can synchronize your
forks with the changes have been made with git (while keeping your own changes too!).

Here's how you do it (based on [this tutorial](https://medium.com/@sahoosunilkumar/how-to-update-a-fork-in-git-95a7daadc14e)).


Noric Couderc's avatar
Noric Couderc committed
225
<a id="orge5951eb"></a>
Noric Couderc's avatar
Noric Couderc committed
226 227 228

### TL;DR

229 230
If you're too lazy to read the rest, here is the following in script form.
Run these instructions in the `exercise-1` directory.
Noric Couderc's avatar
Noric Couderc committed
231

232
    git remote add upstream https://git.cs.lth.se/creichen/edap15-exercise-1.git
Noric Couderc's avatar
Noric Couderc committed
233 234 235 236 237 238 239 240
    git fetch upstream
    git checkout master
    git merge upstream/master
    git push origin master

Otherwise, here are the explanations!


Noric Couderc's avatar
Noric Couderc committed
241
<a id="orgc124a66"></a>
Noric Couderc's avatar
Noric Couderc committed
242 243 244 245 246 247 248 249 250 251 252 253 254 255

### List Remotes

This gives you the list of remote repositories, they are places where code lives
that aren't on your computer.

    git remote -v

You should see something like

    origin	git@coursegit.cs.lth.se:edap15-2020/<group>/exercise-1.git (fetch)
    origin	git@coursegit.cs.lth.se:edap15-2020/<group>/exercise-1.git (push)


Noric Couderc's avatar
Noric Couderc committed
256
<a id="orgc5e6ef5"></a>
Noric Couderc's avatar
Noric Couderc committed
257 258 259 260 261 262 263

### Specify a Remote Upstream

This is a way to tell git you know another place where similar code
is, and that will be the address of the main exercise 1 repo, the one you forked.
We can give names to remote, we'll call this one *upstream*.

264
    git remote add upstream https://git.cs.lth.se/creichen/edap15-exercise-1.git
Noric Couderc's avatar
Noric Couderc committed
265 266


Noric Couderc's avatar
Noric Couderc committed
267
<a id="org6f1c095"></a>
Noric Couderc's avatar
Noric Couderc committed
268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285

### Get the Changes

You can get the new changes by calling the following (don't worry, it won't erase any of your code!):

    git fetch upstream

If you look at your files, nothing should have changed. That's because
git can handle several copies of your code simultaneously without a problem,
using something called *branches*.

So now both the code from the upstream repo and yours are on your computer
you just can't see the other branch. You can look at it by typing `git checkout upstream/master`

You can also *compare* branches with `git diff upstream/master`, this will show
the differences between your master branch and `upstream/master`.


Noric Couderc's avatar
Noric Couderc committed
286
<a id="org43e5eb7"></a>
Noric Couderc's avatar
Noric Couderc committed
287 288 289 290 291 292 293 294 295 296 297 298 299

### Merging Changes

Lastly, git is also able to merge changes from two branches together.
There might be conflicts that you would have to resolve by hand, but in most
cases, it works.

You do this by running

    git checkout master # make sure you're on the right branch
    git merge upstream/master


Noric Couderc's avatar
Noric Couderc committed
300
<a id="org3497367"></a>
Noric Couderc's avatar
Noric Couderc committed
301 302 303 304 305

### Pushing to Gitlab

Now you can update gitlab's copy of your code with `git push origin master`