how-to

# 🪟 Windows (scoop — no admin needed, clean install to ~/scoop/)
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
Invoke-RestMethod -Uri https://get.scoop.sh | Invoke-Expression
scoop install git cmake ninja ccache ripgrep fd bat fzf just llvm zig lazygit

# 🐧 Linux (Ubuntu/Debian)
sudo apt update && sudo apt install -y \
  build-essential cmake ninja-build ccache gdb lldb clang clang-tidy \
  ripgrep fd-find bat fzf strace tcpdump

# 🍎 macOS (get Xcode CLT first for clang + lldb + git)
xcode-select --install
brew install cmake ninja ccache ripgrep fd bat fzf just lazygit

# THE daily command — debug + ninja + ccache + compile_commands
cmake -B build -G Ninja -DCMAKE_BUILD_TYPE=Debug -DCMAKE_EXPORT_COMPILE_COMMANDS=ON -DCMAKE_C_COMPILER_LAUNCHER=ccache -DCMAKE_CXX_COMPILER_LAUNCHER=ccache
cmake --build build
ln -sf build/compile_commands.json .         # clangd/clang-tidy/IDE need this at root

# Build one target
cmake --build build --target myapp

# Test
ctest --test-dir build --output-on-failure

# Sanitizers
cmake -B build -DCMAKE_CXX_FLAGS="-fsanitize=address,undefined -fno-omit-frame-pointer" -DCMAKE_EXE_LINKER_FLAGS="-fsanitize=address,undefined"

# Presets (if project has CMakePresets.json)
cmake --list-presets
cmake --preset dev && cmake --build --preset dev && ctest --preset dev

# Study the project — what targets exist?
cmake --build build --target help | sort
# What features/options does it expose?
cmake -B build -LAH | rg -i "feature|enable|option|with"
# Generate dependency graph (needs graphviz)
cmake -B build --graphviz=deps.dot && dot -Tpng deps.dot -o deps.png
# Profile configure speed (CMake 3.28+)
cmake -B build --profiling-output=prof.json --profiling-format=google-trace
# → open prof.json at https://ui.perfetto.dev

# Cross-compile
cmake -B build/linux -DCMAKE_TOOLCHAIN_FILE=zig-toolchain.cmake
cmake -B build/android -DCMAKE_TOOLCHAIN_FILE="$ANDROID_NDK/build/cmake/android.toolchain.cmake" -DANDROID_ABI=arm64-v8a -DANDROID_PLATFORM=android-24
cmake -B build/ios -GXcode -DCMAKE_SYSTEM_NAME=iOS -DCMAKE_OSX_ARCHITECTURES=arm64

# What is this project?
scc                                         # language mix + line counts
tree -L 2 --dirsfirst -I 'build|.git|node_modules'
bat README.md

# What does it build?
cmake -B build -G Ninja && cmake --build build --target help | sort

# Who works on it?
git shortlog -sn --all | head -10           # top contributors
git log --oneline -20                       # recent activity

# Hottest files (most changed = most complex, most bugs)
git log --format=format: --name-only --since="6 months ago" | sort | uniq -c | sort -rn | head -15

# Who wrote this and when?
git blame src/engine/renderer.cpp | bat -l gitblame
git log --oneline -10 -- src/engine/renderer.cpp

# When was this function added?
git log -S "initVulkan" --oneline

# What changed in this file recently?
git diff HEAD~10 -- src/engine/renderer.cpp

# aider — AI pair programmer in terminal (https://aider.chat)
pip install aider-chat
aider --read-only src/engine/               # study mode: ask questions about code
# > "explain how the rendering pipeline works"
# > "what are the main abstractions and data flow?"

# GitHub Copilot Chat in terminal (https://cli.github.com)
gh copilot suggest "find all functions that allocate without RAII"
gh copilot explain "git rebase -i HEAD~5"

git bisect start
git bisect bad HEAD                          # current is broken
git bisect good v1.0                         # v1.0 was good
# Test each checkout → git bisect good/bad → repeat until found
git bisect reset

# Automated (if you have a test):
git bisect start HEAD v1.0
git bisect run cmake --build build && ctest --test-dir build

# Install: scoop install lazygit / brew install lazygit / sudo apt install lazygit
lazygit                                      # launch TUI — everything is visual

# Interactive rebase (lazygit: go to Commits [3], press 'e' to edit, 's' to squash)
git rebase -i HEAD~5                         # CLI equivalent

# Cherry-pick
git cherry-pick abc1234                      # one commit
git cherry-pick abc1234..def5678             # range

# Stash tricks
git stash push -m "WIP: feature X"          # named stash
git stash push -- src/a.cpp src/b.cpp       # specific files only
git stash push -u -m "with untracked"       # include untracked
git stash list                              # see all stashes
git stash apply stash@{2}                   # apply without dropping

# Reflog — recover anything
git reflog                                  # every HEAD movement ever
git checkout -b recovered-branch abc1234    # recover deleted branch

# Worktrees — work on multiple branches simultaneously
git worktree add ../project-hotfix hotfix-branch
cd ../project-hotfix                        # separate dir, same repo

# Pretty log
git log --oneline --graph --decorate --all -30

# Compare two command outputs
diff <(cmake --build build --target help | sort) <(cmake --build build-rel --target help | sort)

# Compare compile_commands between builds
diff <(jq '.[].file' build/compile_commands.json | sort) <(jq '.[].file' build-rel/compile_commands.json | sort)

# Compare git log of two branches
diff <(git log main --oneline -20) <(git log feature --oneline -20)

# Feed multiple sources to one command
cat <(rg "#include" --type cpp --no-filename) <(rg "#include" --type c --no-filename) | sort -u

# Pipe to multiple commands simultaneously
cmake --build build 2>&1 | tee >(grep -i error > errors.log) >(grep -i warning > warnings.log)

# xargs with parallel execution
fd -e cpp | xargs -P 8 -I {} clang-format -i {}

# Pipe to clipboard
rg "pattern" --type cpp | xclip -selection clipboard    # Linux
rg "pattern" --type cpp | pbcopy                         # macOS
rg "pattern" --type cpp | clip                           # Windows

# GNU parallel — process files 8 at a time
fd -e cpp -e hpp | parallel -j8 clang-format -i {}

# Brace expansion — create project structure fast
mkdir -p project/{src/{core,render,audio},include,test,build}
cp main.cpp{,.bak}                           # same as: cp main.cpp main.cpp.bak

# Install fzf key bindings: ~/.fzf/install
# Now you get:
# Ctrl+R = fuzzy history search with preview
# Ctrl+T = fuzzy file search inline
# Alt+C  = fuzzy cd

# Fuzzy open file with preview
fd -e cpp | fzf --preview 'bat --style=numbers {}' | xargs vim

# Fuzzy git branch checkout
git branch | fzf | xargs git checkout

# ccache — 5-10× faster rebuilds
ccache -s                                    # stats
ccache -C                                    # clear

# Enable in cmake:
cmake -B build -DCMAKE_C_COMPILER_LAUNCHER=ccache -DCMAKE_CXX_COMPILER_LAUNCHER=ccache

# Unity builds (CI only!)
cmake -B build -DCMAKE_UNITY_BUILD=ON

# ripgrep — search code
rg "pattern" --type cpp -n -C 3             # with context
rg "TODO|FIXME|HACK" --type cpp             # todos
rg "new\s+\w+" --type cpp                   # raw owning pointers (smart ptr candidates)
rg "^#include" --type cpp --no-filename | sort -u  # all unique includes

# fd — find files
fd -e cpp -e hpp                            # all C++ files
fd --changed-within 1day                    # modified today

# fzf — fuzzy find
fd -e cpp | fzf --preview 'bat {}'          # fuzzy open with preview
git branch | fzf | xargs git checkout       # fuzzy branch switch

# bat — cat with syntax
bat src/main.cpp --diff                     # show git changes in gutter

# cppcheck — find bugs without compiling
cppcheck --enable=all --suppress=missingIncludeSystem src/

# clang-tidy (needs compile_commands.json from cmake configure)
clang-tidy -p build src/main.cpp
clang-tidy -p build --fix src/main.cpp      # auto-fix what it can

# clang-format (https://clang.llvm.org/docs/ClangFormat.html)
clang-format -style=llvm -dump-config > .clang-format
clang-format -i src/**/*.cpp src/**/*.hpp   # format all files

# ast-grep — structural search (AST-aware, not text)
sg -p 'new $$$' --lang cpp                  # all raw new
sg -p 'NULL' -r 'nullptr' --lang cpp -i     # replace all NULLs with nullptr

gdb -tui ./myapp
# b main | r | n | s | c | p var | bt | bt full | watch var | layout split | thread apply all bt

lldb ./myapp
# b main | run | next | step | continue | print var | po obj | bt | frame variable | expr myFunc(42)

# GDB — freeze all threads except current
info threads                                 # list threads
thread 3                                     # switch to thread 3
set scheduler-locking on                     # NOW only YOUR thread steps
n                                            # next — only thread 3 moves
s                                            # step — only thread 3 moves
set scheduler-locking off                    # resume all

# LLDB — same concept
thread list                                  # list threads
thread select 3                              # switch to thread 3
settings set target.process.stop-others true # freeze others during step
next                                         # only thread 3 moves
settings set target.process.stop-others false

