GrailGUI is a prototype of a replacement for web programming (HTTP, HTML, CSS, JavaScript) and GUI programming. It includes a client graphical API, a browser implemented in C++ and OpenGL, a protocol to transmit metadata and data in binary, a language (XDL) to describe the binary data, and local storage to retain data on the client should that be necessary. Encrypted communications (equivalent of TLS) have not yet been implemented.
For more info see our writeup from Summer 2021.
We'll be managing the things we want to get done with GitHub Issues and Pull Requests. Check there for a good place to start contributing.
We are using C++20 features, so you'll need a compiler with full C++17 support and a decent amount of C++20. Our current recommendation is gcc-10, but up to date versions of clang should be fine as well.
We use CMake to build the project, you'll need vertion 3.16 or later.
We vendor some of our dependencies either directly committed to version control, or pulled from GitHub with CMake fetchcontent. The dependencies you'll need from your system package manager are the following:
- GLFW to manage windows
- freetype to read fonts
- mpv for audio and video
Other Utilities
- We use clang-format to enforce
formatting specifications, which are in the
.clang-formatfile. 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.
You shouldn't need to do anything special during the install, just keep clicking next.
- Run MSYS2:
MSYS2 UCRT64from the Windows Start Menu.
This shell should have a yellow / gold MSYS2 logo. Make sure you're using this one in the future, as if you run the wrong one your C++ compiler will have trouble finding the right libraries.
- Install dependencies
pacman -Syyu
pacman -S mingw-w64-ucrt-x86_64-gcc
pacman -S pactoys
pacman -S git
pacboy -S cmake:p
pacboy -S freetype:p
pacboy -S glfw:p
pacboy -S mpv:p
pacboy -S youtube-dl:p
pacboy -S github-cli:p
pacboy -S gdb:p- Authenticate with GitHub CLI
If you know how to add an ssh key to GitHub, and you've done it for MSYS2 before then you can skip this step. If you have no idea what ssh is or how to add a key to GitHub, just use the cli tools for authentication.
gh auth loginJust follow the prompts and you'll be good to go.
- Optional: Setup the GRAIL Environment Variable
The way sources in Grail are layed out means that you'll need to be in the
test/ directory to run the tests, but when the project builds the test
executables will be places in bin/. You can deal with this in a couple of
ways:
- Just use relative paths
# when you're in the test folder
../bin/<executable you want to run here>
# example
../bin/Globe.exe- Add an environment variable
Edit ~/.bashrc to include export GRAIL=/path/to/GRAIL and
export PATH=$PATH:$GRAIL/bin on the following line. Restart your terminal that
should be it.
If the MSYS2 method does not work, or there are issues, you can try the method below, but support for it will be limited.
-
Follow this guide to install WSL.
-
In Windows Powershell, type the following command to install Ubuntu 20.04 as the default WSL distribution.
wsl --install -d Ubuntu-20.04 wsl --set-version Ubuntu-20.04 2
- Note: If you have an error about version mismatch, use command
wsl -lto show what the name of the Ubuntu LTS is.
- Note: If you have an error about version mismatch, use command
-
Download the x server here. To finish the install click Next -> Next -> Finish.
-
Once installation is complete, right click on the desktop and create a new shortcut.
-
In the shortcut's properties, fill in the target field with the following and apply the changes
"C:\Program Files\VcXsrv\vcxsrv.exe" :0 -ac -terminate -lesspointer -multiwindow -clipboard -dpi auto
-
Double-click the shortcut to run VcXsrv, there should now be an icon for it in your taskbar's tray.
-
In the WSL2 shell, edit the
~/.bashrcfile and add the following line. This allows WSL2 to connect to VcXsrv.export DISPLAY="`grep nameserver /etc/resolv.conf | sed 's/nameserver //'`:0"
-
To test VcXsrv, run the following commands. These should make a pair of eyes appear on your screen, followed by a calculator.
sudo apt install x11-apps xeyes xcalc
-
Install dependencies by referring to the Debian and Ubuntu setup.
-
Edit the
~/.bashrcfile the same way as the step above.
The oldest Linux distribution we've tested to build successfully on is Debian 11 Bullseye. It has a C++20 compatible compiler and recent enough versions of packages. Anything derived from it should be fine, as well as somewhat recent versions of Ubuntu. Run the following to get everything you should need:
sudo apt update && sudo apt install \
build-essential \
cmake \
ca-certificates \
git \
ninja-build \
libglfw3-dev \
libfreetype-dev \
libmpv-dev \
liblzma-dev \
pkg-configAs with MSYS2, optionally edit your ~/.bashrc as described here.
- Install dependencies
sudo pacman -S glfw-x11 freetype2 base-devel cmake ninja mpv youtube-dlIf you are using Wayland, then install glfw-wayland instead of glfw-x11.
Wayland support is currently unconfirmed.
- Refer to step 4 of MSYS2 to set up the environment variables.
To compile one test with default settings, run ./build.sh <testname>
To compile all tests with default settings, run ./build.sh
For those who want to modify the default configuration and compile themselves, we use the following:
cmake -S . -Bbuild -GNinja
cmake --build buildFor building performance-tuned with optimization with debug:
cmake -Bbuild -GNinja -DCMAKE_BUILD_TYPE=relwithdebinfo
cmake --build buildFor building performance-tuned with optimization without debugging information:
cmake -Bbuild -GNinja -DCMAKE_BUILD_TYPE=release
cmake --build build-
Update
test/CMakeLists.txtto compile the file you want to compile and link it to grail. -
cd test && testWidgets- Cursors and other features might not work for other tests as they are not 100% Linux/Windows compatible yet.
GitHub has a great guide on how to do this!
This guide
will show you how to load ssh-agent when your terminal starts and add a new
SSH key to ssh-agent and GitHub. If you've authenticated with GitHub CLI, then
no need to worry about doing this.
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:
git remote set-url origin [email protected]:StevensDeptECE/GrailGUI.gitThis 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. The virtual video drivers are only compatible with the ancient OpenGL 1.1, and we're using much more modern version of OpenGL. We've tried installing newer standalone video drivers and Grail programs are able to launch, but immediately segfault once shaders are loaded.
This means that the issue 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 or Debian 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 could be a antivirus software quarantining your files. Avast is a common software that will prevent your PC from running the program properly. To fix this, go into the antivirus software and add an exception to the git-remote-https.exe file so that your computer can access it.
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!