Skip to content

Commit

Permalink
Update README.md based on #49
Browse files Browse the repository at this point in the history 
Also adds a .prettierrc.toml file, which will cap the length of lines in
Markdown files and wrap things to new lines to that it's much easier to
read, without changing what the final html/display on github looks like.
This assumes that you have the prettier utility installed in the first
place.
  • Loading branch information
@dkrautha
dkrautha committed Aug 4, 2021
1 parent 279d710 commit 80ade7b
Show file tree
Hide file tree
Showing 2 changed files with 145 additions and 95 deletions.
2 changes: 2 additions & 0 deletions .prettierrc.toml
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
printWidth = 80
proseWrap = "always"
238 changes: 143 additions & 95 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,18 +1,37 @@
# How to build Grail on Linux and Windows

This document describes how to build Grail on a number of different platforms. Grail requires a number of cutting edge tools, so the default ones may have to be replaced. Specifically, we need:

1. gcc-11. We use C++-20 language features including C++17 variadic templates, C++-20 concepts
1. CMake. We need some specific features so require 3.16 or better.
1. Ninja. We used make, but it is slower and labor intensive. CMake + Ninja is a big improvement.
1. Libraries
1. GLFW to manage windows
1. freetype to read fonts
1. mpv for audio and video
1. We also use vscode to edit collaboratively, though contributors may use anything as long as they don't change our formatting conventions.

Older platforms can be modified to work, but the easiest way to develop with grail is to install on Ubuntu 20.04LTS or newer, or msys2 under windows.
Instructions can be found below for various platforms.
This document describes how to build Grail on a number of different platforms.
Grail requires a number of cutting edge tools, so the default ones may have to
be replaced. Specifically, we need:

- gcc-10, or another compiler that supports C++17 fully and has most features of
C++20. We use C++20 language features such as the numbers header and concepts
for templates, as well as C++17 variadic templates.
- CMake version 3.16 or later.

Libraries

- GLFW to manage windows
- freetype to read fonts
- mpv for audio and video

Other Utilities