# GDB — record & reverse
(gdb) target record-full                     # start recording EVERY instruction
(gdb) continue                                # run forward normally
# ... hit breakpoint or crash ...
(gdb) reverse-step                            # step BACKWARDS
(gdb) reverse-continue                        # run backwards to previous breakpoint
(gdb) reverse-next                            # next line, backwards

# Windows — LLDB (exe as target, dump as core — BOTH required!)
lldb myapp.exe -c crash.dmp
(lldb) bt                                    # backtrace at crash
(lldb) bt all                                # all threads
(lldb) frame variable                        # locals

# Windows — WinDbg for deeper analysis (auto-finds exe from dump)
windbg -z crash.dmp
.sympath+ C:\path\to\pdbs                    # add YOUR PDBs!
!analyze -v                                  # auto-analysis
kb                                           # call stack with params

# Linux — GDB core dump (binary + core — BOTH required!)
gdb ./myapp core.12345
(gdb) bt full                                # backtrace + locals
(gdb) thread apply all bt full               # all threads

# Linux — coredumpctl (systemd — auto-finds binary + core)
coredumpctl list                             # captured cores
coredumpctl gdb <pid>                        # opens GDB with correct binary + core

# Linux — LLDB (binary + core — BOTH required!)
lldb ./myapp -c core.12345
(lldb) bt

# macOS — crash report (binary + report — BOTH required!)
lldb ./MyApp -c MyApp-2024-01-15.ips
(lldb) bt

# Android — tombstone symbolication (unstripped .so path is critical!)
adb logcat | ndk-stack -sym obj/local/arm64-v8a

# iOS — symbolicate crash log (dSYM is critical!)
xcrun symbolicatecrash crash.ips MyApp.app.dSYM > symbolicated.crash

cmake -B build -DCMAKE_CXX_FLAGS="-fsanitize=address,undefined -fno-omit-frame-pointer" -DCMAKE_EXE_LINKER_FLAGS="-fsanitize=address,undefined"

tracy-profiler & ./build/dev/myapp          # GUI connects automatically

# Step 1: Can I reach the host?
ping -c 4 host.com                           # by name
ping -c 4 1.2.3.4                            # by IP (bypasses DNS)

# Step 2: Is DNS working?
dig host.com                                 # DNS lookup (Linux/macOS)
nslookup host.com                            # all platforms

# Step 3: Is the port open?
nc -zv host.com 443 -w 3                     # TCP connect test
# PowerShell:
Test-NetConnection host.com -Port 443

# Step 4: What's the route?
traceroute host.com                          # Linux/macOS
tracert host.com                             # Windows

# tcpdump — capture everything on a port
sudo tcpdump -i any port 8080 -w capture.pcap
# Open capture.pcap in Wireshark

# Filter by host + save
sudo tcpdump -i any -w capture.pcap host api.example.com

# Show only connection attempts (SYN) and refusals (RST)
sudo tcpdump -i any 'tcp[tcpflags] & (tcp-syn|tcp-rst) != 0'

# DNS queries only
sudo tcpdump -i any port 53

# Set SSLKEYLOGFILE before running your app
export SSLKEYLOGFILE=~/sslkeys.log
curl https://api.example.com                 # or run your app
# In Wireshark: Preferences → Protocols → TLS → set key log file
# Now you see decrypted HTTP content!

curl -o /dev/null -w "DNS: %{time_namelookup}s\nConnect: %{time_connect}s\nTLS: %{time_appconnect}s\nFirst byte: %{time_starttransfer}s\nTotal: %{time_total}s\n" https://api.example.com
# If DNS is slow → check /etc/resolv.conf
# If Connect is slow → firewall or routing issue
# If TLS is slow → certificate chain too long
# If First byte is slow → server-side processing

# /etc/hosts — redirect domain to localhost
sudo sh -c 'echo "127.0.0.1 api.example.com" >> /etc/hosts'
# Or without modifying hosts:
curl --resolve api.example.com:443:127.0.0.1 https://api.example.com

# Zig — one-command cross-compile
zig c++ -target x86_64-linux-gnu -O2 main.cpp -o main_linux
zig c++ -target aarch64-linux-gnu -O2 main.cpp -o main_arm
zig c++ -target x86_64-macos-none -O2 main.cpp -o main_mac

# Test with QEMU
qemu-x86_64 ./main_linux
qemu-x86_64 -strace ./main_linux            # trace syscalls

# CMake + Zig toolchain
cmake -B build/linux -DCMAKE_TOOLCHAIN_FILE=zig-toolchain.cmake -G Ninja

# vcpkg (install: scoop install vcpkg / brew install vcpkg)
cmake -B build -DCMAKE_TOOLCHAIN_FILE="$VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake"
vcpkg install fmt spdlog nlohmann-json       # classic mode

