Commit ccad2b57 authored by Bednárek David RNDr. Ph.D.'s avatar Bednárek David RNDr. Ph.D.
Browse files

redirected doc to web

parent ba330ce7
......@@ -4,7 +4,11 @@ The skeleton of Cecko.
## Getting Started
* [Prerequisities](doc/Prerequisities.md)
* [Creating your Cecko repository](doc/Repository.md)
* [Building Cecko](doc/Building.md)
* [Running and debugging Cecko](doc/Runnning.md)
* [Prerequisities](https://www.ksi.mff.cuni.cz/teaching/nswi098-web/index.html#@tab_prerequisites)
* [Creating your Cecko repository](https://www.ksi.mff.cuni.cz/teaching/nswi098-web/index.html#@tab_repository)
* [Building and running Cecko](https://www.ksi.mff.cuni.cz/teaching/nswi098-web/index.html#@tab_building_and_running)
## [The assignments](https://www.ksi.mff.cuni.cz/teaching/nswi098-web/index.html#@tab_assignments)
* [The Cecko grammar](doc/selected-grammar.md)
# Building Cecko
## Command-line
Create a `<build-folder>`, by convention as `<cecko-folder>/build`. Then configure using these commands:
```bash
cd <build-folder>
cmake -DCMAKE_BUILD_TYPE=Debug -DLLVM_DIR=<llvm-install-folder>/lib/cmake/llvm <cecko-folder>
```
The `-DLLVM_DIR` option is usually not required if LLVM was installed as a system package.
Building is then done by invoking `cmake --build .` or `make` in `<build-folder>`.
The resulting executables are located in `<build-folder>/stud-main` and invoked like:
```bash
cd <build-folder>
<build-folder>/stud-main/cecko1 <cecko-folder>/test/test1.c
```
## Visual Studio 2019
Open the `<cecko-folder>` with Visual Studio.
When opened for the first time, use **PROJECT/CMake Settings** to adjust the cmake configuration, the `LLVM_DIR` variable in particular (see Prerequisities). The default `x64-Debug` configuration is created automatically; to use WSL, add the `WSL-GCC-Debug` configuration, adjust it if necessary and switch to it.
## Visual Studio Code
In Windows, install the Visual C++ compiler first. Then start an **x64 Developer Command Prompt** (which defines the environment where the compiler is visible), then run `code` from the command prompt. Then follow the documentation for the **CMake Tools** extension.
# Prerequisities
## Platform
Recodex uses Linux and GCC to compile and run your submissions. It may trigger errors which escaped detection in other compile/run environments. For such cases, it is advantageous to have a GCC-based build environment prepared beforehand.
On the other hand, the Cecko sources are intended to be multi-platform and the skeleton is regularly tested with both GCC and Microsoft Visual C++. Therefore, development using MSVC is possible (and encouraged).
### Windows Subsystem for Linux
For developers equipped with Windows 10, [Windows Subsystem for Linux](https://docs.microsoft.com/en-us/windows/wsl/about) (WSL) is recommended as the best approach to multi-platform development. Compiling, running and debugging in the WSL-GCC environment is integrated in Visual Studio 2019 (as well as VS Code) and fully supported by Cecko projects.
_Note: Due to the small size of Cecko, there is no significant build-performance difference neither between WSL 1 and WSL 2 nor between Windows and Linux filesystems. However, if you plan to build LLVM on your own (instead of downloading binaries), placing the working folder in the Linux filesystem of WSL 2 may shorten the build time by an hour. Ubuntu (currently 20.04 Focal) is the recommended distribution for WSL (and the default supplied by Microsoft)._
## Git
Make yourself familiar with the principles of **git**.
In Linux, you will probably use command-line `git` which is present in all modern Linux distributions.
In Windows, [TortoiseGit](https://tortoisegit.org/download/) is the recommended option.
_You may also try using the Git plugins in Visual Studio 2019 or VS Code; however, be aware that some advanced commands may not be available there._
To access [gitlab.mff.cuni.cz](https://gitlab.mff.cuni.cz), you will first need to login (using your SIS credentials) in its web interface and register your SSH keys there (if you have not done so yet).
## Build tools
### cmake
**CMake 3.8 or newer is required.** It is present in any (sufficiently new) distribution of **Linux (including WSL)**, installed by something like:
```bash
sudo apt install cmake
```
For **Windows**, cmake (and ninja) is installed with Visual Studio 2019 when **C++ CMake tools for Windows** is enabled in the Visual Studio Installer. **C++ CMake tools for Linux** is required when Visual Studio is used to build in WSL or remote Linux.
When using VS Code, cmake (as well as a C++ compiler) must be installed as an external tool.
### bison and flex
**bison 3.4 and flex 2.6.4 or newer are required.** They are present in any (sufficiently new) distribution of **Linux (including WSL)**, installed by something like:
```bash
sudo apt install bison flex
```
For **Windows**, they may be downloaded from [lexxmark/winflexbison](https://github.com/lexxmark/winflexbison/releases). Unpack the .zip to a suitable location and **add the folder to the `Path` variable** using the **Edit the system environment variables** control panel dialog. This package contains `win_bison.exe` and `win_flex.exe` - these names *are* recognized by cmake.
_Note: Although Chocolatey contains a `winflexbison3` package, it (as of July 2020) does **not** satisfy our version requirements._
_Note: You cannot use WSL installations of bison/flex for MSVC builds (and vice versa) because cmake would not invoke them properly. Therefore you will probably end with two bison/flex installations if you do both MSVC and GCC builds, similarly to having two installations of cmake in this case._
### C++17 compiler
MSVC 19.26 (part of Visual Studio 2019) and gcc 9.3.0 are verified to be sufficient for the compilation of Cecko.
## LLVM
Cecko uses the intermediate code (IR) and JIT x86 code generator (MCJIT) from the [LLVM](https://llvm.org/docs/) framework. Although the LLVM team recommends building LLVM from sources, it may be well beyond the capability and patience of most Cecko developers. Therefore, downloading a binary version is recommended.
_Note: Cecko requires only headers and static libraries; however, all binary distributions of LLVM include also many executables and dynamic libraries. Some downloads/packages include only the executables which is insufficient for Cecko._
### Linux (including WSL) binaries
The simplest way to install the required LLVM modules is from a Linux distribution channel, like:
```bash
sudo apt install llvm-10
```
cmake will automatically find LLVM if installed in this way.
_Note: Although these libraries are compatible with Debug mode, they do not contain full debug info, for example, stepping into LLVM procedures during debugging of Cecko may be impossible._
_Note: LLVM is also available in the form of [Pre-Built Binaries](https://releases.llvm.org/download.html). Hovewer, their availability and contents are variable; also their correct installation is not trivial (see the Windows subsection below for some hints)._
### Windows binaries
_Beware: The Windows versions of Pre-Built Binaries published by LLVM (as of July 2020) are **not** complete enough for Cecko._
Pre-built LLVM binaries for Cecko are avalable at [gitlab.mff.cuni.cz](https://gitlab.mff.cuni.cz/teaching/nswi098/cecko/llvm-install). The version for Windows MSVC is located at the branch `MSVC-x64-Debug`. Clone the branch into `<llvm-install-folder>` using:
```bash
git clone -b MSVC-x64-Debug git@gitlab.mff.cuni.cz:teaching/nswi098/cecko/llvm-install.git <llvm-install-folder>
```
_The cloning may take some time, the download size is about 600 MB because of full debug info._
_Note: Because publishing incomplete binaries may interfere with the LLVM licence, this gitlab repository is available only for logged-on users._
When building Cecko, **cmake must be instructed to find LLVM** by setting the `LLVM_DIR` cmake variable to the value `<llvm-install-folder>/lib/cmake/llvm`.
In Visual Studio 2019, the `LLVM_DIR` variable is set in the **CMake variables and cache** section of the **CMake Settings** (CMakeSettings.json); you may run **Generate Cache** to pre-create this variable before setting it to the correct value.
In VS Code, the `LLVM_DIR` variable is located in the `cmake.configureSettings` entry of `.vscode/settings.json`.
When cmake is invoked from command-line, it may look like:
```bash
cmake -DLLVM_DIR=<llvm-install-folder>/lib/cmake/llvm <...other-arguments...>
```
### Building LLVM (advanced)
If you decide to ignore binary distributions and build LLVM on your own (beware, it may require several hours of downloading and building), the simplest approach is cloning [llvm-project](https://github.com/llvm/llvm-project.git) into a `<llvm-project-folder>`:
```bash
git clone https://github.com/llvm/llvm-project.git <llvm-project-folder>
```
To build and install, create a `<llvm-build-folder>` and a `<llvm-install-folder>`, then configure, build and install using:
```bash
cd <llvm-build-folder>
cmake -DCMAKE_BUILD_TYPE=Debug -DCMAKE_INSTALL_PREFIX=<llvm-install-folder> <llvm-project-folder>/llvm
cmake --build .
cmake --build . --target install
```
When building Cecko with the home-built LLVM, define the `LLVM_DIR` variable as `<llvm-install-folder>/lib/cmake/llvm`.
_See also [Building LLVM with CMake](https://llvm.org/docs/CMake.html)._
# Creating your Cecko repository
It is advisable to have your work backed up in a private remote repository. If you store it in [gitlab.mff.cuni.cz](https://gitlab.mff.cuni.cz/), your teachers may easily be able to access your sources in case you need help.
Important: **Your remote repository shall remain private**, otherwise you may be deemed guilty if a plagiarism case appears. Grant access only to your teachers, even after your work is finished and points awarded.
Create your private remote repository using the gitlab web interface (initialize it with README.md).
## Importing the skeleton into your private repository
Clone your private repository into a local folder:
```
git clone <private-remote-repository-url> <local-folder>
```
Pull [teaching/nswi098/cecko/skeleton](https://gitlab.mff.cuni.cz/teaching/nswi098/cecko/skeleton) into the local repository:
```
cd <local-folder>
git remote add upstream git@gitlab.mff.cuni.cz:teaching/nswi098/cecko/skeleton.git
git pull upstream master
```
In TortoiseGit, the commands above are done in the **Git Sync...** dialog by first using **Manage** to add the new *remote* called `upstream`, then selecting `upstream` and invoking **Pull**. (Remember to switch back to `origin` if you want to pull from your private repository later.)
_The first upstream pull will likely trigger a conflict on README.md - resolve it in any way you like._
Repeat `git pull upstream master` whenever you think the skeleton repository may have been updated. If you encounter conflicts on subsequent upstream pulls, it probably means that you added your code to an unexpected place in the skeleton files. Try to resolve it carefully, if in doubts, ask your teachers.
If you have more than one local folder, repeat the procedure in all of them but remember to `push` to and `pull` from your private remote repository (as is customary when working with multiple local folders) whenever you switch to another local folder, otherwise you risk conflicts due to upstream pulls performed more than once.
# Running Cecko
## Command-line
The resulting executables are located in `<build-folder>/stud-main` and invoked like:
```bash
cd <build-folder>
<build-folder>/stud-main/cecko1 <cecko-folder>/test/test1.c
```
## Visual Studio 2019
Open *DEBUG -> Debug and Launch Settings for ...* (launch.vs.json) and add the following settings into the *x64* configuration(s) in use:
```json
"currentDir": ".",
"args": [ "test\\test1.c" ]
```
For *WSL* configurations, use:
```json
"cwd": ".",
"args": [ "test/test1.c" ]
```
## Visual Studio Code
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment