Skip to content

🔥 From Source

The most flexible way to use the Projects • Latest features, bugs, fixes, highly configurable.

Recommended for: Basic++ users, contributors, developers.

⚡️ Installing

Open a folder to download the code on Windows Explorer
Press Ctrl+L , run powershell and execute:
PowerShell
1
2
# What it does: 'irm' downloads, 'iex' executes, '|' links the two
irm https://brokensrc.dev/get.ps1 | iex

Open a Terminal on some directory and run:
Terminal
1
2
# Curl downloads the script, bash executes as if you typed it
/bin/bash -c "$(curl -sS https://brokensrc.dev/get.sh)"

Open a Terminal on some directory and run:
Terminal
1
2
# Curl downloads the script, bash executes as if you typed it
/bin/bash -c "$(curl -sS https://brokensrc.dev/get.sh)"

  • Install Git and uv on your Platform

Download the code
1
git clone https://github.com/BrokenSource/BrokenSource --recurse-submodules --jobs 4
Enter the directory
1
cd BrokenSource
Ensure submodules are on main
1
git submodule foreach --recursive 'git checkout main || true'
Create venv and install dependencies
1
uv sync --all-packages

Start using any Project
1
2
3
uv run shaderflow
uv run depthflow
uv run broken

Activate the venv
1
2
3
4
5
6
7
# Windows:
.venv\Scripts\Activate.ps1 # PowerShell
.venv\Scripts\Activate.bat # CMD

# Linux and MacOS:
source .venv/bin/activate # Bash
source .venv/bin/activate.fish # Fish
Start using any Project
1
2
3
broken
shaderflow
depthflow

Read what the install scripts does get.sh, get.ps1

The content below is a verbatim copy of the current live script on this website

PowerShell script
  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
#!/usr/bin/env pwsh
# (c) MIT License, Tremeschin
# Script version: 2024.11.10

# This function reloads the "PATH" environment variable so that we can
# find newly installed applications on the same script execution
function Reload-Path {
    $wingetPath  = $env:LocalAppData + "\Microsoft\WindowsApps"
    $machinePath = [System.Environment]::GetEnvironmentVariable("Path", "Machine")
    $userPath    = [System.Environment]::GetEnvironmentVariable("Path", "User")
    $env:Path    = $machinePath + ";" + $userPath + ";" + $wingetPath
}

# Option to continue normally even on errors
function Ask-Continue {
    echo "`nPress Enter to continue normally, or Ctrl+C to exit"
    Read-Host
}

# Consistency in showing steps
function Print-Step {
    echo "`n:: $args`n"
}

# This function immediately exits if Winget is found, else it tries to install it with
# the official Microsoft docs 'Add-AppxPackage' method. If it still fails, it tries
# to download the Appx package (.msibundle) and install it manually.
function Have-Winget {
    Reload-Path
    if ((Get-Command winget -ErrorAction SilentlyContinue)) {
        return
    }

    Print-Step "Installing Winget"

    # Attempt via: https://learn.microsoft.com/en-us/windows/package-manager/winget/
    Add-AppxPackage -RegisterByFamilyName -MainPackage Microsoft.DesktopAppInstaller_8wekyb3d8bbwe
    Reload-Path

    # Attempt manual method if still not found
    if (-not (Get-Command winget -ErrorAction SilentlyContinue)) {
        echo "Winget installation with Add-AppxPackage failed, trying 'manual' method.."
        Print-Step "Downloading Winget installer, might take a while.."

        # Why tf does disabling progress bar yields 50x faster downloads????? https://stackoverflow.com/a/43477248
        $msi="https://github.com/microsoft/winget-cli/releases/download/v1.7.10582/Microsoft.DesktopAppInstaller_8wekyb3d8bbwe.msixbundle"
        $tempFile = [System.IO.Path]::GetTempPath() + "\winget.msixbundle"
        $ProgressPreference = 'SilentlyContinue'
        Invoke-WebRequest -Uri $msi -OutFile $tempFile

        # Install the Appx package
        echo "Finished download, now installing it, can take a while on HDDs systems.."
        Add-AppxPackage -Path $tempFile
        Reload-Path
    }

    # If Winget is still not available, exit
    if (-not (Get-Command winget -ErrorAction SilentlyContinue)) {
        Print-Step "Winget was not found, and installation failed with Add-AppxPackage"
        echo "Winget was installed but still not found. Probably a Path issue or installation failure"
        echo "> Please get it at https://learn.microsoft.com/en-us/windows/package-manager/winget"
        echo "> Alternatively, install manually what was meant to be installed but failed"
        Ask-Continue
    }
}

if (-not (Get-Command git -ErrorAction SilentlyContinue)) {
    Print-Step "Git was not found, installing with Winget"
    Have-Winget
    winget install -e --id Git.Git
    Reload-Path
    if (-not (Get-Command git -ErrorAction SilentlyContinue)) {
        Print-Step "Git was not found, and installation failed with Winget"
        echo "Git was installed but still not found. Probably a Path issue or installation failure"
        echo "> Please get it at https://git-scm.com"
        Ask-Continue
    } else {
        echo "Git was installed successfully"
    }
} else {
    Print-Step "Updating Git"
    winget upgrade --id Git.Git
}

if (-not (Get-Command uv -ErrorAction SilentlyContinue)) {
    Print-Step "uv was not found, installing with Winget"
    Have-Winget
    winget install -e --id=astral-sh.uv
    Reload-Path
    if (-not (Get-Command uv -ErrorAction SilentlyContinue)) {
        Print-Step "uv was not found, and installation failed with Winget"
        echo "uv was installed but still not found. Probably a Path issue or installation failure"
        echo "> Please get it at https://docs.astral.sh/uv/"
        Ask-Continue
    } else {
        echo "uv was installed successfully"
    }
} else {
    Print-Step "Updating uv"
    winget upgrade --id astral-sh.uv
}

# # Clone the Repositories, Install Python Dependencies on venv and Spawn a new Shell

# Skip cloning if already on a cloned directory
if (-not (Test-Path -Path "Broken")) {
    Print-Step "Cloning BrokenSource Repository and all Submodules"
    git clone https://github.com/BrokenSource/BrokenSource --recurse-submodules --jobs 4
    cd BrokenSource

    Print-Step "Checking out main branch for all submodules"
    git submodule foreach --recursive 'git checkout main || true'
} else {
    Print-Step "Already in a Cloned Directory, Skipping Cloning"
}

# The PowerShell execution policy must allow for the Python activation script to run
if ((Get-ExecutionPolicy) -notin @("Unrestricted", "RemoteSigned", "Bypass")) {
    echo "`n(Warning) The current PowerShell ExecutionPolicy disallows activating the Python venv"
    echo "> More info: https://github.com/microsoft/vscode-python/issues/2559"
    echo "> Need any of: 'Unrestricted', 'RemoteSigned', or 'Bypass'"
    echo "> Current ExecutionPolicy: '$(Get-ExecutionPolicy)'"

    echo "`nDon't worry, we just need to run as admin the following:"
    echo "> 'Set-ExecutionPolicy RemoteSigned'`n"
    Read-Host "Press Enter to do it, or Ctrl+C to exit"

    Start-Process powershell -Verb RunAs -ArgumentList "-Command Set-ExecutionPolicy RemoteSigned"
}

Print-Step "Creating Virtual Environment and Installing Dependencies"
uv sync --all-packages

Print-Step "Spawning a new Shell in the Virtual Environment"
powershell -ExecutionPolicy Bypass -NoLogo -NoExit -File .\.venv\Scripts\Activate.ps1

Bash script
  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
#!/bin/bash
# (c) MIT License, Tremeschin
# Script version: 2024.11.10

{ # Prevent execution if partially downloaded

# Exit on any error or failed command (includes pipes)
set -euo pipefail

# Detect current system
MACOS=false
[[ "$OSTYPE" == "darwin"* ]] && MACOS=true

# macOS: Must have 'Xcode Command Line Tools' installed
if $MACOS; then
  if [ ! xcode-select -p &> /dev/null ]; then
    printf "(Error) Xcode Command Line Tools are not installed\n"
    printf "• Install them with 'xcode-select --install'\n"
    printf "• Run again this script after installation\n"
    exit 1
  fi
fi

# Must have 'git' installed
git=""
if [ -x "$(command -v git)" ]; then
  git=$(readlink -f $(which git))
  printf "\n• Found Git at ($git)\n"
else
  printf "\n(Error) Git wasn't found, and is required to clone the repositories\n"
  printf "• Get it at (https://git-scm.com/), or from your distro:\n"
  printf "• macOS:  'brew install git' - needs (https://brew.sh/)\n"
  printf "• Ubuntu: 'sudo apt update && sudo apt install git'\n"
  printf "• Arch:   'sudo pacman -Syu git'\n"
  printf "• Fedora: 'sudo dnf install git'\n"
  exit 1
fi

# Must have 'uv' installed
uv=""
for attempt in $(seq 1 2); do
  if [ -x "$(command -v uv)" ]; then
    uv=$(readlink -f $(which uv))
    printf "\n• Found uv at ($uv)\n"
    break
  fi

  if [ $attempt -eq 2 ]; then
    printf "\n(Error) uv wasn't found after an installation attempt\n"
    printf "• Do you have the Shims directory on PATH?\n"
    printf "• Try restarting the Shell and retrying\n"
    printf "• Get it at (https://docs.astral.sh/uv/)\n"
    exit 1
  fi

  printf "\n• uv wasn't found, will attempt to install it\n\n"
  /bin/bash -c "$(curl -sSfL https://astral.sh/uv/install.sh)"
done

# # Clone the Repositories, Install Python Dependencies on venv and Spawn a new Shell

# Already inside a git repository
if git rev-parse --is-inside-work-tree &> /dev/null; then
  work_tree=$(git rev-parse --show-toplevel)

  # Must be on BrokenSource to continue
  if (cd "$work_tree" && git remote get-url origin 2>/dev/null | grep -q "BrokenSource"); then
    printf "\n• Already inside the BrokenSource main repository\n"
    printf "  - For latest changes, run 'Scripts/update.sh'\n"
    cd "$work_tree"
  else
    printf "\n(Error) Currently in a non-BrokenSource main git epository, exiting\n"
    exit 1
  fi

# Directory exists
elif [ -d "BrokenSource" ]; then
  printf "\n• BrokenSource directory exists. Assuming it's the repository\n"
  printf "  - On errors, try deleting the directory and run again\n"
  printf "  - For latest changes, run 'Scripts/update.sh'\n"
  cd BrokenSource

# Fresh clone
else
  printf "\n• Cloning BrokenSource Repository and all Submodules\n\n"
  $git clone https://github.com/BrokenSource/BrokenSource/ --recurse-submodules --jobs 4
  cd BrokenSource

  printf "\n• Checking out main branch for all submodules\n\n"
  $git submodule foreach --recursive 'git checkout main || true'
fi

# Make scripts executable for later use
chmod +x Website/get.sh
chmod +x ./Scripts/activate.sh

printf "\n• Creating Virtual Environment and Installing Dependencies\n\n"
$uv self update || printf "\n• uv self update failed, ignoring..\n\n"
$uv sync --all-packages || printf "\n• uv sync failed, could cause issues..\n\n"

printf "\n• Spawning a new Shell in the Virtual Environment\n"
printf "  - Source the Virtual Environment to get here again\n"
printf "  - Tip: Alternative, run 'Scripts/activate.sh'\n\n"
source .venv/bin/activate
exec $SHELL

}

⭐️ Usage

Go to the project tab of your interest above and see the quickstart!

  • You can also run the projects with: uv run 'project' directly

Next time, to use the projects

You just have to Open a Terminal on the BrokenSource directory and source the virtual environment

  • For that, run Scripts/activate.sh if on Linux/MacOS or Scripts/activate.ps1 if on Windows
  • Or manually with source .venv/bin/activate or .venv\Scripts\Activate.ps1

🚀 Upgrading

Repositories

The installation script should've initialized and set all submodules to the main branch:

Command
1
git submodule foreach --recursive 'git checkout main || true'

After that, you can pull the latest changes of all repositories with:

Command
1
git pull --recurse-submodules --jobs=4

If you have any local changes

  • Keep them: Add --rebase to the command above
  • Delete them: Add --force to the command above

Packages

The Python tooling I'm using to orchestrate the Monorepo is uv

  • You'll probably only need to know of a single command:

Command: uv sync --all-packages

This will update the venv and install any new dependencies

After that, just activate the venv and you're good to go!

♻️ Uninstalling

See the uninstalling page