- We use [clang-format](https://clang.llvm.org/docs/ClangFormat.html) to enforce
formatting specifications, which are in the `.clang-format` file. In the
future we will have an automated system that formats all code submitted to
these specs, but in the meantime please format your code accordingly.
- VS Code uses clang-format by default when working with C++, so it's a good
place to start off if you're looking for an editor. We also often use it to
edit collaboratively as well.
- [Doom Emacs](https://github.com/hlissner/doom-emacs) is another popular choice
for an editor, and is well documented for getting up and running editing C++.

If you'd like to begin working on Grail, the easiest way to do so would be to
install a copy of Ubuntu 20.04 LTS or newer, or MSYS2 if you are using Windows.
It is possible to make Linux distributions with older package versions work, but
it will require additional setup, and some parts of Grail may not work (mainly
audio and video).

[![CMake](https://github.com/StevensDeptECE/GrailGUI/actions/workflows/cmake.yml/badge.svg?branch=main)](https://github.com/StevensDeptECE/GrailGUI/actions/workflows/cmake.yml)

Expand All @@ -22,160 +41,189 @@ Instructions can be found below for various platforms.

2. Run MSYS2: `MSYS2 MinGW 64-bit` from the Windows Start Menu.

- Make sure you are running the correct executable or else you will have trouble with the C++ compiler not recognizing your system correctly.
- Make sure you are running the correct executable or else you will have
trouble with the C++ compiler not recognizing your system correctly.

3. Install dependencies

``` shell
pacman -S git nano make mingw64/mingw-w64-x86_64-gcc mingw-w64-x86_64-gdb mingw-w64-x86_64-gcc mingw-w64-x86_64-toolchain mingw-w64-x86_64-cmake mingw-w64-x86_64-ninja mingw-w64-x86_64-zlib mingw-w64-x86_64-freetype mingw-w64-x86_64-glfw mingw-w64-x86_64-mpv mingw-w64-x86_64-youtube-dl bison flex mingw-w64-x86_64-xz
```
```shell
pacman -S git nano make mingw64/mingw-w64-x86_64-gcc mingw-w64-x86_64-gdb mingw-w64-x86_64-gcc mingw-w64-x86_64-toolchain mingw-w64-x86_64-cmake mingw-w64-x86_64-ninja mingw-w64-x86_64-zlib mingw-w64-x86_64-freetype mingw-w64-x86_64-glfw mingw-w64-x86_64-mpv mingw-w64-x86_64-youtube-dl bison flex mingw-w64-x86_64-xz
```

<!-- This may be possible to remove in the very near future, I've nearly removed all -->
<!-- references to the the environment variable from core parts of Grail. DK-->

4. Edit `~/.bashrc` to include `export GRAIL=/path/to/GRAIL` and `export PATH=$PATH:$GRAIL/bin` on the following line. `source ~/.bashrc` the first time.
4. Edit `~/.bashrc` to include `export GRAIL=/path/to/GRAIL` and
`export PATH=$PATH:$GRAIL/bin` on the following line. `source ~/.bashrc` the
first time.

## Getting Set Up - Ubuntu

### Ubuntu 18.04

1. Install gcc-11 and g++-11

``` shell
sudo add-apt-repository ppa:ubuntu-toolchain-r/test
sudo apt-get update
sudo apt-get install gcc-11 g++-11
```
```shell
sudo add-apt-repository ppa:ubuntu-toolchain-r/test
sudo apt-get update
sudo apt-get install gcc-11 g++-11
```

- Preferred, but optional
1. Set gcc-11 and g++-11 as default compiler
- Preferred, but optional

``` shell
sudo update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-11 11
sudo update-alternatives --install /usr/bin/g++ g++ /usr/bin/g++-11 11
```
1. Set gcc-11 and g++-11 as default compiler

2. Confirm that the default versions of gcc and g++ are correct
```shell
sudo update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-11 11
sudo update-alternatives --install /usr/bin/g++ g++ /usr/bin/g++-11 11
```

``` shell
sudo update-alternatives --config gcc
sudo update-alternatives --config g++
```
2. Confirm that the default versions of gcc and g++ are correct

```shell
sudo update-alternatives --config gcc
sudo update-alternatives --config g++
```

2. If the default version of CMake is installed, purge it from `apt`

``` shell
sudo apt purge --auto-remove cmake
```
```shell
sudo apt purge --auto-remove cmake
```

3. Install the latest version of CMake

``` shell
wget -O - https://apt.kitware.com/keys/kitware-archive-latest.asc 2>/dev/null | gpg --dearmor - | sudo tee /usr/share/keyrings/kitware-archive-keyring.gpg >/dev/null
echo 'deb [signed-by=/usr/share/keyrings/kitware-archive-keyring.gpg] https://apt.kitware.com/ubuntu/ bionic main' | sudo tee /etc/apt/sources.list.d/kitware.list >/dev/null
sudo rm /etc/apt/trusted.gpg.d/kitware.gpg
sudo apt update
sudo apt install kitware-archive-keyring
sudo apt update
sudo apt install cmake
```
```shell
wget -O - https://apt.kitware.com/keys/kitware-archive-latest.asc 2>/dev/null | gpg --dearmor - | sudo tee /usr/share/keyrings/kitware-archive-keyring.gpg >/dev/null
echo 'deb [signed-by=/usr/share/keyrings/kitware-archive-keyring.gpg] https://apt.kitware.com/ubuntu/ bionic main' | sudo tee /etc/apt/sources.list.d/kitware.list >/dev/null
sudo rm /etc/apt/trusted.gpg.d/kitware.gpg
sudo apt update
sudo apt install kitware-archive-keyring
sudo apt update
sudo apt install cmake
```

4. Install other dependencies

``` shell
sudo apt install ninja-build libglfw3-dev libfreetype6-dev mpv libmpv-dev liblzma-dev flex bison pkg-config
```
```shell
sudo apt install ninja-build libglfw3-dev libfreetype6-dev mpv libmpv-dev liblzma-dev flex bison pkg-config
```

5. Refer to step 4 of [Getting Set up - Windows](#getting-set-up---windows) to set up the environment variables.
5. Refer to step 4 of [Getting Set up - Windows](#getting-set-up---windows) to
set up the environment variables.

### Ubuntu 20.04

1. Install gcc-11 and g++-11
1. Install gcc-10 and g++-10

``` shell
sudo add-apt-repository ppa:ubuntu-toolchain-r/test
sudo apt-get update
sudo apt-get install gcc-11 g++-11
```
```shell
sudo apt-get install gcc-10 g++-10
```

- Preferred, but optional
- Preferred, but optional

1. Set gcc-11 and g++-11 as default compiler
1. Set gcc-10 and g++-10 as default compiler

``` shell
sudo update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-11 11
sudo update-alternatives --install /usr/bin/g++ g++ /usr/bin/g++-11 11
```
```shell
sudo update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-10 10
sudo update-alternatives --install /usr/bin/g++ g++ /usr/bin/g++-10 10
```

2. Confirm that the default versions of gcc and g++ are correct
2. Confirm that the default versions of gcc and g++ are correct

``` shell
sudo update-alternatives --config gcc
sudo update-alternatives --config g++
```
```shell
sudo update-alternatives --config gcc
sudo update-alternatives --config g++
```

2. Install dependencies

``` shell
sudo apt install make cmake ninja-build libglfw3-dev libfreetype-dev mpv libmpv-dev liblzma-dev flex bison pkg-config
```
```shell
sudo apt install make cmake ninja-build libglfw3-dev libfreetype-dev mpv libmpv-dev liblzma-dev flex bison pkg-config
```

3. Refer to step 4 of [Getting Set up - Windows](#getting-set-up---windows) to set up the environment variables.
3. Refer to step 4 of [Getting Set up - Windows](#getting-set-up---windows) to
set up the environment variables.

## Getting Set Up - Arch-Based Linux

1. Install dependencies

``` shell
sudo pacman -S glfw-x11 freetype2 base-devel cmake ninja mpv youtube-dl
```shell
sudo pacman -S glfw-x11 freetype2 base-devel cmake ninja mpv youtube-dl
```

```
- If you are using Wayland, then install `glfw-wayland` instead of
`glfw-x11`. Wayland support is currently unconfirmed.

- If you are using Wayland, then install `glfw-wayland` instead of `glfw-x11`. Wayland support is currently unconfirmed.

2. Refer to step 4 of [Getting Set up - Windows](#getting-set-up---windows) to set up the environment variables.
2. Refer to step 4 of [Getting Set up - Windows](#getting-set-up---windows) to
set up the environment variables.

## Compiling

- To compile with default settings, run `./build.sh`
- For those who want to modify the default configuration and compile themselves, we use the following:
- For those who want to modify the default configuration and compile themselves,
we use the following:

``` shell
cmake -S . -Bbuild -GNinja
cmake --build build
```
```shell
cmake -S . -Bbuild -GNinja
cmake --build build
```

- For versions of Ubuntu with custom versions of gcc, but did not set the default compiler with update-alternatives:
- For versions of Ubuntu with custom versions of gcc, but did not set the
default compiler with update-alternatives:

``` shell
CC=gcc-11 CXX=g++-11 cmake -S . -Bbuild -GNinja
cmake --build build
```
```shell
CC=gcc-11 CXX=g++-11 cmake -S . -Bbuild -GNinja
cmake --build build
```

## Running

1. Update `test/CMakeLists.txt` to compile the file you want to compile and link it to grail.
1. Update `test/CMakeLists.txt` to compile the file you want to compile and link
it to grail.
2. `cd test && testWidgets`

- Cursors and other features might not work for other tests as they are not 100% Linux/Windows compatible yet.
- Cursors and other features might not work for other tests as they are not
100% Linux/Windows compatible yet.

## Frequent Issues

### Need to create an SSH key to push into the repository

GitHub has a great guide on how to do this! [This guide](https://docs.github.com/en/github/authenticating-to-github/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent) will show you how to load `ssh-agent` when your terminal starts and add a new SSH key to `ssh-agent` and GitHub
GitHub has a great guide on how to do this!
[This guide](https://docs.github.com/en/github/authenticating-to-github/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent)
will show you how to load `ssh-agent` when your terminal starts and add a new
SSH key to `ssh-agent` and GitHub

### Cloned the repository using HTTPS, but now have to push to the repository

In this instance, you'll need to change the remote url that git is pointing to. This can be done with a single git command that changes which website the remote called `origin` is pointing at. Once you run this, try to push again and you should be good to go!
In this instance, you'll need to change the remote url that git is pointing to.
This can be done with a single git command that changes which website the remote
called `origin` is pointing at. Once you run this, try to push again and you
should be good to go!
Git command:
``` shell
```shell
git remote set-url origin git@github.com:StevensDeptECE/GrailGUI.git
```
### Runtime Error: `Failed to open GLFW window`
### Runtime Error: `Failed to open GLFW window`
This error is most commonly seen when attempting to run Grail on a Windows virtual machine. If your use-case is different, please open an issue with the details of your environment. As far as the project team is aware, this error can be traced to a lack of OpenGL compatibility on Windows virtual machines. This means that the issues is a driver problem that cannot be resolved until there is better OpenGL support in virtual video drivers. If you need a virtual machine, but do not need Windows, a virtual machine running Ubuntu Linux should work. Otherwise, until there is sufficient OpenGL support for virtual Windows, you will have to resort to a dual boot or alternative computer to run Grail and Grail-based programs.
This error is most commonly seen when attempting to run Grail on a Windows
virtual machine. If your use-case is different, please open an issue with the
details of your environment. As far as the project team is aware, this error can
be traced to a lack of OpenGL compatibility on Windows virtual machines. This
means that the issues is a driver problem that cannot be resolved until there is
better OpenGL support in virtual video drivers. If you need a virtual machine,
but do not need Windows, a virtual machine running Ubuntu Linux should work.
Otherwise, until there is sufficient OpenGL support for virtual Windows, you
will have to resort to a dual boot or alternative computer to run Grail and
Grail-based programs.
### Everything Else
If you have an issue not on this list, and feel it should be included in the list of frequent issues, open an issue and let us know!
If you have an issue not on this list, and feel it should be included in the
list of frequent issues, open an issue and let us know!

0 comments on commit 80ade7b

Please sign in to comment.