// Moved from docs/src/getting-started/QUICKSTART.adoc to docs/working/scratch/src/getting-started/QUICKSTART.adoc on 2026-06-16 (docs reorg Phase 2) == StarForth - Quick Start Guide :toc: left :toc-title: Contents :toclevels: 3 xref:../README.adoc[← Back to Documentation Index] === 🀠 The Fastest Forth in the West! ==== One-Line Quick Start [source,bash] ---- # Build the fastest version for your platform make fastest ---- === πŸš€ Common Commands [width="100%",cols="26%,37%,37%",options="header",] |=== |Command |What It Does |When To Use |`+make fastest+` |Maximum speed build |Production, benchmarking |`+make fast+` |Fast without LTO |Development, debugging |`+make debug+` |Debug build (-g -O0) |Debugging with GDB |`+make benchmark+` |Run full benchmark suite |Performance testing |`+make help+` |Show all options |When you forget πŸ˜… |=== === 🎯 Platform-Specific Builds ==== On x86_64 Linux [source,bash] ---- make fastest # Auto-detects x86_64, builds with ASM optimizations ./build/starforth # Run it! ---- ==== On Raspberry Pi 4 [source,bash] ---- make fastest # Auto-detects ARM64, builds optimized for Cortex-A72 ./build/starforth ---- ==== Cross-Compile for Raspberry Pi 4 [source,bash] ---- # On your x86_64 development machine (requires gcc-aarch64-linux-gnu): make rpi4-cross # Builds 987 KB ARM64 binary with inline ASM # Copy to Raspberry Pi: scp build/starforth pi@raspberrypi.local:~/ # On Raspberry Pi: ./starforth # Statically linked, ready to run! ---- *Note:* ARM64 cross-compilation has been tested and verified. The binary includes inline assembly optimizations for ARM64/AArch64. === ⚑ Performance Modes ==== Speed Rankings (Fastest to Slowest) [arabic] . *`+make pgo+`* - Profile-Guided Optimization ⭐ ULTIMATE * Two-stage build with profiling * 5-15% faster than `+fastest+` * Takes 2-3x longer to build . *`+make fastest+`* - Maximum Performance ⭐ RECOMMENDED * Assembly optimizations * Direct threading * LTO enabled * Best balance of speed and build time . *`+make fast+`* - Fast Development * Assembly optimizations * Direct threading * No LTO (easier debugging) . *`+make turbo+`* - Assembly Only * Assembly optimizations * No direct threading * Good middle ground . *`+make all+`* - Standard Build * Default optimizations (-O2) * No assembly optimizations . *`+make debug+`* - Debug Build * No optimizations (-O0) * Full debug symbols (-g) === πŸ”§ INIT System StarForth automatically loads `+./conf/init.4th+` at startup, which contains foundational Forth definitions. This is completely automatic - just run starforth and it’s ready to go! [source,bash] ---- ./build/starforth # INIT runs automatically... ok> F # Words from init.4th are immediately available ---- *What INIT does:* - Loads blocks from `+./conf/init.4th+` - Executes them (defines words) - Protects them from FORGET (dictionary fence) - Zeros blocks for your use πŸ“– *link:docs/INIT_SYSTEM.md[Full INIT Documentation β†’]* === πŸ§ͺ Testing & Benchmarking [source,bash] ---- # Quick benchmark (1 million operations) make bench # Full benchmark suite make benchmark # Run test suite make test ---- ==== Expected Performance (1M stack operations) [cols=",,",options="header",] |=== |Build Type |x86_64 |ARM64 (RPi4) |Debug |~800ms |~1200ms |Standard |~250ms |~380ms |Fastest |~60ms |~95ms |PGO |~50ms |~80ms |=== === πŸ“ Generate Assembly [source,bash] ---- # Generate .s files for inspection make asm # View assembly less build/stack_management.s ---- === 🧹 Cleanup [source,bash] ---- # Clean everything make clean # Clean only object files (keep executables) make clean-obj ---- === πŸ”§ Advanced Usage ==== Custom Compiler Flags [source,bash] ---- make fastest CFLAGS="$(make -s print-cflags) -DCUSTOM_FLAG" ---- ==== Static Binary [source,bash] ---- make fastest LDFLAGS="-static -s" ---- ==== Different Compiler [source,bash] ---- make fastest CC=clang ---- ==== Cross-Compilation [source,bash] ---- make fastest CC=aarch64-linux-gnu-gcc \ CFLAGS="..." \ LDFLAGS="-static" ---- === πŸŽ“ Understanding the Build Flags ==== What’s Enabled in `+make fastest+`? [cols=",",options="header",] |=== |Flag |What It Does |`+-O3+` |Maximum optimization |`+-march=native+` (x86_64) |Use all CPU features |`+-march=armv8-a+crc+simd+` (ARM64) |ARMv8 + NEON |`+-DUSE_ASM_OPT=1+` |Enable assembly optimizations |`+-DUSE_DIRECT_THREADING=1+` |Direct-threaded interpreter |`+-flto+` |Link-Time Optimization |`+-funroll-loops+` |Unroll loops |`+-finline-functions+` |Aggressive inlining |`+-fomit-frame-pointer+` |Use register for extra speed |=== === πŸ› Debugging ==== Debug Build [source,bash] ---- make debug gdb build/starforth ---- ==== Debug Optimized Build [source,bash] ---- make fast CFLAGS="$(make -s print-cflags) -g" gdb build/starforth ---- ==== Verify Optimizations Are Working [source,bash] ---- # Check for assembly symbols nm build/starforth | grep -i "vm_push_asm" # Check architecture file build/starforth # Check for LTO readelf -s build/starforth | grep -i lto ---- === πŸ“Š Comparing Builds [source,bash] ---- # Build baseline make clean && make all cp build/starforth build/starforth_baseline # Build optimized make clean && make fastest cp build/starforth build/starforth_fastest # Compare sizes ls -lh build/starforth_* # Compare performance time ./build/starforth_baseline -c ": TEST 1000000 0 DO 1 2 + DROP LOOP ; TEST BYE" time ./build/starforth_fastest -c ": TEST 1000000 0 DO 1 2 + DROP LOOP ; TEST BYE" ---- === πŸ† Performance Tips [arabic] . *Use `+make fastest+`* for production . *Add heatsink* on Raspberry Pi 4 for sustained performance . *Set CPU governor* to `+performance+`: + [source,bash] ---- echo performance | sudo tee /sys/devices/system/cpu/cpu*/cpufreq/scaling_governor ---- . *Use `+make pgo+`* for ultimate performance (takes longer to build) . *Profile your workload* and customize optimization flags === πŸ“š More Information * *Full Documentation*: See `+docs/+` directory * *Assembly Optimizations*: `+docs/ASM_OPTIMIZATIONS.md+` * *ARM64 Guide*: `+docs/ARM64_OPTIMIZATIONS.md+` * *Raspberry Pi*: `+docs/RASPBERRY_PI_BUILD.md+` * *L4Re Integration*: `+docs/L4RE_INTEGRATION.md+` === πŸ†˜ Troubleshooting ==== "`Illegal instruction`" Error [source,bash] ---- # Your CPU doesn't support all optimizations # Use more conservative flags: make fastest CFLAGS="$(BASE_CFLAGS) -O3 -march=x86-64 -DUSE_ASM_OPT=1" ---- ==== Build Errors [source,bash] ---- # Try standard build first: make clean && make all # If that works, gradually add optimizations: make clean && make fast make clean && make fastest ---- ==== Slow Performance [source,bash] ---- # Verify optimizations are enabled: ./build/starforth --version # (if implemented) # Or check binary: file build/starforth nm build/starforth | grep vm_push_asm ---- === 🎯 Quick Reference Card .... ╔══════════════════════════════════════════════════╗ β•‘ 🀠 FASTEST FORTH IN THE WEST - QUICK REFERENCE β•‘ ╠══════════════════════════════════════════════════╣ β•‘ β•‘ β•‘ BUILD: make fastest β•‘ β•‘ BENCHMARK: make benchmark β•‘ β•‘ DEBUG: make debug β•‘ β•‘ CLEAN: make clean β•‘ β•‘ HELP: make help β•‘ β•‘ β•‘ β•‘ RASPBERRY PI 4: make rpi4-cross β•‘ β•‘ ULTIMATE SPEED: make pgo β•‘ β•‘ β•‘ β•šβ•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β• .... ''''' *Now go forth and be the fastest! 🀠⚑*