# Conan 2 (install: pip install conan)
conan install . --output-folder=build --build=missing
cmake -B build -DCMAKE_TOOLCHAIN_FILE=build/conan_toolchain.cmake

just build preset=clang
just watch
just todos

# Basic
hyperfine --warmup 5 --min-runs 20 "./myapp"

# Compare two versions
hyperfine "./old" "./new"

# Parameter sweep
hyperfine -P size 1024 65536 "./myapp --buf {size}"

# Compilation benchmark
hyperfine --prepare 'rm -rf build && cmake -B build -G Ninja' 'cmake --build build'

# strace — trace all file opens/writes (https://strace.io)
strace -f -e trace=open,openat,write -o trace.log ./myapp
strace -f -e trace=openat ./myapp 2>&1 | grep "O_CREAT"   # only new files

# macOS — fs_usage (built-in, comprehensive)
fs_usage -f filesys ./myapp

# Quick before/after snapshot
touch marker && ./myapp && find . -newer marker -type f

# Install: scoop install adb / brew install android-platform-tools
adb devices -l                              # list devices
adb install -r app.apk                      # install/reinstall
adb logcat -s MyTag *:E                     # filtered errors

# Root (eng/userdebug builds or [Magisk](https://topjohnwu.github.io/Magisk/))
adb root                                    # restart adbd as root
adb shell setenforce 0                      # disable SELinux
adb shell getenforce                        # check: Enforcing/Permissive

# Google APIs image (no Play Services — for clean testing)
sdkmanager "system-images;android-34;google_apis;arm64-v8a"
emulator -avd pixel_test -writable-system -no-snapshot

xcrun simctl list devices                   # list simulators
xcrun simctl boot "iPhone 15"               # boot one
xcrun simctl install booted MyApp.app       # install
xcrun simctl io booted screenshot screen.png

# Physical device (Xcode 15+)
xcrun devicectl list devices
xcrun devicectl device install app --device <id> MyApp.app

# Build
xcodebuild -project MyApp.xcodeproj -scheme MyApp -sdk iphonesimulator build

# LLDB remote debug
lldb -n MyApp

# Quick recon
file myapp                                   # ELF/PE/Mach-O?
checksec --file=myapp                        # ASLR, DEP, PIE, canary?
strings myapp | rg -i "password|secret|key|token"

# Ghidra — decompile to C
ghidra                                       # launch GUI
# F5 = decompile | L = rename | X = cross-refs | G = go to address

# radare2 — CLI RE
r2 -A myapp                                  # open + full analyze
# afl = functions | iz = strings | pdf = disasm | VV = graph | s main = seek to main

# x64dbg — Windows runtime debug
x64dbg myapp.exe
# F2 = breakpoint | F7 = step in | F8 = step over | F9 = run

# WinDbg — kernel debug + crash dumps
windbg -z crash.dmp
# !analyze -v | kb | lm | .sympath srv*https://msdl.microsoft.com/download/symbols

# Binary patching (r2)
oo+                                        # reopen in write mode
wa nop @ 0x401000                            # NOP out instruction

# Compress
strip myapp.exe && upx --best myapp.exe

# DLL/dylib/so dependencies
depends myapp.exe                            # Windows ([dependencywalker.com](https://www.dependencywalker.com))
ldd myapp                                    # Linux (built-in)
otool -L myapp                               # macOS (built-in)

# PE/ELF inspection
pe-bear myapp.exe                            # Windows PE viewer
readelf -h myapp                             # ELF header
objdump -h myapp.exe                         # PE sections

# Strings audit
strings myapp.exe | rg -i "password|secret|pdb"

# Pre-ship checklist
checksec --file=myapp                        # security flags
strings myapp | rg "\.pdb"                   # debug symbols leaked?
strings myapp | rg -i "password"             # secrets?
depends myapp.exe                            # missing DLLs?

# Static CRT (no vcruntime.dll dependency)
cmake -B build -DCMAKE_MSVC_RUNTIME_LIBRARY="MultiThreaded$<$<CONFIG:Debug>:Debug>"

# PDB in release (crash dumps work — without PDB, crash analysis is impossible)
cmake -B build -DCMAKE_CXX_FLAGS_RELEASE="/Zi" -DCMAKE_EXE_LINKER_FLAGS_RELEASE="/DEBUG /OPT:REF /OPT:ICF"

scoop install sdl3                           # 🪟 Windows
brew install sdl3                            # 🍎 macOS
sudo apt install libsdl3-dev                 # 🐧 Ubuntu/Debian
epm install libSDL3-devel                    # 🐧 ALT Linux

lsusb -tv                                    # 🐧 Linux — full USB tree
system_profiler SPUSBDataType                # 🍎 macOS
Get-PnpDevice -Class USB                     # 🪟 Windows PowerShell