Platform support

Before we begin, here's a list of the current officially supported platforms:

  1. Windows
  2. macOS - Some platform-dependent window functions do not exist
  3. Linux
    • X11
    • Wayland - Missing all window platform-dependent functions
  4. WASM - Limited in capabilities

Wayland issues

Currently we have not implemented most platform-dependent windowing functions for Wayland, due to it being "usable" but not development-ready as of now. Parts of the window interface may also be broken on Wayland.

About WASM's limitations

As you know Web Assembly, a.k.a. WASM runs inside a web browser, which means it's sandboxed. Moreover, a WASM file relies on JavaScript code for any functionality it doesn't implement itself. This means that the following features of the framework will not work, or will work differently, when targeting WASM:

  1. The whole OS module and its submodules are disabled
  2. Vulkan renderer is automatically replaced by the WebGPU renderer
  3. All platform-dependent window functions are unavailable
  4. Much of the window interface itself will not work
  5. Working with the clipboard through code is finicky, as is working with it through user input :/
  6. Plugin support is disabled, since Emscripten requires that all libraries and applications use static linking
  7. The get* functions from the renderer interface are mostly unavailable

Dependencies

Windows

After all of this is installed, give yourself symlink permissions. To do that, open run and run secpol.msc:

image

A window like this should open:

image

Navigate to Local Policies -> User Rights Assignment and double-click on the value of Create symbolic links:

image

Click on Add User or Group. Inside the text box, type in your name and then click Check Names for it to auto-complete. Click Ok, exit the window, log out and log back in.

Caution

Setting the security policy and logging in and out is required for the framework to install. Do not take this step lightly.

macOS

On macOS you need to install homebrew and preferably, Xcode, or an IDE like CLion.

The following libraries should be installed using homebrew:

user $ brew install glfw yaml-cpp

After that, install the Vulkan SDK.

Caution

The homebrew packages for vulkan are incomplete and cannot be used for actual local development. Please install the Vulkan SDK manually! That being said, they are useful for CI builds, where you can use them without any problems.

Linux

Additional developer packages may be required, especially when compiling with system-wide libraries. Packages are listed below.

Debian/Ubuntu:

sudo apt-get install git gcc make g++ cmake libglfw3 libglfw3-dev libyaml-cpp-dev libvulkan-dev libvulkan1 libxinerama-dev libxcursor-dev libxi-dev pkgconf libfreetype-dev libdbus-dev policykit-1 libpolkit-agent-1-dev libpolkit-gobject-1-dev libfontconfig-dev vulkan-validationlayers vulkan-validationlayers-dev libxkbcommon-dev

Fedora:

sudo dnf install git gcc make g++ cmake glfw glfw-devel freetype freetype-devel vulkan vulkan-devel yaml-cpp yaml-cpp-devel dbus dbus-devel polkit polkit-devel fontconfig-devel vulkan-validation-layers-devel

Gentoo:

doas emerge glfw vulkan-layers vulkan-loader xorg-x11 freetype yaml-cpp sys-apps/dbus polkit fontconfig

Arch:

sudo pacman -S base-devel cmake git glfw freetype2 yaml-cpp dbus polkit fontconfig vulkan-headers vulkan-validation-layers make gcc xorg-server libxinerama libxcursor libxi pkgconf

* For Vulkan packages and drivers, refer to the manual on the arch wiki.

Void:

sudo xbps-install git gcc make cmake glfw freetype yaml-cpp dbus polkit fontconfig pkgconf Vulkan-Headers Vulkan-ValidationLayers xorg libX11 libX11-devel yaml-cpp-devel glfw-devel freetype-devel dbus-devel polkit-devel fontconfig-devel

NixOS:

A note from Stanislav Vasilev(Madman10K), the founder of MadLadSquad: As I like to say Nix arbeitet nix!. Please don't use this pile of garbage and choose a normal Linux distribution. Unfortunately, however, I am forced to use the framework in a Nix environment for work-related reasons that are confidential. Anyway, if any masochist around here wants to actually use nix, you can run nix-shell after cloning the repository.

This should be enough for local development, however we're not planning to add any further support for NixOS in the future. As said previously, consider migrating to a normal Linux system. Some examples include:

  1. Debian
  2. Ubuntu
  3. Linux Mint
  4. Fedora
  5. Arch Linux
  6. Gentoo Linux
  7. Void Linux
  8. Linux from scratch
  9. Slackware
  10. RHEL
  11. openSUSE

Install

Steps:

  1. Clone the framework using git: git clone https://github.com/MadLadSquad/UntitledImGuiFramework.git --recursive
  2. Enter the new folder
  3. Run the install.sh script. This will install the necessary files for the framework, but will not compile it. If the script failed, check out how to clean up your environment in the troubleshooting section below. Run instructions below:
    • On Windows, git bundles Git Bash which emulates the bash shell found on Linux, so you can run it with https://madladsquad.com/install.sh or run bash install.sh into CMD
    • On Linux, just run it with the terminal by using https://madladsquad.com/install.sh
  4. Answer the prompts
  5. Wait
  6. If there is an error, read through the error log and go to Troubleshooting.

After the install script is finished, you can now create your project. To create a project, use the same script running instructions below and do the following:

  1. Run https://madladsquad.com/create-project.sh
  2. Enter your application's name
  3. Wait
  4. If there was an error, read the error log and go to Troubleshooting.
  5. Your project will be built under the Projects/<project name>/build directory

Tip

You can run https://madladsquad.com/create-project.sh name to create a project in a headless environment like a CI server

Caution

Make sure that you're running the terminal instance as an Administrator when running in headless mode

Troubleshooting

Cleaning up your environment when the installation fails

Builds sometimes fail and while it's important to report build problems to us here, it's also important to know how to rebuild once the problem is resolved. The issue is, without proper clean-up, you can't rerun the https://madladsquad.com/install.sh script.

Generally, this is done automatically when the install.sh script runs. In case of an issue, below are some things you can do:

  1. Delete the build folder under the UVKBuildTool folder
  2. Delete the Projects folder
  3. Go back to the framework directory
  4. Rerun install.sh

Visual Studio: Command Line error /02 and /RTC1 options are incompatible

This is a very common generation error. To fix it, right-click on the UntitledImGuiFramework project in the Solution Explorer then click the Properties button.

Next, navigate to the C/C++ section, expand the list and click on Code Generation. Inside the list view, you should see a setting called Basic Runtime Checks, which you need to set to Default.

image

Other errors

Don't see your error here? Please create an issue to the GitHub issue tracker and send us your build log with your system information. This way, we can resolve your problem, and if needed, document it here if needed. Thanks for using the UntitledImGuiFramework 😀